OpenID Connect login (SSO)

After #33 is done, Wakapi supports external authentication providers via OpenID Connect (OIDC). This way, users can benefit from single sign-on (SSO) and won't have to create a local account using e-mail address and password. Authentication is entirely delegated to the upstream provider. OIDC can be used for login and signup, that is, for new users, a new Wakapi account will be created upon first login.

Setup

You can configure one or more via the YAML configuration file or using environment variables. Follow the respective provider's instructions to get client ID and -secret. When you register your Wakapi instance as a new application with the provider, make sure to apply these settings:

• Scopes: openid, profile, email
• Redirect URL: https://<your-wakapi-instance>/oidc/<provider>/callback
  • Note: The <provider> is the name of the provider in your config, e.g. gitlab, google, ...

Config example

# ...
security:
  # ...
  oidc_allow_signup: true
  oidc:
    - name: codeberg
      display_name: Codeberg
      client_id: <your oauth2 client id>
      client_secret: <your oauth2 client secret>
      endpoint: https://codeberg.org
# ...

Environment config example

environment:
  - "WAKAPI_OIDC_ALLOW_SIGNUP=true"
  - "WAKAPI_OIDC_PROVIDERS_0_NAME=codeberg"
  - "WAKAPI_OIDC_PROVIDERS_0_DISPLAY_NAME=Codeberg"
  - "WAKAPI_OIDC_PROVIDERS_0_CLIENT_ID=<your oauth2 client id>"
  - "WAKAPI_OIDC_PROVIDERS_0_CLIENT_SECRET=<your oauth2 client secret>"
  - "WAKAPI_OIDC_PROVIDERS_0_ENDPOINT=https://codeberg.org"

Providers

Here's a list of common providers including links to their documentation and OIDC base endpoints.

Note: While GitHub supports OAuth 2.0 in general, it unfortunately does not support acting as an OpenID Connect provider.

Codeberg

• https://forgejo.org/docs/v8.0/user/oauth2-provider/#using-codeberg-as-an-authentication-source
• https://codeberg.org/.well-known/openid-configuration

GitLab

• https://docs.gitlab.com/integration/oauth_provider/
• https://gitlab.com/.well-known/openid-configuration

Google

• https://developers.google.com/identity/sign-in/web/sign-in
• https://accounts.google.com/.well-known/openid-configuration

Microsoft Entra

• https://learn.microsoft.com/en-us/entra/identity-platform/v2-protocols-oidc
• https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration

Okta

• https://developer.okta.com/docs/guides/sign-in-overview/main/
• https://your-okta-domain/.well-known/openid-configuration

Authentik (self-hosted)

• https://docs.goauthentik.io/add-secure-apps/providers/oauth2/
• Also see #857 for details

Migration from local accounts to OIDC

This section describes how existing local user accounts can be migrated to OIDC-based authentication.

At the moment, there is no automated or user-friendly way to migrate users. The migration requires direct access to the database, and several manual steps must be performed for each individual user.

For additional context, see @muety in #858.

Migration Steps

Important

You may need to temporarily change or remove the email address of the existing user, as email addresses must be unique across all users.

1. Register a new user via OIDC

2. Copy the auth_type and sub fields from the new user to the existing user

   update users
   set auth_type = (select q.auth_type from (select auth_type from users where id = '<new user id>') as q),
       sub       = (select q.sub from (select sub from users where id = '<new user id>') as q)
   where id = '<old user id>';

3. Delete the newly created OIDC user

   delete from users where id = '<new user id>';

After completing these steps, you will be able to log in to the existing account using OIDC authentication.