Authentication

Controls how users authenticate to Control Plane.

Authentication Configuration

Key	Type	Required	Description
`methods`	Methods	No	Methods that can be used to authenticate.
`session`	Session	No	Session configuration.
`rate_limit`	Rate Limit	No	Control rate limit settings to all `/auth` endpoints. Available since 1.4.1
`recover_admin_user`	bool	No	Prints a recovery link to access the admin user in the logs on startup. Default is `false`. Available since 1.4.2

Methods

Key	Type	Required	Description
`password`	Password	No	Password authentication method configuration.
`oidc`	OIDC	No	OpenID Connect (OIDC) authentication method configuration.

Password

Key	Type	Required	Description
`enabled`	bool	No	Enable or disable password flow. Default is `true` (enabled).
`min_password_length`	int	No	Minimum password length. Default is `8`.
`recovery_flow_lifespan`	duration	No	Duration that invite and password recovery links are good for. Default is `24h`.

OIDC

Key	Type	Required	Description
`providers`	map of `ID` : OIDC Provider	No	OIDC Provider configuration. Map key is a user-specified ID of the provider, this should not be changed after the provider is in use.

OIDC Provider

Settings for an Open ID Connect (OIDC) Authorization Code flow provider.

Key	Type	Required	Description
`provider`	enum	No	`Generic` (default), `Google`, or `Microsoft`.
`client_id`	string	yes	Client ID.
`client_secret`	string	yes	Client Secret.
`enabled`	bool	no	Enable or disable OIDC provider. Default is `true` (enabled).
`issuer_url`	string	no	Issuer URL.
`auth_url`	string	no	Auth URL.
`token_url`	string	no	Token URL.
`label`	string	no	Label to display in UI.
`scope`	[]string	no	Scope to request, example: `["openid", "email", "profile"]`.
`mapper_schema`	string	no	Jsonnet mapper string to map claims to user.
`microsoft_tenant`	string	no	Azure AD Tenant. Only applies when provider is `Microsoft`.

Session

Key	Type	Required	Description
`lifespan`	duration	No	Duration that session is valid for. Default is `24h`.
`max_lifespan`	duration	No	Maximum duration that session can be extended to if the user remains active within the `lifespan`. Default is off. Available since 1.4.0
`privileged_lifespan`	duration	No	Duration after authenticating where a user can perform a privileged action, such as resetting their password. Default is `5m`. Available since 1.4.1
`cookie`	Cookie	No	Session cookie configuration.

Key	Type	Required	Description
`name`	string	No	Session cookie name. Default is `control_plane_session`.

Rate Limit

Key	Type	Required	Description
`request_limit`	int	No	Number of requests to allow per IP address over the `window_length_seconds`. Defaults to `200`
`window_length_seconds`	int	No	Amount of time in seconds to apply the `request_limit` over. Defaults to `60`

OpenID Connect

Redirect URI

When setting up an OpenID Connect provider, use the Authorization Code flow. The Redirect URI should be:

http(s)://<control-plane-url>/auth/self-service/methods/oidc/callback/<provider-id>

Claims Mapping

Control Plane requires mapping 2 claims using Jsonnet in the mapper_schema field for the OIDC provider. The claims that should be mapped are:

username: Unique user identifier claim, typically a Username, Email Address, or Common Name
name: Full name claim

For example, if your OIDC provider returns an email and a name claim, the mapper_schema would be:

local claims = std.extVar('claims');
{
  identity: {
    traits: {
      username: claims.email,
      name: name,
    },
  },
}

Mapping OIDC Users to App Roles

When using OIDC you may want to set a default App Role for a specific user. This is useful when bootstrapping OIDC in order to upgrade the first user to an Administrator. Example:

authorization:
  user_app_role_mapping:
    admin@example.com: Admin
    ops@example.com: Admin

Google Example

In this example, the provider ID is google because the provider is specified at authentication.methods.oidc.providers.google. When setting up the Google OAuth application, use http(s)://<control-plane-url>/auth/self-service/methods/oidc/callback/google as the Redirect URI.

authentication:
  methods:
    oidc:
      providers:
        google:
          provider: Google
          label: Google
          client_id: your-client-id
          client_secret: your-client-secret
          scope:
            - openid
            - email
            - profile
          mapper_schema: |
            local claims = std.extVar('claims');
            {
              identity: {
                traits: {
                  [if claims.email_verified then 'username' else null]: claims.email,
                  name: claims.given_name + " " + claims.family_name,
                },
              },
            }

Microsoft AAD Example

In this example, the provider ID is microsoft because the provider is specified at authentication.methods.oidc.providers.microsoft. When setting up the Microsoft Azure Active Directory application, use http(s)://<control-plane-url>/auth/self-service/methods/oidc/callback/microsoft as the Redirect URI.

authentication:
  methods:
    oidc:
      providers:
        microsoft:
          provider: Microsoft
          label: Microsoft
          client_id: your-client-id
          client_secret: your-client-secret
          microsoft_tenant: your-microsoft-aad-tenant
          scope:
            - openid
            - email
            - profile
          mapper_schema: |
            local claims = std.extVar('claims');
            {
              identity: {
                traits: {
                  username: claims.preferred_username,
                  name: claims.name,
                },
              },
            }