diff --git a/docs/_docs/getting-started/openidconnect-configuration.md b/docs/_docs/getting-started/openidconnect-configuration.md index 2f11148fa3..d214ad8c1b 100644 --- a/docs/_docs/getting-started/openidconnect-configuration.md +++ b/docs/_docs/getting-started/openidconnect-configuration.md @@ -112,6 +112,20 @@ Set the redirect URI to `<dependency track host>/static/oidc-callback.html` <span style="color:red">\*</span> Requires additional configuration, see [Example setup with Keycloak](#example-setup-with-keycloak) +#### OneLogin + +| API server | Frontend | +| :------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------- | +| alpine.oidc.enabled=true | | +| alpine.oidc.client.id=a9eb980a-fake-45f9-96e0-0891ff63d00d<span style="color:red">\*</span> | OIDC_CLIENT_ID=a9eb980a-fake-45f9-96e0-0891ff63d00d<span style="color:red">\*</span> | +| alpine.oidc.issuer=https://example.onelogin.com/oidc/2 | OIDC_ISSUER=https://example.onelogin.com/oidc/2 | +| alpine.oidc.username.claim=email | | +| alpine.oidc.user.provisioning=true | | +| alpine.oidc.teams.claim=groups | OIDC_SCOPE=openid profile email groups | +| alpine.oidc.team.synchronization=true | | + +<span style="color:red">\*</span> Requires additional configuration, see [Example setup with OneLogin](#example-setup-with-onelogin) + ### Default Groups In cases where team synchronization is not possible, auto-provisioned users can be assigned one or more default teams. @@ -228,6 +242,43 @@ $ curl https://auth.example.com/auth/realms/example/protocol/openid-connect/user > Dependency-Track associates every OpenID Connect user with their subject identifier (`sub` claim of the access token) upon first login. > If a user with the same name but a different subject identifier attempts to log in via OIDC, Dependency-Track will refuse to authenticate that user. This is done to prevent account takeovers, as some identity providers allow users to change their usernames. Also, uniqueness of usernames is not always guaranteed, while the uniqueness of subject identifiers is. +### Example setup with OneLogin + +The following steps demonstrate how to setup OpenID Connect with OneLogin. + +> This guide assumes that: +> +> - the Dependency-Track frontend has been deployed to `https://dependency-track.example.com` +> - a OneLogin instance is available at `https://example.onelogin.com` + +1. Log in to OneLogin and navigate to _Administration -> Applications -> Add App_ + - Search for _OpenID Connect (OIDC)_ + +  + +2. In the _Configuration_ section, set the following values: + - Login Url: `http://dependency-track.example.com/api/v1/user/login` + - Redirect URI's: `https://dependency-track.example.com/static/oidc-callback.html` + +  + +3. In the _Parameters_ section, click on the `Groups` _OpenId Connect (OIDC) Field_ and set the following values: + - Default: `Department (Custom)` (for team synchronization, this must be the field that you use for the user's groups, e.g. Department, Team, Role, etc.) + - Transform: `Semicolon Delimited Input (Multi-value output)` + +  +  + +4. In the _SSO_ section, copy the `Client ID` and use it to set the `alpine.oidc.client.id` and `OIDC_CLIENT_ID` configuration values in the API server and frontend respectively + +  + +5. Login to Dependency-Track as an admin and navigate to _Administration -> Access Management -> OpenID Connect Groups_ + - Create groups with names equivalent to those in OneLogin (these must match exactly, including case, with the values of the `Groups` field set in the _Parameters_ section) + - Add teams that the groups should be mapped to + +6. Use the _OpenID_ button on the login page to sign in with a OneLogin user that is member of at least one of the configured groups. Navigating to _Administration -> Access Management -> OpenID Connect Users_ should now reveal that the user has been automatically provisioned and team memberships have been synchronized + ### Azure Active Directory app registration The following steps demonstrate how to setup OpenID Connect with Azure Active Directory. diff --git a/docs/images/screenshots/onelogin-oidc-configuration.png b/docs/images/screenshots/onelogin-oidc-configuration.png new file mode 100644 index 0000000000..26e24e7f63 Binary files /dev/null and b/docs/images/screenshots/onelogin-oidc-configuration.png differ diff --git a/docs/images/screenshots/onelogin-oidc-parameters-field-groups.png b/docs/images/screenshots/onelogin-oidc-parameters-field-groups.png new file mode 100644 index 0000000000..a3ea320d7c Binary files /dev/null and b/docs/images/screenshots/onelogin-oidc-parameters-field-groups.png differ diff --git a/docs/images/screenshots/onelogin-oidc-parameters.png b/docs/images/screenshots/onelogin-oidc-parameters.png new file mode 100644 index 0000000000..fbf607470f Binary files /dev/null and b/docs/images/screenshots/onelogin-oidc-parameters.png differ diff --git a/docs/images/screenshots/onelogin-oidc-sso.png b/docs/images/screenshots/onelogin-oidc-sso.png new file mode 100644 index 0000000000..b245b068d0 Binary files /dev/null and b/docs/images/screenshots/onelogin-oidc-sso.png differ diff --git a/docs/images/screenshots/onelogin-oidc.png b/docs/images/screenshots/onelogin-oidc.png new file mode 100644 index 0000000000..bca65c73be Binary files /dev/null and b/docs/images/screenshots/onelogin-oidc.png differ