Configuring single sign-on to the Elastic Stack using OpenID Connect

The OpenID Connect Provider (OP) is the entity in OpenID Connect that is responsible for authenticating the user and for granting the necessary tokens with the authentication and user information to be consumed by the Relying Parties.

In order for the Elastic Stack to be able to use your OpenID Connect Provider for authentication, a trust relationship needs to be established between the OP and the RP. In the OpenID Connect Provider, this means registering the RP as a client. OpenID Connect defines a dynamic client registration protocol but this is usually geared towards real-time client registration and not the trust establishment process for cross security domain single sign on. All OPs will also allow for the manual registration of an RP as a client, via a user interface or (less often) via the consumption of a metadata document.

The process for registering the Elastic Stack RP will be different from OP to OP and following the provider’s relevant documentation is prudent. The information for the RP that you commonly need to provide for registration are the following:

At the end of the registration process, the OP will assign a Client Identifier and a Client Secret for the RP (Elastic Stack) to use. Note these two values as they will be used in the Elasticsearch configuration.

The following is a summary of the configuration steps required in order to enable authentication using OpenID Connect in Elasticsearch:

xpack.security.authc.token.enabled: true

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/security/logged_out"
  claims.principal: sub
  claims.groups: "http://example.info/claims/groups"

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

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.authorization_endpoint: "https://op.example.org/oauth2/v1/authorize"
  op.token_endpoint: "https://op.example.org/oauth2/v1/token"
  op.userinfo_endpoint: "https://op.example.org/oauth2/v1/userinfo"
  op.endsession_endpoint: "https://op.example.org/oauth2/v1/logout"
  op.issuer: "https://op.example.org"
  op.jwkset_path: oidc/jwkset.json
  claims.principal: email_verified
  claim_patterns.principal: "^([^@]+)@staff\\.example\\.com$"

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

When a user authenticates using OpenID Connect, they are identified to the Elastic Stack, but this does not automatically grant them access to perform any actions or access any data.

Your OpenID Connect users cannot do anything until they are assigned roles. This can be done through either the add role mapping API or with authorization realms.

This is an example of a simple role mapping that grants the example_role role to any user who authenticates against the oidc1 OpenID Connect realm:

resp = client.security.put_role_mapping(
    name="oidc-example",
    roles=[
        "example_role"
    ],
    enabled=True,
    rules={
        "field": {
            "realm.name": "oidc1"
        }
    },
)
print(resp)

const response = await client.security.putRoleMapping({
  name: "oidc-example",
  roles: ["example_role"],
  enabled: true,
  rules: {
    field: {
      "realm.name": "oidc1",
    },
  },
});
console.log(response);

PUT /_security/role_mapping/oidc-example
{
  "roles": [ "example_role" ], 
  "enabled": true,
  "rules": {
    "field": { "realm.name": "oidc1" }
  }
}

The user properties that are mapped via the realm configuration are used to process role mapping rules, and these rules determine which roles a user is granted.

The user fields that are provided to the role mapping are derived from the OpenID Connect claims as follows:

For more information, see Mapping users and groups to roles and Role mappings.

If your OP has the ability to provide groups or roles to RPs via tha use of an OpenID Claim, then you should map this claim to the claims.groups setting in the Elasticsearch realm (see Mapping claims to user properties), and then make use of it in a role mapping as per the example below.

This mapping grants the Elasticsearch finance_data role, to any users who authenticate via the oidc1 realm with the finance-team group membership.

resp = client.security.put_role_mapping(
    name="oidc-finance",
    roles=[
        "finance_data"
    ],
    enabled=True,
    rules={
        "all": [
            {
                "field": {
                    "realm.name": "oidc1"
                }
            },
            {
                "field": {
                    "groups": "finance-team"
                }
            }
        ]
    },
)
print(resp)

const response = await client.security.putRoleMapping({
  name: "oidc-finance",
  roles: ["finance_data"],
  enabled: true,
  rules: {
    all: [
      {
        field: {
          "realm.name": "oidc1",
        },
      },
      {
        field: {
          groups: "finance-team",
        },
      },
    ],
  },
});
console.log(response);

PUT /_security/role_mapping/oidc-finance
{
  "roles": [ "finance_data" ],
  "enabled": true,
  "rules": { "all": [
        { "field": { "realm.name": "oidc1" } },
        { "field": { "groups": "finance-team" } }
  ] }
}

If your users also exist in a repository that can be directly accessed by Elasticsearch (such as an LDAP directory) then you can use authorization realms instead of role mappings.

In this case, you perform the following steps:

By default users who authenticate via OpenID Connect will have some additional metadata fields. These fields will include every OpenID Claim that is provided in the authentication response (regardless of whether it is mapped to an Elasticsearch user property). For example, in the metadata field oidc(claim_name), "claim_name" is the name of the claim as it was contained in the ID Token or in the User Info response. Note that these will include all the ID Token claims that pertain to the authentication event, rather than the user themselves.

This behaviour can be disabled by adding populate_user_metadata: false as a setting in the oidc realm.

OpenID Connect authentication in Kibana requires a small number of additional settings in addition to the standard Kibana security configuration. The Kibana security documentation provides details on the available configuration options that you can apply.

In particular, since your Elasticsearch nodes have been configured to use TLS on the HTTP interface, you must configure Kibana to use a https URL to connect to Elasticsearch, and you may need to configure elasticsearch.ssl.certificateAuthorities to trust the certificates that Elasticsearch has been configured to use.

OpenID Connect authentication in Kibana is subject to the following timeout settings in kibana.yml:

You may want to adjust these timeouts based on your security requirements.

The three additional settings that are required for OpenID Connect support are shown below:

xpack.security.authc.providers:
  oidc.oidc1:
    order: 0
    realm: "oidc1"

The configuration values used in the example above are:

xpack.security.authc.providers:
  oidc.oidc1:
    order: 0
    realm: "oidc1"
  basic.basic1:
    order: 1

This will allow users that haven’t already authenticated with OpenID Connect to log in using the Kibana login form.

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.

resp = client.security.put_role(
    name="facilitator-role",
    cluster=[
        "manage_oidc",
        "manage_token"
    ],
)
print(resp)

const response = await client.security.putRole({
  name: "facilitator-role",
  cluster: ["manage_oidc", "manage_token"],
});
console.log(response);

POST /_security/role/facilitator-role
{
  "cluster" : ["manage_oidc", "manage_token"]
}

resp = client.security.put_user(
    username="facilitator",
    password="<somePasswordHere>",
    roles=[
        "facilitator-role"
    ],
)
print(resp)

const response = await client.security.putUser({
  username: "facilitator",
  password: "<somePasswordHere>",
  roles: ["facilitator-role"],
});
console.log(response);

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