Configure custom claims for app integrations
Early Access release. See Enable self-service features.
This topic explains how custom claims are created and managed in Okta app integrations. It provides instructions for configuring your Security Assertion Markup Language (SAML) and OpenID Connect (OIDC) app integrations to pass custom claims in SAML assertions and OIDC ID tokens.
Understand custom claims
Custom claims (known as attribute statements in SAML apps and token claims in OIDC apps) allow you to pass user information from Okta to your app integrations.
Previously, only user and group claims were supported. This is now considered the legacy configuration. You can still create and manage legacy claims using the legacy configuration (see Generate entitlement claims using the legacy configuration), or you can use the latest, more powerful claims management feature to generate a wider variety of custom claims, including entitlement claims.
Custom claims are now created and managed on the Sign On tab of the app page. Using Okta Expression Language for Okta Identity Engine (EL for OIE), you can specify the user information that you want to pass in your SAML assertions and OIDC ID tokens. You can no longer define claims when creating a SAML or OIDC app integration.
Supported claims
You can use the following EL for OIE expressions to generate custom claims. For more information about the syntax and features of EL for OIE, see Okta Expression Language in Okta Identity Engine.
| Claim Type | Expression |
|---|---|
| User Profile Attributes | user.profile.{$property} |
| Group Affiliations | user.getGroups.{$arrayOfProperties} |
| Device Profile Attributes | device.profile.{$property} |
| Session AMR | session.amr |
| Session ID | session.id |
|
Entitlements Requires Okta Identity Governance. |
appuser.entitlements.{$attribute} |
Pass custom claims in SAML assertions and OIDC ID tokens
- Go to and open a SAML or OIDC app.
- Click the Sign On tab.
- In the Attributes Statements (SAML) or Token claims (OIDC) section, click Add expression.
- In the Name field, enter a name for the custom claim.
- In the Expression field, enter an EL for OIE expression to specify the information that you want to include in your custom claim. Refer to Supported claims for a list of supported expressions. For more information about EL for OIE, see Okta Expression Language in Okta Identity Engine.
- Click Save.
Custom claims FAQs
Are legacy claims automatically migrated to the new claims interface?
No. Legacy claims use an older version of the Okta Expression Language. To migrate your claims to the new claims interface, you need to recreate the expressions using the Okta Expression Language for OIE.
Should I migrate my expressions to the new interface?
You are not required to migrate your legacy expressions. Both the legacy and new expressions coexist and are additive. However, the new interface is more streamlined, and in some cases a single expression can replace many legacy expressions. Test new expressions in your preview org before making changes in your production org.
Why are my claims no longer in SAML Settings or OIDC ID Token settings?
Your claims have been moved from the SAML settings or OIDC ID token settings to the app Sign On tab. In the Attributes Statements (SAML) or Token claims (OIDC) section, expand Show legacy configuration.
Why are my claims no longer in the General tab?
Your claims have moved from the General tab to the Sign On tab. In the Attributes Statements (SAML) or Token claims (OIDC) section, expand Show legacy configuration.
Why can't I configure SAML attribute statements or claims when I create an app integration?
This is now done on the Sign On tab. As with other similar functions, you can configure this after you save the application with the minimally required information.