Documentation/canton-network-docs/Wallet GatewaySet up & operateView on canton-network-docs ↗
canton-network-docs/Wallet GatewaySet up & operate

Networks & identity providers

A Wallet Gateway connects users to one or more networks. Each network points at a Canton validator’s Ledger API and references an identity provider (IDP) that issues the JWT used to authenticate against that validator. This guide covers both, plus the authentication methods a network can use. Networks and IDPs are seeded from the bootstrap section on first run. After that, the admin user (see server.admin in Configure the Wallet Gateway) can manage them at runtime through the User API or User UI.

​
Identity providers

Every network references an IDP by id. The Wallet Gateway supports two IDP types.
Use an OAuth IDP for production. Self-signed tokens are for development and testing only.

​
OAuth / OpenID Connect

Integrates with an external OAuth 2.0 / OpenID Connect provider to obtain tokens.
  • id (required): must match the identityProviderId referenced by networks.
  • type (required): "oauth".
  • issuer (required): the iss claim value, matching your provider’s configuration.
  • configUrl (required): the OpenID Connect discovery endpoint, typically ${OAuthServerURL}/.well-known/openid-configuration.
{
    "bootstrap": {
        "idps": [
            {
                "id": "idp-production",
                "type": "oauth",
                "issuer": "https://auth.example.com",
                "configUrl": "https://auth.example.com/.well-known/openid-configuration"
            }
        ]
    }
}

​
Self-signed

Generates JWTs locally using a secret. Convenient for development, not for production.
  • id (required): must match the identityProviderId referenced by networks.
  • type (required): "self_signed".
  • issuer (required): the iss claim value, matching what the validator expects.
{
    "bootstrap": {
        "idps": [
            {
                "id": "idp-self-signed",
                "type": "self_signed",
                "issuer": "self-signed"
            }
        ]
    }
}

​
Identity Provider Management in the Wallet Gateway

This guide is only for parties with administrator access.
  1. Select the hamburger icon on the top right and click Identity Provider.
  2. Review the list of available identity providers.
  3. To add: click on + New to add a new identify provider.
  4. To edit: click on an identity provider card to make changes or delete it permanently.

​
Networks

A network represents a Canton validator that users can reach through the Wallet Gateway. networks is an array, so you can configure several in one Wallet Gateway.
  • id (required): unique identifier in CAIP-2 form, for example "canton:localnet".
  • name (required): a user-friendly name shown in the UI.
  • description (optional): a description shown to users.
  • synchronizerId (required): the synchronizer ID used on the validator. For multiple synchronizers, configure a separate network per synchronizer.
  • identityProviderId (required): must match the id of a configured IDP.
  • ledgerApi.baseUrl (required): the base URL of the validator’s Ledger API.
  • auth (required): authentication for normal ledger operations. This is the method users go through in the UI.
  • adminAuth (optional): authentication for admin operations, used by the backend only.
{
    "bootstrap": {
        "networks": [
            {
                "id": "canton:localnet",
                "name": "Local Network",
                "description": "Local development network",
                "synchronizerId": "local",
                "identityProviderId": "idp-self-signed",
                "auth": {
                    "method": "self_signed",
                    "issuer": "self-signed",
                    "audience": "https://canton.network.global",
                    "scope": "openid daml_ledger_api offline_access",
                    "clientId": "ledger-api-user",
                    "clientSecret": "unsafe"
                },
                "ledgerApi": {
                    "baseUrl": "http://localhost:2975"
                }
            }
        ]
    }
}

​
Authentication methods

A network’s auth (and optional adminAuth) uses one of three methods.
MethodUse forNotes
authorization_codeInteractive, user-facing flowsUsers grant authorization in their browser.
client_credentialsMachine-to-machine (production)Recommended for adminAuth and server deployments.
self_signedDevelopment and testingThe Wallet Gateway signs tokens locally.

​
authorization_code

{
    "auth": {
        "method": "authorization_code",
        "audience": "https://canton.network.global",
        "scope": "openid daml_ledger_api offline_access",
        "clientId": "my-client-id"
    }
}

​
client_credentials

{
    "auth": {
        "method": "client_credentials",
        "audience": "https://canton.network.global",
        "scope": "openid daml_ledger_api offline_access",
        "clientId": "my-service-client",
        "clientSecret": "my-secure-secret"
    }
}

​
self_signed

{
    "auth": {
        "method": "self_signed",
        "issuer": "self-signed",
        "audience": "https://canton.network.global",
        "scope": "openid daml_ledger_api offline_access",
        "clientId": "ledger-api-user",
        "clientSecret": "unsafe-secret-for-development"
    }
}
clientSecret and adminAuth credentials are sensitive. Keep them out of version control and supply them through environment variables or a secret manager. See the Configuration reference.

​
Network Management in the Wallet Gateway

This guide is only for parties with administrator access.
  1. Select the hamburger icon on the top right and choose Network.
  2. Review the list of available networks.
  3. To add: click on + New to add a new network.
  4. To edit: click on a network card to make changes or delete it permanently.
  5. The connected network can be reviewed at the top of the pop-up showing a green dot: [network name] or in the network list with a green Connected tag.

​
Runtime management

Once the Wallet Gateway is running, the admin user can add, edit, and remove networks and IDPs without restarting, using the User API (addNetwork, removeNetwork, addIdp, removeIdp, listNetworks, listIdps) or the Settings page in the User UI. Runtime changes are stored in the database, so back it up to avoid losing them. See the User API and Manage wallets.