Skip to main content

OIDC (OpenID Connect)

Single Sign-On with OIDC​

PLANKA can be configured to use an OIDC (OpenID Connect) provider for authentication. When a user logs in via OIDC:

  • If the user doesn't exist in PLANKA, an account will be automatically created.
  • If the user already exists and their email claim matches the email stored in PLANKA, the accounts will be linked.

Required Configuration Values​

  • OIDC_ISSUER: The URL pointing to your identity provider. This URL is used to retrieve the .well-known/openid-configuration endpoint which helps to identify the necessary endpoints.
  • OIDC_CLIENT_ID: The OAuth client ID created within the identity provider.
  • OIDC_CLIENT_SECRET: The OAuth client secret created within the identity provider.

Optional Configuration Values​

  • OIDC_SCOPES: Scopes to request from the identity provider. This controls what data the OAuth client can access. PLANKA requires access to the email and name claims. By default, it requests openid profile email.
  • OIDC_ADMIN_ROLES: The role claim used to determine if a user is an admin. By default, the admin role is checked.
  • OIDC_CLAIMS_SOURCE: Determines whether the claims are sourced from the id_token or userinfo. By default, it is set to userinfo.
  • OIDC_EMAIL_ATTRIBUTE: The claim that contains the email. By default, it is email.
  • OIDC_NAME_ATTRIBUTE: The claim that contains the user's name. By default, it is name.
  • OIDC_USERNAME_ATTRIBUTE: The claim containing the username. By default, it is preferred_username.
  • OIDC_ROLES_ATTRIBUTE: The claim containing the roles used to identify an admin. By default, it is groups.
  • OIDC_IGNORE_USERNAME: If set to true, the OIDC_USERNAME_ATTRIBUTE will be ignored. This is useful if the format of usernames in your identity provider differs from PLANKA. By default, it is not ignored.
  • OIDC_IGNORE_ROLES: If set to true, the OIDC_ADMIN_ROLES and OIDC_ROLES_ATTRIBUTE will be ignored. This is useful if you wish to use OIDC only for authentication and not authorization, in which case user roles will be managed by PLANKA. By default, it is not ignored.
  • OIDC_ENFORCED: If set to true, all built-in authentication/authorization will be disabled. By default, it is not enforced.

Examples​

Authentik​

Below is an example configuration for using Authentik as an OIDC provider. This configuration will work with any OIDC provider.

OIDC_ISSUER=https://auth.local/application/o/planka/
OIDC_CLIENT_ID=sxxaAIAxVXlCxTmc1YLHBbQr8NL8MqLI2DUbt42d
OIDC_CLIENT_SECRET=om4RTMRVHRszU7bqxB7RZNkHIzA8e4sGYWxeCwIMYQXPwEBWe4SY5a0wwCe9ltB3zrq5f0dnFnp34cEHD7QSMHsKvV9AiV5Z7eqDraMnv0I8IFivmuV5wovAECAYreSI
OIDC_SCOPES=openid profile email
OIDC_ADMIN_ROLES=planka-admin
# OIDC_EMAIL_ATTRIBUTE=email
# OIDC_NAME_ATTRIBUTE=name
# OIDC_USERNAME_ATTRIBUTE=preferred_username
# OIDC_ROLES_ATTRIBUTE=groups
# OIDC_IGNORE_USERNAME=true
# OIDC_IGNORE_ROLES=true
# OIDC_ENFORCED=true

Note: Be sure to modify the following values:

  • auth.local is the domain on which Authentik is hosted.
  • The client ID (sxxaAIAxVXlCxTmc1YLHBbQr8NL8MqLI2DUbt42d) and client secret (om4RTMRVHRszU7bqxB7RZNkHIzA8e4sGYWxeCwIMYQXPwEBWe4SY5a0wwCe9ltB3zrq5f0dnFnp34cEHD7QSMHsKvV9AiV5Z7eqDraMnv0I8IFivmuV5wovAECAYreSI) are generated by Authentik.
  • planka-admin is the role used in Authentik to create admin accounts (you can alternatively set OIDC_IGNORE_ROLES to true).

Google​

For Google OAuth setup, follow these steps:

  1. Go to Google API Credentials.
  2. Select an existing project or create a new one.
  3. Choose Create Credentials > OAuth Client ID.
  4. Set application type as Web application.
  5. Add the following Redirect URI: https://your-domain.com/oidc-callback.
  6. Set the Client ID and Client Secret as environment variables.
OIDC_ISSUER=https://accounts.google.com
OIDC_CLIENT_ID=xxx-xxx.apps.googleusercontent.com
OIDC_CLIENT_SECRET=xxxx-xxxx-xx
OIDC_SCOPES=openid profile email

Synology SSO​

Follow the Synology SSO Server Tutorial to create an OIDC application.

  • Use https://my-planka.url/oidc-callback as the Redirect URI.
  • Set the following environment variables:
OIDC_ISSUER=https://sso.mysynology.me/webman/sso
OIDC_CLIENT_ID=xxx
OIDC_CLIENT_SECRET=xxx
OIDC_NAME_ATTRIBUTE=email # Synology does not support the profile scope
OIDC_SCOPES=openid email
OIDC_IGNORE_USERNAME=true
OIDC_IGNORE_ROLES=true

This setup will enable you to authenticate users via OIDC, linking or creating accounts automatically depending on the email claim, and giving you flexibility in managing user roles.