OpenSearch/x-pack/docs/en/rest-api/security/oidc-prepare-authentication-api.asciidoc

[role="xpack"]
[[security-api-oidc-prepare-authentication]]

=== OpenID Connect Prepare Authentication API

Creates an oAuth 2.0 authentication request as a URL string based on the configuration of the respective
OpenID Connect authentication realm in {es}. 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>>

==== Request

`POST /_security/oidc/prepare`


==== Request Body

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

`realm`::
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.

`state`::
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`::
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.

`issuer`::
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.

`login_hint`::
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


==== Examples

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

[source,js]
--------------------------------------------------
POST /_security/oidc/prepare
{
  "realm" : "oidc1"
}
--------------------------------------------------
// CONSOLE
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,js]
--------------------------------------------------
{
  "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"
}
--------------------------------------------------
// 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,js]
--------------------------------------------------
POST /_security/oidc/prepare
{
  "realm" : "oidc1",
  "state" : "lGYK0EcSLjqH6pkT5EVZjC6eIW5YCGgywj2sxROO",
  "nonce" : "zOBXLJGUooRrbLbQk5YCcyC8AXw3iloynvluYhZ5"
}
--------------------------------------------------
// CONSOLE

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,js]
--------------------------------------------------
{
  "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"
}
--------------------------------------------------
// TESTRESPONSE

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,js]
--------------------------------------------------
POST /_security/oidc/prepare
{
  "iss" : "http://127.0.0.1:8080",
  "login_hint": "this_is_an_opaque_string"
}
--------------------------------------------------
// CONSOLE

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,js]
--------------------------------------------------
{
  "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"
}
--------------------------------------------------
// TESTRESPONSE[s/4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I/\$\{body.state\}/]
// TESTRESPONSE[s/WaBPH0KqPVdG5HHdSxPRjfoZbXMCicm5v1OiAj0DUFM/\$\{body.nonce\}/]