{kib} supports the following authentication mechanisms:
Enable multiple authentication mechanisms at the same time specifying a prioritized list of the authentication providers (typically of various types) in the configuration. Providers are consulted in ascending order. Make sure each configured provider has a unique name (e.g. basic1 or saml1 in the configuration example) and order setting. In the event that two or more providers have the same name or order, {kib} will fail to start.
When two or more providers are configured, you can choose the provider you want to use on the Login Selector UI. The order the providers appear is determined by the order setting. The appearance of the specific provider entry can be customized with the description setting.
If you don’t want a specific provider to show up at the Login Selector UI (e.g. to only support third-party initiated login) you can hide it with showInSelector setting set to false. However, in this case, the provider is presented in the provider chain and may be consulted during authentication based on its order. To disable the provider, use the enabled setting.
|
Tip
|
The Login Selector UI can also be disabled or enabled with xpack.security.authc.selector.enabled setting.
|
Here is how your kibana.yml can look like if you deal with multiple authentication providers:
xpack.security.authc.providers:
basic.basic1:
order: 0
saml.saml1:
order: 1
realm: saml1
description: "Log in with SSO"
saml.saml2:
order: 2
realm: saml2
showInSelector: false
kerberos.kerberos1:
order: 3
enabled: false
To successfully log in to {kib}, basic authentication requires a username and password. Basic authentication is enabled by default, and is based on the Native, LDAP, or Active Directory security realm that is provided by {es}. The basic authentication provider uses a {kib} provided login form, and supports authentication using the Authorization request header Basic scheme.
The session cookies that are issued by the basic authentication provider are stateless. Therefore, logging out of {kib} when using the basic authentication provider clears the session cookies from the browser, but does not invalidate the session cookie for reuse.
|
Note
|
You can configure only one Basic provider per {kib} instance. |
For more information about basic authentication and built-in users, see {ref}/setting-up-authentication.html[User authentication].
Token authentication allows users to log in using the same {kib} provided login form as basic authentication, and is based on the Native security realm or LDAP security realm that is provided by {es}. The token authentication provider is built on {es} token APIs.
The session cookies that are issued by the token authentication provider are stateful, and logging out of {kib} invalidates the session cookies for reuse.
Prior to configuring {kib}, ensure token support is enabled in {es}. See the {ref}/security-api-get-token.html[{es} token API] documentation for more information.
To enable the token authentication provider in {kib}, set the following value in your kibana.yml:
|
Note
|
You can configure only one Token provider per {kib} instance. |
xpack.security.authc.providers:
token.token1:
order: 0Switching to the token authentication provider from basic one will make {kib} to reject requests from applications like curl that usually use Authorization request header with the Basic scheme for authentication. If you still want to support such applications you’ll have to either switch to using Bearer scheme with the tokens {ref}/security-api-get-token.html[created by {es} token API] or add Basic scheme to the list of supported schemes for the HTTP authentication.
|
Important
|
PKI authentication will not work if {kib} is hosted behind a TLS termination reverse proxy. In this configuration, {kib} does not have direct access to the client certificates and cannot authenticate the user. |
PKI authentication allows users to log into {kib} using X.509 client certificates that must be presented while connecting to {kib}. The certificates must first be accepted for authentication on the {kib} TLS layer, and then they are further validated by an {es} PKI realm. The PKI authentication provider relies on the {es} {ref}/security-api-delegate-pki-authentication.html[Delegate PKI authentication API] to exchange X.509 client certificates to access tokens. All subsequent requests to {es} APIs on behalf of users will be authenticated using these access tokens.
Prior to configuring {kib}, ensure that the PKI realm is enabled in {es} and configured to permit delegation. See {ref}/configuring-pki-realm.html[Configuring a PKI realm] for more information.
To enable the PKI authentication provider in {kib}, you must first configure {kib} to encrypt communications between the browser and {kib} server. You must also enable TLS client authentication and include the certificate authority (CA) used to sign client certificates into a list of CAs trusted by {kib} in your kibana.yml:
|
Note
|
You can configure only one PKI provider per {kib} instance. |
server.ssl.certificateAuthorities: /path/to/your/cacert.pem
server.ssl.clientAuthentication: required
xpack.security.authc.providers:
pki.pki1:
order: 0|
Note
|
Trusted CAs can also be specified in a PKCS #12 keystore bundled with your {kib} server certificate/key using
server.ssl.keystore.path or in a separate trust store using server.ssl.truststore.path.
|
You can also configure both PKI and basic authentication for the same {kib} instance:
xpack.security.authc.providers:
pki.pki1:
order: 0
basic.basic1:
order: 1Note that with server.ssl.clientAuthentication set to required, users are asked to provide a valid client certificate, even if they want to authenticate with username and password. Depending on the security policies, it may or may not be desired. If not, server.ssl.clientAuthentication can be set to optional. In this case, {kib} still requests a client certificate, but the client won’t be required to present one. The optional client authentication mode might also be needed in other cases, for example, when PKI authentication is used in conjunction with Reporting.
SAML authentication allows users to log in to {kib} with an external Identity Provider, such as Okta or Auth0. Make sure that SAML is enabled and configured in {es} before setting it up in {kib}. See {ref}/saml-guide.html[Configuring SAML single sign-on on the Elastic Stack].
Enable the SAML authentication specifying which SAML realm in {es} should be used:
xpack.security.authc.providers:
saml.saml1:
order: 0
realm: saml1You can log in to {kib} via SAML Single Sign-On by navigating directly to the {kib} URL. If you aren’t authenticated, you are redirected to the Identity Provider for login. Most Identity Providers maintain a long-lived session. If you log in to a different application using the same Identity Provider in the same browser, you are automatically authenticated. An exception is if {es} or the Identity Provider is configured to force you to re-authenticate. This login scenario is called Service Provider initiated login.
It’s also possible to configure multiple SAML authentication providers at the same time. In this case, you will need to choose which provider to use for login at the Login Selector UI:
xpack.security.authc.providers:
saml.saml1:
order: 0
realm: saml1
description: "Log in with Elastic"
saml.saml2:
order: 1
realm: saml2
description: "Log in with Auth0"You can also configure both SAML and basic authentication for the same {kib} instance. This might be the case for {kib} or {es} admins whose accounts aren’t linked to the Single Sign-On users database:
xpack.security.authc.providers:
saml.saml1:
order: 0
realm: saml1
description: "Log in with Elastic"
basic.basic1:
order: 1Basic authentication is supported only if the basic authentication provider is explicitly declared in xpack.security.authc.providers setting, in addition to saml.
To support basic authentication for the applications like curl or when the Authorization: Basic base64(username:password) HTTP header is included in the request (for example, by reverse proxy), add Basic scheme to the list of supported schemes for the HTTP authentication.
At the beginning of the SAML handshake, {kib} stores the initial URL in the session cookie, so it can redirect the user back to that URL after successful SAML authentication. If the URL is long, the session cookie might exceed the maximum size supported by the browser—typically 4KB for all cookies per domain. When this happens, the session cookie is truncated, or dropped completely, and you might experience sporadic failures during SAML authentication.
To remedy this issue, you can decrease the maximum size of the URL that {kib} is allowed to store during the SAML handshake. The default value is 2KB.
xpack.security.authc.providers:
saml.saml1:
order: 0
realm: saml1
maxRedirectURLSize: 1kbSimilar to SAML, authentication with OpenID Connect allows users to log in to {kib} using an OpenID Connect Provider such as Google, or Okta. OpenID Connect should also be configured in {es}. For more details, see {ref}/oidc-guide.html[Configuring single sign-on to the {stack} using OpenID Connect].
Enable the OpenID Connect authentication specifying which OpenID Connect realm in {es} should be used:
xpack.security.authc.providers:
oidc.oidc1:
order: 0
realm: oidc1If you want to use Third Party initiated Single Sign-On, configure your OpenID Provider to use /api/security/oidc/initiate_login as Initiate Login URI.
It’s also possible to configure multiple OpenID Connect authentication providers at the same time. In this case, you need to choose which provider to use for login at the Login Selector UI:
xpack.security.authc.providers:
oidc.oidc1:
order: 0
realm: oidc1
description: "Log in with Elastic"
oidc.oidc2:
order: 1
realm: oidc2
description: "Log in with Auth0"You can also configure both OpenID Connect and basic authentication for the same {kib} instance. This might be the case for {kib} or {es} admins whose accounts aren’t linked to the Single Sign-On users database:
xpack.security.authc.providers:
oidc.oidc1:
order: 0
realm: oidc1
description: "Log in with Elastic"
basic.basic1:
order: 1Basic authentication is supported only if the basic authentication provider is explicitly declared in xpack.security.authc.providers setting, in addition to oidc.
To support basic authentication for the applications like curl or when the Authorization: Basic base64(username:password) HTTP header is included in the request (for example, by reverse proxy), add Basic scheme to the list of supported schemes for the HTTP authentication.
The following sections apply both to SAML single sign-on and OpenID Connect single sign-on
Once the user logs in to {kib} Single Sign-On, either using SAML or OpenID Connect, {es} issues access and refresh tokens
that {kib} encrypts and stores them in its own session cookie. This way, the user isn’t redirected to the Identity Provider
for every request that requires authentication. It also means that the {kib} session depends on the xpack.security.session.idleTimeout and xpack.security.session.lifespan settings, and the user is automatically logged
out if the session expires. An access token that is stored in the session cookie can expire, in which case {kib} will
automatically renew it with a one-time-use refresh token and store it in the same cookie.
{kib} can only determine if an access token has expired if it receives a request that requires authentication. If both access and refresh tokens have already expired (for example, after 24 hours of inactivity), {kib} initiates a new "handshake" and redirects the user to the external authentication provider (SAML Identity Provider or OpenID Connect Provider) Depending on {es} and the external authentication provider configuration, the user might be asked to re-enter credentials.
If {kib} can’t redirect the user to the external authentication provider (for example, for AJAX/XHR requests), an error indicates that both access and refresh tokens are expired. Reloading the current {kib} page fixes the error.
During logout, both the {kib} session cookie and access/refresh token pair are invalidated. Even if the cookie has been leaked, it can’t be re-used after logout. This is known as "local" logout.
{kib} can also initiate a "global" logout or Single Logout if it’s supported by the external authentication provider and not explicitly disabled by {es}. In this case, the user is redirected to the external authentication provider for log out of all applications associated with the active provider session.
As with the previous SSOs, make sure that you have configured {es} first accordingly. See {ref}/kerberos-realm.html[Kerberos authentication].
Next, to enable Kerberos in {kib}, you will need to enable the Kerberos authentication provider in the kibana.yml configuration file, as follows:
|
Note
|
You can configure only one Kerberos provider per {kib} instance. |
xpack.security.authc.providers:
kerberos.kerberos1:
order: 0You may want to be able to authenticate with the basic authentication provider as a secondary mechanism or while you are setting up Kerberos for the stack:
xpack.security.authc.providers:
kerberos.kerberos1:
order: 0
description: "Log in with Kerberos"
basic.basic1:
order: 1Kibana uses SPNEGO, which wraps the Kerberos protocol for use with HTTP, extending it to web applications. At the end of the Kerberos handshake, Kibana will forward the service ticket to Elasticsearch. Elasticsearch will unpack it and it will respond with an access and refresh token which are then used for subsequent authentication.
|
Important
|
Be very careful when you modify HTTP authentication settings as it may indirectly affect other important {kib} features that implicitly rely on HTTP authentication (e.g. Reporting). |
HTTP protocol provides a simple authentication framework that can be used by a client to provide authentication information. It uses a case-insensitive token as a means to identify the authentication scheme, followed by additional information necessary for achieving authentication via that scheme.
This type of authentication is usually useful for machine-to-machine interaction that requires authentication and where human intervention is not desired or just infeasible. There are a number of use cases when HTTP authentication support comes in handy for {kib} users as well.
By default {kib} supports ApiKey authentication scheme and any scheme supported by the currently enabled authentication provider. For example, Basic authentication scheme is automatically supported when basic authentication provider is enabled, or Bearer scheme when any of the token based authentication providers is enabled (Token, SAML, OpenID Connect, PKI or Kerberos). But it’s also possible to add support for any other authentication scheme in the kibana.yml configuration file, as follows:
|
Note
|
Don’t forget to explicitly specify default apikey scheme when you just want to add a new one to the list.
|
xpack.security.authc.http.schemes: [apikey, basic, something-custom]With this configuration, you can send requests to {kib} with the Authorization header using ApiKey, Basic or Something-Custom HTTP schemes (case insensitive). Under the hood, {kib} relays this header to {es}, then {es} authenticates the request using the credentials in the header.