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.

To activate OpenID authentication, please configure and set the xeotek_kadeck_authentication_method to"openid".

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 (e.g., "http://kadeck.acme.org/api/auth/oauth/callback").
  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. Activate OpenID authentication: Configure and set the xeotek_kadeck_authentication_method to "openid".
  6. 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. 
  7. Group Claim Configuration: Set the groups_claim variable to match the claim name used by your OpenID provider for group information (e.g., groups).
  8. Scopes: Configure the scope variable with the required OpenID scopes, typically including "openid", "profile", "email", and any custom scopes for group information.
  9. Debug Mode: Set debug to "true" for detailed logging during setup and troubleshooting.
  10. Group management: Configure and set the group_management configuration to "true" to enable group mapping through OpenID.
  11. 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).
  12. 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.
  5. Set the group_management configuration to "true" to enable group management through OpenID.

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.

Info
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.
  6. Make sure the group_management configuration is set to "true" to enable group mapping through OpenID.
  7. If SSL is used, make sure that the SSL certificate is configured in Kadeck. Otherwise, the forwarding from your OpenID provider to Kadeck won't work. Configuring the SSL certificate on the ingress service only is not sufficient.