Configure claims sharing

Early Access

This guide explains how to configure

a SAML 2.0

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

---

Learning outcomes

• Know the purpose of claims sharing
• Configure your

  SAML 2.0

  identity provider (IdP) to send authentication claims during SSO

What you need

• An Okta SP org and an Okta IdP org configured for an Okta-to-Okta use case. This guide covers how to configure authentication claims sharing for this scenario.
• The Okta-to-Okta Claims Sharing feature enabled for both orgs. Go to Settings | Features, locate the feature, and then enable it.
• If you don't have Okta orgs, you can create Okta Developer Edition orgs (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.

Accepted authenticators

All authenticators that are natively performed on the Okta IdP are accepted. This includes authenticators like WebAuthn, password, Okta Verify, Okta FastPass, SMS, and email. Claim sharing doesn't currently support the use of any Custom Authenticators for MFA, such as using another IdP or smart card.

AMR claims mapping is enabled on your org

When you enable the Okta-to-Okta Claims Sharing feature for your orgs and trust claims from an identity provider, Okta ignores the legacy AMR Claims Mapping feature.

SAML 2.0

IdP authentication claims sharing

When you use SAML 2.0 with claims sharing, the data that's shared between an Okta IdP and an Okta SP is included in the SAML response in a new reserved tag in the Extension section called OktaAuth. This content is communicated in JSON within the Assertion response and contains information about authentication performed at the Okta IdP org. The entire assertion is securely encrypted with a published encryption key from the SP org.

Example

SAML 2.0 IdP response

Note: The OktaAuth JSON payload is redacted and the response is truncated for brevity.

.....
<saml2:AuthnStatement AuthnInstant="2024-08-21T21:22:21.250Z" SessionIndex="id29513242525044581346797160">
    <saml2:AuthnContext>
        <saml2:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:X509</saml2:AuthnContextClassRef>
        <saml2:AuthnContextDecl>
            <AuthenticationContextDeclaration xmlns="urn:okta:saml:2.0:OktaAuth">
                <Extension>
                    <OktaAuth xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">
                        ...JSON payload...
                    </OktaAuth>
                </Extension>
            </AuthenticationContextDeclaration>
        </saml2:AuthnContextDecl>
    </saml2:AuthnContext>
</saml2:AuthnStatement>
.....

Configure claims sharing

The Okta-to-Okta Claims Sharing feature enables claims sharing between Okta orgs. This section covers how to configure authentication claims sharing for this use case.

Okta IdP configuration

Okta supports the use of SAML 2.0 and OpenID Connect app integrations, and the Org2Org app in the OIN catalog. This is the app that you use for authenticating and authorizing your users. Use the app that you've configured in your Okta IdP org for this example use case. There are no configuration requirements for claims sharing for the Okta IdP org.

Okta SP configuration

To use claims sharing, update the 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 a SAML 2.0 Identity Provider (opens new window)

.

Note: When Okta-to-Okta Claims Sharing and the legacy AMR Claims Mapping feature are both used 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

SAML 2.0

IdP update request

This request is an example of an Okta SAML 2.0 IdP update to trust claims. In the policy section, the trustClaims: true key and value pair appears.

Note: The request example is truncated for brevity.

{
    "type":"SAML2",
    "status":"ACTIVE",
    "features":[],
    "id":"0oa78rktqwQbG2m9O0g4",
    "orgUrl":"http://{yourOktaDomain}",
    "name":"Org2Org",
    "created":null,
    "lastUpdated":"2025-01-15T19:45:03.000Z",
    "protocol":{
        "endpoints":{
            "authorization":{"binding":"HTTP-REDIRECT"},
            "token":{"binding":"HTTP-POST"},
            "userInfo":null,
            "jwks":{"binding":"HTTP-REDIRECT"},
            "acs":{
                "binding":"HTTP-POST",
                "type":"INSTANCE"},
            "sso":{
                "url":"http://{yourOktaDomain}/app/okta_org2org/exk78hrRdLRNV4EZY0g4/sso/saml",
                "binding":"HTTP-POST",
                "destination":"http://{yourOktaDomain}"
                }
        },
        "scopes":[],
        "settings":{
            "nameFormat":"urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified",
            "honorPersistentNameId":true
        },
        "type":"SAML2",
        "algorithms":{
            "response":{
                "signature":{
                    "algorithm":"SHA-256",
                        "scope":"ANY"
                }
            },
        "request":{
            "signature":{
                "algorithm":"SHA-256",
                    "scope":"REQUEST"
              }
          }
        },
        "credentials":{
            "trust":{
                "issuer":"http://{yourOktaDomain}/exk78hrRdLRNV4EZY0g4",
                "audience":"https://{yourOktaDomain}/saml2/service-provider/spjhiydxfezknoimtoye",
                "kid":"eb5c22a1-c2c2-484b-839f-2ca6d29fd519",
                "revocation":null,
                "revocationCacheLifetime":0
             },
        "signing":{"kid":"uiiidnMQ4_WXZlt-ovtrRKJDK6UivJfFSnrfN4nNdwg"}
        }
    },
      "policy":{
        "trustClaims":true,
        "accountLink":{
            "action":"AUTO",
            "filter":null
        },
        "provisioning":{
              "action":"AUTO",
              "profileMaster":false,
              "groups":{"action":"NONE"}
        },
        "maxClockSkew":120000,
        "subject":{
          "userNameTemplate":{ "template":"idpuser.subjectNameId"},
          "filter":"",
          "matchType":"USERNAME",
          "matchAttribute":null
        },
        "mapAMRClaims":false,
        "trustClaims":true
    },
    .....
}

Response example

Note: This example is truncated for brevity.

{
    "id": "0oa78rktqwQbG2m9O0g4",
    "name": "Third-Party SAML IdP",
    "status": "ACTIVE",
    "created": null,
    "lastUpdated": "2025-01-15T19:45:16.000Z",
    "protocol": {
        "type": "SAML2",
        "endpoints": {
            "sso": {
                "url": "http://{yourOktaDomain}/app/okta_org2org/exk78hrRdLRNV4EZY0g4/sso/saml",
                "binding": "HTTP-POST",
                "destination": "http://{yourOktaDomain}"
            },
            "acs": {
                "binding": "HTTP-POST",
                "type": "INSTANCE"
            }
        },
        "algorithms": {
            "request": {
                "signature": {
                    "algorithm": "SHA-256",
                    "scope": "REQUEST"
                }
            },
            "response": {
                "signature": {
                    "algorithm": "SHA-256",
                    "scope": "ANY"
                }
            }
        },
        "settings": {
            "nameFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified",
            "honorPersistentNameId": true
        },
        "credentials": {
            "trust": {
                "issuer": "http://{yourOktaDomain}/exk78hrRdLRNV4EZY0g4",
                "audience": "https://{yourOktaDomain}/saml2/service-provider/spjhiydxfezknoimtoye",
                "kid": "eb5c22a1-c2c2-484b-839f-2ca6d29fd519",
                "revocation": null,
                "revocationCacheLifetime": 0
            },
            "signing": {
                "kid": "uiiidnMQ4_WXZlt-ovtrRKJDK6UivJfFSnrfN4nNdwg"
            }
        }
    },
    "policy": {
        "provisioning": {
            "action": "AUTO",
            "profileMaster": false,
            "groups": {
                "action": "NONE"
            },
            "conditions": {
                "deprovisioned": {
                    "action": "NONE"
                },
                "suspended": {
                    "action": "NONE"
                }
            }
        },
        "accountLink": {
            "filter": null,
            "action": "AUTO"
        },
        "subject": {
            "userNameTemplate": {
                "template": "idpuser.subjectNameId"
            },
            "filter": "",
            "matchType": "USERNAME",
            "matchAttribute": null
        },
        "maxClockSkew": 120000,
        "mapAMRClaims": false,
        "trustClaims": true
    },
    .....
}

Policies and claims sharing

You can configure many scenarios for authentication using claims sharing and policies in your Okta SP and Okta IdP orgs.

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.

With trust claims enabled and your IdP org able to verify any two factors, you can satisfy the requirements in the SP org.

Other authentication policy scenarios

• Possession factor constraints: If you enable any possession factor constraints in the authentication policy of your SP org, the IdP org must satisfy the requirement with appropriate factor verification.

• 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 any authenticator that meets those requirements. This includes authenticators that aren't configured locally in the SP org.
  • Disallow specific authentication methods: If you specify authentication methods to disallow, then the SP org disallows those methods.
  • Allow specific authentication methods: If you specify authentication methods to allow, then the SP org only considers those methods.

  After you define these conditions, if you still haven't met the policy requirement, then the SP org redirects you to verify any locally configured authenticator. If there's no local authenticator available, or the enrollment policy for a particular authenticator is disabled, then the SP org displays an error.

Global session policy example

This same concept applies to the global session policy. Without trust claims enabled, if you have only the password authenticator configured in the SP org, you can't save a global session policy rule that requires MFA.

However, with trust claims enabled, you can specify MFA as required. As long as the claim is coming from the IdP, the session is established because that claim can satisfy the global session policy rule.

Okta Identity Engine and Classic Engine orgs

If you have a combination of Okta Identity Engine and Classic Engine orgs, the rules work in the following ways:

Example scenario one

Your SP org is an Identity Engine org. Your IdP is a Classic Engine org. MFA from the Classic Engine org can only satisfy one of the following authentication policy rules on the Identity Engine SP org:

• Any 1 factor type/IdP
• Any 2 factor types

For the global session policy, MFA from the Classic Engine org can only satisfy the Any factor used to meet the Authentication Policy requirements rule.

Example scenario two

Your IdP org is an Identity Engine org. Your SP org is a Classic Engine org. The Classic Engine org only evaluates whether MFA was completed, such as if more than one factor verification was performed on the IdP org.

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

     Assertion Consumer Service (ACS) URL

     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

Okta-to-Okta Claims Sharing

feature.

Reauthentication

Okta claims sharing doesn't currently support reauthentication. The user isn’t prompted for reauthentication as long as the session is active.

Also, when you federate from the IdP org to the SP org’s Okta dashboard and then click Admin, you aren't prompted for reauthentication. The factors from the IdP are valid until the end of the session on the SP org.