Skip to main content

Single sign-on

The server can sign people in through an OpenID Connect (OIDC) or a SAML identity provider. Both can be enabled at the same time, and each adds a button to the sign-in page. Passwords can stay on, or be turned off so that only the provider works.

Single sign-on is configured with environment variables, not on the Settings page.

Before you start​

  • Set PUBLIC_URL to the address people use, for example https://vop.example.com. Both providers redirect back to addresses built from it.
  • Set the provider to send a verified e-mail address. The server refuses a sign-in whose token says email_verified: false. Set OIDC_ALLOW_UNVERIFIED_EMAIL=true only when your provider cannot verify e-mail addresses.
  • Decide which groups give which roles. See Users, roles and scopes.

OpenID Connect​

Register an OIDC client at your provider with this redirect URI:

<PUBLIC_URL>/api/v1/auth/oidc/callback

Then set:

VariableExamplePurpose
OIDC_ISSUER_URLhttps://login.example.com/realms/mainThe issuer. Setting it turns OIDC on.
OIDC_CLIENT_ID, OIDC_CLIENT_SECRETThe client registration.
OIDC_NAMESSOThe label of the button on the sign-in page.
OIDC_SCOPESopenid,email,profileThe scopes requested.
OIDC_GROUPS_CLAIMgroupsThe claim with the group list.
OIDC_GROUP_MAPPINGSThe JSON list that maps groups to roles and scopes.

SAML​

Register the service provider at your identity provider with these addresses:

  • Assertion consumer service (HTTP-POST): <PUBLIC_URL>/api/v1/auth/saml/acs
  • Service provider metadata: <PUBLIC_URL>/api/v1/auth/saml/metadata

Then give the identity provider's metadata, by URL or by file, and set the attribute names the provider uses:

VariableExamplePurpose
SAML_METADATA_URL or SAML_METADATA_FILEThe identity provider's metadata. Either one enables SAML.
SAML_NAMESAMLThe label of the button.
SAML_ENTITY_ID<PUBLIC_URL>/api/v1/auth/saml/metadataThe service provider's entity ID.
SAML_EMAIL_ATTRIBUTE, SAML_NAME_ATTRIBUTE, SAML_GROUPS_ATTRIBUTEemail, displayName, groupsThe attribute names in the assertion.
SAML_GROUP_MAPPINGSThe same mapping as for OIDC, for the groups attribute.
SAML_SP_CERT_FILE, SAML_SP_KEY_FILEOptional PEM certificate and key that sign the sign-in requests.

Group mappings​

The mapping is a JSON list. Each entry names a group, the roles it grants, and the clusters or nodes it can see. An entry with "all": true gives every cluster and node.

[
{"group": "vop-admins", "roles": ["admin"], "all": true},
{"group": "vop-prod-viewers", "roles": ["viewer"], "clusters": ["prod"]}
]

When mappings are configured, a user in none of the mapped groups cannot sign in. Roles and scope are read again at every sign-in, so removing someone from a group takes effect at their next sign-in.

Turn off passwords​

Set AUTH_PASSWORD_LOGIN=false once the provider works, so that the sign-in page sends people straight to it. Keep at least one administrator who can sign in another way, for example by turning the setting back on, until you have tested the provider with an administrator account.

Errors during sign-in​

The provider sends the user back to the sign-in page with an error. Common causes:

  • the redirect URI or the assertion consumer address differs from the one registered at the provider, including the scheme and the port;
  • PUBLIC_URL does not match the address the user typed;
  • the e-mail address is not verified at the provider;
  • the user is in no mapped group.

The state of a sign-in lives in Redis for ten minutes, so a sign-in that takes longer than that must be started again. Any replica can finish a sign-in that another one started.