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_GROUP that start with "Test".

    user.getGroups({'group.type': {'OKTA_GROUP'}}, {'group.profile.name': {'Test.*'}}).![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'}}).![name]

• Retrieve specific 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*'}}).![name]

• • The expression retrieves both the identifier and the name for groups starting with "test".

    user.getGroups({'group.profile.name': { 'test.*'}}).![{name, id}]

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 (.![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 (.![{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"
       ]
    ]