diff --git a/x-pack/docs/en/security/authentication/oidc-guide.asciidoc b/x-pack/docs/en/security/authentication/oidc-guide.asciidoc index c000e2cc735..fca31f4ee96 100644 --- a/x-pack/docs/en/security/authentication/oidc-guide.asciidoc +++ b/x-pack/docs/en/security/authentication/oidc-guide.asciidoc @@ -62,8 +62,7 @@ If your {es} cluster is operating in production mode, then you must configure the HTTP interface to use SSL/TLS before you can enable OpenID Connect authentication. -For more information, see -{ref}/configuring-tls.html#tls-http[Encrypting HTTP Client Communications]. +For more information, see <>. [[oidc-enable-token]] ==== Enable the token service @@ -84,8 +83,8 @@ OpenID Connect based authentication is enabled by configuring the appropriate re the authentication chain for {es}. This realm has a few mandatory settings, and a number of optional settings. -The available settings are described in detail in the -{ref}/security-settings.html#ref-oidc-settings[Security settings in {es}]. This +The available settings are described in detail in +<>. This guide will explore the most common settings. Create an OpenID Connect (the realm type is `oidc`) realm in your `elasticsearch.yml` file @@ -188,7 +187,7 @@ claims.groups:: See <>. A final piece of configuration of the OpenID Connect realm is to set the `Client Secret` that was assigned to the RP during registration in the OP. This is a secure setting and as such is not defined in the realm -configuration in `elasticsearch.yml` but added to the {ref}/secure-settings.html[elasticsearch keystore]. +configuration in `elasticsearch.yml` but added to the <>. For instance @@ -252,7 +251,7 @@ The recommended steps for configuring OpenID Claims mapping are as follows: party. This process greatly varies by provider. You can use a static configuration while others will support that the RP requests the scopes that correspond to the claims to be "released" on authentication time. See - {ref}/security-settings.html#ref-oidc-settings[`rp.requested_scopes`] for details about how + <> for details about how to configure the scopes to request. To ensure interoperability and minimize the errors, you should only request scopes that the OP supports, and which you intend to map to {es} user properties. @@ -413,7 +412,7 @@ access any data. Your OpenID Connect users cannot do anything until they are assigned roles. This can be done through either the -{ref}/security-api-put-role-mapping.html[add role mapping API], or with +<> or with <>. NOTE: You cannot use <> @@ -447,7 +446,7 @@ mapping are derived from the OpenID Connect claims as follows: - `metadata`: See <> For more information, see <> and -{ref}/security-api.html#security-role-mapping-apis[role mapping APIs]. +<>. If your OP has the ability to provide groups or roles to RPs via tha use of an OpenID Claim, then you should map this claim to the `claims.groups` setting in @@ -621,7 +620,7 @@ authenticate a user with OpenID Connect: . Make an HTTP POST request to `_security/oidc/prepare`, authenticating as the `facilitator` user, using the name of the OpenID Connect realm in the {es} configuration in the request body. See the -{ref}/security-api-oidc-prepare-authentication.html[OIDC Prepare Authentication API] for more details +<> for more details + [source,console] -------------------------------------------------- @@ -644,7 +643,7 @@ POST /_security/oidc/prepare values for `nonce` and `state` it had saved in the user's session previously. If more than one OpenID Connect realms are configured, the custom web app can specify the name of the realm to be used for handling this, but this parameter is optional. - See {ref}/security-api-oidc-authenticate.html[OIDC Authenticate API] for more details + See <> for more details + [source,console] ----------------------------------------------------------------------- @@ -660,9 +659,9 @@ POST /_security/oidc/authenticate + Elasticsearch will validate this and if all is correct will respond with an access token that can be used as a `Bearer` token for subsequent requests and a refresh token that can be later used to refresh the given -access token as described in {ref}/security-api-get-token.html[get token API]. +access token as described in <>. . At some point, if necessary, the custom web application can log the user out by using the - {ref}/security-api-oidc-logout.html[OIDC Logout API] passing the access token and refresh token as parameters. For example: + <> passing the access token and refresh token as parameters. For example: + [source,console] -------------------------------------------------- diff --git a/x-pack/docs/en/security/authentication/overview.asciidoc b/x-pack/docs/en/security/authentication/overview.asciidoc index fc960dee049..943a4a894dd 100644 --- a/x-pack/docs/en/security/authentication/overview.asciidoc +++ b/x-pack/docs/en/security/authentication/overview.asciidoc @@ -16,9 +16,9 @@ integrate with external user management systems such as LDAP and Active Directory. The {stack-security-features} provide built-in realms such as `native`,`ldap`, -`active_directory`, `pki`, `file`, and `saml`. If none of the built-in realms -meet your needs, you can also build your own custom realm and plug it into the -{stack}. +`active_directory`, `pki`, `file`, `saml`, and `oidc`. If none of the built-in +realms meet your needs, you can also build your own custom realm and plug it +into the {stack}. When {security-features} are enabled, depending on the realms you've configured, you must attach your user credentials to the requests sent to {es}. For example, diff --git a/x-pack/docs/en/security/authentication/realms.asciidoc b/x-pack/docs/en/security/authentication/realms.asciidoc index 2ffe95c2490..fffcf22a343 100644 --- a/x-pack/docs/en/security/authentication/realms.asciidoc +++ b/x-pack/docs/en/security/authentication/realms.asciidoc @@ -11,7 +11,7 @@ _native_:: An internal realm where users are stored in a dedicated {es} index. This realm supports an authentication token in the form of username and password, and is available by default when no realms are explicitly configured. The users -are managed via the {ref}/security-api.html#security-user-apis[user management APIs]. +are managed via the <>. See <>. _ldap_:: @@ -44,6 +44,11 @@ _kerberos_:: A realm that authenticates a user using Kerberos authentication. Users are authenticated on the basis of Kerberos tickets. See <>. +_oidc_:: +A realm that facilitates authentication using OpenID Connect. It enables {es} to +serve as an OpenID Connect Relying Party (RP) and provide single sign-on (SSO) +support in {kib}. See <>. + The {stack} {security-features} also support custom realms. If you need to integrate with another authentication system, you can build a custom realm plugin. For more information, see