[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.

[[security-api-oidc-authenticate-request]]
==== {api-request-title}

`POST /_security/oidc/authenticate`

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

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

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>>

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

`redirect_uri`::
  (Required, string) 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`::
  (Required, string) 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`::
  (Required, string) 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.

`realm`::
  (Optional, string) Used to identify the name of the OpenID Connect realm that should
be used to authenticate this. Useful when multiple realms have been defined.

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

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,console]
--------------------------------------------------
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",
  "realm" : "oidc1"
}
--------------------------------------------------
// TEST[catch:unauthorized]

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