[role="xpack"]
[[security-api-oidc-authenticate]]

=== OpenID Connect Authenticate API

Submits the response to an oAuth 2.0 authentication request for consumption from {es}. Upon successful validation, {es}
will respond with an {es} internal Access Token and Refresh Token that can be subsequently used for authentication. This
API endpoint basically exchanges successful OpenID Connect Authentication responses for {es} access and refresh tokens
to be used for authentication.

{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-prepare-authentication,OpenID Connect Prepare Authentication API>> and
<<security-api-oidc-logout,OpenID Connect Logout API>>

==== Request

`POST /_security/oidc/authenticate`

==== Request Body

`redirect_uri`::
The URL to which the OpenID Connect Provider redirected the User Agent in response to an authentication request, after a
 successful authentication. This URL is expected to be provided as-is (URL encoded), taken from the body of the response
 or as the value of a `Location` header in the response from the OpenID Connect Provider.

`state`::
String value used to maintain state between the authentication request and the response. This value needs to be the same
as the one that was provided to the call to `/_security/oidc/prepare` earlier, or the one that was generated by {es}
and included in the response to that call.

`nonce`::
String value used to associate a Client session with an ID Token, and to mitigate replay attacks. This value needs to be
the same as the one that was provided to the call to `/_security/oidc/prepare` earlier, or the one that was generated by {es}
and included in the response to that call.

==== Examples

The following example request exchanges the response that was returned from the OpenID Connect Provider after a successful
authentication, for an {es} access token and refresh token to be used in subsequent requests. This example is from an
authentication that uses the authorization code grant flow.

[source,js]
--------------------------------------------------
POST /_security/oidc/authenticate
{
  "redirect_uri" : "https://oidc-kibana.elastic.co:5603/api/security/v1/oidc?code=jtI3Ntt8v3_XvcLzCFGq&state=4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I",
  "state" : "4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I",
  "nonce" : "WaBPH0KqPVdG5HHdSxPRjfoZbXMCicm5v1OiAj0DUFM"
}
--------------------------------------------------
// CONSOLE
// TEST[skip:These are properly tested in the OpenIDConnectIT suite]

The following example output contains the access token that was generated in response, the amount of time (in
seconds) that the token expires in, the type, and the refresh token:

[source,js]
--------------------------------------------------
{
  "access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
  "type" : "Bearer",
  "expires_in" : 1200,
  "refresh_token": "vLBPvmAB6KvwvJZr27cS"
}
--------------------------------------------------
// NOTCONSOLE
