Add Group Claims Using the "getGroups" Function to a Custom Authorization Server in Okta
Last Updated:
Overview
A group claims added to a custom authorization server can use the getGroups function, which allows for filtering user group membership by name and type, as well as retrieving specific group attributes. This function supports filtering groups based on group.id, group.type, group.profile.name, and group.source.id and can return a list of group names, group IDs, or a list of objects containing both the group name and the ID for all matching groups.
Applies To
- Custom Authorization Server
- Okta Expression Language
- Okta Identity Engine (OIE)
Solution
Review the instructions in the Add a Groups claim for a Custom Authorization Server guide to configure the claim.
The following samples illustrate how to configure the group claim expression:
-
Retrieve specific group names: The expression retrieves a list of group names with the type
OKTA_GROUPthat start with "Test".user.getGroups({'group.type': {'OKTA_GROUP'}}, {'group.profile.name': 'Test', 'operator': 'STARTS_WITH'}).![profile.name]
-
Retrieve all group names: The expression retrieves a list of all group names, including the
BUILT_INEveryone group.user.getGroups({'group.type': {'OKTA_GROUP', 'APP_GROUP', 'BUILT_IN'}}).![profile.name]
- Retrieve specific Lightweight Directory Access Protocol (LDAP) groups: 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'}, 'operator': 'STARTS_WITH'}).![profile.name]
- 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'}, 'operator': 'STARTS_WITH'}).![{profile.name, id}]
- Retrieve a specific group name: The expression retrieves the exact group "Test" and only that group.
user.getGroups({'group.profile.name': { 'Test'}, 'operator': 'EXACT'}).![profile.name]
Collection Projection Syntax
The user.getGroups function supports "collection projection" for configuring group claims. Collection projections enable the use of a subexpression (for example, .![name]) that transforms a collection (such as an array) into a new collection. The expression applies the subexpression to each element in the array and returns a new collection without modifying the original collection.
The following examples illustrate the output formats for different projections:
-
Array of
Strings(.![profile.name]).-
The
.![name]suffix returns a list containing only the names of the groups."grp": [ "test_example_123", "test_example_456", "test_example_789" ]
-
-
Array of Objects
(.![{profile.name, id}]).-
The
.![{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" ] ]
-
