From 4bebc5d98ae71fbfbcfe128f27e8b80faff53d75 Mon Sep 17 00:00:00 2001 From: Aleh Zasypkin Date: Thu, 2 Apr 2020 11:58:05 +0200 Subject: [PATCH] [7.7] Switch to the most recent Kibana configuration format and SAML/OIDC endpoints. (#54625) --- .../settings/security-settings.asciidoc | 4 +- .../security/oidc-authenticate-api.asciidoc | 2 +- .../authentication/oidc-guide.asciidoc | 39 +++++----- .../authentication/saml-guide.asciidoc | 71 +++++++++---------- .../docs/en/security/troubleshooting.asciidoc | 16 +++-- 5 files changed, 63 insertions(+), 69 deletions(-) diff --git a/docs/reference/settings/security-settings.asciidoc b/docs/reference/settings/security-settings.asciidoc index 791d24e5786b5..5365c4271ebcb 100644 --- a/docs/reference/settings/security-settings.asciidoc +++ b/docs/reference/settings/security-settings.asciidoc @@ -1277,8 +1277,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 0cbb2c9a6417f..7974ac49f6262 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. @@ -100,7 +100,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" @@ -143,7 +143,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. @@ -318,7 +318,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" @@ -520,15 +520,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, @@ -536,25 +537,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} @@ -653,7 +650,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 d65d801e16491..b4c6a518ca420 100644 --- a/x-pack/docs/en/security/authentication/saml-guide.asciidoc +++ b/x-pack/docs/en/security/authentication/saml-guide.asciidoc @@ -365,24 +365,24 @@ in order to assess the level of confidence that it can place in the corresponding authentication response. The restrictions might have to do with the authentication method (password, client certificates, etc), the user identification method during registration, and other details. {es} implements -https://docs.oasis-open.org/security/saml/v2.0/saml-authn-context-2.0-os.pdf[SAML 2.0 Authentication Context], which can be used for this purpose as defined in SAML 2.0 Core +https://docs.oasis-open.org/security/saml/v2.0/saml-authn-context-2.0-os.pdf[SAML 2.0 Authentication Context], which can be used for this purpose as defined in SAML 2.0 Core Specification. In short, the SAML SP defines a set of Authentication Context Class Reference values, which describe the restrictions to be imposed on the IdP, and sends these -in the Authentication Request. The IdP attempts to grant these restrictions. -If it cannot grant them, the authentication attempt fails. If the user is -successfully authenticated, the Authentication Statement of the SAML Response +in the Authentication Request. The IdP attempts to grant these restrictions. +If it cannot grant them, the authentication attempt fails. If the user is +successfully authenticated, the Authentication Statement of the SAML Response contains an indication of the restrictions that were satisfied. -You can define the Authentication Context Class Reference values by using the `req_authn_context_class_ref` option in the SAML realm configuration. See -<>. +You can define the Authentication Context Class Reference values by using the `req_authn_context_class_ref` option in the SAML realm configuration. See +<>. -{es} supports only the `exact` comparison method for the Authentication Context. -When it receives the Authentication Response from the IdP, {es} examines the +{es} supports only the `exact` comparison method for the Authentication Context. +When it receives the Authentication Response from the IdP, {es} examines the value of the Authentication Context Class Reference that is part of the -Authentication Statement of the SAML Assertion. If it matches one of the -requested values, the authentication is considered successful. Otherwise, the +Authentication Statement of the SAML Assertion. If it matches one of the +requested values, the authentication is considered successful. Otherwise, the authentication attempt fails. [[saml-logout]] @@ -663,7 +663,7 @@ mapping are derived from the SAML attributes as follows: - `metadata`: See <> For more information, see <> and -<>. +<>. If your IdP has the ability to provide groups or roles to Service Providers, then you should map this SAML attribute to the `attributes.groups` setting in @@ -740,29 +740,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/v1/saml] +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} @@ -774,17 +767,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 @@ -871,7 +866,7 @@ an {es} access token and a refresh token. The access token is used as credential for subsequent calls to {es}. The refresh token enables the user to get new {es} access tokens after the current one expires. -[[saml-no-kibana-realm]]] +[[saml-no-kibana-realm]] ==== SAML realm You must create a SAML realm and configure it accordingly @@ -930,7 +925,7 @@ POST /_security/saml/prepare . Handle the response from `/_security/saml/prepare`. The response from {es} will contain 3 parameters: `redirect`, `realm` and `id`. The custom web application would need to store the value for `id` in the user's session (client side in a cookie or server side if session information is -persisted this way). It must also redirect the user's browser to the URL that was returned in the +persisted this way). It must also redirect the user's browser to the URL that was returned in the `redirect` parameter. The `id` value should not be disregarded as it is used as a nonce in SAML in order to mitigate against replay attacks. . Handle a subsequent response from the SAML IdP. After the user is successfully authenticated with the @@ -999,10 +994,10 @@ POST /_security/saml/logout If the SAML realm is configured accordingly and the IdP supports it (see <>), this request will trigger a SAML SP-initiated Single Logout. In this case, the response will include a `redirect` parameter indicating where the user needs to be redirected at the IdP in order to complete the logout. -. Alternatively, the IdP might initiate the Single Logout flow at some point. In order to handle this, +. Alternatively, the IdP might initiate the Single Logout flow at some point. In order to handle this, the Logout URL (`sp.logout`) needs to be handled by the custom web app. The query part of the URL that the user will be redirected to will contain a SAML Logout request and this query part needs to be relayed to {es} -using the <> +using the <> + [source,console] -------------------------------------------------- @@ -1016,4 +1011,4 @@ POST /_security/saml/invalidate + The custom web application will then need to also handle the response, which will include a `redirect` parameter with a URL in the IdP that contains the SAML Logout response. The application should redirect the user -there to complete the logout. +there to complete the logout. diff --git a/x-pack/docs/en/security/troubleshooting.asciidoc b/x-pack/docs/en/security/troubleshooting.asciidoc index 35aa0716807a4..a3362f577d45a 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/v1/saml}] 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. --