Skip to content

Commit be7bea9

Browse files
authored
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
1 parent b8ef612 commit be7bea9

File tree

1 file changed

+10
-34
lines changed

1 file changed

+10
-34
lines changed

x-pack/docs/en/security/authentication/saml-guide.asciidoc

+10-34
Original file line numberDiff line numberDiff line change
@@ -741,20 +741,25 @@ SAML authentication in {kib} is also subject to the
741741
`xpack.security.sessionTimeout` setting that is described in the {kib} security
742742
documentation, and you may wish to adjust this timeout to meet your local needs.
743743

744-
The two additional settings that are required for SAML support are shown below:
744+
The three additional settings that are required for SAML support are shown below:
745745

746746
[source, yaml]
747747
------------------------------------------------------------
748-
xpack.security.authProviders: [saml]
748+
xpack.security.authc.providers: [saml]
749+
xpack.security.authc.saml.realm: saml1
749750
server.xsrf.whitelist: [/api/security/v1/saml]
750751
------------------------------------------------------------
751752

752753
The configuration values used in the example above are:
753754

754-
`xpack.security.authProviders`::
755+
`xpack.security.authc.providers`::
755756
Set this to `[ saml ]` to instruct {kib} to use SAML SSO as the authentication
756757
method.
757758

759+
`xpack.security.authc.saml.realm`::
760+
Set this to the name of the SAML realm that you have used in your <<saml-create-realm,
761+
Elasticsearch realm configuration>>, for instance: `saml1`
762+
758763
`server.xsrf.whitelist`::
759764
{kib} has in-built protection against _Cross Site Request Forgery_ attacks which
760765
are designed to prevent the {kib} server from processing requests that
@@ -763,47 +768,18 @@ In order to support SAML authentication messages that originate from your
763768
Identity Provider, we need to explicitly _whitelist_ the SAML authentication URL
764769
within {kib}, so that the {kib} server will not reject these external messages.
765770

766-
If your {kib} instance is behind a proxy, you may also need to add configuration
767-
to tell {kib} how to form its public URL. This is needed because all SAML
768-
messages are exchanged via the user's web browser, so {kib} needs to know what
769-
URLs are used within the browser. In this case, the following settings should be
770-
added to your `kibana.yml` configuration file:
771-
772-
[source, yaml]
773-
------------------------------------------------------------
774-
xpack.security.public:
775-
protocol: https
776-
hostname: kibana.proxy.com
777-
port: 443
778-
------------------------------------------------------------
779-
780-
`xpack.security.public.protocol`::
781-
This is the protocol that the user's web browser uses to connect to the proxy.
782-
Must be one of `http` or `https`. It is strongly recommended that you use the
783-
`https` protocol for all access to {kib}.
784-
785-
`xpack.security.public.hostname`::
786-
The fully qualified hostname that your users use to connect to the proxy server.
787-
788-
`xpack.security.public.port`::
789-
The port number that your users use to connect to the proxy server (e.g. `80`
790-
for `http` or `443` for `https`).
791-
792-
These values must be aligned with the URLs used in the {es} configuration for
793-
`sp.acs` and `sp.logout`.
794-
795771
[[saml-kibana-basic]]
796772
==== Supporting SAML and basic authentication in {kib}
797773

798774
The SAML support in {kib} is designed on the expectation that it will be the
799775
primary (or sole) authentication method for users of that {kib} instance.
800776
However, it is possible to support both SAML and Basic authentication within a
801-
single {kib} instance by setting `xpack.security.authProviders` as per the
777+
single {kib} instance by setting `xpack.security.authc.providers` as per the
802778
example below:
803779

804780
[source, yaml]
805781
------------------------------------------------------------
806-
xpack.security.authProviders: [saml, basic]
782+
xpack.security.authc.providers: [saml, basic]
807783
------------------------------------------------------------
808784

809785
The order is important - this will _initiate_ SAML authentication for

0 commit comments

Comments
 (0)