Add Group Claims Using the "getGroups" Function to a Custom Authorization Server in Okta
Last Updated:
Overview
Administrators can add group claims to a custom authorization server using the getGroups functiongroup.id, group.type, group.profile.name, and group.source.id to 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. Review the configuration examples to implement the getGroups function in Okta.
Applies To
- Okta Identity Engine (OIE)
- Custom Authorization Server
- Okta Expression Language
Solution
How are group claims configured using the getGroups function?
Review the instructions in the Add a Groups claim for a Custom Authorization Server guide to configure the claim.
Configure the group claim expression to retrieve specific group names, all group names, specific Lightweight Directory Access Protocol (LDAP) groups, group identifiers and names, or an exact group name using the following examples:
-
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]
How does collection projection syntax work?
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.
Review the following examples to understand the output formats for different projections, including arrays of strings and arrays of objects:
-
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" ] ]
-
