Configure claims sharing

This guide explains how to configure

an OpenID Connect

identity provider (IdP) to send authentication claims during Single Sign-On (SSO).

---

Learning outcomes

• Know the purpose of claims sharing
• Configure your

  Third-party OpenID Connect

  identity provider (IdP) to send authentication claims during SSO

What you need

• An existing OpenID Connect (OIDC) third-party identity provider (IdP) that's able to send AMR claims to Okta. See

  Add an OpenID Connect Identity Provider

  .
• The third-party IdP configured in Okta. See Create an identity provider in Okta. This connects your Okta org to the IdP.
• If you don't have an Okta org, you can create an Okta Developer Edition org (opens new window).

---

Overview

Claims sharing is the exchange of identity-related information (claims) between different orgs to enable secure access to resources. A claim is a statement made about a user or entity, such as their username, email address, roles, or permissions. This statement is then shared to help determine access rights.

Authentication claims sharing

Authentication claims sharing allows an admin to configure their Okta org to trust claims from IdPs during SSO. Sharing claims also allows Okta to interpret the authentication context from an IdP. This helps eliminate duplicate factor challenges during user authentication and helps improve security posture.

Claims sharing provides assurance context to Okta during policy evaluation. For example, these claims give Okta a better understanding of which factors were used by the IdP to verify the user's identity. Claims do this by conveying information from the IdP that's needed to make policy decisions in the SP. This creates a seamless and secure user experience, which reduces friction and boosts productivity to achieve end-to-end security.

AMR claims mapping is enabled on your org

When you enable the Third-party IdP claims sharing feature for your org and trust claims from an identity provider, Okta ignores the legacy AMR Claims Mapping feature.

Third-party OpenID Connect

IdP authentication claims sharing

When you use OpenID Connect with claims sharing, the data that's shared between a third-party IdP and an Okta SP is included in the ID token (id_token) as AMR claims within an amr array.

Okta can extract AMR claims from the access token when the ID token contains no AMR claims. The access token must be in a signed JWT format and signed with the same keys as the ID token. If you use opaque access tokens, then the AMR value must be sent in the ID token.

Example

Third-party ID token

{
  "ver": 1,
  "sub": "00uid4BxXw6I6TV4m0g3",
  "iss": "https://{yourOktaDomain}",
  "aud": "uAaunofWkaDJxukCFeBx",
  "iat": 1449624026,
  "exp": 1449627626,
  "amr": [
        "sms",
        "mfa",
        "pwd"
    ],
  "jti": "ID.4eAWJOCMB3SX8XewDfVR",
  "auth_time": 1449624026,
  "at_hash": "cpqKfdQA5eH891Ff5oJr_Q",
  "name" :"John Doe",
  "nickname":"Jimmy",
  "preferred_username": "john.doe@example.com",
  "updated_at":1311280970,
  "email":"john.doe@example.com",
  "email_verified":true,
  "address" : { "street_address": "123 Hollywood Blvd.",
    "locality": "Los Angeles",
    "region": "CA",
    "postal_code": "90210",
    "country": "US"
  },
  "phone_number":"+1 (425) 555-1212"
}

Configure claims sharing

The Third-party IdP claims sharing feature enables claims sharing between an Okta SP and a third-party IdP. This section covers how to configure authentication claims sharing for this use case.

Third-party IdP configuration

It's important to ensure that your third-party IdPs return Authentication Method Reference (AMR) claims. The client app used for authenticating and authorizing users must send an amr array with AMR claims in the OpenID Connect ID token (id_token).

Note: You can break a functioning flow with your third-party IdP. This happens after you enable Third-party IdP claims sharing in your Okta SP org, but your third-party IdP isn't configured to return AMR claims. The user can't authenticate with the third-party IdP and the flow is broken.

Supported AMR claims

The following table describes the AMR claims values that Okta supports. Okta ignores unsupported AMR values. See Authentication Method Reference Values (opens new window) for a description of each value type.

Note: You must use a possession AMR value such as hwk with the biometric AMR values (face, fpt, iris, retina, vbm) to satisfy their method characteristics.

AMR value	Factor type	Method characteristic
face	Biometric	User presence, User verifying
fpt	Biometric	User presence, User verifying
iris	Biometric	User presence, User verifying
retina	Biometric	User presence, User verifying
vbm	Biometric	User presence, User verifying
hwk	Possession	User presence, Device-bound, Hardware-protected
kba	Knowledge	N/A
mfa	N/A	N/A
otp	Possession	User presence, Device-bound
pwd	Knowledge	N/A
sc	Possession	User presence, Device-bound
sms	Possession	User presence
swk	Possession	User presence, Device-bound
tel	Possession	User presence
pop	Possession	User presence, Device-bound

Okta SP configuration

To use claims sharing, update the third-party IdP settings in your Okta SP org by adding the trustClaims: true key and value pair to your IdP PUT request. Alternatively, you can enable the Trust claims from this identity provider checkbox in the Admin Console. See

Add an OpenID Connect Identity Provider

.

Note: When Third-party IdP claims sharing and the legacy AMR Claims Mapping features are enabled in your SP org, claims sharing is the only feature considered. The mapAMRClaims property (Trust AMR claims from this identity provider checkbox in the Admin Console) is associated with the legacy claims mapping feature. If you include this property and the trustClaims: true property in your request, Okta only considers the trustClaims property.

Example Okta

Third-party OpenID Connect

IdP update request

{
    "id": "0oa3rmyd0GTuaQdPt806",
    "issuerMode": "DYNAMIC",
    "name": "OIDC3rdParty",
    "status": "ACTIVE",
    "created": "2025-03-28T21:57:24.000Z",
    "lastUpdated": "2025-03-28T21:58:44.000Z",
    "protocol": {
        "type": "OIDC",
        "endpoints": {
            "authorization": {
                "url": "https://{thirdPartyIdPDomain}/authorize",
                "binding": "HTTP-REDIRECT"
            },
            "token": {
                "url": "https://{thirdPartyIdPDomain}/token",
                "binding": "HTTP-POST"
            },
            "jwks": {
                "url": "https://{thirdPartyIdPDomain}/oauth2/v1/keys",
                "binding": "HTTP-REDIRECT"
            }
        },
        "scopes": [
            "email",
            "openid",
            "profile"
        ],
        "issuer": {
            "url": "https://{thirdPartyIdPDomain}"
        },
        "credentials": {
            "client": {
                "client_id": "0oa3q52oiB4UBbQFT806",
                "client_secret": "X7i4OV8UXUkrqIhr2vFs0RzeYFy3AUmXe_huqfgMw-eiw1KMUUCEs7X7YXrR_9Sq"
            }
        }
    },
    "policy": {
        "provisioning": {
            "action": "AUTO",
            "profileMaster": false,
            "groups": {
                "action": "NONE"
            },
            "conditions": {
                "deprovisioned": {
                    "action": "NONE"
                },
                "suspended": {
                     "action": "NONE"
                }
            }
        },
        "accountLink": {
            "filter": null,
            "action": "DISABLED"
        },
        "subject": {
            "userNameTemplate": {
                "template": "idpuser.email"
            },
            "filter": "",
            "matchType": "USERNAME",
            "matchAttribute": ""
        },
        "maxClockSkew": 0,
        "mapAMRClaims": false,
        "trustClaims": true
    },
    "type": "OIDC",
    "_links": {
        "authorize": {
            "href": "https://{thirdPartyIdPDomain}/oauth2/v1/authorize?idp=0oa3rmyd0GTuaQdPt806&client_id={clientId}&response_type={responseType}&response_mode={responseMode}&scope={scopes}&redirect_uri={redirectUri}&state={state}&nonce={nonce}",
            "templated": true,
            "hints": {
                "allow": [
                    "GET"
                ]
             }
        },
        "clientRedirectUri": {
            "href": "https://{yourOktaDomain}/oauth2/v1/authorize/callback",
            "hints": {
                "allow": [
                    "POST"
                ]
            }
        }
    }
}

Response example

Note: This example is truncated for brevity.

{
    "id": "0oa3rmyd0GTuaQdPt806",
    "issuerMode": "DYNAMIC",
    "name": "OIDC3rdParty",
    "status": "ACTIVE",
    "created": null,
    "lastUpdated": "2025-03-28T22:05:25.000Z",
    "protocol": {
        "type": "OIDC",
        "endpoints": {
            "authorization": {
                "url": "https://{thirdPartyIdPDomain}/authorize",
                "binding": "HTTP-REDIRECT"
            },
            "token": {
                "url": "https://{thirdPartyIdPDomain}/token",
                "binding": "HTTP-POST"
            },
            "jwks": {
                "url": "https://{thirdPartyIdPDomain}/oauth2/v1/keys",
                "binding": "HTTP-REDIRECT"
            }
        },
        "scopes": [
            "email",
            "openid",
            "profile"
        ],
        "issuer": {
            "url": "https://{thirdPartyIdPDomain}"
        },
        "credentials": {
            "client": {
                "client_id": "0oa3q52oiB4UBbQFT806",
                "client_secret": "X7i4OV8UXUkrqIhr2vFs0RzeYFy3AUmXe_huqfgMw-eiw1KMUUCEs7X7YXrR_9Sq"
            }
        }
    },
    "policy": {
        "provisioning": {
            "action": "AUTO",
            "profileMaster": false,
            "groups": {
                "action": "NONE"
            },
            "conditions": {
                "deprovisioned": {
                    "action": "NONE"
                },
                "suspended": {
                    "action": "NONE"
                }
            }
        },
        "accountLink": {
            "filter": null,
            "action": "DISABLED"
        },
        "subject": {
            "userNameTemplate": {
                "template": "idpuser.email"
            },
            "filter": "",
            "matchType": "USERNAME",
            "matchAttribute": ""
        },
        "maxClockSkew": 0,
        "mapAMRClaims": false,
        "trustClaims": true
    },
    "type": "OIDC",
    .....
}

Policies and claims sharing

You can configure scenarios for authentication using claims sharing and policies using your Okta SP org and a third-party IdP.

Authentication policy example

Create an authentication policy and rule for your app (opens new window) in your SP org. Select Any 2 factor types, don't select a possession constraint, and select Allow any method that can be used to meet the requirement.

Each individual AMR value represents a factor and possession property. During policy evaluation, Okta uses the AMR values to verify if the authentication policy can be satisfied.

For example, the pwd and sms AMR claims can satisfy an authentication policy configured with Any 2 factor types.

Note: The mfa AMR claim isn't mapped to any factor type or method characteristics. It indicates that the user performed authentication using more than one factor type. It's defined to satisfy the authentication policy Any two factors configuration and to satisfy the global session policy MFA requirement. If there's any additional constraints from the authentication policy, the mfa AMR claim alone doesn't satisfy it. Configure your SP org to require more AMR claims.

Other authentication policy scenarios

• Possession factor constraints: If you enable any possession factor constraints in the authentication policy of your SP org, Okta uses the AMR values to satisfy the requirement. See Supported AMR values.

• User must authenticate with:

  • Authentication method chain: If you select Authentication method chain instead of Any 2 factor types, then Okta can't use AMR values to evaluate the policy. The SP org challenges the user to verify using any locally configured authenticator.

• Authentication methods:

  • Allow any method that can be used to meet the requirement: If you enable this setting in your SP org, you can satisfy the policy requirements by using AMR values and authenticators configured locally in the SP org.
  • Disallow specific authentication methods: If you specify authentication methods to disallow, then Okta can't use AMR values to evaluate the policy. The SP org challenges the user to verify using any locally configured authenticator.
  • Allow specific authentication methods: If you specify authentication methods to allow, Okta can't use AMR claims to evaluate the policy. The SP org challenges the user to verify using any locally configured authenticator.

Global session policy

The global session policy works the same as the authentication policy. AMR values can satisfy the MFA requirement, depending on the AMR values sent.

Okta Classic Engine

With AMR claims, you can use the pwd amr value if the Okta sign-on policy or an app sign-on policy doesn't have an MFA requirement.

If the Okta sign-on policy or an app sign-on policy requires MFA, you have two options:

1. Use the pwd AMR value plus any possession-based AMR value, for example, sms, hwk.
2. Use the mfa AMR value.

The mfa or pwd AMR value is always required for a Classic Engine flow. If these values aren't supplied, the user is prompted with the locally configured MFA factor.

Test your integration

To test your integration, first configure a routing rule (opens new window) for the IdP and then use the IdP to sign in.

Configure a routing rule for the IdP

Configure a simple routing rule for the IdP in the Okta SP org:

• From the Admin Console, go to Security > Identity Providers.
• Select the IdP you want to configure the routing rule for.
• On the Routing rules tab, click Add Routing Rule.
• Enter a name and leave the default values.
• In the THEN Use this identity provider section, add your IdP in the IdP(s) field.
• Click Create Rule.

Use the IdP to sign in

1. Access your Okta SP org using your browser's privacy or incognito mode to avoid false positive or negative results.

2. Click Sign in with {Name of IdP} on the Okta sign-in page.

   The following are the results if everything is configured properly:

   • The user is redirected to the IdP's sign-in page.
   • The authenticators configured in the authentication policy prompt the user for more authentication.
   • After successful authentication, the user is redirected to the

     redirect URI

     specified in the Okta IdP org.

   If something is configured incorrectly, the authorization response contains error information to help you resolve the issue.

Trust claims deletion/deactivation

You can only deactivate or delete an IdP with trust claims enabled if there are other active IdPs that have trust claims enabled. Or, you can deactivate or delete the IdP if all policies are configured in a way that doesn't require trusted claims.

Note: This is also true if you try to disable the

Third-party IdP claims sharing

feature.