# 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.


```mermaid
flowchart LR
    Claims["OIDC claims from IdP"] --> Mappers["Keycloak provider mappers"]
    Mappers --> Token["Keycloak-issued token"]
    Token --> LoginId["Custody loginId lookup"]
    LoginId --> User["Custody user record"]
```

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.

## Provider aliases and login IDs

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


```json
{
  "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](/products/custody/identity-and-access/sso/keycloak-session-limiting) and [Keycloak inactivity timeout](/products/custody/identity-and-access/sso/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](/products/custody/identity-and-access/sso/keycloak-integration).