Remove Substring from Group Names in Okta OpenID Connect Claims

Administrators often need to send group claims to OpenID Connect (OIDC) applications while removing a common substring prefix from the group names. Use Okta Expression Language in either the custom authorization server claims or the Okta app's token claims configuration to filter groups by prefix and remove the substring using the String.replace() function.

• Okta Identity Engine (OIE)
• Okta Classic Engine
• OpenID Connect (OIDC)
• API Access Management

Downstream applications often require specific role names to recognize them as valid roles. Administrators must transform groups named with prefixes, such as "OIDC-app-Admin", "OIDC-app-Employee", and "OIDC-app-Customer", to "Admin", "Employee", and "Customer" before Okta sends the group claims to the OIDC application. 

How are substrings removed from group names in custom authorization servers?

Navigate to the authorization server claims in the Admin Console and add a new claim with the Okta Expression Language configuration:

• Custom authorization server (API Access Management):
  • Navigate to Admin > Security > API > Authorization Servers > the authorization server that the application uses > Claims  (or Admin > API > Authorization Servers > the authorization server that the application uses > Claims.
  • Add a new claim with the following configuration:
    • Name: roles (or the claim name that the application expects)
    • Include in token type: Access Token (or in the ID token, based on application requirements)
    • Value type: Expression
    • Value: Arrays.flatten(String.replace(Arrays.toCsvString(Groups.startsWith("OKTA","OIDC-app-",100)),"OIDC-app-", ""))
    • Disable claim: Unchecked
    • Include in: Any scope (or specify a particular scope as needed)
• Okta Authorization Server
  • Navigate to Admin > Applications > OpenID Connect Application > Sign On > Token Claims.
  • Select Edit and configure the group claim as follows:
    • Group claim type: Expression
    • Groups claim expression: 
      • roles (or the claim name the application expects)
      • Arrays.flatten(String.replace(Arrays.toCsvString(Groups.startsWith("OKTA","OIDC-app-",100)),"OIDC-app-", ""))

How does the Okta Expression Language function work?

The provided Okta Expression Language performs a sequence of operations to filter, convert, modify, and format the group data for the token claim.

1. Retrieves all groups starting with the prefix "OIDC-app-" (up to 100 groups).
2. Converts the group array into a comma-separated string.
3. Removes all occurrences of the substring "OIDC-app-" from the string.
4. Converts the resulting string back into an array format suitable for token claims.