Okta and Keycloak OIDC Configuration Guide

To deploy a validator node, configure authentication using your preferred OIDC provider. This section provides instructions for Okta and Keycloak. For Auth0 instructions and more details on configuring authentication, see Configuring Authentication.

Okta

Follow these steps to configure Okta as your validator’s OIDC provider:

1. Create an application for the validator app backend.

   1. Navigate to “Admin Panel > Applications > Applications”, and click “Create App Integration”.

   2. Choose “API Services” as the sign-in method (not OIDC).

   3. For “App integration name”, enter Validator app backend.

   4. In General Settings, uncheck “Proof of possession”.

   5. Click “Save” and copy the “Client ID” and “Client Secret”.

2. Create an application for the wallet web UI.

   1. Navigate to “Admin Panel > Applications > Applications”, and click “Create App Integration”.

   2. Choose “OIDC” as the sign-in method then “Single-Page Application” as the application type.

   3. For “App integration name”, enter Wallet web UI.

      • In “Sign-in redirect URIs”, enter your wallet UI URL: https://wallet.validator.YOUR_HOSTNAME

      • In “Sign-out redirect URIs”, enter your wallet UI URL: https://wallet.validator.YOUR_HOSTNAME

      • In “Trusted Origins/Base URIs”, enter your wallet UI URL: https://wallet.validator.YOUR_HOSTNAME

   4. Assign the app to the groups you want to have access to it.

   5. Click “Save” and copy the “Client ID”.

3. Create an application for the CNS web UI.

   1. Navigate to “Admin Panel > Applications > Applications”, and click “Create App Integration”.

   2. Choose “OIDC” as the sign-in method then “Single-Page Application” as the application type.

   3. For “App integration name”, enter CNS web UI.

      • In “Sign-in redirect URIs”, enter your CNS UI URL : https://cns.validator.YOUR_HOSTNAME

      • In “Sign-out redirect URIs”, enter your CNS UI URL : https://cns.validator.YOUR_HOSTNAME

      • In “Trusted Origins/Base URIs”, enter your CNS UI URL : https://cns.validator.YOUR_HOSTNAME

   4. Assign the app to the groups you want to have access to it.

   5. Click “Save” and copy the “Client ID”.

4. Create a client for a custom audience (optional)

   1. If you want other applications to access the ledger API, create an additional client by following steps 1–3.

5. Create a custom Authorization server per validator/environment

   1. Navigate to “Admin Panel > Directory > Groups”, click “Add Group” and name the group “canton_wallet_admin”.

   2. Add another group “canton_all.”

   3. Navigate to “Admin Panel > Security > API”

   4. In the “Authorization Servers” tab, click “Add Authorization Server”. Define a name and audience. Note that the authorization server is used for the M2M flow and must be different for each environment/validator for security reasons.

   5. In the “Scopes” tab, add a custom scope named daml_ledger_api and click “Set as a default scope”.

   6. In the “Claims” tab, change the “sub” value to “app.clientId”. If the default value is kept, it uses the user email, which requires formatting in values.yaml as ‘ “ email.address@domain “ ‘, without the spaces. This is necessary until the Helm chart is updated to properly quote them.

   7. In the “Access Policies” tab, create one policy for each of the three applications.

      • Name: Validator app backend

      • Assigned to : Validator app backend created in step #1

      • Click “Add rule.” Enter a “Rule Name” and check “Any user assigned the app” next to “User is” to define a rule that matches any user assigned to the app. Click “Create rule.”

      • Name: Wallet web UI

      • Assigned to: Wallet web UI created in step #2

      • Click “Add rule.” Enter a “Rule Name” and check “Assigned the app and a member of one of the following” next to “User is.” Add the group “canton_wallet_admin” to define a rule that matches the group. Click “Create rule.”

      • Name: CNS web UI

      • Assigned to: CNS web UI created in step #3

      • Click “Add rule.” Enter a “Rule Name” and check “Assigned the app and a member of one of the following” next to “User is.” Add the group “canton_all” to define a rule that matches the group. Click “Create rule.”

Keycloak

Follow these steps to configure Keycloak as your validator’s OIDC provider:

1. Create a realm

   1. Navigate to “Admin Panel > Manage realms”, click “Create realm”, and enter a realm name.

2. Create a client for the Ledger API

   1. Navigate to “Admin Panel > Clients” and click “Create client”.

   2. Set the client type to “OpenID Connect”, enter ledger-api as the client ID, and click “Next”.

   3. In the “Capability config”, uncheck all fields and click “Next”.

   4. In the “Login settings”, leave the “Valid redirect URIs” and “Web origins” fields blank, then click “Save”.

   5. Navigate to the “Admin Panel > Client scopes” tab and click “Create client scope”.

   6. Enter daml_ledger_api as the name and select the type “Default”.

   7. In the “Mappers” tab, click “Configure a new mapper”.

   8. Select “User Client Role” as the mapper type and name it daml_ledger_api_scope. Enable “Add to Access Token” and disable all the other options, such as “Add to ID token”, “Add to userinfo”, and “Add to token introspection”. Click “Save”.

   9. To add this scope to the ledger-api client, navigate to “Admin Panel > Clients > ledger_api > Client scopes” and click “Add client scope”. Select daml_ledger_api and click “Add” with the type “Default”.

   10. Navigate to “Admin Panel > Realm Settings > Sessions”, and ensure that “Offline Session Max Limited” is enabled with a sufficient value for “Offline Session Max.” This enables refresh tokens, similar to “Allow Offline Access” in Auth0. Click “Save”.

3. Create a client for a custom audience (optional)

   1. If your backend services require a different audience, create another client with the “Client ID” set to validator-app-api (e.g., https://validator.example.com/api), and optionally define custom client scopes as described in step #2 to distinguish this API.

4. Create a client for the validator app backend.

   1. Navigate to “Admin Panel > Clients” and click “Create client”.

   2. Set the client type to “OpenID Connect”, enter validator-app-backend as the client ID, and click “Next”.

   3. In the “Capability config”, only check “Client authentication” and “Service accounts”. Click “Next”.

   4. In the “Login settings”, leave the “Valid redirect URIs” and “Web origins” fields blank, then click “Save”.

   5. Copy the “Client ID” from the “Settings” tab and “Client Secret” from the “Credentials” tab. The Client ID in Keycloak is the name assigned to the client at creation (validator-app-backend).

5. Create a client for the wallet web UI.

   1. Navigate to “Admin Panel > Clients” and click “Create client”.

   2. Set the client type to “OpenID Connect”, enter wallet-web-ui as the client ID, and click “Next”.

   3. In the “Capability config”, only check “Standard flow” and click “Next”.

   4. In the “Login settings”, set:

      • “Valid redirect URIs” to: https://wallet.validator.YOUR_HOSTNAME/*

      • “Valid post logout redirect URIs” to: https://wallet.validator.YOUR_HOSTNAME

      • “Web origins” to: https://wallet.validator.YOUR_HOSTNAME

      • Click Save.

   5. Copy the “Client ID” from the “Settings” tab (wallet-web-ui).

6. Create a client for the CNS web UI.

   1. Follow the same steps as for the wallet web UI, using cns-ui as the “Client ID”, setting:

      • “Valid redirect URIs” to: https://cns.validator.YOUR_HOSTNAME/*

      • “Valid post logout redirect URIs” to: https://cns.validator.YOUR_HOSTNAME

      • “Web origins” to: https://cns.validator.YOUR_HOSTNAME

   2. Copy the “Client ID” from the “Settings” tab (cns-ui).

Comments