Okta has a simple way to send over the groups as a`claim` in the`id_token`

payload.

In Okta, go to the application“Sign On” settings page.

In Okta, go to the application**Sign On** settings page.

Applications > Select Application > General > Sign On

**Applications** >**Select Application** >**General** >**Sign On**

In the“OpenID Connect ID Token” section, turn on“Groups Claim Type” and set

the“Claim name” to`groups`. Optionally configure a filter for which groups to

be sent.

In the**OpenID Connect ID Token** section, turn on**Groups Claim Type** and set

the**Claim name** to`groups`.

Optionally, configure a filter for which groups tobe sent.


Configure Coder to use these claims for group sync. These claims are present in

the`id_token`. See all configuration options for group syncin the

[docs](https://coder.com/docs/admin/auth#group-sync-enterprise).

Configure Coder to use these claims for group sync.

These claims are presentin the`id_token`.

For more group sync configuration options, consult the[IDP sync documentation](../admin/users/idp-sync.md#group-sync).

CODER_OIDC_SCOPES=openid,profile,email,offline_access,groups

CODER_OIDC_GROUP_FIELD=groups

These groups can also be used to configure role syncing based on group

membership.

membership:

CODER_OIDC_SCOPES=openid,profile,email,offline_access,groups

CODER_OIDC_USER_ROLE_FIELD=groups

If roles or groups cannot be completely inferred from Okta group memberships,

another option is to source them from a user’s attributes. The user attribute

list can be found in“Directory > Profile Editor > User (default)”.

another option is to source them from a user's attributes.

The user attributelist can be found in**Directory** >**Profile Editor** >**User (default)**.

Coder can query an Okta profile for the application from the`/userinfo` OIDC

endpoint.To pass attributes to Coder, create the attribute in your application,

Coder can query an Okta profile for the application from the`/userinfo` OIDC endpoint.

To pass attributes to Coder, create the attribute in your application,

then add a mapping from the Okta profile to the application.

“Directory > Profile Editor > {Your Application} > Add Attribute”

**Directory** >**Profile Editor** > {Your Application} >**Add Attribute**

Create the attribute for the roles, groups, or both.**Make sure the attribute

is of type`string array`.**

Create the attribute for the roles, groups, or both. Make sure the attribute

is of type`string array`:


On the“Okta User to {Your Application}” tab, map a`roles` or`groups`

attribute you have configured to the application.

On the**Okta User to {Your Application}** tab, map a`roles` or`groups`

attribute you have configured to the application:


Configure using these new attributes in Coder.

Configure using these new attributes in Coder:

CODER_OIDC_IGNORE_USERINFO=false

CODER_OIDC_SCOPES=openid,profile,email,offline_access

CODER_OIDC_USER_ROLE_FIELD=approles

Okta does not support setting custom scopes and claims in the default

authorization server used by your application. If you require this

functionality, you must create (or modify) an authorization server.

authorization server used by your application.

If you require thisfunctionality, you must create (or modify) an authorization server.

To see your custom authorization servers go to “Security > API”. Note the

`default` authorization server**is not the authorization server your app is

using.** You can configure this default authorization server, or create a new

one specifically for your application.

To see your custom authorization servers go to**Security** >**API**.

Note the`default` authorization server is not the authorization server your app is using.

You can configure this default authorization server, or create a new one specifically for your application.

Authorization servers also give more refined controls over things such as

token/session lifetimes.

Authorization servers also give more refined controls over things such as token/session lifetimes.


To get custom claims working,we shouldmap them to a custom scope. Click the

authorization server you wish to use (likely just using the default).

To get custom claims working, map them to a custom scope.

Click theauthorization server you wish to use (likely just using the default).

Go to“Scopes”, and“Add Scope”. Feel free to create one for roles, groups, or

both.

Go to**Scopes**, and**Add Scope**.

Feel free to create one for roles, groups, orboth:


Now createthe claim to go with the said scope. Go to “Claims”, then “Add

Claim”. Make suretoselect**ID Token** for the token type. The**Value**

expression is uptoyou based on where you are sourcingtherole information.

about.

Createthe claim to go with the said scope.

Goto**Claims**, then**Add Claim**.

Make suretoselect**ID Token** forthetoken type.

This is so if other applications exist, we do not send them information they do not careabout:


Now we have a custom scope+ claim configured under an authorization server, we

need to configure coderto use this.

Now we have a custom scopeand claim configured under an authorization server.

Configure Coderto use this:

CODER_OIDC_ISSUER_URL=https://dev-12222860.okta.com/oauth2/default

CODER_OIDC_SCOPES=openid,profile,email,roles,offline_access

CODER_OIDC_USER_ROLE_FIELD=roles

CODER_OIDC_USER_ROLE_MAPPING='{"admin-group":["template-admin","user-admin"]}'

You can use the “Token Preview” page to verify it has been correctly configured

You can use the "Token Preview" page to verify it has been correctly configured

and verify the`roles` is in the payload.


**Symptoms**: Users experience session timeouts approximately every hour and must re-authenticate

**Cause**: Missing`offline_access` scope in`CODER_OIDC_SCOPES`

**Solution**:

1. Add`offline_access` to your`CODER_OIDC_SCOPES` configuration

1. Restart your Coder deployment

1. All existing users must logout and login once to receive refresh tokens

**Symptoms**: Hourly timeouts, even after adding`offline_access`

**Cause**: Existing user sessions don't have refresh tokens stored

**Solution**: Users must logout and login again to get refresh tokens stored in the database

To confirm that refresh tokens are working correctly:

1. Check that`offline_access` is included in your`CODER_OIDC_SCOPES`

1. Verify users can stay logged in beyond Okta's access token lifetime (typically one hour)

1. Monitor Coder logs for any OIDC refresh errors during token renewal