Skip to content

Commit

Permalink
Document xpack.security.authc.saml.realm for Kibana (#44705)
Browse files Browse the repository at this point in the history
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
  • Loading branch information
jkakavas committed Jul 31, 2019
1 parent f4edb31 commit 944c998
Showing 1 changed file with 10 additions and 34 deletions.
44 changes: 10 additions & 34 deletions x-pack/docs/en/security/authentication/saml-guide.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -741,20 +741,25 @@ SAML authentication in {kib} is also subject to the
`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.

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]
------------------------------------------------------------
xpack.security.authProviders: [saml]
xpack.security.authc.providers: [saml]
xpack.security.authc.saml.realm: saml1
server.xsrf.whitelist: [/api/security/v1/saml]
------------------------------------------------------------

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
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`::
{kib} has in-built protection against _Cross Site Request Forgery_ attacks which
are designed to prevent the {kib} server from processing requests that
Expand All @@ -763,47 +768,18 @@ In order to support SAML authentication messages that originate from your
Identity Provider, we need to explicitly _whitelist_ the SAML authentication URL
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]]
==== Supporting SAML and basic authentication in {kib}

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.
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:

[source, yaml]
------------------------------------------------------------
xpack.security.authProviders: [saml, basic]
xpack.security.authc.providers: [saml, basic]
------------------------------------------------------------

The order is important - this will _initiate_ SAML authentication for
Expand Down

0 comments on commit 944c998

Please sign in to comment.