Okta SSO: Mapping the Groups Claim

I'm working with Okta again and ran into an interesting situation. I'm hesitant to call it an issue since the solution was available, but finding the solution was more difficult than I expected, in part because I was new to this type of configuration.

I felt a succinct guide to Okta Groups Claim mapping might help someone else. Below are the steps that helped me the most.

Getting Started: What is the Groups Claim in Okta?

We will be using the term "Groups Claim" quite often in this guide, so let's start out by defining what it is and the details on how it is configured by default in Okta.

The Groups Claim is a claim that can be optionally configured to be added to an ID Token (OpenID Connect ID Token). When added, it will list all of the Okta Groups that a user is assigned. Additionally, the list of groups can be filtered by Regex or Okta Expressions.

It can be found by:

1. Logging into your Okta Tenant

2. Navigating to the Admin Dashboard

3. Clicking Applications > Applications

4. Selecting the application from the list

5. Clicking on the Sign On Tab

6. Scroll down to the OpenID Connect ID Token section

Customizing: How Can We Customize the Groups Claim?

So, we've established what a Groups Claim is. Now, let's move on to the ways we can customize it (TLDR; not many!).

There are 3 options available for customizing your Groups Claim:

1. Issuer

2. Groups claim type

   1. Filter:

      1. Filter ONLY OKTA GROUPS associated with the user. Using the "Filter" will only apply to Okta groups. If you are looking to apply Application or AD groups this option will not work.

   2. Expression:

      1. Expressions apply to ALL GROUP TYPES, including Okta groups. This is the best option to start with, given the limitations of the "Filter" option.

      2. You must use the Okta Expression syntax when using this option.

3. Groups claim expression

   1. The functionality of this will change depending on if you choose "Filter" or "Expression".

Filtering: How Do I Filter Groups From My Groups Claim?

This is the question I set out to provide an easy answer to. The TLDR is "It Depends"!

The method you use to filter your Okta Groups Claim will depend on the type of group you are trying to map to your claim. The matrix below will help you decide which methodology you need to use.

Okta Group Types

• Reference: https://help.okta.com/en-us/content/topics/users-groups-profiles/usgp-group-types.htm

Group Type	Definition
Okta Groups	The groups created directly within Okta itself. These can be managed by accessing the Directory > Groups page.
Active Directory Groups	Groups created via the Okta Active Directory integration. Please note, these are not Azure AD or Azure Entra ID groups.
LDAP Groups	Groups created via an LDAP integration within Okta.
Application Groups	Groups created and associated to an Application within Okta. These groups include Azure AD/Azure Entra ID groups.

Supported Claim Types Filters by Group Type

Group Type	Supported Claim Types
Okta Groups	Filter, Expression
Active Directory Groups	Expression
LDAP Groups	Expression
Application Groups	Expression

Troubleshooting Tip: Why Don't I See My Groups After Mapping?

If you have set up your Groups Claims mapping and still aren't seeing groups mapped to your token, check the following:

1. Are you trying to use a Filter on a group that is not an Okta group?

   1. This is unsupported. Switch to using an Expression.

2. Have you validated that the scope you've applied to your Group Expression is correct?

   1. The first parameter in a group expression tells Okta where to look for that group; in Okta, In AD, LDAP, or within an Application. In the case of Application Groups, you need to ensure you are using the ID of the group and not the name.