Configure OpenId authentication

Configure OpenId authentication

This guide outlines the process of setting up OpenID authentication in Kadeck. OpenID provides a secure and standardized way for users to authenticate across different platforms.

Environment Variables

Kadeck uses the following environment variables for OpenID configuration. All variables are prefixed with xeotek_kadeck_authentication_openid_:

Required configurations

  1. client_secret: The client secret provided by your OpenID provider.
  2. client_id: The client ID provided by your OpenID provider.
  3. redirect_url: The URL where the OpenID provider will redirect after authentication.
  4. jwks_url: The URL of the JSON Web Key Set (JWKS) for verifying tokens.
  5. authorization_url: The URL for initiating the OpenID authorization process.
  6. token_url: The URL for exchanging authorization codes for tokens.

Optional configurations

  1. groups_claim: The claim name in the ID token that contains user group information. Defaults to "groups".
  2. scope: The OpenID scopes requested during authentication. Defaults to "openid profile email offline_access"
  3. debug: Enable or disable debug mode for OpenID authentication. Defaults to false.
  4. group_management: Configuration for group management in OpenID. Defaults to false.
  5. login_url: The URL from which the Kadeck login page is reachable (e.g., "http://kadeck.acme.org/#/login"). Defaults to "/#/login".
  6. sync_interval_mins: The interval (in minutes) for synchronizing group information. Defaults to 60 (mins).

Configuration Steps

  1. Configure a database: You will need to restart Kadeck at least once during the setup. It is therefore mandatory that an external database is configured.
  2. Start & login: Start Kadeck and login with your admin user account.
  3. Configure group mapping:
    1. Map the Superusers group to a group ID that you, as the Kadeck administrator, are assigned to (read the section "Group Mapping in Kadeck" below).
    2. Alternatively, create a user with your email as the user id and assign it to the Superusers group.
  4. Start OpenID configuration: Exit Kadeck and start configuring OpenID.
  5. OpenID Provider Setup:
    1. Register Kadeck as a client in your OpenID provider (e.g., Azure AD, Okta).
    2. Configure the necessary scopes and claims in your OpenID provider.
    3. Tip: Have a look at your provider's .well-known/openid-configuration to fill out the required information.
    4. Configure the client id, secret and all other required configurations for Kadeck using the environment variables.
    5. Ensure the redirect URL of your OpenID registration matches the redirect_url environment variable. 
  6. Group Claim Configuration: Set the groups_claim variable to match the claim name used by your OpenID provider for group information (e.g., groups).
  7. Scopes: Configure the scope variable with the required OpenID scopes, typically including "openid", "profile", "email", and any custom scopes for group information.
  8. Debug Mode: Set debug to "true" for detailed logging during setup and troubleshooting.
  9. Login url: Ensure the login URL is correctly configured; otherwise, the user won't be logged in correctly after authentication (read the login_url description above).
  10. Synchronization Interval: Set sync_interval_mins to define how often Kadeck should synchronize group information with the OpenID provider. 

Group Mapping in Kadeck

Kadeck provides a feature to map OpenID and LDAP groups to internal Kadeck groups:

  1. Navigate to the Kadeck administration section.
  2. Go to the Groups and click edit or add new.
  3. Look for the "External mapping" field.
  4. In this field, you can specify a name that should be used to match the groups from OpenID (e.g., the group ID) with the Kadeck group.

This mapping allows for flexible group management, especially when the group names or IDs in your OpenID provider don't directly match the group names in Kadeck.

We recommend adding an external mapping for the Superusers group in Kadeck, especially when setting up OpenID authentication for the first time. This allows Kadeck administrators to log in and make further changes after OpenID is enabled. 

Verification

After configuration:

  1. Restart Kadeck to apply the changes.
  2. Attempt to log in using the OpenID authentication flow.
  3. Verify that users are correctly authenticated and assigned to the appropriate groups based on their OpenID claims and the group mappings you've configured.

Troubleshooting

  1. If authentication fails, check the Kadeck logs for error messages.
  2. Ensure all URLs (redirect, JWKS, authorization, token) are correct and accessible.
  3. Verify that the client ID and secret are correct and active in your OpenID provider.
  4. Check that the necessary scopes are being requested and granted.
  5. If group assignments are incorrect, review the groups_claim configuration and the group mappings in Kadeck.

    • Related Articles

    • Configure LDAP Basic module

      Active Directory (AD) and OpenLDAP are supported to authenticate users. LDAP is only available to specific licenses. LDAP is configured via Startup Parameters with the prefix xeotek_kadeck_authentication_ldap. To enable LDAP, the ...

    • Configure a home path

      The home path can be used to change the URL through which the Kadeck Teams UI and API are accessible. In the default configuration, all endpoints are exposed via the host domain (e.g. localhost:80/). The home path parameter can be used to append ...

    • Configure a Kadeck cluster setup

      This article describes how to configure multiple Kadeck instances that run as a cluster. Define master nodes First define a list of master nodes. In this example, we will configure 3 Kadeck instances running as a minimum (to handle 2 simultaneous ...

    • Startup parameters for Desktop

      You can pass any parameter to Kadeck's Java backend by adding them to the KA_DECK_OPTS environment variable. Windows cmd /c "SET KA_DECK_OPTS='-Xmx6G'&KaDeck.exe MacOS launchctl setenv KA_DECK_OPTS "-Xms6G" && open Kadeck.app/ Linux ...

    • Configure a database

      Kadeck requires a database for storing information. An external database such as H2 or PostgreSQL is recommended in a production environment. If no external database information is supplied, Kadeck will use an internal H2 file-based database. This is ...