Configure an OpenID Connect authentication

In this topic, you learn how to set up an authentication via OpenID and how to configure it in your Cockpit.

Prerequisites

  • There are no prerequisites.

Procedure

  1. In the Cockpit, go to Settings, and select System Settings.

  2. In the Authentication tab, select Edit.

  3. Select Add, and select OpenID Connect.

    Result: The Authentication window opens.

  4. Enter a Name for the authentication.

  5. Select Active to activate this authentication method.

  6. Select Show on Login Page to display the authentication method on the login page.

  7. Enter a Description.

  8. Enter a Path to generate the endpoints for the authentication method.

  9. In Discovery URL, enter a well-known openid-configuration.

  10. In Client ID, enter the ID of the client that is registered at your identity provider.

  11. Enter the Client Secret.

  12. Optionally, to send a reminder email to renew your client secret for OpenID Connect, turn on the switch Send Reminder Email before Expiry.

    If you turn on the switch, in Expiry Date, select the expiry date of the client secret. In Days before Expiry, select the number of days in 24 hours until midnight that the email reminder should be sent before expiry of the client secret. In Send to Email Address, enter an email address of your choosing or one that corresponds to the email address you configure for the SMTP host in the Emailing tab.

  13. Optionally, to send a reminder email to renew your client secret for OpenID Connect, turn on the switch Send Reminder Email before Expiry.

    If you turn on the switch, in Expiry Date, select the expiry date of the client secret. In Days before Expiry, select the number of days in 24 hours until midnight that the email reminder should be sent before expiry of the client secret. In Send to Email Address, enter an email address of your choosing or one that corresponds to the email address you configure for the SMTP host in the Emailing tab.

  14. Select whether you want the login to occur using a dialog or via redirect.

    For the dialog login option, set the redirect URI via the OpenID Connect IdP to: https://<your-domain.com>/public/oidc_redirect.html

    For the redirect login option, set the redirect URI via the OpenID Connect IdP to: https://<your-domain.com>/user/logon/openid-connect/<path>/callback

  15. To influence how the login interaction process occurs, select between the following:

    None

    Log in silently if possible (no UI is shown)

    Login

    Always show the login screen, even if the user is already signed in

    Consent

    Ask the user to approve access again, even if they’ve already consented

    Select Account

    Let the user choose which account to use, even if one is already active

  16. When the user logs in through the standard login page, the Redirect URL is included automatically in the request. If instead you use a direct login link, for example: /user/logon/openid-connect/<path>, the system cannot determine the redirect URL on its own. In this case, you must enter the redirect URL manually in After Login Redirect.

  17. In Launchpad Logout Redirect, enter a URL that the user should be redirected to when logging out of the launchpad.

  18. Enter any login scopes required by your application in Login Scopes. The login already includes openid, profile, offline_access, and user.read. Any scopes you add here trigger a separate token request during authentication.

  19. In Token Endpoint Authentication Method, select between the following:

    None

    No authentication is sent (suitable for public clients)

    Client Secret Basic

    Sends client ID and secret in HTTP header

    Client Secret Post

    Sends client ID and secret in the POST body

  20. In Claims Assignment, you can map incoming identity-provider claims to user properties within the system. Each entry consists of three parts:

    • Claim: The name of the incoming claim or scope provided by the authentication authority.

    • Default: An optional fallback value used when the claim is missing or not supplied.

    • User Fields: A selectable internal user attribute (for example, Username, Email, Language, Name, Phone, Mobile) that the claim should populate.

      You can create multiple rows to define as many claim–to–property mappings as required. When a user signs in, the system evaluates the received token, applies the mappings, and populates or updates the corresponding user fields accordingly.

      If the token contains group claims, then group assignment for the user is handled entirely by OpenID Connect.

  21. If required, in Auto Assignment, assign roles and groups that you have defined in the Role and Security Group tools in the Cockpit.

  22. Enable Only assign on first login to assign the claims, roles and security groups only on the first login.

  23. In Post Authentication Script, use Script to select a server script that should run after authentication. The script has access to the global variables profile, user, and updatedUser.

    If no server script is selected, you can enter custom logic in Function (profile, user, updatedUser, require, getEntityRepository, log). This allows you to run post-authentication code, such as logging details or modifying the variables, for example:

    log.info("XXuser",user);
log.info("XXprofile",profile);
log.info("Member of:"+ profile.memberof);
    Inline post-authentication scripts will be deprecated in a future patch. Plan to move any custom logic to a server script.

  24. Select OK.

  25. In System Settings, select Restart to activate the OpenID Connect authentication.

Results

  • You have configured and activated an OpenID Connect authentication.

Related topics