DependencyTrack / DependencyTrack/dependency-track
Instructions for configuring OIDC authentication via Okta, including team synchronization / group synchronization
- Dominant language
- Java
- Stars
- 4.2k
- Forks
- 811
- Avg merge
- 8h 39m
- Merged PRs (30d)
- 237
Description
### Current Behavior
Hi,
We went through the process of getting Okta and DependencyTrack synced up with OIDC. It was pretty tough the first time to get group synchronization going, and not exactly easy this time. But mostly it is due to mysterious "wtf?" moments with Okta.
I figured it'd be useful to write down the process and information for a future seeker, and perhaps even convert it into docs.
Note that you need to pre-create the groups in DependencyTrack first, and assign that group to a team, like this:
# On the Okta side:
1. Create a new app integration,
2. for Sign-in method select "OIDC - OpenID Connect"
3. for "Application type" select "Single-Page Application"
For the sign-in redirect URIs, set `https://your-domain/static/oidc-callback.html`.
Once it is configured, it should look like this:
and:
Then, for group synchronization to work you must go to the "Sign On" tab, then scroll to "Token Claims":
then expand "Show legacy configuration":
Then set:
* "Groups claim type" to "Filter"
* "Groups claim filter" to `groups`
* then select "Matches regex" and type in `.*`
...and press save.
Finally, of course, assign groups to the app in Okta:
# Now on to the application.
For environment variables...
On the frontend:
```
OIDC_ISSUER=https://yourdomain.okta.com
OIDC_CLIENT_ID=from-your-app-in-okta
OIDC_SCOPE=openid email profile groups
```
And on the backend:
```
DT_OIDC_ENABLED=true
DT_OIDC_CLIENT_ID=from-your-app-in-okta
DT_OIDC_ISSUER=https://yourdomain.okta.com
DT_OIDC_TEAM_SYNCHRONIZATION=true
DT_OIDC_TEAMS_CLAIM=groups
DT_OIDC_USER_PROVISIONING=true
DT_OIDC_USERNAME_CLAIM=email
```
Note that the issuer is plain `https://yourdomain.okta.com/` and NOT the `https://yourdomain.okta.com/oauth2/default` format.
That method is more complicated, and is not necessary.
### Debugging:
If you find you're not getting group membership synced, check the token you're getting back from Okta to see if the groups are present.
1. Use the network inspector in your browser and click the login button.
2. Find the `login` request and copy the `idToken`:
3. And run it through jwt-cli: https://github.com/mike-engel/jwt-cli
4. ...and at this point you should see the groups in the id token:
If you do and the group synchronization isn't working, you probably need to pre-create the group in DependencyTrack by hand like the screenshot says.
If you don't see groups in the token you need to go back and reconfigure Okta, especially the "legacy" groups claim.
### Proposed Behavior
Not sure I know exactly what to put in this field.
### Checklist
- [x] I have read and understand the [contributing guidelines](https://github.com/DependencyTrack/dependency-track/blob/main/CONTRIBUTING.md#filing-issues)
- [x] I have checked the [existing issues](https://github.com/DependencyTrack/dependency-track/issues) for whether this enhancement was already requested
Contributor guide
Assessment
This issue has not been assessed yet.