This article provides guidance and examples for creating a custom groups claim in Okta using the federated claims feature and the getGroups function. The original groups claim configuration is now legacy, requiring administrators to configure custom claims for application integrations using the updated expression syntax.

• Okta Identity Engine (OIE)
• Okta Classic Engine
• Token claims
• OpenID Connect (OIDC) applications
• Org Authorization Server

How do administrators create a custom groups claim using the federated claims feature?

Navigate to the application settings and add a new expression to create the custom claim.

1. Navigate to the Sign On or Authentication tab.
2. Select Add Expression.
3. Enter a name for the claim and the desired expression.

Review the following images for examples of the token claims and add expression interfaces.

Review Example Expressions for Retrieving Group Data

Review the following examples to retrieve specific group names, all group names, specific Lightweight Directory Access Protocol (LDAP) groups, or group identifiers and names.

• 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: 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]

• 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}]

How does the collection projection format the output?

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.

Review the following examples to understand the output formats for different collection 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 or 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 Add Group Claims Using the getGroups Function in a Custom Authorization Server.

Related References

• Add Group Claims Using the getGroups Function in a Custom Authorization Server | Okta Support Center
• Regex Expression Support With "user.getGroups" Function | Okta Support Center
• Authorization servers | Concepts | Okta Developer
• Configure custom claims for app integrations | Okta Docs