> ## Documentation Index
> Fetch the complete documentation index at: https://docs.canton.network/llms.txt
> Use this file to discover all available pages before exploring further.

# Networks & identity providers

> Connect the Wallet Gateway to a Canton validator and configure how users authenticate.

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](/integrations/wallet-gateway/operate/configure))
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.

<Warning>
  Use an **OAuth** IDP for production. Self-signed tokens are for development and testing only.
</Warning>

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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
    "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.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
    "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](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md)
  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.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
    "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.

| Method               | Use for                         | Notes                                               |
| -------------------- | ------------------------------- | --------------------------------------------------- |
| `authorization_code` | Interactive, user-facing flows  | Users grant authorization in their browser.         |
| `client_credentials` | Machine-to-machine (production) | Recommended for `adminAuth` and server deployments. |
| `self_signed`        | Development and testing         | The Wallet Gateway signs tokens locally.            |

### authorization\_code

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
    "auth": {
        "method": "authorization_code",
        "audience": "https://canton.network.global",
        "scope": "openid daml_ledger_api offline_access",
        "clientId": "my-client-id"
    }
}
```

### client\_credentials

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
    "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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
    "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"
    }
}
```

<Warning>
  `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](/integrations/wallet-gateway/reference/configuration-reference#secrets-and-environments).
</Warning>

### 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](/integrations/wallet-gateway/reference/user-api) and
[Manage wallets](/integrations/wallet-gateway/use/manage-wallets).