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:
parent
821f6f893b
commit
ac131f986b
|
@ -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
|
||||||
|
|
Loading…
Reference in New Issue