> For the complete documentation index, see [llms.txt](https://docs.catalyx.solutions/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.catalyx.solutions/catalyx-blockchain-manager/canton-network/version-2.0/installation-instructions-canton/identity-provider-configuration/external-identity-provider.md).

# External Identity Provider

With `spec.auth.managedKeycloak: false` — the default — you create the OIDC objects yourself and reference them from the `Validator` resource. This works with any OIDC-compliant identity provider, including Okta, Microsoft Entra ID, Auth0, and Ping Identity.

## What to create in your identity provider

<table><thead><tr><th width="230">Object</th><th width="140">Type</th><th>Used by</th></tr></thead><tbody><tr><td>Wallet UI client</td><td>Public</td><td>The Canton Wallet web UI. Needs a redirect URI of <code>https://wallet-&#x3C;validator-name>.&#x3C;baseHostname>/*</code> and the matching web origin.</td></tr><tr><td>CNS UI client</td><td>Public</td><td>The Canton Name Service web UI. Redirect URI <code>https://cns-&#x3C;validator-name>.&#x3C;baseHostname>/*</code>.</td></tr><tr><td>Backend client</td><td>Confidential</td><td>The validator app, PQS, and the Wallet Gateway, for machine-to-machine access to the Ledger API. Needs the client credentials grant enabled.</td></tr><tr><td>Wallet Gateway client</td><td>Public</td><td>Only when the Wallet Gateway is enabled. Redirect URI <code>https://wallet-gateway-&#x3C;validator-name>.&#x3C;baseHostname>/*</code>.</td></tr><tr><td>Participant admin user</td><td>User</td><td>The Canton participant's admin user identity.</td></tr><tr><td>Wallet user</td><td>User</td><td>The user the validator app treats as the wallet owner.</td></tr></tbody></table>

Every token issued to these clients must carry the audience you configure as `spec.auth.targetAudience`. Add an audience mapper or equivalent to each client.

## Store the backend client secret

```bash
kubectl create secret generic my-validator-ledger-api-auth \
  --from-literal=client-secret=<backend-client-secret> \
  -n catalyx-system
```

***

## Configuration

```yaml
spec:
  auth:
    enabled: true
    managedKeycloak: false

    authUrl: https://idp.example.com/realms/canton
    jwksUrl: https://idp.example.com/realms/canton/protocol/openid-connect/certs
    targetAudience: https://canton.network.global
    ledgerApiUserManagementScope: daml_ledger_api

    ledgerApiUser: participant-admin
    walletUserName: wallet-user

    ledgerApiClientId: my-validator-backend
    walletUiClientId: my-validator-wallet-ui
    cnsUiClientId: my-validator-cns-ui
    ledgerApiClientSecretRef:
      name: my-validator-ledger-api-auth
      key: client-secret
```

### Field reference

<table><thead><tr><th width="330">Field</th><th>Purpose</th></tr></thead><tbody><tr><td><code>authUrl</code></td><td>OIDC issuer URL. Used by the UIs, and by the validator app, PQS, and Wallet Gateway to obtain tokens. Either an issuer URL or a token endpoint is accepted — an issuer URL is discovered via <code>.well-known/openid-configuration</code>.</td></tr><tr><td><code>jwksUrl</code></td><td>JWKS endpoint the participant and validator app verify tokens against.</td></tr><tr><td><code>targetAudience</code></td><td>The audience every token must carry.</td></tr><tr><td><code>ledgerApiUserManagementScope</code></td><td>The OAuth scope that grants Ledger API user-management rights.</td></tr><tr><td><code>ledgerApiUser</code></td><td>The participant's admin user name.</td></tr><tr><td><code>walletUserName</code></td><td>The wallet owner's user name.</td></tr><tr><td><code>ledgerApiClientId</code></td><td>The confidential backend client ID.</td></tr><tr><td><code>walletUiClientId</code> / <code>cnsUiClientId</code></td><td>The public client IDs for the two web UIs.</td></tr><tr><td><code>walletGatewayClientId</code></td><td>The public client ID for the Wallet Gateway. Required only when the Wallet Gateway is enabled.</td></tr><tr><td><code>ledgerApiClientSecretRef</code></td><td>Secret holding the backend client secret. <code>key</code> defaults to <code>client-secret</code>.</td></tr></tbody></table>

{% hint style="warning" %}
None of these fields is marked required in the CRD schema, so a `Validator` missing them will be **accepted** by the API server and then fail during reconciliation. The `Ready` condition will report `InvalidSpec` with the name of the missing field. Check the condition after applying.
{% endhint %}

{% hint style="info" %}
The `walletGatewayClientId` field cannot currently be set through the `catalyx-canton-validator` Helm chart. If you use that chart and need the Wallet Gateway with an external identity provider, apply the `Validator` resource directly instead.
{% endhint %}

***

## Verifying

Open the validator's [Identity](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/validators/identity-and-endpoints.md) tab in the console. It shows `Managed Keycloak: External`, the resolved auth URL, the target audience, and each client ID — a quick way to confirm the values reached the components.

If tokens are being rejected, the usual causes are:

* the audience mapper is missing on one of the clients, so `targetAudience` does not match;
* the redirect URI registered on a public client does not match the hostname the operator generated from `operatorRuntime.baseHostname`;
* the client credentials grant is not enabled on the backend client.

***

## Disabling authentication

`spec.auth.enabled: false` disables authentication on the participant entirely.

{% hint style="danger" %}
Never do this outside a local development cluster. It leaves the Ledger API open to anyone who can reach it.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.catalyx.solutions/catalyx-blockchain-manager/canton-network/version-2.0/installation-instructions-canton/identity-provider-configuration/external-identity-provider.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.