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
andname
claims. By default, it requestsopenid 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
oruserinfo
. By default, it is set touserinfo
. - 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
, theOIDC_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
, theOIDC_ADMIN_ROLES
andOIDC_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 setOIDC_IGNORE_ROLES
totrue
).
Google
For Google OAuth setup, follow these steps:
- Go to Google API Credentials.
- Select an existing project or create a new one.
- Choose Create Credentials > OAuth Client ID.
- Set application type as Web application.
- Add the following Redirect URI:
https://your-domain.com/oidc-callback
. - 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.