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_URLto the address people use, for examplehttps://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. SetOIDC_ALLOW_UNVERIFIED_EMAIL=trueonly 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:
| Variable | Example | Purpose |
|---|---|---|
OIDC_ISSUER_URL | https://login.example.com/realms/main | The issuer. Setting it turns OIDC on. |
OIDC_CLIENT_ID, OIDC_CLIENT_SECRET | The client registration. | |
OIDC_NAME | SSO | The label of the button on the sign-in page. |
OIDC_SCOPES | openid,email,profile | The scopes requested. |
OIDC_GROUPS_CLAIM | groups | The claim with the group list. |
OIDC_GROUP_MAPPINGS | The 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:
| Variable | Example | Purpose |
|---|---|---|
SAML_METADATA_URL or SAML_METADATA_FILE | The identity provider's metadata. Either one enables SAML. | |
SAML_NAME | SAML | The label of the button. |
SAML_ENTITY_ID | <PUBLIC_URL>/api/v1/auth/saml/metadata | The service provider's entity ID. |
SAML_EMAIL_ATTRIBUTE, SAML_NAME_ATTRIBUTE, SAML_GROUPS_ATTRIBUTE | email, displayName, groups | The attribute names in the assertion. |
SAML_GROUP_MAPPINGS | The same mapping as for OIDC, for the groups attribute. | |
SAML_SP_CERT_FILE, SAML_SP_KEY_FILE | Optional 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_URLdoes 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.