This article provides guidance and examples on how to create a custom groups claim using the new federated claims feature and the getGroups function.
- Token claims
- OpenID Connect applications
- Org Authorization Server
With the release of the Federated Claims feature, the original Groups claim configuration is now considered legacy. More details about this feature can be found in the Configure custom claims for app integrations | Okta Docs documentation.
To create this claim, navigate to the Sign On or Authentication tab (depending on the features enabled in the org, it can have either name) and click the Add Expression button. When prompted, provide a name for this claim and the desired expression.
Example expressions
-
Retrieve specific group names.
-
The expression retrieves a list of group names with the type OKTA_GROUP that start with "Test".
user.getGroups({'group.type': {'OKTA_GROUP'}}, {'group.profile.name': {'Test.*'}}).![profile.name]
-
-
Retrieve all group names.
-
The expression retrieves a list of all group names, including the BUILT_IN Everyone group.
user.getGroups({'group.type': {'OKTA_GROUP', 'APP_GROUP', 'BUILT_IN'}}).![profile.name]
-
- Retrieve a specific LDAP group.s
- The expression matches specific group names using wildcards and pulls groups with the type APP_GROUP (for example, from an LDAP integration).
user.getGroups({'group.type': {'APP_GROUP'}}, {'group.profile.name': {'group1*', 'group2*'}}).![profile.name]
- The expression matches specific group names using wildcards and pulls groups with the type APP_GROUP (for example, from an LDAP integration).
- Retrieve group identifiers and names.
-
- The expression retrieves both the identifier and the name for groups starting with "test".
user.getGroups({'group.profile.name': { 'test.*'}}).![{profile.name, id}]
- The expression retrieves both the identifier and the name for groups starting with "test".
Collection Projection
The user.getGroups function supports "collection projection" for configuring group claims. Collection projections enable the use of a subexpression (for example, .![profile.name]) that transforms a collection (such as an array) into a new collection. The expression applies the subexpression to each element of the array and returns a new collection without modifying the original.
The following examples illustrate the output formats for different projections:
-
Array of
Strings(.![profile.name])-
The
.![profile.name]suffix returns a list containing only the group names."grp": [ "test_example_123", "test_example_456", "test_example_789" ]
-
-
Array of Objects
(.![{profile.name, id}])-
The
.![{profile.name, id}]suffix returns a list of objects containing multiple attributes for each group, such as the name and identifier."grp": [ [ "00gbxxxxxxxxxxMlr1d7", "test_example_123" ], [ "00gbxxxxxxxxx7UXC1d7", "test_example_456" ], [ "00g5xxxxxxxxxxxTi1d7", "test_example_789" ] ]
-
NOTE: The collection projection used when configuring a Token claim on the Sign On/Authentication tab for an Application differs from that used when configuring the same claim on a Custom Authorization Server. If there is a need to create a group claim on a Custom Authorization Server instead, review the following article instead: Add Group Claims Using the getGroups Function in a Custom Authorization Server | Okta Support Center.
