Synadia Platform

Authentication

Controls how users authenticate to Control Plane.

Authentication Configuration

KeyTypeRequiredDescription
methodsMethodsNoMethods that can be used to authenticate.
sessionSessionNoSession configuration.

Methods

KeyTypeRequiredDescription
passwordPasswordNoPassword authentication method configuration.
oidcOIDCNoOpenID Connect (OIDC) authentication method configuration.

Password

KeyTypeRequiredDescription
enabledboolNoEnable or disable password flow. Default is true (enabled).
min_password_lengthintNoMinimum password length. Default is 8.
recovery_flow_lifespandurationNoDuration that invite and password recovery links are good for. Default is 24h.

OIDC

KeyTypeRequiredDescription
providersmap of ID : OIDC ProviderNoOIDC 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.

KeyTypeRequiredDescription
providerenumNoGeneric (default), Google, or Microsoft.
client_idstringyesClient ID.
client_secretstringyesClient Secret.
enabledboolnoEnable or disable OIDC provider. Default is true (enabled).
issuer_urlstringnoIssuer URL.
auth_urlstringnoAuth URL.
token_urlstringnoToken URL.
labelstringnoLabel to display in UI.
scope[]stringnoScope to request, example: ["openid", "email", "profile"].
mapper_schemastringnoJsonnet mapper string to map claims to user.
microsoft_tenantstringnoAzure AD Tenant. Only applies when provider is Microsoft.

Session

KeyTypeRequiredDescription
lifespandurationNoDuration that session is valid for. Default is 24h.
max_lifespandurationNoMaximum duration that session can be extended to if the user remains active within the lifespan. Default is off.
cookieCookieNoSession cookie configuration.
KeyTypeRequiredDescription
namestringNoSession cookie name. Default is control_plane_session.

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,
                },
              },
            }
Previous
Configuration