OpenID Connect authentication definition

This authentication method is configured globally and is not tied to any particular user. Thus even if a user has no authentication methods configured, they can authenticate using OpenID Connect in Access Gateway and Admin Panel.


Follow the steps to configure the OpenID Connect authentication method:

  1. Select Settings > Authentication.
  2. Choose OpenID Connect tab.
  3. Click Add OpenID Connect.
  4. Check the Enabled option to globally enable OpenID Connect authentication.
  5. Provide Name (Azure, Okta or any other Identity Provider).
  6. Provide Bind address.
../../_images/5-5-openid-connect-auth.png
  1. In the General section, input Configuration URL.

Note

This URL is specific for every Identity Provider and allows identifying one for correct configuration. Example of Configuration URL for Google: https://accounts.google.com/.well-known/openid-configuration.

  1. Provide Client ID, and Client secret. Those values are available after registering with the selected provider.

Note

Please refer to the section OpenID Connect authentication definition with Microsoft Entra (Azure) for a use case example on configuring OpenID authentication using the Microsoft Entra.

  1. In the Mappings field, add Username mapping and Email mapping if necessary. These fields are useful when the user’s name follows a different naming convention.

Note

To ensure proper authentication via Okta external provider, specific mapping configurations are required based on the format of the user’s name and the presence of the email address in the User configuration.

../../_images/5-5-mapping-okta.png

  1. Username Contains Email Address:

    Scenario: If the Name field in the User configuration includes an email address (e.g., user1@fudosecurity.com) and the Email field in the User Data tab is empty.

    Configuration: Set the Username mapping to email. This ensures that the email address within the username is correctly recognized and used for authentication purposes.

  2. Username with Text and Email Field Populated:

    Scenario: If the Name field in the User configuration contains any text (e.g., Fudo_1, user1) and the Email field in the User Data tab contains the actual email address (e.g., user1@fudosecurity.com).

    Configuration: Set the Email mapping to email. This configuration ensures that the email address provided in the Email field is used for authentication, even if the username is a non-email string.

  1. Click Save.

Note

The algorithm to determine the user’s identity is following:

  1. The user is initially identified using the sub claim from the OpenID Connect (OIDC) provider.
  2. If the user is not identified using the sub claim from the OIDC provider, the next step involves checking the autolink setting for the OIDC provider. If this setting is false, the process concludes without finding the user. However, if the autolink setting is true, the search process continues.
  3. If Username mapping is defined, a search for a corresponding claim in the data is conducted. Once the claim is located in the JSON data, the system then looks for the user with that name.
  4. If Username mapping is not defined, the claim is not found in the data or the user is not found by name, the next step is to verify if Email mapping is defined. If it is defined and exists in JSON data, the process then tries to identify the user based on this email.
  5. When neither Username mapping nor Email mapping is defined, the system will seek to identify the user by their name or email. This is done by searching for the upn or unique_name claims within the data, in this specified order.
  6. When the email claim is used for user identification, it is mandatory for the email_verified field to be included in the data and set to true.
  7. The last step checks if the found user has a sub claim stored already, but different from the one received from the OIDC provider. If they don’t match, it fails.
  8. The received user sub claim is stored in the database for future use.
  1. Log in using the defined authentication method:
../../_images/5-3-azure-okta-login.png

Related topics: