Identity providers

An identity provider signs users in; DIAL Core verifies the tokens it issues and reads each user's ID, roles, and project from their claims. These static settings register one or more identity providers under identityProviders.<name>. This reference is for platform engineers who connect Core to an OIDC provider; per-provider setup guides are in SSO and identity providers.

At least one identity provider must be configured. Each provider needs either jwksUrl or userInfoEndpoint, unless JWT verification is turned off.

Settings

Setting	Default	Description
`identityProviders.<name>.jwksUrl`	—	The URL of the provider's JWKS endpoint. Required when JWT verification is on.
`identityProviders.<name>.userInfoEndpoint`	—	The URL of the provider's user info endpoint, for providers whose tokens Core cannot verify with JWKS, such as Google. Must be unset when `disableJwtVerification` is `true`.
`identityProviders.<name>.rolePath`	—	Required. The path or paths to the roles claim in the token or user info response, for example `roles` or `resource_access.chatbot-ui.roles`. A string or an array of strings.
`identityProviders.<name>.rolesDelimiter`	—	The delimiter that splits roles when the claim is a single string, for example `" "`.
`identityProviders.<name>.projectPath`	—	The path to the claim that holds the project name, for example `azp`, `aud`, or `some.path.client`.
`identityProviders.<name>.userIdPath`	`sub`	The path to the claim that holds the user ID. It differs by provider; Microsoft Entra ID uses `oid`.
`identityProviders.<name>.userDisplayName`	—	The path to the claim that holds the user's display name. `GET /v1/user/info` returns it as `userDisplayName`.
`identityProviders.<name>.loggingKey`	—	The claim that identifies the user in logs. `email` or `sub` is usually enough; some providers do not issue `email`.
`identityProviders.<name>.loggingSalt`	—	The salt used to hash the `loggingKey` value in logs.
`identityProviders.<name>.issuerPattern`	—	A regular expression matched against the token's `iss` claim to pick this provider.
`identityProviders.<name>.audience`	—	When set, Core checks it against the token's `aud` claim.
`identityProviders.<name>.disableJwtVerification`	`false`	Turns off JWT verification. For local evaluation only.
`identityProviders.<name>.positiveCacheExpirationMs`	`600000`	How long a successful JWKS response stays cached, in milliseconds.
`identityProviders.<name>.negativeCacheExpirationMs`	`10000`	How long a failed JWKS response stays cached, in milliseconds.
`identityProviders.<name>.offlineClient`	—	The OAuth client Core uses to get a user's platform-wide offline credentials for `DIAL_NATIVE` external services (`/v1/user/offline-credentials`). See Offline client.
`printAuthorizationHeader`	`false`	Logs the raw `Authorization` header at `DEBUG` level for each request, to debug identity provider setup.

warning

printAuthorizationHeader writes tokens to the log. Do not turn it on in production.

JWKS requests go through client.proxyOptions when an outbound proxy is configured. See Server and client.

Offline client

offlineClient is an object with these fields:

Field	Required	Description
`clientId`	Yes	The OAuth client ID.
`tokenEndpoint`	Yes	The provider's token endpoint.
`authorizationEndpoint`	Yes	The provider's authorization endpoint.
`clientSecret`	No	The client secret.
`redirectUri`	No	The redirect URI.
`scopes`	No	The requested scopes. Default `["openid", "offline_access"]`.

issuerPattern must also match the issuer of the ID tokens this client mints. On Microsoft Entra ID, v1 access tokens (sts.windows.net/...) and v2 ID tokens (login.microsoftonline.com/.../v2.0) carry different issuers, and a pattern that covers only one of them breaks the later credential refresh.

DIAL Scheduler depends on these credentials. For a DIAL_NATIVE service, Core's on-behalf-of operation redeems the user's offline credentials, so scheduled tasks can run while the user is away. See Register Scheduler in DIAL.

Examples

Local evaluation

From dial-docker-compose/settings/settings.json. Any JWT-formatted token is accepted without signature verification:

{
  "identityProviders": {
    "test": {
      "rolePath": "roles",
      "disableJwtVerification": true
    }
  }
}

Keycloak

{
  "identityProviders": {
    "keycloak": {
      "jwksUrl": "http://keycloak:8180/realms/dial/protocol/openid-connect/certs",
      "rolePath": "roles",
      "issuerPattern": "http://keycloak:8180/realms/dial",
      "loggingKey": "email",
      "loggingSalt": "<RANDOM_SALT>"
    }
  }
}

Several providers

Core picks the provider whose issuerPattern matches the token's iss claim:

{
  "identityProviders": {
    "internal": {
      "jwksUrl": "http://keycloak:8180/realms/dial/protocol/openid-connect/certs",
      "rolePath": "roles",
      "issuerPattern": "http://keycloak:8180/realms/dial"
    },
    "entra": {
      "jwksUrl": "https://login.microsoftonline.com/<TENANT_ID>/discovery/v2.0/keys",
      "rolePath": "roles",
      "issuerPattern": "https://login.microsoftonline.com/.*",
      "userIdPath": "oid"
    }
  }
}

Settings​

Offline client​

Examples​

Local evaluation​

Keycloak​

Several providers​

Further reading​