126 lines
5.7 KiB
Plaintext
126 lines
5.7 KiB
Plaintext
[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\}/] |