{"templateId":"markdown","versions":[{"version":"v1.40","label":"v1.40 STS","link":"/products/custody/identity-and-access/sso/identity-federation-guide","default":true,"active":false,"folderId":"c15a2701"},{"version":"v1.39","label":"v1.39 STS","link":"/products/custody/v1.39/identity-and-access/sso/identity-federation-guide","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.38","label":"v1.38 STS","link":"/products/custody/v1.38/identity-and-access/sso/identity-federation-guide","default":false,"active":true,"folderId":"c15a2701"},{"version":"v1.34","label":"v1.34 LTS","link":"/products/custody/v1.34/identity-and-access/sso/identity-federation-guide","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.26","label":"v1.26 LTS","link":"/products/custody/v1.26/identity-and-access/sso/identity-federation-guide","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.19","label":"v1.19 LTS","link":"/products/custody/v1.19/identity-and-access/sso/identity-federation-guide","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.15","label":"v1.15 LTS","link":"/products/custody/v1.15/identity-and-access/sso/identity-federation-guide","default":false,"active":false,"folderId":"c15a2701"}],"sharedDataIds":{"sidebar":"sidebar-products/custody/@v1.15/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Plan identity federation","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":"plan-identity-federation","__idx":0},"children":["Plan identity federation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use this page to plan federated identity before configuring Keycloak or updating users."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"planning-checklist","__idx":1},"children":["Planning checklist"]},{"$$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":"Decision"},"children":["Decision"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What to define"},"children":["What to define"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["OIDC provider"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The external identity provider, its discovery endpoint, and network connectivity from Keycloak."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Provider alias"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A unique lower-case alias in Keycloak. This value must match the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["providerId"]}," in Custody user ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["loginIds"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["User identifier"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The claim that uniquely identifies each user. Prefer a stable claim that does not change when an email address changes."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Scopes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Request the claims needed by your mappers. OIDC requires ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["openid"]},"; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["profile"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["email"]}," are commonly needed for username and email claims."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required claims"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional claim checks that restrict access to users assigned to the Custody application in your identity provider."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["User mapping"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Existing Custody users must have ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["loginIds"]}," that match the identifier Keycloak emits after mapping."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Session policy"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Keycloak session lifetimes, concurrent-session controls, and upstream IdP logout behavior."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Secrets"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Where client secrets are stored, how they are rotated, and how Keycloak and deployment secrets stay synchronized."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Rollout"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Test users, fallback access, operator responsibilities, and production verification."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"identifier-design","__idx":2},"children":["Identifier design"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The most important SSO design choice is the identifier that links the external identity provider to a Custody user."]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"flowchart LR\n Claims[\"OIDC claims from IdP\"] --> Mappers[\"Keycloak provider mappers\"]\n Mappers --> Token[\"Keycloak-issued token\"]\n Token --> LoginId[\"Custody loginId lookup\"]\n LoginId --> User[\"Custody user record\"]\n","diagramHtml":"

OIDC claims from IdP

Keycloak provider mappers

Keycloak-issued token

Custody loginId lookup

Custody user record

","diagramHtmlDark":"

OIDC claims from IdP

Keycloak provider mappers

Keycloak-issued token

Custody loginId lookup

Custody user record

"},"children":["flowchart LR\n Claims[\"OIDC claims from IdP\"] --> Mappers[\"Keycloak provider mappers\"]\n Mappers --> Token[\"Keycloak-issued token\"]\n Token --> LoginId[\"Custody loginId lookup\"]\n LoginId --> User[\"Custody user record\"]\n"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Choose a claim that is:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Unique for each user."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Stable over time."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Present in every login token."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Available through the scopes configured in Keycloak."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sub"]}," claim is required in OIDC ID tokens. Claims such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["email"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["preferred_username"]}," can be useful, but they depend on provider configuration and requested scopes."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"claims-scopes-and-access-gating","__idx":3},"children":["Claims, scopes, and access gating"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use scopes and required claims deliberately:"]},{"$$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":"Setting"},"children":["Setting"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Guidance"},"children":["Guidance"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["openid"]}," scope"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required for OIDC identity tokens."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["profile"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["email"]}," scopes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Request only when your mapper design needs profile or email claims. Some identity providers let these scopes be optional instead of granted by default."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required or essential claim"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Use when your identity provider marks users as assigned to the Custody application through a specific claim. Users without the claim should not be treated as assigned."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Mapper claim"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Choose the claim that produces the Custody ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["loginIds.id"]}," value. Avoid claims that are absent, mutable, or not unique."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do not publish real tenant identifiers, client IDs, client secrets, or required-claim values in public runbooks. Use placeholders and store the actual values in your approved secret-management system."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"provider-aliases-and-login-ids","__idx":4},"children":["Provider aliases and login IDs"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Keycloak identity provider alias identifies the upstream provider. The same value is used as the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["providerId"]}," in Custody user records."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"loginIds\": [\n {\n \"id\": \"user@example.com\",\n \"providerId\": \"harmonize\"\n },\n {\n \"id\": \"user@example.com\",\n \"providerId\": \"corporate-oidc\"\n }\n ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["corporate-oidc"]}," must match the Keycloak provider alias. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," value must match the identifier produced by your Keycloak mapper design."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"existing-users","__idx":5},"children":["Existing users"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before enabling SSO for existing users:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Confirm each user has the expected ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["loginIds"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check for duplicate aliases or login IDs in the same domain."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check that users with the same public key across domains use consistent identity data."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Confirm each user still has the roles and domain access needed after login."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If existing users are not mapped correctly, authentication can succeed in Keycloak while ","Ripple Custody"," cannot match the token to the expected user."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"session-and-logout-planning","__idx":6},"children":["Session and logout planning"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once Keycloak federates a user, Keycloak becomes the identity provider from the downstream application perspective. Plan these controls in Keycloak:"]},{"$$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":"Control"},"children":["Control"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Why it matters"},"children":["Why it matters"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["SSO session idle and max values"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Bound how long a Keycloak session can remain active."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Concurrent-session controls"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Define how repeat sign-ins should behave for the same federated user."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Logout behavior"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Upstream IdP logout support varies. At minimum, Keycloak can terminate the local session."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Session revocation"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Operators may need to end a user's Keycloak sessions after access changes."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more information, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.38/identity-and-access/sso/keycloak-session-limiting"},"children":["Keycloak session limiting"]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.38/identity-and-access/sso/keycloak-inactivity-timeout"},"children":["Keycloak inactivity timeout"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"interactive-sso-and-service-credentials","__idx":7},"children":["Interactive SSO and service credentials"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Interactive user federation and service-to-service credentials are separate concerns."]},{"$$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":"Credential type"},"children":["Credential type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Use"},"children":["Use"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Federated user login"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Human users authenticate through Keycloak and the external OIDC provider."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Custody API signing"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["State mutation Custody API requests still require Custody signing."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Service-to-service client credentials"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Components or integrations use OAuth2 client credentials where supported by the deployment. Manage these credentials separately from the interactive SSO provider client."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do not reuse an interactive SSO client secret for service-to-service access. Rotate and test each credential path independently."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"rollout-model","__idx":8},"children":["Rollout model"]},{"$$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":"Phase"},"children":["Phase"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Verification"},"children":["Verification"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Prepare"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Keycloak can reach the OIDC discovery document and JWKS endpoint over the expected network path."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Configure"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Provider alias, scopes, client ID, client secret, redirect URI, and mappers are set in the Metaco realm."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Provision"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Custody users have ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["loginIds"]}," matching the provider alias and mapped identifier."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Test"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A test user can log in, repeat login without duplicate users, and access the expected domains."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Operate"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Logs, secret rotation, session controls, and troubleshooting evidence are documented."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For the Keycloak setup procedure, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.38/identity-and-access/sso/keycloak-integration"},"children":["Configure OIDC federation in Keycloak"]},"."]}]},"headings":[{"value":"Plan identity federation","id":"plan-identity-federation","depth":1},{"value":"Planning checklist","id":"planning-checklist","depth":2},{"value":"Identifier design","id":"identifier-design","depth":2},{"value":"Claims, scopes, and access gating","id":"claims-scopes-and-access-gating","depth":2},{"value":"Provider aliases and login IDs","id":"provider-aliases-and-login-ids","depth":2},{"value":"Existing users","id":"existing-users","depth":2},{"value":"Session and logout planning","id":"session-and-logout-planning","depth":2},{"value":"Interactive SSO and service credentials","id":"interactive-sso-and-service-credentials","depth":2},{"value":"Rollout model","id":"rollout-model","depth":2}],"frontmatter":{"seo":{"title":"Plan identity federation"}},"lastModified":"2026-07-27T10:10:43.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/custody/v1.38/identity-and-access/sso/identity-federation-guide","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}