{"templateId":"markdown","versions":[{"version":"v1.39","label":"v1.39 STS","link":"/products/custody/identity-and-access/sso","default":true,"active":true,"folderId":"c15a2701"},{"version":"v1.38","label":"v1.38 STS","link":"/products/custody/v1.38/identity-and-access/sso","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.34","label":"v1.34 LTS","link":"/products/custody/v1.34/identity-and-access/sso","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.26","label":"v1.26 LTS","link":"/products/custody/v1.26/identity-and-access/sso","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.19","label":"v1.19 LTS","link":"/products/custody/v1.19/identity-and-access/sso","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.15","label":"v1.15 LTS","link":"/products/custody/v1.15/identity-and-access/sso","default":false,"active":false,"folderId":"c15a2701"}],"sharedDataIds":{"sidebar":"sidebar-products/custody/@v1.15/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Federated identity and SSO","description":"User guides, API reference, and support resources.","siteUrl":"https://docs.ripple.com","lang":"en-US","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"federated-identity-and-sso","__idx":0},"children":["Federated identity and SSO"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Executive summary"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Federated identity lets users authenticate to ","Ripple Custody"," through an external OpenID Connect identity provider, with Keycloak acting as the broker for the Custody realm."]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["OIDC federation changes how users authenticate; it does not replace Custody authorization or signature requirements."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The Keycloak provider alias must match the provider ID used in the user's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["loginIds"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Mapper configuration determines the user identifier that ","Ripple Custody"," receives in the Keycloak-issued token."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Session lifetime, session limiting, and logout behavior are controlled by Keycloak and your upstream identity provider configuration."]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"success","name":"Why this matters"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Federated login depends on correct identity-provider configuration, Keycloak mapper configuration, and Custody user provisioning. Treat SSO as an identity mapping project: choose stable identifiers, configure mappers deliberately, and test the full login path before enabling it for production users."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-federation-works","__idx":1},"children":["How federation works"]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"sequenceDiagram\n actor User\n participant UI as Custody UI\n participant KC as Keycloak Metaco realm\n participant IDP as External OIDC provider\n participant CUS as Custody APIs\n\n User->>UI: Start sign in\n UI->>KC: Redirect to Keycloak\n KC->>IDP: OIDC authorization code flow\n IDP-->>KC: ID token and claims\n KC->>KC: Apply provider mappers\n KC-->>UI: Keycloak-issued token\n UI->>CUS: Call APIs with token\n CUS->>CUS: Apply Custody authorization and signature checks\n","diagramHtml":"Custody APIsExternal OIDC providerKeycloak Metaco realmCustody UICustody APIsExternal OIDC providerKeycloak Metaco realmCustody UIUserStart sign inRedirect to KeycloakOIDC authorization code flowID token and claimsApply provider mappersKeycloak-issued tokenCall APIs with tokenApply Custody authorization and signature checksUser","diagramHtmlDark":"Custody APIsExternal OIDC providerKeycloak Metaco realmCustody UICustody APIsExternal OIDC providerKeycloak Metaco realmCustody UIUserStart sign inRedirect to KeycloakOIDC authorization code flowID token and claimsApply provider mappersKeycloak-issued tokenCall APIs with tokenApply Custody authorization and signature checksUser"},"children":["sequenceDiagram\n actor User\n participant UI as Custody UI\n participant KC as Keycloak Metaco realm\n participant IDP as External OIDC provider\n participant CUS as Custody APIs\n\n User->>UI: Start sign in\n UI->>KC: Redirect to Keycloak\n KC->>IDP: OIDC authorization code flow\n IDP-->>KC: ID token and claims\n KC->>KC: Apply provider mappers\n KC-->>UI: Keycloak-issued token\n UI->>CUS: Call APIs with token\n CUS->>CUS: Apply Custody authorization and signature checks\n"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Keycloak is the broker between ","Ripple Custody"," and the external identity provider. The upstream provider authenticates the user and emits claims. Keycloak maps those claims to a local Keycloak user and issues the token used by ","Ripple Custody","."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"login-and-logout-checkpoints","__idx":2},"children":["Login and logout checkpoints"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The exact screens depend on your identity provider, but the control points are consistent."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Flow"},"children":["Flow"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Checkpoint"},"children":["Checkpoint"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What to verify"},"children":["What to verify"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Login"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Browser redirects to Keycloak."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The Keycloak issuer, callback URL, TLS certificate, and realm endpoint are reachable."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Login"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Keycloak redirects to the upstream OIDC provider."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The provider discovery document, client ID, redirect URI, scopes, and required claims are correct."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Login"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Keycloak exchanges the authorization code server-side."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Keycloak can reach the provider token endpoint, validate TLS, and authenticate with the configured client secret."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Login"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ripple Custody"," receives a Keycloak-issued token."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The token subject, issuer, audience, and mapped login ID match the Custody user."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Logout"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The local application session is cleared."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The user can no longer call protected UI routes with the old browser session."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Logout"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Keycloak token/session state is revoked or expired."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Token revocation and session lifetime settings match your security requirements."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Upstream identity-provider logout support varies. At minimum, plan for local Keycloak session termination. If you require upstream SSO logout as well, verify that your identity provider supports the logout behavior you expect."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"authentication-versus-authorization","__idx":3},"children":["Authentication versus authorization"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Area"},"children":["Area"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What SSO controls"},"children":["What SSO controls"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What stays in Ripple Custody"},"children":["What stays in ","Ripple Custody"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Authentication"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["How a user signs in through an external identity provider."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["API authentication and signing still follow the documented Custody flows."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["User identity"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Which external identifier maps to a Custody user login ID."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["User records, roles, domains, and public keys."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Authorization"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Nothing by itself."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Custody authorization and signature requirements remain separate from federation."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Session behavior"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Keycloak and upstream IdP session lifetimes, session limits, and logout behavior."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Custody intent lifecycle and approval state."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"sso-topics","__idx":4},"children":["SSO topics"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Task"},"children":["Task"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Start here"},"children":["Start here"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Plan an SSO rollout"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/identity-and-access/sso/identity-federation-guide"},"children":["Plan identity federation"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Configure an OIDC provider in Keycloak"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/identity-and-access/sso/keycloak-integration"},"children":["Configure OIDC federation in Keycloak"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Limit concurrent Keycloak sessions"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/identity-and-access/sso/keycloak-session-limiting"},"children":["Keycloak session limiting"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Configure frontend inactivity logout"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/identity-and-access/sso/keycloak-inactivity-timeout"},"children":["Keycloak inactivity timeout"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Investigate SSO login failures"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/identity-and-access/sso/troubleshooting"},"children":["Troubleshoot SSO"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Review deployment configuration areas"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/deployment/reference/keycloak"},"children":["Keycloak configuration"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"supported-federation-path","__idx":5},"children":["Supported federation path"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use OpenID Connect for federated identity. The public SSO documentation covers OIDC federation through Keycloak. SAML federation is not covered in this section."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"troubleshooting-data","__idx":6},"children":["Troubleshooting data"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When troubleshooting SSO with Ripple or an identity-provider vendor, share only the information needed to prove the failure point:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Discovery document reachability."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Non-secret client settings, such as redirect URI, scopes, issuer, and provider alias."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Decoded token headers and claims with secrets, signatures, and personal data removed."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Keycloak and application log snippets with tokens and secrets redacted."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do not share client secrets, private keys, full JWTs, or unredacted identity data in tickets or chat."]}]},"headings":[{"value":"Federated identity and SSO","id":"federated-identity-and-sso","depth":1},{"value":"How federation works","id":"how-federation-works","depth":2},{"value":"Login and logout checkpoints","id":"login-and-logout-checkpoints","depth":2},{"value":"Authentication versus authorization","id":"authentication-versus-authorization","depth":2},{"value":"SSO topics","id":"sso-topics","depth":2},{"value":"Supported federation path","id":"supported-federation-path","depth":2},{"value":"Troubleshooting data","id":"troubleshooting-data","depth":2}],"frontmatter":{"seo":{"title":"Federated identity and SSO"}},"lastModified":"2026-08-04T20:25:11.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/custody/identity-and-access/sso","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}