mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-04-25 23:57:20 -04:00
255c9a7f95
**Problem:** For historical reasons, source files for the Elasticsearch Guide's security, watcher, and Logstash API docs are housed in the `x-pack/docs` directory. This can confuse new contributors who expect Elasticsearch Guide docs to be located in `docs/reference`. **Solution:** - Move the security, watcher, and Logstash API doc source files to the `docs/reference` directory - Update doc snippet tests to use security Rel: https://github.com/elastic/platform-docs-team/issues/208
116 lines
5.2 KiB
Text
116 lines
5.2 KiB
Text
[role="xpack"]
|
|
[[security-api-delegate-pki-authentication]]
|
|
=== Delegate PKI authentication API
|
|
++++
|
|
<titleabbrev>Delegate PKI authentication</titleabbrev>
|
|
++++
|
|
|
|
Implements the exchange of an _X509Certificate_ chain into an {es} access
|
|
token.
|
|
|
|
[[security-api-delegate-pki-authentication-request]]
|
|
==== {api-request-title}
|
|
|
|
`POST /_security/delegate_pki`
|
|
|
|
[[security-api-delegate-pki-authentication-prereqs]]
|
|
==== {api-prereq-title}
|
|
|
|
* To call this API, the (proxy) user must have the `delegate_pki` or the `all`
|
|
cluster privilege. The `kibana_system` built-in role already grants this
|
|
privilege. See <<security-privileges>>.
|
|
|
|
[[security-api-delegate-pki-authentication-desc]]
|
|
==== {api-description-title}
|
|
|
|
This API implements the exchange of an _X509Certificate_ chain for an {es}
|
|
access token. The certificate chain is validated, according to RFC 5280, by
|
|
sequentially considering the trust configuration of every installed PKI realm
|
|
that has `delegation.enabled` set to `true` (default is `false`). A
|
|
successfully trusted client certificate is also subject to the validation of
|
|
the subject distinguished name according to that respective's realm
|
|
`username_pattern`.
|
|
|
|
This API is called by *smart* and *trusted* proxies, such as {kib}, which
|
|
terminate the user's TLS session but still want to authenticate the user
|
|
by using a PKI realm--as if the user connected directly to {es}. For more
|
|
details, see <<pki-realm-for-proxied-clients>>.
|
|
|
|
IMPORTANT: The association between the subject public key in the target
|
|
certificate and the corresponding private key is *not* validated. This is part
|
|
of the TLS authentication process and it is delegated to the proxy that calls
|
|
this API. The proxy is *trusted* to have performed the TLS authentication and
|
|
this API translates that authentication into an {es} access token.
|
|
|
|
[[security-api-delegate-pki-authentication-request-body]]
|
|
==== {api-request-body-title}
|
|
|
|
`x509_certificate_chain`::
|
|
(Required, list of strings) The _X509Certificate_ chain, which is represented as
|
|
an ordered string array. Each string in the array is a base64-encoded
|
|
(Section 4 of RFC4648 - not base64url-encoded) of the certificate's DER encoding.
|
|
+
|
|
The first element is the target certificate contains the subject distinguished
|
|
name that is requesting access. This may be followed by additional certificates;
|
|
each subsequent certificate is used to certify the previous one.
|
|
|
|
|
|
[[security-api-delegate-pki-authentication-response-body]]
|
|
==== {api-response-body-title}
|
|
|
|
`access_token`::
|
|
(string) An access token associated to the subject distinguished name of the
|
|
client's certificate.
|
|
|
|
`expires_in`::
|
|
(time units) The amount of time (in seconds) that the token expires in.
|
|
|
|
`type`::
|
|
(string) The type of token.
|
|
|
|
[[security-api-delegate-pki-authentication-example]]
|
|
==== {api-examples-title}
|
|
|
|
The following is an example request:
|
|
|
|
[source,console]
|
|
------------------------------------------------------------
|
|
POST /_security/delegate_pki
|
|
{
|
|
"x509_certificate_chain": ["MIIDeDCCAmCgAwIBAgIUBzj/nGGKxP2iXawsSquHmQjCJmMwDQYJKoZIhvcNAQELBQAwUzErMCkGA1UEAxMiRWxhc3RpY3NlYXJjaCBUZXN0IEludGVybWVkaWF0ZSBDQTEWMBQGA1UECxMNRWxhc3RpY3NlYXJjaDEMMAoGA1UEChMDb3JnMB4XDTIzMDcxODE5MjkwNloXDTQzMDcxMzE5MjkwNlowSjEiMCAGA1UEAxMZRWxhc3RpY3NlYXJjaCBUZXN0IENsaWVudDEWMBQGA1UECxMNRWxhc3RpY3NlYXJjaDEMMAoGA1UEChMDb3JnMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAllHL4pQkkfwAm/oLkxYYO+r950DEy1bjH+4viCHzNADLCTWO+lOZJVlNx7QEzJE3QGMdif9CCBBxQFMapA7oUFCLq84fPSQQu5AnvvbltVD9nwVtCs+9ZGDjMKsz98RhSLMFIkxdxi6HkQ3Lfa4ZSI4lvba4oo+T/GveazBDS+NgmKyq00EOXt3tWi1G9vEVItommzXWfv0agJWzVnLMldwkPqsw0W7zrpyT7FZS4iLbQADGceOW8fiauOGMkscu9zAnDR/SbWl/chYioQOdw6ndFLn1YIFPd37xL0WsdsldTpn0vH3YfzgLMffT/3P6YlwBegWzsx6FnM/93Ecb4wIDAQABo00wSzAJBgNVHRMEAjAAMB0GA1UdDgQWBBQKNRwjW+Ad/FN1Rpoqme/5+jrFWzAfBgNVHSMEGDAWgBRcya0c0x/PaI7MbmJVIylWgLqXNjANBgkqhkiG9w0BAQsFAAOCAQEACZ3PF7Uqu47lplXHP6YlzYL2jL0D28hpj5lGtdha4Muw1m/BjDb0Pu8l0NQ1z3AP6AVcvjNDkQq6Y5jeSz0bwQlealQpYfo7EMXjOidrft1GbqOMFmTBLpLA9SvwYGobSTXWTkJzonqVaTcf80HpMgM2uEhodwTcvz6v1WEfeT/HMjmdIsq4ImrOL9RNrcZG6nWfw0HR3JNOgrbfyEztEI471jHznZ336OEcyX7gQuvHE8tOv5+oD1d7s3Xg1yuFp+Ynh+FfOi3hPCuaHA+7F6fLmzMDLVUBAllugst1C3U+L/paD7tqIa4ka+KNPCbSfwazmJrt4XNiivPR4hwH5g=="] <1>
|
|
}
|
|
------------------------------------------------------------
|
|
<1> A one element certificate chain.
|
|
|
|
Which returns the following response:
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
|
|
"type" : "Bearer",
|
|
"expires_in" : 1200,
|
|
"authentication" : {
|
|
"username" : "Elasticsearch Test Client",
|
|
"roles" : [ ],
|
|
"full_name" : null,
|
|
"email" : null,
|
|
"metadata" : {
|
|
"pki_dn" : "O=org, OU=Elasticsearch, CN=Elasticsearch Test Client",
|
|
"pki_delegated_by_user" : "test_admin",
|
|
"pki_delegated_by_realm" : "file"
|
|
},
|
|
"enabled" : true,
|
|
"authentication_realm" : {
|
|
"name" : "pki1",
|
|
"type" : "pki"
|
|
},
|
|
"lookup_realm" : {
|
|
"name" : "pki1",
|
|
"type" : "pki"
|
|
},
|
|
"authentication_type" : "realm"
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// TESTRESPONSE[s/dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==/$body.access_token/]
|