IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Configuring Kibana User authorization »
Elastic Docs ›Elasticsearch Guide [7.10] ›Secure a cluster ›Configuring single sign-on to the Elastic Stack using OpenID Connect

OpenID Connect without Kibana

edit

OpenID Connect without Kibana

edit

The OpenID Connect realm is designed to allow users to authenticate to Kibana and as such, most of the parts of the guide above make the assumption that Kibana is used. This section describes how a custom web application could use the relevant OpenID Connect REST APIs in order to authenticate the users to Elasticsearch, with OpenID Connect.

Single sign-on realms such as OpenID Connect and SAML make use of the Token Service in Elasticsearch and in principle exchange a SAML or OpenID Connect Authentication response for an Elasticsearch access token and a refresh token. The access token is used as credentials for subsequent calls to Elasticsearch. The refresh token enables the user to get new Elasticsearch access tokens after the current one expires.

The Elasticsearch Token Service can be seen as a minimal oAuth2 authorization server and the access token and refresh token mentioned above are tokens that pertain only to this authorization server. They are generated and consumed only by Elasticsearch and are in no way related to the tokens ( access token and ID Token ) that the OpenID Connect Provider issues.

Register the RP with an OpenID Connect Provider

edit

The Relying Party ( Elasticsearch and the custom web app ) will need to be registered as client with the OpenID Connect Provider. Note that when registering the Redirect URI, it needs to be a URL in the custom web app.

OpenID Connect Realm

edit

An OpenID Connect realm needs to be created and configured accordingly in Elasticsearch. See Configure Elasticsearch for OpenID Connect authentication

Service Account user for accessing the APIs

edit

The realm is designed with the assumption that there needs to be a privileged entity acting as an authentication proxy. In this case, the custom web application is the authentication proxy handling the authentication of end users ( more correctly, "delegating" the authentication to the OpenID Connect Provider ). The OpenID Connect APIs require authentication and the necessary authorization level for the authenticated user. For this reason, a Service Account user needs to be created and assigned a role that gives them the manage_oidc cluster privilege. The use of the manage_token cluster privilege will be necessary after the authentication takes place, so that the the user can maintain access or be subsequently logged out.

POST /_security/role/facilitator-role
{
  "cluster" : ["manage_oidc", "manage_token"]
}
POST /_security/user/facilitator
{
  "password" : "<somePasswordHere>",
  "roles"    : [ "facilitator-role"]
}

Handling the authentication flow

edit

On a high level, the custom web application would need to perform the following steps in order to authenticate a user with OpenID Connect:

  1. Make an HTTP POST request to _security/oidc/prepare, authenticating as the facilitator user, using the name of the OpenID Connect realm in the Elasticsearch configuration in the request body. See the OIDC prepare authentication API for more details

    POST /_security/oidc/prepare
{
  "realm" : "oidc1"
}
  2. Handle the response to /_security/oidc/prepare. The response from Elasticsearch will contain 3 parameters: redirect, state, nonce. The custom web application would need to store the values for state and nonce in the user’s session (client side in a cookie or server side if session information is persisted this way) and redirect the user’s browser to the URL that will be contained in the redirect value.

  3. Handle a subsequent response from the OP. After the user is successfully authenticated with the OpenID Connect Provider, they will be redirected back to the callback/redirect URI. Upon receiving this HTTP GET request, the custom web app will need to make an HTTP POST request to _security/oidc/authenticate, again - authenticating as the facilitator user - passing the URL where the user’s browser was redirected to, as a parameter, along with the values for nonce and state it had saved in the user’s session previously. If more than one OpenID Connect realms are configured, the custom web app can specify the name of the realm to be used for handling this, but this parameter is optional. See OIDC authenticate API for more details

    POST /_security/oidc/authenticate
{
  "redirect_uri" : "https://oidc-kibana.elastic.co:5603/api/security/oidc/callback?code=jtI3Ntt8v3_XvcLzCFGq&state=4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I",
  "state" : "4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I",
  "nonce" : "WaBPH0KqPVdG5HHdSxPRjfoZbXMCicm5v1OiAj0DUFM",
  "realm" : "oidc1"
}

    Elasticsearch will validate this and if all is correct will respond with an access token that can be used as a Bearer token for subsequent requests and a refresh token that can be later used to refresh the given access token as described in get token API.

  4. At some point, if necessary, the custom web application can log the user out by using the OIDC logout API passing the access token and refresh token as parameters. For example:

    POST /_security/oidc/logout
{
  "token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
  "refresh_token": "vLBPvmAB6KvwvJZr27cS"
}

    If the realm is configured accordingly, this may result in a response with a redirect parameter indicating where the user needs to be redirected in the OP in order to complete the logout process.

« Configuring Kibana User authorization »