Skip to main content

OpenID

Vikunja allows for authentication with an external identity source such as Authentik, Keycloak or similar via the OpenID Connect standard.

OpenID Connect Overview#

OpenID Connect is a standardized identity layer built on top of the more generic OAuth 2.0 specification, simplifying interaction between the involved parties significantly. While the OpenID specification is worth a read, we summarize the most important basics here.

The involved parties are:

  • Resource Owner: typically the end-user
  • Resource Server: the application server handling requests from the client, the Vikunja API in our case
  • Client: the application or client accessing the RS on behalf of the RO. Vikunja web frontend or any of the apps
  • Authorization Server: the server verifying the user identity and issuing tokens. These docs also use the words OAuth 2.0 provider, Identity Provider interchangeably.

After the user is authenticated, the provider issues a token to the user, containing various claims. There’s different types of tokens (ID token, access token, refresh token), and all of them are created as JSON Web Token. Claims in turn are assertions containing information about the token bearer, usually the user.

Scopes are requested by the client when redirecting the end-user to the Authorization Server for authentication, and indirectly control which claims are included in the resulting tokens. There’s certain default scopes, but it’s also possible to define custom scopes, which are used by the feature assigning users to Teams automatically.

Supported and required claims#

Vikunja only requires a few claims to be present in the ID token to successfully authenticate the user. Additional claims can be added though to customize behaviour during user creation.

The following table gives an overview about the claims supported by Vikunja. The scope column lists the scope that should request the claim according to the OpenID Connect Standard. It omits the claims such as sub or issuer required by the openid scope, which must always be present.

ClaimTypeScopeComment
emailrequiredemailSets the email address of the user. Taken from the userinfo endpoint if not present in ID token. User creation fails if claim not present and userinfo lookup fails.
nameoptionalprofileSets the display name of the user. Taken from the userinfo endpoint if not present in ID token.
preferred_usernameoptionalprofileSets the username of the user. Taken from the userinfo endpoint if not present in ID token. If this also doesn’t contain the claim, use the nickname claim from userinfo instead. If that one is not available either, the username is auto-generated by Vikunja.
pictureoptionalprofileIf provided and not empty, sets the avatar of the user. Must be a valid url which yields an image when queried. Taken from the userinfo endpoint if not present in ID token.
vikunja_groupsoptionalN/ACan be used to automatically assign users to teams. See below for a more detailed explanation about the expected format and implementation examples.
groupsoptionalgroupsUsed instead of vikunja_groups to assign users to teams when the provider’s scope contains groups. See Using the standard groups claim.

If one of the claims email, name, preferred_username or picture is missing from the ID token, Vikunja will attempt to query the userinfo endpoint to obtain the information from there. Additionally, you can set the forceuserinfo option to always use the userinfo endpoint instead of relying on claims from the ID token. This is useful for providers like Casdoor that may have inconsistencies between token data and UserInfo endpoint data.

Configuring OIDC Authentication#

To achieve authentication via an external provider, it is required to (a) configure a confidential Client on your OAuth 2.0 provider and (b) configure Vikunja to authenticate against this provider. Example configurations are provided for various different identity providers, below you can find generic guides though.

OpenID Connect defines various flow types indicating how exactly the interaction between the involved parties work, Vikunja makes use of the standard Authorization Code Flow.

Step 1: Configure your Authorization Server#

The first step is to configure the Authorization Server to correctly handle requests coming from Vikunja. In general, this involves the following steps at a minimum:

  • Create a confidential client and obtain the client ID and client secret
  • Configure (whitelist) redirect URLs that can be used by Vikunja
  • Make sure the required scopes (openid profile email are the default scopes used by Vikunja) are supported
  • Optional: configure an additional scope for automatic team assignment, see below for details

More detailed instructions for various different identity providers can be found here

Step 2: Configure Vikunja#

Vikunja has to be configured to use the identity provider. The configuration schema is as follows:

auth:
  openid:
    enabled: true
    providers:
      <provider-id>:
        name: <provider-name>
        authurl: <auth-url>  <----- Used for OIDC Discovery, usually the issuer
        clientid: <vikunja client-id>
        clientsecret: <vikunja client-secret>
        scope: openid profile email
        forceuserinfo: false # Optional: Set to true to always use UserInfo endpoint instead of ID token claims, defaults to false

The <provider-id> is used in the redirect URL for your identity provider (e.g., /auth/openid/<provider-id>).

The value for authurl can be obtained from the metadata of your provider. Note that the authurl is used for OIDC Discovery. Typically, you’ll want to use the issuer URL as found in the provider metadata.

The values for clientid and clientsecret are typically obtained when configuring the client. The scope usually doesn’t need to be specified or changed, unless you want to configure the automatic team assignment.

The same settings can also be provided through environment variables, following the standard VIKUNJA_ prefix and uppercased, underscore-separated path used elsewhere in Vikunja’s config. The <provider-id> becomes part of the variable name. For the example above, the equivalent environment variables would be:

VIKUNJA_AUTH_OPENID_ENABLED=true
VIKUNJA_AUTH_OPENID_PROVIDERS_<PROVIDER_ID>_NAME=<provider-name>
VIKUNJA_AUTH_OPENID_PROVIDERS_<PROVIDER_ID>_AUTHURL=<auth-url>
VIKUNJA_AUTH_OPENID_PROVIDERS_<PROVIDER_ID>_CLIENTID=<vikunja client-id>
VIKUNJA_AUTH_OPENID_PROVIDERS_<PROVIDER_ID>_CLIENTSECRET=<vikunja client-secret>
VIKUNJA_AUTH_OPENID_PROVIDERS_<PROVIDER_ID>_SCOPE="openid profile email"
VIKUNJA_AUTH_OPENID_PROVIDERS_<PROVIDER_ID>_FORCEUSERINFO=false

Replace <PROVIDER_ID> with the uppercased provider key you would have used in YAML. Multiple providers can be configured by repeating the VIKUNJA_AUTH_OPENID_PROVIDERS_<PROVIDER_ID>_* block with a different ID. Note that values containing spaces (such as scope) need to be quoted.

Optionally it is possible to disable local authentication and therefore forcing users to login via OpenID connect:

auth:
  local:
    enabled: false

Migration from versions before 1.0

Version 1.0 introduced a new syntax to declare providers. If you’re upgrading from a pre-1.0 version, the conversion is straightforward:

Pre-1.0 syntax (deprecated):

auth:
  openid:
    enabled: true
    providers:
      - name: <provider-name>
        authurl: <auth-url>  <----- Used for OIDC Discovery, usually the issuer
        clientid: <vikunja client-id>
        clientsecret: <vikunja client-secret>
        scope: openid profile email
        forceuserinfo: false # Optional: Set to true to always use UserInfo endpoint instead of ID token claims, defaults to false
      - name: <provider2-name>
        authurl: <auth-url>  <----- Used for OIDC Discovery, usually the issuer
        clientid: <vikunja client-id>
        clientsecret: <vikunja client-secret>
        scope: openid profile email
        forceuserinfo: false # Optional: Set to true to always use UserInfo endpoint instead of ID token claims, defaults to false

1.0+ syntax:

auth:
  openid:
    enabled: true
    providers:
      <provider-id1>:
        name: <provider1-name>
        authurl: <auth-url>  <----- Used for OIDC Discovery, usually the issuer
        clientid: <vikunja client-id>
        clientsecret: <vikunja client-secret>
        scope: openid profile email
        forceuserinfo: false # Optional: Set to true to always use UserInfo endpoint instead of ID token claims, defaults to false
      <provider-id2>:
        name: <provider2-name>
        authurl: <auth-url>  <----- Used for OIDC Discovery, usually the issuer
        clientid: <vikunja client-id>
        clientsecret: <vikunja client-secret>
        scope: openid profile email
        forceuserinfo: false # Optional: Set to true to always use UserInfo endpoint instead of ID token claims, defaults to false

Login existing local user with OpenID#

Users who already have a local account (one that logs in with a Vikunja password) can log in through an OpenID provider by linking the provider account to their local account. From Vikunja 2.8.0 onwards, users can do this themselves from their settings. The older emailfallback and usernamefallback options are deprecated and will be removed in the next major release.

Linked accounts#

Linking OpenID accounts from the user settings is available from Vikunja 2.8.0 onwards (or unstable builds).

Local users can link an account at any configured provider under Settings > Linked accounts. After that, logging in through the provider opens their local account instead of creating a new one. The help page describes the steps for users.

No extra configuration is needed. Linking reuses the provider’s regular redirect URL, so you don’t have to register another one at your provider. The tab only shows up for local users while at least one provider is configured. Users created through OpenID or LDAP can’t link accounts.

How linking works:

  • The user starts the link from their settings while logged in. Vikunja sends them to the provider with prompt=select_account, so they can pick the provider account to link.
  • Back in Vikunja, the user sees the provider account they’re about to link (the email, preferred_username, name or sub from the verified ID token, whichever is set first).
  • To confirm, the user enters their password, plus a TOTP code if they have two-factor authentication enabled. Failed attempts count toward the account lockout and are rate limited per user.
  • Vikunja stores the issuer and subject of the ID token. Each user can link one account per provider, and each provider account can belong to only one Vikunja user.
  • Vikunja sends the user a notification email when an account is linked.
  • Users can unlink an account from the same page. This also requires their password and, if enabled, a TOTP code.

When a user logs in through a linked account:

  • They land in their local account.
  • Vikunja does not update the local account’s name, email or avatar from the provider’s claims.
  • Team sync still runs.
  • If the user has two-factor authentication enabled, Vikunja still asks for a TOTP code.

Linking fails if Vikunja already created a separate OpenID account for that provider account on an earlier login. Delete that account first, then let the user link again. Move anything the user wants to keep out of that account before you delete it.

Email and username fallback (deprecated)#

emailfallback and usernamefallback are deprecated. They still work in Vikunja 2.8.0, but will be removed in the next major release. After that, an OpenID login only reaches a local account if the user linked it. Otherwise their next OpenID login creates a separate account.

Ask your users to link their accounts before you upgrade to the release that removes the options. A login through the fallback does not create a link on its own.

We recommend disabling both options now. The email fallback is the subject of security advisory GHSA-8pm4-w983-mx58: on an instance with the mailer disabled, someone could register a local account with another person’s email address. With emailfallback enabled, that person’s first SSO login then landed in the attacker’s account.

While either option is enabled, Vikunja logs a warning:

  • once at startup, for each provider that has one of the options enabled
  • every time a login matches a local user through the fallback, with the ID of that user

You can use the second warning to find users who still need to link their accounts.

The fallback options only match local user accounts. They never merge or link users across different OIDC issuers.

  • usernamefallback: looks for a local user whose username equals the sub claim, or the preferred_username claim with spaces replaced by dashes.
  • emailfallback: looks for a local user whose email equals the email claim. Vikunja only uses the email if the provider sends email_verified: true.

Either option works on its own. If both are enabled, Vikunja first looks for a local user matching both username and email, then for one matching the email alone.

A configuration that enables both options looks like this:

auth:
  local:
    enabled: true
  openid:
    enabled: true
    providers:
      authentiklogin:
        name: "Login using authentik"
        usernamefallback: true
        emailfallback: true
        authurl: https://authentik.domain.tld/application/o/vikunja/
        clientid: xxxxxxxxxxxxxxxxx
        clientsecret: xxxxxxxxxxxxxxxxxxxxxxxxxxxx

If no matching local user is found, Vikunja creates a new OpenID user. If the matching is misconfigured, this can result in duplicate accounts. The fallback also lets the provider log in as any local user whose username or email it can control in the claims.

Automatically login with specified provider#

Vikunja supports automatic redirection to a specific OpenID provider by appending the query parameter ?redirectToProvider=provider-id1 to the login URL.

This will immediately redirect the user to the authentication flow for the provider with the key provider-id1 in your configuration.

If you have only one provider configured, you can use any of these simplified parameters:

  • ?redirectToProvider
  • ?redirectToProvider=true
  • ?redirectToProvider=1

Example: https://vikunja.domain.tld/login?redirectToProvider=authentik

Automatically assign users to teams#

Starting with version 0.24.0, Vikunja is capable of automatically adding users to a team based on OIDC claims added by the identity provider. If configured, Vikunja will sync teams, automatically create new ones and make sure the members are part of the configured teams. Teams which exist only because they were created from OIDC attributes are not editable in Vikunja.

To distinguish between teams created in Vikunja and teams generated automatically via OIDC, generated teams have an oidcID assigned internally. Within the UI, the teams created through OIDC get a (OIDC) suffix to make them distinguishable from locally created teams.

On a high level, you need to make sure that the ID token issued by your identity provider contains a vikunja_groups claim, following the structure defined below. It depends on the provider being used as well as the preferences of the administrator how this is achieved. Typically you’d want to request an additional scope (e.g. vikunja_scope) which then triggers the identity provider to add the claim. If the vikunja_groups is part of the ID token, Vikunja will start the procedure and import teams and team memberships. From Vikunja 2.8.0 onwards, you can use the standard groups claim instead. See Using the standard groups claim.

The minimal claim structure expected by Vikunja is as follows:

{
    "vikunja_groups": [
        {
            "name": "team 1",
            "oidcID": 33349
        },
        {
            "name": "team 2",
            "oidcID": 35933
        }
    ]
}

It is also possible to pass the description and the isPublic flag as optional parameters. If not present, the description will be empty and team visibility defaults to false.

{
    "vikunja_groups": [
        {
            "name": "team 3",
            "oidcID": 33349,
            "description": "My Team Description",
            "isPublic": true
        },
    ]
}

For each team, you need to define a team name and an oidcID, where the oidcID can be any string with a length of less than 250 characters. The oidcID is used to uniquely identify the team, so please make sure to keep this unique.

Using the standard groups claim#

Team sync from the groups claim is available from Vikunja 2.8.0 onwards (or unstable builds).

Many identity providers can send a groups claim with the names of the user’s groups. Vikunja can create and assign teams from that claim instead of vikunja_groups. To use it, add groups to the provider’s scope:

auth:
  openid:
    enabled: true
    providers:
      <provider-id>:
        # ...
        scope: openid profile email groups

When the scope contains groups as a separate word, Vikunja reads the groups claim and ignores vikunja_groups for that provider.

  • The claim can be a list of strings or a single string. Vikunja skips empty names and values that aren’t strings.
  • Each group name becomes both the team name and the team’s external id. Teams created this way have no description and are not public.
  • Since the name is the id, renaming a group at your provider creates a new team. Users leave the old team on their next login.
  • Vikunja reads groups from the ID token. If the token doesn’t contain it and Vikunja queries the userinfo endpoint anyway (see Supported and required claims), it uses the value from there. With forceuserinfo enabled, the userinfo value takes precedence.

If your provider’s scope already contains groups and you rely on vikunja_groups, Vikunja switches to the groups claim when you upgrade to 2.8.0. Because the external ids change from your oidcID values to group names, users join new teams created from the group names on their next login and leave the teams created from vikunja_groups. If the provider sends no groups claim, users leave all teams synced from that provider. To keep using vikunja_groups, remove groups from the scope.

The extra_settings_links claim allows identity providers to inject custom links into the user settings navigation in Vikunja. This is useful for organizations that want to point users to related services or documentation.

The expected format in the ID token is:

{
    "extra_settings_links": {
        "key1": {"text": "Link Text", "url": "https://example.com"},
        "key2": {"text": "Another Link", "url": "https://other.com"}
    }
}

Each key in the object represents a unique link identifier. The text field is the display text shown in the navigation, and url is the destination when clicked.

Common use cases include:

  • Linking to organization-specific documentation
  • Pointing to related internal services (password reset, account management)
  • Providing quick access to support resources

Below you’ll find two example implementations for Authentik and Keycloak. If you’ve successfully implemented this with another identity provider, please let us know and submit a PR to improve the docs.

Setup in Authentik#

To configure automatic team management through Authentik, we assume you have already set up Authentik as an OIDC provider for authentication with Vikunja.

To use Authentik’s group assignment feature, follow these steps:

  1. Edit your config to include the following scopes: openid profile email vikunja_scope
  2. Open <your authentik url>/if/admin/#/core/property-mappings
  3. Create a new property mapping called vikunja_scope as scope mapping. There is a field expression to enter python expressions that will be delivered with the oidc token.
  4. Write a small script like the following to add group information to vikunja_scope:
groupsDict = {"vikunja_groups": []}
for group in request.user.ak_groups.all():
  groupsDict["vikunja_groups"].append({"name": group.name, "oidcID": group.num_pk})
return groupsDict
  1. In Authentik’s menu on the left, go to Applications > Providers > Select the Vikunja provider. Then click on “Edit”, on the bottom open “Advanced protocol settings”, select the newly created property mapping under “Scopes”. Save the provider.

Now when you log into Vikunja via Authentik it will show you a list of scopes you are claiming. You should see the description you entered on the OIDC provider’s admin area.

Proceed to Vikunja and open the teams page in the sidebar menu. You should see “(OIDC)” written next to each team you were assigned through OIDC.

Setup in Keycloak#

If you want full control over the mapping, you can follow the guide written by the kind people from Makerspace Darmstadt e.V. on how to create a mapper for Vikunja here.

For a simple mapping using the standard groups claim, create a groups client scope with a Group Membership mapper and add it to your Vikunja client. It does not matter whether it’s set to “Optional” or “Default”. You will still need to include groups in the Vikunja OIDC config scope attribute, otherwise the groups won’t be read by Vikunja. See the Keycloak example for the steps.

Troubleshooting#

Vikunja ignores my configured endpoint URLs#

Vikunja uses OpenID Connect Discovery to automatically determine endpoint URLs. It fetches <authurl>/.well-known/openid-configuration and uses the URLs returned by your provider.

This means that even if you manually configure specific endpoint URLs, the values from the discovery document will take precedence. If your provider is running on a non-standard port or behind a proxy, make sure the discovery document returns the correct URLs.

To debug, fetch the discovery document yourself:

curl https://your-provider/.well-known/openid-configuration | jq .

Verify that the authorization_endpoint, token_endpoint, and userinfo_endpoint values point to the correct host and port.

Vikunja can’t reach the provider through a proxy#

Routing OpenID Connect requests through a proxy is available from Vikunja 2.7.0 onwards (or unstable builds).

If you configured an outgoing proxy, Vikunja sends all requests to your provider through it. When outgoingrequests.proxyurl is set, this includes providers on your internal network. Either make sure the proxy can reach the provider, or configure the proxy with the HTTPS_PROXY environment variable and add the provider’s host to NO_PROXY.

Usernames are auto-generated (random characters)#

If users logging in via OIDC get random usernames instead of their actual name, the identity provider is not including the preferred_username claim. Vikunja checks these sources in order:

  1. preferred_username from the ID token
  2. preferred_username from the userinfo endpoint
  3. nickname from the userinfo endpoint
  4. If none are available, a random username is generated

Check your provider’s configuration to ensure it includes preferred_username in the profile scope. Some providers (like Synology SSO) do not include this claim by default.

Users must log in before they can be assigned to tasks#

Vikunja creates user accounts on first OIDC login. There is no SCIM provisioning or bulk user import via OIDC. This means you cannot assign a user to a task or team until they have logged in at least once.

If you need to pre-create users, you can use the Vikunja API to create local user accounts, but these will be separate from OIDC accounts until the users link their OpenID account from their settings. The deprecated email and username fallback can also match them, but will be removed in the next major release.

OIDC works in browser but not on mobile app#

The Android and iOS apps use an embedded webview for the OIDC flow, which may behave differently than a full browser. Known limitations:

  • Some providers may have issues with the webview’s cookie handling
  • The “Login with frontend” option is recommended for mobile OIDC
  • If you see a “State does not match” error, this is typically a webview session issue

If you encounter OIDC issues only on mobile, please report it with your provider details.

Use cases#

All examples assume one team called “Team 1” to be configured within your provider.

  • Token delivers team.name +team.oidcID and Vikunja team does not exist:
    New team will be created called “Team 1” with attribute oidcID: “33929”
  1. In Vikunja Team with name “team 1” already exists, but has no oidcID set:
    new team will be created called “team 1” with attribute oidcID: “33929”

  2. In Vikunja Team with name “team 1” already exists, but has different oidcID set:
    new team will be created called “team 1” with attribute oidcID: “33929”

  3. In Vikunja Team with oidcID “33929” already exists, but has different name than “team1”:
    new team will be created called “team 1” with attribute oidcID: “33929”

  4. Scope vikunja_scope is not set:
    nothing happens

  5. oidcID is not set:
    You’ll get an error. Custom Scope malformed “The custom scope set by the OIDC provider is malformed. Please make sure the openid provider sets the data correctly for your scope. Check especially to have set an oidcID.”

  6. In Vikunja I am in “team 3” with oidcID "", but the token does not deliver any data for “team 3”:
    You will stay in team 3 since it was not set by the oidc provider

  7. In Vikunja I am in “team 3” with oidcID “12345”, but the token does not deliver any data for “team 3”:
    You will be signed out of all teams, which have an oidcID set and are not contained in the token. Especially if you’ve been the last team member, the team will be deleted.