<commit_before>[[saml-guide]]

== Configuring SAML Single-Sign-On on the Elastic Stack

The Elastic Stack supports SAML single-sign-on (SSO) into {kib}, using {es} as
a backend service. In SAML terminology, the Elastic Stack is operating as a
_Service Provider_.

The other component that is needed to enable SAML single-sign-on is the
_Identity Provider_, which is a service that handles your credentials and
performs that actual authentication of users.

If you are interested in configuring SSO into {kib}, then you will need to
provide {es} with information about your _Identity Provider_, and you will need
to register the Elastic Stack as a known _Service Provider_ within that
Identity Provider.  There are also a few configuration changes that are
required in {kib} to activate the SAML authentication provider.

NOTE: The SAML support in {kib} is designed on the expectation that it will be
the primary (or sole) authentication method for users of that {kib} instance.
Once you enable SAML authentication in {kib} it will affect all users who try
to login. The <<saml-kibana>> section provides more detail about how this works.

=== The Identity Provider

The Elastic Stack supports the SAML 2.0 _Web Browser SSO_ and the SAML
2.0 _Single Logout_ profiles and can integrate with any Identity Provider (IdP)
that supports at least the SAML 2.0 _Web Browser SSO Profile_.
It has been tested with a number of popular IdP implementations.

This guide assumes that you have an existing IdP and wish to add {kib} as a
Service Provider.

The Elastic Stack uses a standard SAML _metadata_ document, in XML format that
defines the capabilities and features of your IdP. You should be able to
download or generate such a document within your IdP administration interface.

Download the IdP metadata document and store it within the `config` directory on
each {es} node. For the purposes of this guide, we will assume that you are
storing it as `config/saml/idp-metadata.xml`.

The IdP will have been assigned an identifier (_EntityID_ in SAML terminology)
which is most commonly expressed in _Uniform Resource Identifier_ (URI) form.
Your admin interface may tell you what this is, or you might need to
read the metadata document to find it - look for the `entityID` attribute on the
`EntityDescriptor` element.

Most IdPs will provide an appropriate metadata file with all the features that
the Elastic Stack requires, and should only require the  configuration steps
described below. For completeness sake, the minimum requirements that the Elastic
Stack has for the IdP's metadata are:

- An `<EntityDescriptor>` with an `entityID` that matches the {es}
  <<saml-create-realm, configuration>>
- An `<IDPSSODescriptor>` that supports the SAML 2.0 protocol
  (`urn:oasis:names:tc:SAML:2.0:protocol`).
- At least one `<KeyDescriptor>` that is configured for _signing_ (that is, it
  has `use="signing"` or leaves the `use` unspecified)
- A `<SingleSignOnService>` with binding of HTTP-Redirect
  (`urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect`)
- If you wish to support <<saml-logout, Single Logout>>, a `<SingleLogoutService>`
  with binding of HTTP-Redirect
  (`urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect`)

The Elastic Stack requires that all messages from the IdP are signed.
For authentication `<Response>` messages, the signature may be applied to either
the response itself, or to the individual assertions.
For `<LogoutRequest>` messages, the message itself must be signed, and the
signature should be provided as a URL parameter, as required by the HTTP-Redirect
binding.

=== Configure {es} for SAML Authentication

There are five configuration steps to enable SAML authentication in {es}:

. Enable SSL/TLS for HTTP
. Enable the Token Service
. Create one or more SAML realms
. Configure role mappings
. Generate a SAML Metadata file for use by your Identity Provider _(optional)_

==== Enable TLS for HTTP

If your {es} cluster is operating in production mode, then you must
configure the HTTP interface to use SSL/TLS before you can enable SAML
authentication.

See <<enable-ssl>> for instructions on how to do this.

==== Enable the Token Service

The {es} SAML implementation makes use of the {es} 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:

[source, yaml]
------------------------------------------------------------
xpack.security.authc.token.enabled: true
------------------------------------------------------------

[[saml-create-realm]]
==== Create a SAML Realm

SAML authentication is enabled by configuring a SAML realm within the
authentication chain for {es}.

This realm has a few mandatory settings, and a number of optional settings.
The available settings are described in detail in the
<<saml-settings, SAML realm documentation>>, this guide will walk you through
the most common settings.

Create a realm by adding the following to your `elasticsearch.yml`
configuration file. Each configuration value is explained below.

[source, yaml]
------------------------------------------------------------
xpack.security.authc.realms.saml1:
  type: saml
  order: 2
  idp.metadata.path: saml/idp-metadata.xml
  idp.entity_id: "https://sso.example.com/"
  sp.entity_id:  "https://kibana.example.com/"
  sp.acs: "https://kibana.example.com/api/security/v1/saml"
  sp.logout: "https://kibana.example.com/logout"
  attributes.principal: "urn:oid:0.9.2342.19200300.100.1.1"
  attributes.groups: "urn:oid:1.3.6.1.4.1.5923.1.5.1."
------------------------------------------------------------

IMPORTANT: SAML is used when authenticating via {kib}, but it is not an
effective means of authenticating directly to the {es} REST API. For this reason
we recommend that you include at least one additional realm such as the
<<native-realm, native realm>> in your authentication chain for use by API
clients.

The configuration values used in the example above are:

xpack.security.authc.realms.saml::
    This defines a new authentication realm named "saml1".
    See <<how-authc-works>> for more explanation of realms.

type:: The `type` must be `saml`
order::
    You should define a unique order on each realm in your authentication chain.
    It is recommended that the SAML realm be at the bottom of your authentication
    chain (that is, that it has the _highest_ order).

idp.metadata.path::
    This is the path to the metadata file that you saved for your Identity Provider.
    The path that you enter here is relative to your `config/` directory.
    {security} will automatically monitor this file for changes and will
    reload the configuration whenever it is updated.

idp.entity_id::
    This is the identifier (SAML EntityID) that your IdP uses.
    It should match the `entityID` attribute within the metadata file.

sp.entity_id::
    This is a unique identifier for your {kib} instance, expressed as a URI.
    You will use this value when you add {kib} as a service provider within your IdP.
    We recommend that you use the base URL for your {kib} instance as the entity ID.

sp.acs::
    The _Assertion Consumer Service_ (ACS) endpoint is the URL within {kib} that accepts
    authentication messages from the IdP.
    This ACS endpoint supports the SAML HTTP-POST binding only.
    It must be a URL that is accessible from the web browser of the user who is
    attempting to login to {kib}, it does not need to be directly accessible by {es}
    or the IdP.
    The correct value may vary depending on how you have installed {kib} and
    whether there are any proxies involved, but it will typically be
    `${kibana-url}/api/security/v1/saml` where _${kibana-url}_ is the base URL for
    your {kib} instance.

sp.logout::
    This is the URL within {kib} that accepts logout messages from the IdP.
    Like the `sp.acs` URL, it must be accessible from the web browser, but does
    not need to be directly accessible by {es} or the IdP. The correct value may
    vary depending on how you have installed {kib} and whether there are any
    proxies involved, but it will typically be `${kibana-url}/logout` where
    _${kibana-url}_ is the base URL for your {kib} instance.

attribute.principal:: See <<saml-attribute-mapping>>.
attribute.groups:: See <<saml-attribute-mapping>>.

[[saml-attribute-mapping]]
==== Attribute Mapping

When a user connects to {kib} through your Identity Provider, the Identity
Provider will supply a SAML Assertion about the user. The assertion will contain
an _Authentication Statement_ indicating that the user has successfully<commit_msg>[DOCS] Fix broken format in SAML guide<commit_after>[[saml-guide]]

== Configuring SAML Single-Sign-On on the Elastic Stack

The Elastic Stack supports SAML single-sign-on (SSO) into {kib}, using {es} as
a backend service. In SAML terminology, the Elastic Stack is operating as a
_Service Provider_.

The other component that is needed to enable SAML single-sign-on is the
_Identity Provider_, which is a service that handles your credentials and
performs that actual authentication of users.

If you are interested in configuring SSO into {kib}, then you will need to
provide {es} with information about your _Identity Provider_, and you will need
to register the Elastic Stack as a known _Service Provider_ within that
Identity Provider.  There are also a few configuration changes that are
required in {kib} to activate the SAML authentication provider.

NOTE: The SAML support in {kib} is designed on the expectation that it will be
the primary (or sole) authentication method for users of that {kib} instance.
Once you enable SAML authentication in {kib} it will affect all users who try
to login. The <<saml-kibana>> section provides more detail about how this works.

=== The Identity Provider

The Elastic Stack supports the SAML 2.0 _Web Browser SSO_ and the SAML
2.0 _Single Logout_ profiles and can integrate with any Identity Provider (IdP)
that supports at least the SAML 2.0 _Web Browser SSO Profile_.
It has been tested with a number of popular IdP implementations.

This guide assumes that you have an existing IdP and wish to add {kib} as a
Service Provider.

The Elastic Stack uses a standard SAML _metadata_ document, in XML format that
defines the capabilities and features of your IdP. You should be able to
download or generate such a document within your IdP administration interface.

Download the IdP metadata document and store it within the `config` directory on
each {es} node. For the purposes of this guide, we will assume that you are
storing it as `config/saml/idp-metadata.xml`.

The IdP will have been assigned an identifier (_EntityID_ in SAML terminology)
which is most commonly expressed in _Uniform Resource Identifier_ (URI) form.
Your admin interface may tell you what this is, or you might need to
read the metadata document to find it - look for the `entityID` attribute on the
`EntityDescriptor` element.

Most IdPs will provide an appropriate metadata file with all the features that
the Elastic Stack requires, and should only require the  configuration steps
described below. For completeness sake, the minimum requirements that the Elastic
Stack has for the IdP's metadata are:

- An `<EntityDescriptor>` with an `entityID` that matches the {es}
  <<saml-create-realm, configuration>>
- An `<IDPSSODescriptor>` that supports the SAML 2.0 protocol
  (`urn:oasis:names:tc:SAML:2.0:protocol`).
- At least one `<KeyDescriptor>` that is configured for _signing_ (that is, it
  has `use="signing"` or leaves the `use` unspecified)
- A `<SingleSignOnService>` with binding of HTTP-Redirect
  (`urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect`)
- If you wish to support <<saml-logout, Single Logout>>, a `<SingleLogoutService>`
  with binding of HTTP-Redirect
  (`urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect`)

The Elastic Stack requires that all messages from the IdP are signed.
For authentication `<Response>` messages, the signature may be applied to either
the response itself, or to the individual assertions.
For `<LogoutRequest>` messages, the message itself must be signed, and the
signature should be provided as a URL parameter, as required by the HTTP-Redirect
binding.

=== Configure {es} for SAML Authentication

There are five configuration steps to enable SAML authentication in {es}:

. Enable SSL/TLS for HTTP
. Enable the Token Service
. Create one or more SAML realms
. Configure role mappings
. Generate a SAML Metadata file for use by your Identity Provider _(optional)_

==== Enable TLS for HTTP

If your {es} cluster is operating in production mode, then you must
configure the HTTP interface to use SSL/TLS before you can enable SAML
authentication.

See <<enable-ssl>> for instructions on how to do this.

==== Enable the Token Service

The {es} SAML implementation makes use of the {es} 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:

[source, yaml]
------------------------------------------------------------
xpack.security.authc.token.enabled: true
------------------------------------------------------------

[[saml-create-realm]]
==== Create a SAML Realm

SAML authentication is enabled by configuring a SAML realm within the
authentication chain for {es}.

This realm has a few mandatory settings, and a number of optional settings.
The available settings are described in detail in the
<<saml-settings, SAML realm documentation>>, this guide will walk you through
the most common settings.

Create a realm by adding the following to your `elasticsearch.yml`
configuration file. Each configuration value is explained below.

[source, yaml]
------------------------------------------------------------
xpack.security.authc.realms.saml1:
  type: saml
  order: 2
  idp.metadata.path: saml/idp-metadata.xml
  idp.entity_id: "https://sso.example.com/"
  sp.entity_id:  "https://kibana.example.com/"
  sp.acs: "https://kibana.example.com/api/security/v1/saml"
  sp.logout: "https://kibana.example.com/logout"
  attributes.principal: "urn:oid:0.9.2342.19200300.100.1.1"
  attributes.groups: "urn:oid:1.3.6.1.4.1.5923.1.5.1."
------------------------------------------------------------

IMPORTANT: SAML is used when authenticating via {kib}, but it is not an
effective means of authenticating directly to the {es} REST API. For this reason
we recommend that you include at least one additional realm such as the
<<native-realm, native realm>> in your authentication chain for use by API
clients.

The configuration values used in the example above are:

xpack.security.authc.realms.saml::
    This defines a new authentication realm named "saml1".
    See <<how-authc-works>> for more explanation of realms.

type:: The `type` must be `saml`
order::
    You should define a unique order on each realm in your authentication chain.
    It is recommended that the SAML realm be at the bottom of your authentication
    chain (that is, that it has the _highest_ order).

idp.metadata.path::
    This is the path to the metadata file that you saved for your Identity Provider.
    The path that you enter here is relative to your `config/` directory.
    {security} will automatically monitor this file for changes and will
    reload the configuration whenever it is updated.

idp.entity_id::
    This is the identifier (SAML EntityID) that your IdP uses.
    It should match the `entityID` attribute within the metadata file.

sp.entity_id::
    This is a unique identifier for your {kib} instance, expressed as a URI.
    You will use this value when you add {kib} as a service provider within your IdP.
    We recommend that you use the base URL for your {kib} instance as the entity ID.

sp.acs::
    The _Assertion Consumer Service_ (ACS) endpoint is the URL within {kib} that accepts
    authentication messages from the IdP.
    This ACS endpoint supports the SAML HTTP-POST binding only.
    It must be a URL that is accessible from the web browser of the user who is
    attempting to login to {kib}, it does not need to be directly accessible by {es}
    or the IdP.
    The correct value may vary depending on how you have installed {kib} and
    whether there are any proxies involved, but it will typically be
    +$\{kibana-url}/api/security/v1/saml+ where _$\{kibana-url}_ is the base URL for
    your {kib} instance.

sp.logout::
    This is the URL within {kib} that accepts logout messages from the IdP.
    Like the `sp.acs` URL, it must be accessible from the web browser, but does
    not need to be directly accessible by {es} or the IdP. The correct value may
    vary depending on how you have installed {kib} and whether there are any
    proxies involved, but it will typically be +$\{kibana-url}/logout+ where
    _$\{kibana-url}_ is the base URL for your {kib} instance.

attribute.principal:: See <<saml-attribute-mapping>>.
attribute.groups:: See <<saml-attribute-mapping>>.

[[saml-attribute-mapping]]
==== Attribute Mapping

When a user connects to {kib} through your Identity Provider, the Identity
Provider will supply a SAML Assertion about the user. The assertion will contain
an _Authentication Statement_ indicating that the user has successfully
{'fraction_non_alphanumeric': 0.09231654676258993, 'fraction_numerical': 0.005870503597122302, 'mean_word_length': 3.7102195716996476, 'pattern_counts': {'":': 0, '<': 53, '<?xml version=': 0, '>': 53, 'https://': 8, 'lorem ipsum': 0, 'www.': 0, 'xml': 4}, 'pii_count': 6, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6737789', 'n_tokens_mistral': 4786, 'n_tokens_neox': 4599, 'n_words': 2391}