DependencyTrack / DependencyTrack/dependency-track

Instructions for configuring OIDC authentication via Okta, including team synchronization / group synchronization

Open
#6,311 4 comments 1 reaction 0 assignees View on GitHub
enhancement
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:

Image

# 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:

Image

and:

Image

Then, for group synchronization to work you must go to the "Sign On" tab, then scroll to "Token Claims":

Image

then expand "Show legacy configuration":

Image

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:

Image

# 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`:

Image

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:

Image

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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.