From 9ffeb171e0c460449e132840c29ae598a36fafb5 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Tue, 22 May 2018 08:50:35 -0700 Subject: [PATCH] [DOCS] Add SAML configuration information (#30548) --- .../configuring-saml-realm.asciidoc | 225 ++++++++++++++++++ .../authentication/saml-guide.asciidoc | 2 + .../docs/en/security/configuring-es.asciidoc | 2 + 3 files changed, 229 insertions(+) create mode 100644 x-pack/docs/en/security/authentication/configuring-saml-realm.asciidoc diff --git a/x-pack/docs/en/security/authentication/configuring-saml-realm.asciidoc b/x-pack/docs/en/security/authentication/configuring-saml-realm.asciidoc new file mode 100644 index 0000000000000..cbcbeebb359ef --- /dev/null +++ b/x-pack/docs/en/security/authentication/configuring-saml-realm.asciidoc @@ -0,0 +1,225 @@ +[role="xpack"] +[[configuring-saml-realm]] +=== Configuring a SAML realm + +The {stack} supports Security Assertion Markup Language Single Sign On (SAML SSO) +into {kib} with {es} as a backend service. In particular, the {stack} supports +the SAML 2.0 Web Browser SSO and the SAML 2.0 Single Logout profiles. It can +integrate with any identity provider (IdP) that supports at least the SAML 2.0 +Web Browser SSO Profile. + +In SAML terminology, the {stack} is operating as a _service provider_ (SP). For more +information, see {stack-ov}/saml-realm.html[SAML authentication] and +{stack-ov}/saml-guide.html[Configuring SAML SSO on the {stack}]. + +[NOTE] +-- + +* If you configure a SAML realm for use in {kib}, you should also configure +another realm, such as the native realm in your authentication chain. +* These instructions assume that you have an existing SAML identity provider. +-- + +To enable SAML authentication in {es} and add the {stack} as a service provider: + +. Enable SSL/TLS for HTTP. ++ +-- +If your {es} cluster is operating in production mode, you must +configure the HTTP interface to use TLS before you can enable SAML +authentication. + +See <>. +-- + +. 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. You can +explicitly enable it by including the following setting in your +`elasticsearch.yml` file: + +[source, yaml] +------------------------------------------------------------ +xpack.security.authc.token.enabled: true +------------------------------------------------------------ +-- + +. Configure a SAML IdP metadata file. ++ +-- +The {stack} uses a standard SAML metadata document in XML format, which defines +the capabilities and features of your identity provider. You should be able to +download or generate such a document within your IdP administration interface. + +Most IdPs will provide an appropriate metadata file with all the features that +the {stack} requires. For more information, see +{stack-ov}/saml-guide-idp.html[The identity provider]. +-- + +.. Download the IdP metadata document and store it within the `config` directory +on each {es} node. For example, store it as `config/saml/idp-metadata.xml`. + +.. Get the identifier for your identity provider. ++ +-- +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 might 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. +-- + +. Create one or more SAML realms. ++ +-- +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 +<>. The following settings (in the `elasticsearch.yml` +configuration file) are the most common settings: + +[source, yaml] +------------------------------------------------------------ +xpack.security.authc.realms.saml1: <1> + type: saml <2> + order: 2 <3> + idp.metadata.path: saml/idp-metadata.xml <4> + idp.entity_id: "https://sso.example.com/" <5> + sp.entity_id: "https://kibana.example.com/" <6> + sp.acs: "https://kibana.example.com/api/security/v1/saml" <7> + sp.logout: "https://kibana.example.com/logout" <8> +------------------------------------------------------------ +<1> This setting defines a new authentication realm named "saml1". For an +introduction to realms, see {stack-ov}/realms.html[Realms]. +<2> The `type` must be `saml`. +<3> 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, it has the _highest_ order). +<4> 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} +automatically monitors this file for changes and reloads the configuration +whenever it is updated. +<5> This is the identifier (SAML EntityID) that your IdP uses. It should match +the `entityID` attribute within the metadata file. +<6> 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. +<7> 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 can vary depending on +how you have installed {kib} and whether there are any proxies involved, but it +is typically +$\{kibana-url}/api/security/v1/saml+ where _$\{kibana-url}_ is the +base URL for your {kib} instance. +<8> 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 can +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. + +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 in your authentication chain for use by API clients. + +For more information, see +{stack-ov}/saml-guide-authentication.html#saml-create-realm[Create a SAML realm]. +-- + +. Add attribute mappings. ++ +-- +When a user connects to {kib} through the identity provider, the IdP supplies a +SAML assertion that includes attributes for the user. You can configure the SAML +realm to map these attributes to properties on the authenticated user. + +The recommended steps for configuring these SAML attributes are as follows: +-- +.. Consult your IdP to see what user attributes it can provide. This varies +greatly between providers, but you should be able to obtain a list from the +documentation or from your local admin. + +.. Read through the list of user properties that {es} supports and decide which +of them are useful to you and can be provided by your IdP. At a minimum, the +`principal` attribute is required. The `groups` attribute is recommended. + +.. Configure your IdP to release those attributes to your {kib} SAML service +provider. ++ +-- +This process varies by provider - some provide a user interface for this, while +others might require that you edit configuration files. Usually the IdP (or your +local administrator) have suggestions about what URI to use for each attribute. +You can simply accept those suggestions, as the {es} service is entirely +configurable and does not require that any specific URIs are used. +-- + +.. Configure the SAML realm to associate the {es} user properties to the URIs +that you configured in your IdP. ++ +-- +For example, add the following settings to the `elasticsearch.yml` configuration +file: + +[source, yaml] +------------------------------------------------------------ +xpack.security.authc.realms.saml1: + ... + 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." +------------------------------------------------------------ + +For more information, see +{stack-ov}/saml-guide-authentication.html#saml-attribute-mapping[Attribute mapping]. +-- + +. (Optional) Configure logout services. ++ +-- +The SAML protocol supports the concept of Single Logout (SLO). The level of +support for SLO varies between identity providers. + +For more information, see +{stack-ov}/saml-guide-authentication.html#saml-logout[SAML logout]. +-- + +. (Optional) Configure encryption and signing. ++ +-- +The {stack} supports generating signed SAML messages (for authentication and/or +logout), verifying signed SAML messages from the IdP (for both authentication +and logout), and processing encrypted content. + +You can configure {es} for signing, encryption, or both, with the same or +separate keys. For more information, see +{stack-ov}/saml-guide-authentication.html#saml-enc-sign[Encryption and signing]. +-- + +. (Optional) Generate service provider metadata. ++ +-- +There are some extra configuration steps that are specific to each identity +provider. If your identity provider can import SP metadata, some of those steps +can be automated or expedited. You can generate SP metadata for the {stack} by +using the <>. +-- + +. Configure role mappings. ++ +-- +When a user authenticates using SAML, they are identified to the {stack}, +but this does not automatically grant them access to perform any actions or +access any data. + +Your SAML users cannot do anything until they are mapped to {security} +roles. See {stack-ov}/saml-role-mapping.html[Configuring role mappings]. +-- + +. {stack-ov}/saml-kibana.html[Configure {kib} to use SAML SSO]. + diff --git a/x-pack/docs/en/security/authentication/saml-guide.asciidoc b/x-pack/docs/en/security/authentication/saml-guide.asciidoc index 740f51c877ded..a57cfaec84c43 100644 --- a/x-pack/docs/en/security/authentication/saml-guide.asciidoc +++ b/x-pack/docs/en/security/authentication/saml-guide.asciidoc @@ -22,6 +22,7 @@ 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 <> section provides more detail about how this works. +[[saml-guide-idp]] === The identity provider The Elastic Stack supports the SAML 2.0 _Web Browser SSO_ and the SAML @@ -70,6 +71,7 @@ For `` messages, the message itself must be signed, and the signature should be provided as a URL parameter, as required by the HTTP-Redirect binding. +[[saml-guide-authentication]] === Configure {es} for SAML authentication There are five configuration steps to enable SAML authentication in {es}: diff --git a/x-pack/docs/en/security/configuring-es.asciidoc b/x-pack/docs/en/security/configuring-es.asciidoc index de3895d34b000..d8ef6c2809b34 100644 --- a/x-pack/docs/en/security/configuring-es.asciidoc +++ b/x-pack/docs/en/security/configuring-es.asciidoc @@ -76,6 +76,7 @@ user API. ** <>. ** <>. ** <>. +** <>. . Set up roles and users to control access to {es}. For example, to grant _John Doe_ full access to all indices that match @@ -140,5 +141,6 @@ include::authentication/configuring-file-realm.asciidoc[] include::authentication/configuring-ldap-realm.asciidoc[] include::authentication/configuring-native-realm.asciidoc[] include::authentication/configuring-pki-realm.asciidoc[] +include::authentication/configuring-saml-realm.asciidoc[] include::{xes-repo-dir}/settings/security-settings.asciidoc[] include::{xes-repo-dir}/settings/audit-settings.asciidoc[]