Document xpack.security.authc.saml.realm for Kibana (#44705)

Since 7.3, it's possible to explicitly configure the SAML realm to
be used in Kibana's configuration. This in turn, eliminates the need
of properly setting `xpack.security.public.*` settings in Kibana
and largely simplifies relevant documentation.
This also changes `xpack.security.authProviders` to
`xpack.security.authc.providers` as the former was deprecated in
favor of the latter in 7.3 in Kibana
This commit is contained in:
Ioannis Kakavas 2019-07-26 09:37:45 +03:00
parent 821f6f893b
commit ac131f986b
1 changed files with 10 additions and 34 deletions

View File

@ -733,20 +733,25 @@ SAML authentication in {kib} is also subject to the
`xpack.security.sessionTimeout` setting that is described in the {kib} security `xpack.security.sessionTimeout` setting that is described in the {kib} security
documentation, and you may wish to adjust this timeout to meet your local needs. documentation, and you may wish to adjust this timeout to meet your local needs.
The two additional settings that are required for SAML support are shown below: The three additional settings that are required for SAML support are shown below:
[source, yaml] [source, yaml]
------------------------------------------------------------ ------------------------------------------------------------
xpack.security.authProviders: [saml] xpack.security.authc.providers: [saml]
xpack.security.authc.saml.realm: saml1
server.xsrf.whitelist: [/api/security/v1/saml] server.xsrf.whitelist: [/api/security/v1/saml]
------------------------------------------------------------ ------------------------------------------------------------
The configuration values used in the example above are: The configuration values used in the example above are:
`xpack.security.authProviders`:: `xpack.security.authc.providers`::
Set this to `[ saml ]` to instruct {kib} to use SAML SSO as the authentication Set this to `[ saml ]` to instruct {kib} to use SAML SSO as the authentication
method. method.
`xpack.security.authc.saml.realm`::
Set this to the name of the SAML realm that you have used in your <<saml-create-realm,
Elasticsearch realm configuration>>, for instance: `saml1`
`server.xsrf.whitelist`:: `server.xsrf.whitelist`::
{kib} has in-built protection against _Cross Site Request Forgery_ attacks which {kib} has in-built protection against _Cross Site Request Forgery_ attacks which
are designed to prevent the {kib} server from processing requests that are designed to prevent the {kib} server from processing requests that
@ -755,47 +760,18 @@ In order to support SAML authentication messages that originate from your
Identity Provider, we need to explicitly _whitelist_ the SAML authentication URL Identity Provider, we need to explicitly _whitelist_ the SAML authentication URL
within {kib}, so that the {kib} server will not reject these external messages. within {kib}, so that the {kib} server will not reject these external messages.
If your {kib} instance is behind a proxy, you may also need to add configuration
to tell {kib} how to form its public URL. This is needed because all SAML
messages are exchanged via the user's web browser, so {kib} needs to know what
URLs are used within the browser. In this case, the following settings should be
added to your `kibana.yml` configuration file:
[source, yaml]
------------------------------------------------------------
xpack.security.public:
protocol: https
hostname: kibana.proxy.com
port: 443
------------------------------------------------------------
`xpack.security.public.protocol`::
This is the protocol that the user's web browser uses to connect to the proxy.
Must be one of `http` or `https`. It is strongly recommended that you use the
`https` protocol for all access to {kib}.
`xpack.security.public.hostname`::
The fully qualified hostname that your users use to connect to the proxy server.
`xpack.security.public.port`::
The port number that your users use to connect to the proxy server (e.g. `80`
for `http` or `443` for `https`).
These values must be aligned with the URLs used in the {es} configuration for
`sp.acs` and `sp.logout`.
[[saml-kibana-basic]] [[saml-kibana-basic]]
==== Supporting SAML and basic authentication in {kib} ==== Supporting SAML and basic authentication in {kib}
The SAML support in {kib} is designed on the expectation that it will be the 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. primary (or sole) authentication method for users of that {kib} instance.
However, it is possible to support both SAML and Basic authentication within a However, it is possible to support both SAML and Basic authentication within a
single {kib} instance by setting `xpack.security.authProviders` as per the single {kib} instance by setting `xpack.security.authc.providers` as per the
example below: example below:
[source, yaml] [source, yaml]
------------------------------------------------------------ ------------------------------------------------------------
xpack.security.authProviders: [saml, basic] xpack.security.authc.providers: [saml, basic]
------------------------------------------------------------ ------------------------------------------------------------
The order is important - this will _initiate_ SAML authentication for The order is important - this will _initiate_ SAML authentication for