elasticsearch/docs/reference/rest-api/security/oidc-prepare-authentication-api.asciidoc

[role="xpack"]
[[security-api-oidc-prepare-authentication]]
=== OpenID Connect prepare authentication API
++++
<titleabbrev>OpenID Connect prepare authentication</titleabbrev>
++++

.New API reference
[sidebar]
--
For the most up-to-date API details, refer to {api-es}/group/endpoint-security[Security APIs].
--

Creates an oAuth 2.0 authentication request as a URL string based on the
configuration of the respective OpenID Connect authentication realm in {es}.

[[security-api-oidc-prepare-authentication-request]]
==== {api-request-title}

`POST /_security/oidc/prepare`

//[[security-api-oidc-prepare-authentication-prereqs]]
//==== {api-prereq-title}

[[security-api-oidc-prepare-authentication-desc]]
==== {api-description-title}

The response of this API is a URL pointing to the Authorization Endpoint of the
configured OpenID Connect Provider and can be used to redirect the browser of
the user in order to continue the authentication process.

{es} exposes all the necessary OpenID Connect related functionality via the
OpenID Connect APIs. These APIs are used internally by {kib} in order to provide
OpenID Connect based authentication, but can also be used by other, custom web
applications or other clients. See also
<<security-api-oidc-authenticate,OpenID Connect authenticate API>>
and <<security-api-oidc-logout,OpenID Connect logout API>>.

[[security-api-oidc-prepare-authentication-request-body]]
==== {api-request-body-title}

The following parameters can be specified in the body of the request:

`realm`::
  (Optional, string) The name of the OpenID Connect realm in {es} the configuration of which should
be used in order to generate the authentication request. Cannot be specified
when `iss` is specified. One of `realm`, `iss` is required.

`state`::
  (Optional, string) Value used to maintain state between the authentication request and the
response, typically used as a Cross-Site Request Forgery mitigation. If the
caller of the API doesn't provide a value, {es} will generate one with
sufficient entropy itself and return it in the response.

`nonce`::
  (Optional, string) Value used to associate a Client session with an ID Token and to mitigate
replay attacks. If the caller of the API doesn't provide a value, {es} will
generate one with sufficient entropy itself and return it in the response.

`iss`::
  (Optional, string) In the case of a 3rd Party initiated Single Sign On, this is the Issuer
Identifier for the OP that the RP is to send the Authentication Request to.
Cannot be specified when `realm` is specified. One of `realm`, `iss` is required.

`login_hint`::
  (Optional, string) In the case of a 3rd Party initiated Single Sign On, a string value to be
included in the authentication request, as the `login_hint` parameter. This
parameter is not valid when `realm` is specified


[[security-api-oidc-prepare-authentication-example]]
==== {api-examples-title}

The following example generates an authentication request for the OpenID Connect
Realm `oidc1`:

[source,console]
--------------------------------------------------
POST /_security/oidc/prepare
{
  "realm" : "oidc1"
}
--------------------------------------------------

The following example output of the response contains the URI pointing to the Authorization Endpoint of the OpenID Connect Provider with all the parameters of
the Authentication Request, as HTTP GET parameters:

[source,console-result]
--------------------------------------------------
{
  "redirect" : "http://127.0.0.1:8080/c2id-login?scope=openid&response_type=id_token&redirect_uri=https%3A%2F%2Fmy.fantastic.rp%2Fcb&state=4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I&nonce=WaBPH0KqPVdG5HHdSxPRjfoZbXMCicm5v1OiAj0DUFM&client_id=elasticsearch-rp",
  "state" : "4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I",
  "nonce" : "WaBPH0KqPVdG5HHdSxPRjfoZbXMCicm5v1OiAj0DUFM",
  "realm" : "oidc1"
}
--------------------------------------------------
// TESTRESPONSE[s/http:.*elasticsearch-rp/\$\{body.redirect\}/]
// TESTRESPONSE[s/4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I/\$\{body.state\}/]
// TESTRESPONSE[s/WaBPH0KqPVdG5HHdSxPRjfoZbXMCicm5v1OiAj0DUFM/\$\{body.nonce\}/]

The following example generates an authentication request for the OpenID Connect
Realm `oidc1`, where the values for the state and the nonce have been generated
by the client:

[source,console]
--------------------------------------------------
POST /_security/oidc/prepare
{
  "realm" : "oidc1",
  "state" : "lGYK0EcSLjqH6pkT5EVZjC6eIW5YCGgywj2sxROO",
  "nonce" : "zOBXLJGUooRrbLbQk5YCcyC8AXw3iloynvluYhZ5"
}
--------------------------------------------------

The following example output of the response contains the URI pointing to the Authorization Endpoint of the OpenID Connect Provider with all the parameters of
the Authentication Request, as HTTP GET parameters:

[source,console-result]
--------------------------------------------------
{
  "redirect" : "http://127.0.0.1:8080/c2id-login?scope=openid&response_type=id_token&redirect_uri=https%3A%2F%2Fmy.fantastic.rp%2Fcb&state=lGYK0EcSLjqH6pkT5EVZjC6eIW5YCGgywj2sxROO&nonce=zOBXLJGUooRrbLbQk5YCcyC8AXw3iloynvluYhZ5&client_id=elasticsearch-rp",
  "state" : "lGYK0EcSLjqH6pkT5EVZjC6eIW5YCGgywj2sxROO",
  "nonce" : "zOBXLJGUooRrbLbQk5YCcyC8AXw3iloynvluYhZ5",
  "realm" : "oidc1"
}
--------------------------------------------------
// TESTRESPONSE[s/http:.*elasticsearch-rp/\$\{body.redirect\}/]

The following example generates an authentication request for a 3rd party
initiated single sign on, specifying the issuer that should be used for matching
the appropriate OpenID Connect Authentication realm:

[source,console]
--------------------------------------------------
POST /_security/oidc/prepare
{
  "iss" : "http://127.0.0.1:8080",
  "login_hint": "this_is_an_opaque_string"
}
--------------------------------------------------

The following example output of the response contains the URI pointing to the Authorization Endpoint of the OpenID Connect Provider with all the parameters of
the Authentication Request, as HTTP GET parameters:

[source,console-result]
--------------------------------------------------
{
  "redirect" : "http://127.0.0.1:8080/c2id-login?login_hint=this_is_an_opaque_string&scope=openid&response_type=id_token&redirect_uri=https%3A%2F%2Fmy.fantastic.rp%2Fcb&state=4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I&nonce=WaBPH0KqPVdG5HHdSxPRjfoZbXMCicm5v1OiAj0DUFM&client_id=elasticsearch-rp",
  "state" : "4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I",
  "nonce" : "WaBPH0KqPVdG5HHdSxPRjfoZbXMCicm5v1OiAj0DUFM",
  "realm" : "oidc1"
}
--------------------------------------------------
// TESTRESPONSE[s/4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I/\$\{body.state\}/]
// TESTRESPONSE[s/WaBPH0KqPVdG5HHdSxPRjfoZbXMCicm5v1OiAj0DUFM/\$\{body.nonce\}/]