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.
- OIDC federation changes how users authenticate; it does not replace Custody authorization or signature requirements.
- The Keycloak provider alias must match the provider ID used in the user's
loginIds. - Mapper configuration determines the user identifier that Ripple Custody receives in the Keycloak-issued token.
- Session lifetime, session limiting, and logout behavior are controlled by Keycloak and your upstream identity provider configuration.
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.
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.
The exact screens depend on your identity provider, but the control points are consistent.
| Flow | Checkpoint | What to verify |
|---|---|---|
| Login | Browser redirects to Keycloak. | The Keycloak issuer, callback URL, TLS certificate, and realm endpoint are reachable. |
| Login | Keycloak redirects to the upstream OIDC provider. | The provider discovery document, client ID, redirect URI, scopes, and required claims are correct. |
| Login | Keycloak exchanges the authorization code server-side. | Keycloak can reach the provider token endpoint, validate TLS, and authenticate with the configured client secret. |
| Login | Ripple Custody receives a Keycloak-issued token. | The token subject, issuer, audience, and mapped login ID match the Custody user. |
| Logout | The local application session is cleared. | The user can no longer call protected UI routes with the old browser session. |
| Logout | Keycloak token/session state is revoked or expired. | Token revocation and session lifetime settings match your security requirements. |
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.
| Area | What SSO controls | What stays in Ripple Custody |
|---|---|---|
| Authentication | How a user signs in through an external identity provider. | API authentication and signing still follow the documented Custody flows. |
| User identity | Which external identifier maps to a Custody user login ID. | User records, roles, domains, and public keys. |
| Authorization | Nothing by itself. | Custody authorization and signature requirements remain separate from federation. |
| Session behavior | Keycloak and upstream IdP session lifetimes, session limits, and logout behavior. | Custody intent lifecycle and approval state. |
| Task | Start here |
|---|---|
| Plan an SSO rollout | Plan identity federation |
| Configure an OIDC provider in Keycloak | Configure OIDC federation in Keycloak |
| Limit concurrent Keycloak sessions | Keycloak session limiting |
| Configure frontend inactivity logout | Keycloak inactivity timeout |
| Investigate SSO login failures | Troubleshoot SSO |
| Review deployment configuration areas | Keycloak configuration |
Use OpenID Connect for federated identity. The public SSO documentation covers OIDC federation through Keycloak. SAML federation is not covered in this section.
When troubleshooting SSO with Ripple or an identity-provider vendor, share only the information needed to prove the failure point:
- Discovery document reachability.
- Non-secret client settings, such as redirect URI, scopes, issuer, and provider alias.
- Decoded token headers and claims with secrets, signatures, and personal data removed.
- Keycloak and application log snippets with tokens and secrets redacted.
Do not share client secrets, private keys, full JWTs, or unredacted identity data in tickets or chat.