Skip to main content

Configuring an external provider for authentication

To work with 2GIS Pro, end users must pass the authentication. The On-Premise solution does not provide an authentication service to be installed in a private environment. Therefore, you need to use your own OpenID Connect (OIDC) provider to authorize users via Single Sign-On (SSO) technology.

Only users registered in the external OIDC provider database can authenticate and be authorized in 2GIS Pro. User management is also handled on the provider side.

Configure your OIDC provider by meeting the following requirements:

  1. Define the mandatory claims. The following user data must always be filled in the user-info response:

    • sub - user identifier.
    • email - user email.
    • email_verified - flag indicating if the email is verified by the user.
    • name - user full name.
    • phone_number - user phone number.

  2. Configure the scopes that can be used to request the defined claims. The standard set of scopes includes the following values:

    • openid - mandatory parameter indicating that OIDC is used for user authentication.
    • email - user email.
    • profile - link to the user profile.
    • phone - user phone number.

  3. Create a client in your OIDC provider:

    1. Configure the client ID (client_id) and secret (client_secret).

    2. Specify the Callback URL and the Logout URL for the service:

      • Callback URL: https://{application_host}/api/auth/code
      • Logout URL: https://{application_host}/api/auth/after_sign_out_openid

    3. Configure the client to work with previously defined scopes.

  4. Configure role mapping for authorization.

    Services that use an OIDC provider (authProvider.schema: Oidc) check access rights based on roles passed in the id_token. If the id_token does not contain a claim with roles, users will not be able to access such services, even after authentication.

    For authorization to work correctly, configure your OIDC provider:

    1. Assign the required roles to users.
    2. Configure role mapping to a separate token claim (for example, roles).
    3. Ensure the claim is placed at the top level of the JSON structure (not in a nested structure).
    4. Specify the claim value type as an array of strings.
    5. Ensure the claim is included in the id_token.

    id_token example:

    {
      "sub": "123456",
      "name": "John Doe",
      "roles": ["admin", "editor"],
      "iss": "https://idp.example.com",
      "aud": "client_id",
      "exp": 1710000000
    }

    If your provider generates nested claims by default, configure transformation to a flat claim.