OpenID Configuration

This document describes the process of OpenID configuration and using it to log into the Platform.

• OpenID
• Requirements
• Using OIDC
• Limitations
• Configuring OIDC
  • Create an Application at an OIDC Provider
  • Register OIDC Provider in the Platform
  • Adding OIDC Connections Manually

OpenID

OpenID Connect (OIDC) is an interoperable authentication protocol based on the OAuth 2.0 family of specifications. It uses straightforward REST/JSON message flows to allow clients of all types, including browser-based JavaScript and native mobile apps, to launch sign-in flows and receive verifiable assertions about the identity of signed-in users.

Elastic.io allows users to utilize OIDC to simplify authentication process. The implemented OpenID Connect Version is 1.0, and the implemented Flow type is Code Flow.

Requirements

1. OIDC provider must support the Discovery process.

2. OIDC provider must provide email as one of the claims.

3. OIDC provider must provide email_verified as one of the claims and it has to be true (if no OIDC identity is found, and the user with the same email already exists).

Using OIDC

In order to login to the platform using the OIDC provider, go to the following URL:

https://platform-tenant-domain-name/oidc/authenticate?iss={issuer}

The issuer query parameter is required and has to be the same as specified during the OIDC provider registration.

OIDC operation scheme:

1. The user logs in with the Provider, which sends user data to the Platform. The Platform performs a check if the profile exists on the Provider, and if there is a Platform user with this profile. With both checks passed the user can log in.

2. If automatic user creation is enabled, it will activate when the first check fails. First, the Platform checks the user by verified email, and then creates a new profile and performs user login. This process includes the automatic creation of a new Contract, a new user, and a new random password.

3. The Tenant can be configured to create new users. In this case, even if there is no user associated with the given email on the Platform, the Platform will still create a new profile.

Here is a diagram of OIDC operation on the Platform:

Limitations

This is the list of current limitations associated with OpenID:

1. Only Final Specifications of OIDC are supported. Drafts are unsupported.

2. Changes made into ID Token on the OpenID Provider will not result in Platform-side changes.

3. As a new user is created with a random password, which is not revealed to the user, it is impossible to change this password.

Configuring OIDC

Each Tenant can be configured with multiple OIDC providers, but an OIDC provider can only be used once per Tenant.

Create an Application at an OIDC Provider

You will need to use the following callback URL: https://<platform-tenant-domain-name>/oidc/callback

EXAMPLE (application configuration in Google Cloud Platform):

Register OIDC Provider in the Platform

OIDC provider could be added via the following API call:

POST /v2/tenants/:tenant_id/openid/providers - more info here.

The following ID Token claims are used:

Parameter	Description
given_name	Given name(s) or first name(s) of the End-User. Note that in some cultures, people can have multiple given names. In that case, all names can be present, being separated by space characters.
family_name	Surname(s) or last name(s) of the End-User. Note that in some cultures, people can have multiple family names or no family name. In that case, either all surnames can be present, separated by space characters, or none.
email	End-User’s preferred e-mail address.
email_verified	Allowed values: true, false. True if the End-User’s e-mail address has been verified; otherwise false. When this Claim Value is true, this means that the OIDC Provider took affirmative steps to ensure that this e-mail address was controlled by the End-User at the time the verification was performed. The means by which an e-mail address is verified is context-specific, and dependent upon the trust framework or contractual agreements within which the parties are operating.
sub	Identifier for the End-User at the Issuer.

Required configuration:

Parameter	Required	Description
issuer	yes	URL of the OIDC issuer (base URL).
client_id	yes	Application client ID.
client_secret	yes	Application client secret.
config.auto_create_users	no	Toggles automated new user creation, in case a user is not registered yet. Allowed values: true, false. Default value: true.

Adding OIDC Connections Manually

It’s possible to manually add an OIDC connection to an existing user via the following API call:

POST /v2/users/{user_id}/openid/identities - more info here.

On successful call, the user will be recognized and logged in during the next login via OIDC.