Plan identity federation

Use this page to plan federated identity before configuring Keycloak or updating users.

Planning checklist

Decision	What to define
OIDC provider	The external identity provider, its discovery endpoint, and network connectivity from Keycloak.
Provider alias	A unique lower-case alias in Keycloak. This value must match the `providerId` in Custody user `loginIds`.
User identifier	The claim that uniquely identifies each user. Prefer a stable claim that does not change when an email address changes.
Scopes	Request the claims needed by your mappers. OIDC requires `openid`; `profile` and `email` are commonly needed for username and email claims.
Required claims	Optional claim checks that restrict access to users assigned to the Custody application in your identity provider.
User mapping	Existing Custody users must have `loginIds` that match the identifier Keycloak emits after mapping.
Session policy	Keycloak session lifetimes, concurrent-session controls, and upstream IdP logout behavior.
Secrets	Where client secrets are stored, how they are rotated, and how Keycloak and deployment secrets stay synchronized.
Rollout	Test users, fallback access, operator responsibilities, and production verification.

Identifier design

The most important SSO design choice is the identifier that links the external identity provider to a Custody user.

Choose a claim that is:

Unique for each user.
Stable over time.
Present in every login token.
Available through the scopes configured in Keycloak.

The sub claim is required in OIDC ID tokens. Claims such as email and preferred_username can be useful, but they depend on provider configuration and requested scopes.

Claims, scopes, and access gating

Use scopes and required claims deliberately:

Setting	Guidance
`openid` scope	Required for OIDC identity tokens.
`profile` and `email` scopes	Request only when your mapper design needs profile or email claims. Some identity providers let these scopes be optional instead of granted by default.
Required or essential claim	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.
Mapper claim	Choose the claim that produces the Custody `loginIds.id` value. Avoid claims that are absent, mutable, or not unique.

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.

The Keycloak identity provider alias identifies the upstream provider. The same value is used as the providerId in Custody user records.

{
  "loginIds": [
    {
      "id": "user@example.com",
      "providerId": "harmonize"
    },
    {
      "id": "user@example.com",
      "providerId": "corporate-oidc"
    }
  ]
}

In this example, corporate-oidc must match the Keycloak provider alias. The id value must match the identifier produced by your Keycloak mapper design.

Existing users

Before enabling SSO for existing users:

Confirm each user has the expected loginIds.
Check for duplicate aliases or login IDs in the same domain.
Check that users with the same public key across domains use consistent identity data.
Confirm each user still has the roles and domain access needed after login.

If existing users are not mapped correctly, authentication can succeed in Keycloak while Ripple Custody cannot match the token to the expected user.

Session and logout planning

Once Keycloak federates a user, Keycloak becomes the identity provider from the downstream application perspective. Plan these controls in Keycloak:

Control	Why it matters
SSO session idle and max values	Bound how long a Keycloak session can remain active.
Concurrent-session controls	Define how repeat sign-ins should behave for the same federated user.
Logout behavior	Upstream IdP logout support varies. At minimum, Keycloak can terminate the local session.
Session revocation	Operators may need to end a user's Keycloak sessions after access changes.

For more information, see Keycloak session limiting and Keycloak inactivity timeout.

Interactive SSO and service credentials

Interactive user federation and service-to-service credentials are separate concerns.

Credential type	Use
Federated user login	Human users authenticate through Keycloak and the external OIDC provider.
Custody API signing	State mutation Custody API requests still require Custody signing.
Service-to-service client credentials	Components or integrations use OAuth2 client credentials where supported by the deployment. Manage these credentials separately from the interactive SSO provider client.

Do not reuse an interactive SSO client secret for service-to-service access. Rotate and test each credential path independently.

Rollout model

Phase	Verification
Prepare	Keycloak can reach the OIDC discovery document and JWKS endpoint over the expected network path.
Configure	Provider alias, scopes, client ID, client secret, redirect URI, and mappers are set in the Metaco realm.
Provision	Custody users have `loginIds` matching the provider alias and mapped identifier.
Test	A test user can log in, repeat login without duplicate users, and access the expected domains.
Operate	Logs, secret rotation, session controls, and troubleshooting evidence are documented.

For the Keycloak setup procedure, see Configure OIDC federation in Keycloak.