If your Elasticsearch cluster is operating in production mode, then you must configure the HTTP interface to use SSL/TLS before you can enable OpenID Connect authentication.

For more information, see Encrypting HTTP client communications.

The Elasticsearch OpenID Connect implementation makes use of the Elasticsearch Token Service. This service is automatically enabled if you configure TLS on the HTTP interface, and can be explicitly configured by including the following in your elasticsearch.yml file:

xpack.security.authc.token.enabled: true

OpenID Connect based authentication is enabled by configuring the appropriate realm within the authentication chain for Elasticsearch.

This realm has a few mandatory settings, and a number of optional settings. The available settings are described in detail in OpenID Connect realm settings. This guide will explore the most common settings.

Create an OpenID Connect (the realm type is oidc) realm in your elasticsearch.yml file similar to what is shown below:

xpack.security.authc.realms.oidc.oidc1:
  order: 2
  rp.client_id: "the_client_id"
  rp.response_type: code
  rp.redirect_uri: "https://kibana.example.org:5601/api/security/oidc/callback"
  op.issuer: "https://op.example.org"
  op.authorization_endpoint: "https://op.example.org/oauth2/v1/authorize"
  op.token_endpoint: "https://op.example.org/oauth2/v1/token"
  op.jwkset_path: oidc/jwkset.json
  op.userinfo_endpoint: "https://op.example.org/oauth2/v1/userinfo"
  op.endsession_endpoint: "https://op.example.org/oauth2/v1/logout"
  rp.post_logout_redirect_uri: "https://kibana.example.org:5601/logged_out"
  claims.principal: sub
  claims.groups: "http://example.info/claims/groups"

The configuration values used in the example above are:

A final piece of configuration of the OpenID Connect realm is to set the Client Secret that was assigned to the RP during registration in the OP. This is a secure setting and as such is not defined in the realm configuration in elasticsearch.yml but added to the elasticsearch keystore. For instance

bin/elasticsearch-keystore add xpack.security.authc.realms.oidc.oidc1.rp.client_secret

The Open ID Connect realm in Elasticsearch supports 3rd party initiated login as described in the relevant specification.

This allows the OP itself or another, third party other than the RP, to initiate the authentication process while requesting the OP to be used for the authentication. Please note that the Elastic Stack RP should already be configured for this OP, in order for this process to succeed.

The OpenID Connect realm in Elasticsearch supports RP-Initiated Logout Functionality as described in the relevant part of the specification

In this process, the OpenID Connect RP (the Elastic Stack in this case) will redirect the user’s browser to predefined URL of the OP after successfully completing a local logout. The OP can then logout the user also, depending on the configuration, and should finally redirect the user back to the RP. The op.endsession_endpoint in the realm configuration determines the URL in the OP that the browser will be redirected to. The rp.post_logout_redirect_uri setting determines the URL to redirect the user back to after the OP logs them out.

When configuring rp.post_logout_redirect_uri, care should be taken to not point this to a URL that will trigger re-authentication of the user. For instance, when using OpenID Connect to support single sign-on to Kibana, this could be set to ${kibana-url}/logged_out, which will show a user- friendly message to the user.

OpenID Connect depends on TLS to provide security properties such as encryption in transit and endpoint authentication. The RP is required to establish back-channel communication with the OP in order to exchange the code for an ID Token during the Authorization code grant flow and in order to get additional user information from the UserInfo endpoint. Furthermore, if you configure op.jwks_path as a URL, Elasticsearch will need to get the OP’s signing keys from the file hosted there. As such, it is important that Elasticsearch can validate and trust the server certificate that the OP uses for TLS. Since the system truststore is used for the client context of outgoing https connections, if your OP is using a certificate from a trusted CA, no additional configuration is needed.

However, if the issuer of your OP’s certificate is not trusted by the JVM on which Elasticsearch is running (e.g it uses a organization CA), then you must configure Elasticsearch to trust that CA. Assuming that you have the CA certificate that has signed the certificate that the OP uses for TLS stored in the /oidc/company-ca.pem` file stored in the configuration directory of Elasticsearch, you need to set the following property in the realm configuration:

xpack.security.authc.realms.oidc.oidc1:
  order: 1
  ...
  ssl.certificate_authorities: ["/oidc/company-ca.pem"]