From 129031c3d287167072b92883f2592ce9a6aeb7fd Mon Sep 17 00:00:00 2001 From: Aleh Zasypkin Date: Thu, 2 Apr 2020 08:00:34 +0200 Subject: [PATCH] Switch to the most recent Kibana configuration format and SAML/OIDC endpoints. (#50652) --- .../settings/security-settings.asciidoc | 4 +- .../security/oidc-authenticate-api.asciidoc | 2 +- .../authentication/oidc-guide.asciidoc | 39 +++++++++---------- .../authentication/saml-guide.asciidoc | 39 ++++++++----------- .../docs/en/security/troubleshooting.asciidoc | 16 ++++---- 5 files changed, 47 insertions(+), 53 deletions(-) diff --git a/docs/reference/settings/security-settings.asciidoc b/docs/reference/settings/security-settings.asciidoc index ccdc763f52d87..f8092c72ef2b9 100644 --- a/docs/reference/settings/security-settings.asciidoc +++ b/docs/reference/settings/security-settings.asciidoc @@ -1281,8 +1281,8 @@ at the OpenID Connect Provider `rp.redirect_uri`:: The Redirect URI within {kib}. If you want to use the authorization code flow, this is the -"api/security/v1/oidc" endpoint of your {kib} server. If you want to use the implicit flow, it is the "api/security/v1/oidc/implicit" endpoint. -For example, `https://kibana.example.com/api/security/v1/oidc`. +"api/security/oidc/callback" endpoint of your {kib} server. If you want to use the implicit flow, it is the "api/security/oidc/implicit" endpoint. +For example, `https://kibana.example.com/api/security/oidc/callback`. `rp.response_type`:: OAuth 2.0 Response Type value that determines the authorization diff --git a/x-pack/docs/en/rest-api/security/oidc-authenticate-api.asciidoc b/x-pack/docs/en/rest-api/security/oidc-authenticate-api.asciidoc index 0814257d3aefa..14d0f2cf7023d 100644 --- a/x-pack/docs/en/rest-api/security/oidc-authenticate-api.asciidoc +++ b/x-pack/docs/en/rest-api/security/oidc-authenticate-api.asciidoc @@ -65,7 +65,7 @@ an authentication that uses the authorization code grant flow. -------------------------------------------------- POST /_security/oidc/authenticate { - "redirect_uri" : "https://oidc-kibana.elastic.co:5603/api/security/v1/oidc?code=jtI3Ntt8v3_XvcLzCFGq&state=4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I", + "redirect_uri" : "https://oidc-kibana.elastic.co:5603/api/security/oidc/callback?code=jtI3Ntt8v3_XvcLzCFGq&state=4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I", "state" : "4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I", "nonce" : "WaBPH0KqPVdG5HHdSxPRjfoZbXMCicm5v1OiAj0DUFM", "realm" : "oidc1" diff --git a/x-pack/docs/en/security/authentication/oidc-guide.asciidoc b/x-pack/docs/en/security/authentication/oidc-guide.asciidoc index b4e647b4a3c97..cc82a24aac230 100644 --- a/x-pack/docs/en/security/authentication/oidc-guide.asciidoc +++ b/x-pack/docs/en/security/authentication/oidc-guide.asciidoc @@ -38,7 +38,7 @@ RP that you commonly need to provide for registration are the following: nor the Elastic Stack implementation impose any constraints on this value. - `Redirect URI`: This is the URI where the OP will redirect the user's browser after authentication. The appropriate value for this will depend on your setup and whether or not {kib} sits behind a proxy or -load balancer. It will typically be +$\{kibana-url}/api/security/v1/oidc+ (for the authorization code flow) or +$\{kibana-url}/api/security/v1/oidc/implicit+ (for the implicit flow) where _$\{kibana-url}_ is the base URL for your {kib} instance. You might also see this +load balancer. It will typically be +$\{kibana-url}/api/security/oidc/callback+ (for the authorization code flow) or +$\{kibana-url}/api/security/oidc/implicit+ (for the implicit flow) where _$\{kibana-url}_ is the base URL for your {kib} instance. You might also see this called `Callback URI`. At the end of the registration process, the OP will assign a Client Identifier and a Client Secret for the RP ({stack}) to use. @@ -101,7 +101,7 @@ xpack.security.authc.realms.oidc.oidc1: order: 2 rp.client_id: "the_client_id" rp.response_type: code - rp.redirect_uri: "https://kibana.example.org:5601/api/security/v1/oidc" + rp.redirect_uri: "https://kibana.example.org:5601/api/security/oidc/callback" op.issuer: "https://op.example.org" op.authorization_endpoint: "https://op.example.org/oauth2/v1/authorize" op.token_endpoint: "https://op.example.org/oauth2/v1/token" @@ -144,7 +144,7 @@ rp.response_type:: rp.redirect_uri:: The redirect URI where the OP will redirect the browser after authentication. This needs to be _exactly_ the same as the one <> and will - typically be +$\{kibana-url}/api/security/v1/oidc+ where _$\{kibana-url}_ is the base URL for your {kib} instance + typically be +$\{kibana-url}/api/security/oidc/callback+ where _$\{kibana-url}_ is the base URL for your {kib} instance op.issuer:: A verifiable Identifier for your OpenID Connect Provider. An Issuer Identifier is usually a case sensitive URL. @@ -320,7 +320,7 @@ xpack.security.authc.realms.oidc.oidc1: order: 2 rp.client_id: "the_client_id" rp.response_type: code - rp.redirect_uri: "https://kibana.example.org:5601/api/security/v1/oidc" + rp.redirect_uri: "https://kibana.example.org:5601/api/security/oidc/callback" op.authorization_endpoint: "https://op.example.org/oauth2/v1/authorize" op.token_endpoint: "https://op.example.org/oauth2/v1/token" op.userinfo_endpoint: "https://op.example.org/oauth2/v1/userinfo" @@ -522,15 +522,16 @@ The three additional settings that are required for OpenID Connect support are s [source, yaml] ------------------------------------------------------------ -xpack.security.authc.providers: [oidc] -xpack.security.authc.oidc.realm: "oidc1" -server.xsrf.whitelist: [/api/security/v1/oidc] +xpack.security.authc.providers: + oidc.oidc1: + order: 0 + realm: "oidc1" ------------------------------------------------------------ The configuration values used in the example above are: `xpack.security.authc.providers`:: -Set this to `[ oidc ]` to instruct {kib} to use OpenID Connect single sign-on as the +Add `oidc` provider to instruct {kib} to use OpenID Connect single sign-on as the authentication method. This instructs Kibana to attempt to initiate an SSO flow everytime a user attempts to access a URL in Kibana, if the user is not already authenticated. If you also want to allow users to login with a username and password, @@ -538,25 +539,21 @@ you must enable the `basic` authentication provider too. For example: [source, yaml] ------------------------------------------------------------ -xpack.security.authc.providers: [oidc, basic] +xpack.security.authc.providers: + oidc.oidc1: + order: 0 + realm: "oidc1" + basic.basic1: + order: 1 ------------------------------------------------------------ This will allow users that haven't already authenticated with OpenID Connect to -navigate directly to the `/login` page in {kib} in order to use the login form. +log in using the {kib} login form. -`xpack.security.authc.oidc.realm`:: +`xpack.security.authc.providers.oidc..realm`:: The name of the OpenID Connect realm in {es} that should handle authentication for this Kibana instance. -`server.xsrf.whitelist`:: -{kib} has in-built protection against _Cross Site Request Forgery_ attacks, which -is designed to prevent the {kib} server from processing requests that -originated from outside the {kib} application. -If you use the authorization code flow, {kib} needs to support unsolicited messages that originate from your -OP or a third party (see <>). In order to do so, you must explicitly _whitelist_ the -OpenID Connect authentication endpoint within {kib}, so that the {kib} server will -not reject these external messages. - [[oidc-without-kibana]] === OpenID Connect without {kib} @@ -656,7 +653,7 @@ POST /_security/oidc/prepare ----------------------------------------------------------------------- POST /_security/oidc/authenticate { - "redirect_uri" : "https://oidc-kibana.elastic.co:5603/api/security/v1/oidc?code=jtI3Ntt8v3_XvcLzCFGq&state=4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I", + "redirect_uri" : "https://oidc-kibana.elastic.co:5603/api/security/oidc/callback?code=jtI3Ntt8v3_XvcLzCFGq&state=4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I", "state" : "4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I", "nonce" : "WaBPH0KqPVdG5HHdSxPRjfoZbXMCicm5v1OiAj0DUFM", "realm" : "oidc1" diff --git a/x-pack/docs/en/security/authentication/saml-guide.asciidoc b/x-pack/docs/en/security/authentication/saml-guide.asciidoc index 1cf13fbd2a15d..40dfbabc56767 100644 --- a/x-pack/docs/en/security/authentication/saml-guide.asciidoc +++ b/x-pack/docs/en/security/authentication/saml-guide.asciidoc @@ -748,29 +748,22 @@ The three additional settings that are required for SAML support are shown below [source, yaml] ------------------------------------------------------------ -xpack.security.authc.providers: [saml] -xpack.security.authc.saml.realm: saml1 -server.xsrf.whitelist: [/api/security/saml/callback] +xpack.security.authc.providers: + saml.saml1: + order: 0 + realm: "saml1" ------------------------------------------------------------ The configuration values used in the example above are: `xpack.security.authc.providers`:: -Set this to `[ saml ]` to instruct {kib} to use SAML SSO as the authentication +Add `saml` provider to instruct {kib} to use SAML SSO as the authentication method. -`xpack.security.authc.saml.realm`:: +`xpack.security.authc.providers.saml..realm`:: Set this to the name of the SAML realm that you have used in your <>, 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 -originated from outside the {kib} application. -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. - [[saml-kibana-basic]] ==== Supporting SAML and basic authentication in {kib} @@ -782,17 +775,19 @@ example below: [source, yaml] ------------------------------------------------------------ -xpack.security.authc.providers: [saml, basic] +xpack.security.authc.providers: + saml.saml1: + order: 0 + realm: "saml1" + basic.basic1: + order: 1 ------------------------------------------------------------ -The order is important - this will _initiate_ SAML authentication for -unauthenticated users, but will _accept_ basic authentication. - -If {kib} is configured in this way, then users who wish to login with a -username and password, can do so by directly accessing the `/login` page in -{kib}. This login will not use SAML credentials, and will rely on one of the -other security realms within {es}. Only users who have a username and password -for a configured {es} authentication realm will be able to login via this page. +If {kib} is configured in this way, users are presented with a choice +at the Login Selector UI. They log in with SAML or they provide a username and password and rely on one +of the other security realms within {es}. Only users who have +a username and password for a configured {es} authentication realm can +log in via {kib} login form. Alternatively, when the `basic` authentication provider is enabled, you can place a reverse proxy in front of {kib}, and configure it to send a basic diff --git a/x-pack/docs/en/security/troubleshooting.asciidoc b/x-pack/docs/en/security/troubleshooting.asciidoc index 66445b49c9400..6c6edb429a819 100644 --- a/x-pack/docs/en/security/troubleshooting.asciidoc +++ b/x-pack/docs/en/security/troubleshooting.asciidoc @@ -451,13 +451,15 @@ assertionConsumerServiceURL=https://my.kibana.url/api/security/saml/callback}] In order to initiate a SAML authentication, {kib} needs to know which SAML realm it should use from the ones that are configured in {es}. You can use the -`xpack.security.authc.saml.reaml` setting to explicitly set the SAML realm name -in {kib}. It must match the name of the SAML realm that is configured in {es}. - -If you get an error like the one above, it possibly means that the value of -`xpack.security.authc.saml.reaml` in your {kib} configuration is wrong. Verify -that it matches the name of the configured realm in {es}, which is the string -after `xpack.security.authc.realms.saml.` in your {es} configuration. +`xpack.security.authc.providers.saml..realm` setting to explicitly +set the SAML realm name in {kib}. It must match the name of the SAML realm that is +configured in {es}. + +If you get an error like the one above, it possibly means that the value of +`xpack.security.authc.providers.saml..realm` in your {kib} +configuration is wrong. Verify that it matches the name of the configured realm +in {es}, which is the string after `xpack.security.authc.realms.saml.` in your +{es} configuration. --