Customize tokens returned from Okta with a groups claim

This guide explains how to add a groups claim to ID tokens. You can add these claims to ID tokens for any combination of app groups and user groups to perform SSO using the org authorization server. You can also add a groups claim to ID tokens and access tokens to perform authentication and authorization using a custom authorization server.

Learning outcomes

Add a groups claim to ID tokens and access tokens to perform authentication and authorization.
Build a request URL to test the full authentication flow.

What you need

Okta Developer Edition organization (opens new window)
OpenID Connect client app (opens new window) in Okta with at least one user assigned to it (opens new window)
A Group in Okta (opens new window) with at least one person assigned to it

About customized tokens with a groups claim

You can create a groups claim for an OpenID Connect client app. This approach is recommended if you’re using only Okta-sourced groups. For groups not sourced in Okta, you need to use an expression. See Retrieve both Active Directory and Okta groups in OpenID Connect claims (opens new window). For an org authorization server, you can only create an ID token with a groups claim, not an access token.

Also, you can create a dynamic or static allowlist. Do this when you need to set group allowlists on a per-app basis using both the org authorization server and a custom authorization server.

See Customize tokens returned from Okta when you want to define your own custom claims. For example, you may want to add a user's email address to an access token and use that to uniquely identify the user. You may want to add information stored in a user profile to an ID token.

Request a token that contains the custom claim

There are sections in this guide that include information on building a URL to request a token that contains a custom claim. These sections refer you here for the specific steps to build the URL. Use this URL to request a claim and then decode the JSON Web Token (JWT) to verify that the claim was included in the token.

Specific request and payload examples remain in the appropriate sections. Move on to the next section if you don't currently need these steps.

To test the full authentication flow that returns an ID or an access token, build your request URL:

Obtain the following values from your OpenID Connect app, both of which can be found on the app's General tab:
- Client ID (client_id)
- Sign-in redirect URI (redirect_uri)
Use the authorization server's authorization endpoint:

Note: See Authorization servers for more information on the types of authorization servers available to you and what you can use them for.
- An org authorization server /authorize endpoint looks like this:
  
  https://{yourOktaDomain}/oauth2/v1/authorize
- A custom authorization server /authorize authorization endpoint looks like this:
  
  https://{yourOktaDomain}/oauth2/{authorizationServerId}/v1/authorize
Note: If you add the claim to the default custom authorization server, the {authorizationServerId} is default.

You can retrieve a custom authorization server's /authorize endpoint using the server's metadata URI.
Add the following query parameters to the URL:
- Your OpenID Connect app's client_id
- The response type, which for an ID token is id_token and an access token is token
Note: The examples in this guide use the Implicit flow. For the Authorization Code flow, the response type is code. You can exchange an authorization code for an ID token and/or an access token using the /token endpoint.
- A scope, which is openid for the examples in this guide. When you’re adding a groups claim, both the openid and the groups scopes are included.
- Your OpenID Connect app's redirect_uri
- Values for state and nonce, which can be anything
Note: These values are fully documented on the Obtain an Authorization Grant from a user (opens new window) page.

The resulting URL looks something like this:
```
curl -X GET
"https://{yourOktaDomain}/oauth2/{authorizationServerId}/v1/authorize?client_id=examplefa39J4jXdcCwWA
&response_type=id_token
&scope=openid
&redirect_uri=https%3A%2F%2FyourRedirectUriHere.com
&state=myState
&nonce=myNonceValue"
```
Note: The response_type for an access token looks like this: &response_type=token
After you paste the request into your browser, the browser is redirected to the sign-in page for your Okta org. Enter the credentials for a user who is mapped to your OpenID Connect app, and then the browser is directed to the redirect_uri that you specified in the URL and in the OpenID Connect app. The response contains an ID token or an access token, and any state that you defined. The following are response examples:

ID token
```
https://yourRedirectUriHere.com#id_token=eyJraWQiOiIxLVN5[...]C18aAqT0ixLKnJUR6EfJI-IAjtJDYpsHqML7mppBNhG1W55Qo3IRPAg&state=myState
```
Access token
```
https://yourRedirectUriHere.com#access_token=eyJraWQiOiIxLVN5M2w2dFl2VTR4MXBSLXR5cVZQWERX[...]YNXrsr1gTzD6C60h0UfLiLUhA&token_type=Bearer&expires_in=3600&scope=openid&state=myState
```
To check the returned ID token or access token payload, you can copy the value and paste it into any JWT decoder (for example: https://token.dev (opens new window)). Using a JWT decoder, confirm that the token contains the claims that you’re expecting, including the custom one. If you specified a nonce, that's also included.

Add a groups claim for the org authorization server

Use these steps to create a groups claim for an OpenID Connect client app. This approach is recommended if you’re using only Okta-sourced groups. For an org authorization server, you can only create an ID token with a groups claim, not an access token. See Authorization servers for more information on the types of authorization servers available to you and what you can use them for.

In the Admin Console, go to Applications > Applications.
Select the OpenID Connect client app that you want to configure.
Go to the Sign On tab and click Edit in the OpenID Connect ID Token section.
In the Group claim type section, you can select either Filter or Expression. For this example, leave Filter selected.
In the Group claims filter section, leave the default name groups (or add it if the box is empty), and then add the appropriate filter. For this example, select Matches regex and enter .* to return the user's groups. See Okta Expression Language Group Functions for more information on expressions.
Click Save.
Click the Back to applications link.
From the More button dropdown menu, click Refresh Application Data.

Request an ID token that contains the groups claim

To test the full authentication flow that returns an ID token, build your request URL. The scopes that you need to include as query parameters are openid and groups. For the specific steps on building the request URL, receiving the response, and decoding the JWT, see Request a token that contains the custom claim.

Note: The examples in this guide use the Implicit flow for quick testing. In the following example, request only id_token as the response_type value. This means that the requests are for a fat ID token, and the ID token is the only token included in the response. The ID token contains any groups assigned to the user that signs in when you include the groups scope in the request.

Requests to the org authorization server for both the ID token and the access token are considered thin ID tokens. A thin ID token contains only base claims. Profile attributes and groups aren't returned, even if those scopes are included in the request. You can use the access token to get the groups claim from the /userinfo endpoint (opens new window).

The resulting URL looks something like this:

Note: In this example, the user signing in to your app is assigned to a group called "IT" and being a part of the "Everyone" group.

  curl -X GET
  "https://{yourOktaDomain}/oauth2/v1/authorize?client_id=examplefa39J4jXdcCwWA
  &response_type=id_token
  &scope=openid%20groups
  &redirect_uri=https%3A%2F%2FyourRedirectUriHere.com
  &state=myState
  &nonce=myNonceValue"

The decoded JWT looks something like this:

{
  "sub": "00uixa271s6x7qt8I0h7",
  "ver": 1,
  "iss": "https://{yourOktaDomain}",
  "aud": "0oaoiuhhch8VRtBnC0h7",
  "iat": 1574201516,
  "exp": 1574205116,
  "jti": "ID.ewMNfSvcpuqyS93OgVeCN3F2LseqROkyYjz7DNb9yhs",
  "amr": [
    "pwd",
    "mfa",
    "kba"
  ],
  "idp": "00oixa26ycdNcX0VT0h7",
  "nonce": "UBGW",
  "auth_time": 1574201433,
  "groups": [
    "Everyone",
    "IT"
  ]
}

Add a groups claim for a custom authorization server

Use these steps to add a groups claim to ID tokens and access tokens to perform authentication and authorization using a custom authorization server. See Authorization servers for more information on the types of authorization servers available to you and what you can use them for.

In the Admin Console, from the Security menu, select API, and then select the custom authorization server that you want to configure.
Go to the Claims tab and click Add Claim.
Enter a name for the claim. For this example, name it Groups.
In the Include in token type section, leave Access Token selected. Add the groups claim to an access token in this example.

Note: You can configure the groups claim to always be included in the ID token. To do that, follow these steps and select ID Token for the Include in token type value and select Always.
Select Groups as the Value type.
In the Filter dropdown box, select Matches regex and then enter the following expression as the Value: .*

Note: For more fine-grained filtering information, see the steps for adding a groups claim with a dynamic allowlist.
Click Create.

Request an access token that contains the groups claim

To test the full authentication flow that returns an access token, build your request URL. Make sure that you include the openid scope in the request. For the specific steps on building the request URL, receiving the response, and decoding the JWT, see Request a token that contains the custom claim.