[7.x] Switch to the most recent Kibana configuration format and SAML/OIDC endpoints. (#54624)
This commit is contained in:
Aleh Zasypkin
GitHub
parent
0ed20cc349
commit
161eac1942
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
|
|
|
|||
|
|
@ -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 <<oidc-guide-op, configured with the OP upon registration>> 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.<provider-name>.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 <<third-party-login>>). 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"
|
||||
|
|
|
|||
|
|
@ -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
|
||||
<<ref-saml-settings>>.
|
||||
You can define the Authentication Context Class Reference values by using the `req_authn_context_class_ref` option in the SAML realm configuration. See
|
||||
<<ref-saml-settings>>.
|
||||
|
||||
{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 <<saml-user-metadata>>
|
||||
|
||||
For more information, see <<mapping-roles>> and
|
||||
<<security-role-mapping-apis>>.
|
||||
<<security-role-mapping-apis>>.
|
||||
|
||||
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.<provider-name>.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
|
||||
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 <<saml-logout>>), 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 <<security-api-saml-invalidate,SAML invalidate API>>
|
||||
using the <<security-api-saml-invalidate,SAML invalidate API>>
|
||||
+
|
||||
[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.
|
||||
|
|
|
|||
|
|
@ -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}.
|
||||
`xpack.security.authc.providers.saml.<provider-name>.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.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.
|
||||
If you get an error like the one above, it possibly means that the value of
|
||||
`xpack.security.authc.providers.saml.<provider-name>.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.
|
||||
|
||||
--
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue