[role="xpack"]
[[security-settings-kb]]
=== Security settings in {kib}
++++
<titleabbrev>Security settings</titleabbrev>
++++

You do not need to configure any additional settings to use the
{security-features} in {kib}. They are enabled by default.

[float]
[[general-security-settings]]
==== General security settings

[cols="2*<"]
|===
| `xpack.security.enabled`
  | By default, {kib} automatically detects whether to enable the
  {security-features} based on the license and whether {es} {security-features}
  are enabled. +
  +
  Do not set this to `false`; it disables the login form, user and role management
  screens, and authorization using <<kibana-privileges>>. To disable
  {security-features} entirely, see
  {ref}/security-settings.html[{es} security settings].

| `xpack.security.audit.enabled`
  | Set to `true` to enable audit logging for security events. By default, it is set
  to `false`. For more details see <<xpack-security-audit-logging>>.

|===

[float]
[[authentication-security-settings]]
==== Authentication security settings

You configure authentication settings in the `xpack.security.authc` namespace in `kibana.yml`.

For example:

[source,yaml]
----------------------------------------
xpack.security.authc:
    providers:
      basic.basic1: <1>
          order: 0 <2>
          ...

      saml.saml1: <3>
          order: 1
          ...
  
      saml.saml2: <4>
          order: 2
          ...
  
      pki.realm3:
          order: 3
          ...
    ...
----------------------------------------
<1> Specifies the type of authentication provider (for example, `basic`, `token`, `saml`, `oidc`, `kerberos`, `pki`) and the provider name. This setting is mandatory.
<2> Specifies the order of the provider in the authentication chain and on the Login Selector UI. This setting is mandatory.
<3> Specifies the settings for the SAML authentication provider with a `saml1` name.
<4> Specifies the settings for the SAML authentication provider with a `saml2` name.

The valid settings in the `xpack.security.authc.providers` namespace vary depending on the authentication provider type. For more information, refer to <<kibana-authentication>>.

[float]
[[authentication-provider-settings]]
===== Valid settings for all authentication providers

[cols="2*<"]
|===
| `xpack.security.authc.providers.`
`<provider-type>.<provider-name>.enabled` {ess-icon}
| Determines if the authentication provider should be enabled. By default, {kib} enables the provider as soon as you configure any of its properties.

| `xpack.security.authc.providers.`
`<provider-type>.<provider-name>.order` {ess-icon}
| Order of the provider in the authentication chain and on the Login Selector UI.

| `xpack.security.authc.providers.`
`<provider-type>.<provider-name>.description` {ess-icon}
| Custom description of the provider entry displayed on the Login Selector UI.

| `xpack.security.authc.providers.`
`<provider-type>.<provider-name>.hint` {ess-icon}
| Custom hint for the provider entry displayed on the Login Selector UI.

| `xpack.security.authc.providers.`
`<provider-type>.<provider-name>.icon` {ess-icon}
| Custom icon for the provider entry displayed on the Login Selector UI.

| `xpack.security.authc.providers.`
`<provider-type>.<provider-name>.showInSelector` {ess-icon}
| Flag that indicates if the provider should have an entry on the Login Selector UI. Setting this to `false` doesn't remove the provider from the authentication chain.

2+a|
[TIP]
[NOTE]
============
You are unable to set this setting to `false` for `basic` and `token` authentication providers.
============

| `xpack.security.authc.providers.`
`<provider-type>.<provider-name>.accessAgreement.message` {ess-icon}
| Access agreement text in Markdown format. For more information, refer to <<xpack-security-access-agreement>>.

|===

[float]
[[saml-authentication-provider-settings]]
===== SAML authentication provider settings

In addition to <<authentication-provider-settings,the settings that are valid for all providers>>, you can specify the following settings:

[cols="2*<"]
|===
| `xpack.security.authc.providers.`
`saml.<provider-name>.realm` {ess-icon}
| SAML realm in {es} that provider should use.

| `xpack.security.authc.providers.`
`saml.<provider-name>.useRelayStateDeepLink` {ess-icon}
| Determines if the provider should treat the `RelayState` parameter as a deep link in {kib} during Identity Provider initiated log in. By default, this setting is set to `false`. The link specified in `RelayState` should be a relative, URL-encoded {kib} URL. For example, the `/app/dashboards#/list` link in `RelayState` parameter would look like this: `RelayState=%2Fapp%2Fdashboards%23%2Flist`.

|===

[float]
[[oidc-authentication-provider-settings]]
===== OpenID Connect authentication provider settings

In addition to <<authentication-provider-settings,the settings that are valid for all providers>>, you can specify the following settings:

[cols="2*<"]
|===
| `xpack.security.authc.providers.`
`oidc.<provider-name>.realm` {ess-icon}
| OpenID Connect realm in {es} that the provider should use.

|===

[float]
[[http-authentication-settings]]
===== HTTP authentication settings

There is a very limited set of cases when you'd want to change these settings. For more information, refer to <<http-authentication>>.

[cols="2*<"]
|===
| `xpack.security.authc.http.enabled`
| Determines if HTTP authentication should be enabled. By default, this setting is set to `true`.

| `xpack.security.authc.http.autoSchemesEnabled`
| Determines if HTTP authentication schemes used by the enabled authentication providers should be automatically supported during HTTP authentication. By default, this setting is set to `true`.

| `xpack.security.authc.http.schemes`
| List of HTTP authentication schemes that {kib} HTTP authentication should support. By default, this setting is set to `['apikey']` to support HTTP authentication with <<api-keys, `ApiKey`>> scheme.

|===

[float]
[[login-ui-settings]]
===== Login user interface settings

You can configure the following settings in the `kibana.yml` file.

[cols="2*<"]
|===
| `xpack.security.loginAssistanceMessage` {ess-icon}
| Adds a message to the login UI. Useful for displaying information about maintenance windows, links to corporate sign up pages, and so on.

| `xpack.security.loginHelp` {ess-icon}
| Adds a message accessible at the login UI with additional help information for the login process.

| `xpack.security.authc.selector.enabled` {ess-icon}
| Determines if the login selector UI should be enabled. By default, this setting is set to `true` if more than one authentication provider is configured.

|===

[float]
[[security-session-and-cookie-settings]]
==== Session and cookie security settings

You can configure the following settings in the `kibana.yml` file.

[cols="2*<"]
|===
| `xpack.security.cookieName`
  | Sets the name of the cookie used for the session. The default value is `"sid"`.

| `xpack.security.encryptionKey`
  | An arbitrary string of 32 characters or more that is used to encrypt session information. Do **not** expose this key to users of {kib}. By
  default, a value is automatically generated in memory. If you use that default
  behavior, all sessions are invalidated when {kib} restarts.
  In addition, high-availability deployments of {kib} will behave unexpectedly
  if this setting isn't the same for all instances of {kib}.

| `xpack.security.secureCookies`
  | Sets the `secure` flag of the session cookie. The default value is `false`. It
  is automatically set to `true` if `server.ssl.enabled` is set to `true`. Set
  this to `true` if SSL is configured outside of {kib} (for example, you are
  routing requests through a load balancer or proxy).

| `xpack.security.sameSiteCookies` {ess-icon}
  | Sets the `SameSite` attribute of the session cookie. This allows you to declare whether your cookie should be restricted to a first-party or same-site context.
  Valid values are `Strict`, `Lax`, `None`.
  This is *not set* by default, which modern browsers will treat as `Lax`. If you use Kibana embedded in an iframe in modern browsers, you might need to set it to `None`. Setting this value to `None` requires cookies to be sent over a secure connection by setting `xpack.security.secureCookies: true`.

| `xpack.security.session.idleTimeout` {ess-icon}
  | Ensures that user sessions will expire after a period of inactivity. This and `xpack.security.session.lifespan` are both
highly recommended. By default, this setting is not set.

2+a|
[TIP]
============
The format is a string of `<count>[ms\|s\|m\|h\|d\|w\|M\|Y]` (e.g. '20m', '24h', '7d', '1w').
============

| `xpack.security.session.lifespan` {ess-icon}
  | Ensures that user sessions will expire after the defined time period. This behavior also known as an "absolute timeout". If
this is _not_ set, user sessions could stay active indefinitely. This and `xpack.security.session.idleTimeout` are both highly
recommended. By default, this setting is not set.

2+a|
[TIP]
============
The format is a string of `<count>[ms\|s\|m\|h\|d\|w\|M\|Y]` (e.g. '20m', '24h', '7d', '1w').
============

| `xpack.security.session.cleanupInterval`
| Sets the interval at which {kib} tries to remove expired and invalid sessions from the session index. By default, this value is 1 hour. The minimum value is 10 seconds.

2+a|
[TIP]
============
The format is a string of `<count>[ms\|s\|m\|h\|d\|w\|M\|Y]` (e.g. '20m', '24h', '7d', '1w').
============

|===