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.
  • OIDC_PROJECT_OWNER_ROLES: The role claim used to determine if a user is a project owner.
  • OIDC_BOARD_USER_ROLES: The role claim used to determine if a user is a board user. Board user will also be assigned if the role claim does not match.
  • 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, all OIDC_*_ROLES variables 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_PROJECT_OWNER_ROLES=project_owner
# OIDC_BOARD_USER_ROLES=board_user
# 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).

Keycloak​

Adjust Authentik example to work with Keycloak.

OIDC_ISSUER=https://auth.local/realms/{realm-name}
OIDC_CLIENT_ID=planka
OIDC_CLIENT_SECRET={secretAutoGeneratedByKeycloak}
OIDC_ADMIN_ROLES=planka-admin
OIDC_PROJECT_OWNER_ROLES=project_owner
# OIDC_ROLES_ATTRIBUTE=groups
# OIDC_ENFORCED=true

If you want to use the groups claim (as is default) then in your Keycloak Realm:

  1. Go to Clients.
  2. Click on the Client ID you gave Planka, in this example planka.
  3. Go to Client Scopes tab.
  4. Click on planka-dedicated.
  5. Click Add mapper > By configuration > Group Membership.
  6. Use the following options:
Name: groups
Token Claim Name: groups
Full group path -> Off
Add to ID token -> On
Add to access token -> On
Add to lightweight access token -> Off
Add to userinfo -> On
Add to token introspection -> On

Now users in the planka-admin or project_owner group receive the respective roles in Planka. Users without a matching group claim become board_user by default.

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

Microsoft Entra ID​

To configure a new App Registration for Planka in Entra ID follow these steps:

  1. Register a new application.

    • Select Web as the Redirect URI type and enter https://your-domain.com/oidc-callback as the URI
    • Note the Application (client) ID and your Directory (tenant) ID.

  2. Create a secret for the new Planka app.

    • Note the Secret Value as it will not be retrievable later.

  3. Add the following API permissions to the Planka app

    • Microsoft Graph > Delegated Permissions: email, openid, profile

  4. Add the below environment variables to your Planka configuration:

OIDC_CLIENT_ID=[ClientID] # Replace with Application (client) ID
OIDC_CLIENT_SECRET=[SecretValue] # Replace with Secret Value
OIDC_ISSUER=https://login.microsoftonline.com/[DirectoryID]/v2.0 # Replace with your Directory ID
OIDC_SCOPES=openid profile email
OIDC_IGNORE_ROLES=true # Do not enter this if managing roles as below

Optional: Assign Planka roles through Entra ID group membership​

In order to use Entra ID for authorization, follow these steps:

  1. Create security groups for the Planka roles (example names below) and add members.
    • APP-Planka-Admin
    • APP-Planka-ProjectOwner
    • APP-Planka-BoardUser (optional)
    • Note the Object IDs for each group
  2. Add a group claim for the Planka app, ensure you select Group ID as the source attribute
  3. Add the below environment variables to your Planka configuration:
OIDC_CLAIMS_SOURCE=id_token # By default userinfo claim does not include groups info
OIDC_USERNAME_ATTRIBUTE=oid # By default preferred_username will return email when id_token used and Planka username regex check does not allow "@"
OIDC_IGNORE_ROLES=false
OIDC_ROLES_ATTRIBUTE=groups
OIDC_ADMIN_ROLES=[ObjectID] # Replace with Object ID for Planka Admin security group
OIDC_PROJECT_OWNER_ROLES=[ObjectID] # Replace with Object ID for Planka Project Owner security group
OIDC_BOARD_USER_ROLES=[ObjectID] # Replace with Object ID for Planka Board User security group
OIDC_ENFORCED=true # Optional if you would like to disable local authentication

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.