It is time to say goodbye: This version of Elastic Cloud Enterprise has reached end-of-life (EOL) and is no longer supported.
The documentation for this version is no longer being maintained. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.
Secure your clusters with OpenID Connect
editSecure your clusters with OpenID Connect
editYou can secure your deployment using OpenID Connect for single sign-on. OpenID Connect is an identity layer on top of the OAuth 2.0 protocol. The end user identity gets verified by an authorization server and basic profile information is sent back to the client.
The OpenID Connect credentials are valid against the deployment, not the ECE platform. You can configure role-based access control for the platform separately.
Before you begin
editTo prepare for using OpenID Connect for authentication for deployments:
-
Create or use an existing deployment version 7.2 and later. Make note of the Kibana endpoint URL, it will be referenced as
<KIBANA_ENDPOINT_URL>
in the following steps. -
The steps in this section required a moderate understanding of OpenID Connect in general and the Authorization Code Grant flow specifically. For more information about OpenID Connect and how it works with the Elastic Stack see:
Configure the OpenID Connect Provider
editThe 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 (RP).
In order for Elastic Cloud Enterprise (acting as an RP) to be able 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.
The process for registering the Elastic Cloud Enterprise 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:
-
Relying Party Name
- An arbitrary identifier for the relying party. Neither the specification nor our implementation impose any constraints on this value.
-
Redirect URI
-
This is the URI where the OP will redirect the user’s browser after authentication. The appropriate value for this is
<KIBANA_ENDPOINT_URL>/api/security/v1/oidc
. You might also see this called as theCallback URI
.
At the end of the registration process, the OP assigns a Client Identifier and a Client Secret for the RP (Elastic Cloud Enterprise) to use. Note these two values as they are used in the cluster configuration.
Configure your cluster to use OpenID Connect
editYou’ll need to add the client secret to the keystore and then update the Elasticsearch user settings to refer to that secret and use the OpenID Connect realm.
Configure the Client Secret
editConfigure the Client Secret that was assigned to the PR by the OP during registration to the Elasticsearch keystore.
This is a sensitive setting, it won’t be stored in plaintext in the cluster configuration but rather as a secure setting. In order to do so, follow the steps below:
-
From the Deployments page, select your deployment.
Narrow the list by name, ID, or choose from several other filters. To further define the list, use a combination of filters.
- From your deployment menu, select Security.
- Under the Elasticsearch Keystore section, click Create settings.
-
On the Create setting window, select the secret Type to be
Secret String
. -
Set the Setting name` to
xpack.security.authc.realms.oidc.oidc1.rp.client_secret
and add the Client Secret you received from the OP during registration in thesecret
field.oidc1
is used as an example, but can be any name apart fromcloud-oidc
which is reserved for internal use only and can’t be used. This should match the one that you will use below in the Elasticsearch user settings.After you configure the Client Secret, any attempt to restart the deployement will fail until you complete the rest of the configuration steps. If you wish to rollback the OpenID Connect related configuration effort, you need to remove the
xpack.security.authc.realms.oidc.oidc1.rp.client_secret
that was just added by clicking on the "remove" button by the setting name underExisting Keystores
. - You must also edit your cluster configuration, sometimes also referred to as the deployment plan, in order to add the appropriate settings.
Configure the user settings
editThe Elasticsearch cluster needs to be configured to use the OpenID Connect realm for user authentication and to map the applicable roles to the users.
-
Update your Elasticsearch user settings for the
oidc
realm and specify the relevant configuration:xpack: security: authc: realms: oidc: oidc1: order: 2 rp.client_id: "client-id" rp.response_type: "code" rp.redirect_uri: "<KIBANA_ENDPOINT_URL>/api/security/v1/oidc" op.issuer: "<check with your OpenID Connect Provider>" op.authorization_endpoint: "<check with your OpenID Connect Provider>" op.token_endpoint: "<check with your OpenID Connect Provider>" op.userinfo_endpoint: "<check with your OpenID Connect Provider>" op.jwkset_path: "<check with your OpenID Connect Provider>" claims.principal: sub claims.groups: "http://example.info/claims/groups"
The
oidc
realm name:cloud-oidc
is reserved for internal use only and can’t be used. Please select another name, as shown here.This, usually opaque, arbitrary string, is the Client Identifier that was assigned to the Elastic Cloud Enterprise RP by the OP upon registration.
Replace
<KIBANA_ENDPOINT_URL>
with the value noted in the previous stepA url, used as a unique identifier for the OP. The value for this setting should be provided by your OpenID Connect Provider.
The URL for the Authorization Endpoint in the OP. This is where the user’s browser will be redirected to start the authentication process. The value for this setting should be provided by your OpenID Connect Provider.
The URL for the Token Endpoint in the OpenID Connect Provider. This is the endpoint where Elastic Cloud Enterprise will send a request to exchange the code for an ID Token, as part of the Authorization Code flow. The value for this setting should be provided by your OpenID Connect Provider.
(Optional) The URL for the UserInfo Endpoint in the OpenID Connect Provider. This is the endpoint of the OP that can be queried to get further user information, if required. The value for this setting should be provided by your OpenID Connect Provider.
The path to a file or an HTTPS URL pointing to a JSON Web Key Set with the key material that the OpenID Connect Provider uses for signing tokens and claims responses. Your OpenID Connect Provider should provide you with this file.
Defines the OpenID Connect claim that is going to be mapped to the principal (username) of the authenticated user in Kibana. In this example, we map the value of the
sub
claim, but this is not a requirement, other claims can be used too. See the claims mapping documentation for details and available options.Defines the OpenID Connect claim that is going to be used for role mapping. Note that the value
"http://example.info/claims/groups"
that is used here, is an arbitrary example. See the claims mapping documentation for a very detailed description of how the claim mapping works and how can these be used for role mapping. The name of this claim should be determined by the configuration of your OpenID Connect Provider.According to the OpenID Connect specification, the OP should also make their configuration available at a well known URL, which is the concatenation of their
Issuer
value with the.well-known/openid-configuration
string. For example:https://op.org.com/.well-known/openid-configuration
. That document should contain all the necessary information to configure the OpenID Connect realm above. -
By default, users authenticating via OpenID Connect have no roles assigned to them. For example, if you want all your users authenticating with OpenID Connect to get access to Kibana, issue the following request to Elasticsearch:
-
Update Kibana in the advanced configuration editor to use OpenID Connect as the authentication provider:
xpack.security.authProviders: [oidc] xpack.security.authc.oidc.realm: "oidc1" server.xsrf.whitelist: [/api/security/v1/oidc]
This needs to be the same value as the one used for the realm in the cluster configuration.
This configuration disables all other realms and only allows users to authenticate with OpenID Connect. If you wish to allow your native realm users to authenticate, you need to also enable the
basic
authProvider
by settingxpack.security.authProviders: [oidc, basic]
in the configuration of Kibana. You can then access the Kibana login screen at<KIBANA_ENDPOINT_URL>/login
-
Optional: If your OpenID Connect Provider doesn’t publish its JWKS at an https URL, or if you want to use a local copy, you can upload the JWKS as a file.
-
Prepare a ZIP file with a custom bundle that contains your OpenID Connect Provider’s JWKS file (
op_jwks.json
) inside of anoidc
folder.This bundle allows all Elasticsearch containers to access the metadata file.
-
Update your Elasticsearch cluster configuration using the advanced configuration editor to use the bundle you prepared in the previous step. You need to modify the
user_bundles
JSON attribute similar to the following example snippet:{ "cluster_name": "REPLACE_WITH_YOUR_CLUSTER_NAME", "plan": { ... "elasticsearch": { "version": "7.2.0", "user_bundles": [ { "name": "oidc-keys", "url": "https://www.MYURL.com/oidc-keys.zip", "elasticsearch_version": "7.*" } ] } }
The URLs that point to the ZIP file containing the bundle must be accessible to the deployment. Custom bundles are unzipped under the path
/app/config/BUNDLE_DIRECTORY_STRUCTURE
, whereBUNDLE_DIRECTORY_STRUCTURE
is the directory structure in the ZIP file. Make sure to save the file location where custom bundles get unzipped, as you will need it in the next step.In our example, the OpenID Connect Provider JWK set file will be located in the path
/app/config/oidc/op_jwks.json
:$ tree . . └── oidc └── op_jwks.json
-
Adjust your
oidc
realm configuration accordingly:
-
Configure SSL
editOpenID Connect depends on TLS to provider 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. As such, it is important that Elastic Cloud Enterprise 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 you OP is using a certificate from a trusted CA, no additional configuration is needed.
However, if your OP uses a certificate that is issued for instance, by a CA used only in your Organization, you must configure Elastic Cloud Enterprise to trust that CA.
-
Prepare a ZIP file with a
custom bundle
that contains the CA certificate (
company-ca.pem
) that signed the certificate your OpenID Connect Provider uses for TLS inside of anoidc-tls
folder -
Update your Elasticsearch cluster configuration using the advanced configuration editor to use the bundle you prepared in the previous step. You need to modify the
user_bundles
JSON attribute similar to the following example snippet:{ "cluster_name": "REPLACE_WITH_YOUR_CLUSTER_NAME", "plan": { ... "elasticsearch": { "version": "7.2.0", "user_bundles": [ { "name": "oidc-tls-ca", "url": "https://www.MYURL.com/oidc-tls-ca.zip", "elasticsearch_version": "7.*" } ] } }
The URLs that point to the ZIP file containing the bundle must be accessible to the deployment. Custom bundles are unzipped under the path
/app/config/BUNDLE_DIRECTORY_STRUCTURE
, whereBUNDLE_DIRECTORY_STRUCTURE
is the directory structure in the ZIP file. Make sure to save the file location where custom bundles get unzipped, as you will need it in the next step.In our example, the CA certificate file will be located in the path
/app/config/oidc-tls/company-ca.pem
:$ tree . . └── oidc-tls └── company-ca.pem
-
Adjust your
oidc
realm configuration accordingly:
Optional Settings
editThe following optional oidc realm settings are supported and can be set if needed:
-
op.endsession_endpoint
The URL to the End Session Endpoint in the OpenID Connect Provider. This is the endpoint where the user’s browser will be redirected after local logout, if the realm is configured for RP initiated Single Logout and the OP supports it. The value for this setting should be provided by your OpenID Connect Provider. -
rp.post_logout_redirect_uri
The Redirect URL where the OpenID Connect Provider should redirect the user after a successful Single Logout. This should be set to a value that will not trigger a new OpenID Connect Authentication,<KIBANA_ENDPOINT_URL>/logged_out
is a good choice for this parameter. -
rp.signature_algorithm
The signature algorithm that will be used by Elasticsearch in order to verify the signature of the ID tokens it will receive from the OpenID Connect Provider. Defaults toRSA256
. -
rp.requested_scopes
The scope values that will be requested by the OpenID Connect Provider as part of the Authentication Request. Defaults toopenid
, which is the only required scope for authentication. If your use case requires that you receive additional claims, you might need to request additional scopes, one ofprofile
,email
,address
,phone
. Note thatopenid
should always be included in the list of requested scopes.