Delegate PKI authentication API
editDelegate PKI authentication API
editImplements the exchange of an X509Certificate chain into an Elasticsearch access token.
Request
editPOST /_security/delegate_pki
Prerequisites
edit-
To call this API, the (proxy) user must have the
delegate_pki
or theall
cluster privilege. Thekibana_system
built-in role already grants this privilege. See Security privileges.
Description
editThis API implements the exchange of an X509Certificate chain for an Elasticsearch
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 Kibana, 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 Elasticsearch. For more details, see PKI authentication for clients connecting to Kibana.
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 Elasticsearch access token.
Request body
edit-
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.
Response body
edit-
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.
Examples
editThe following is an example request:
POST /_security/delegate_pki { "x509_certificate_chain": ["MIIDbTCCAlWgAwIBAgIJAIxTS7Qdho9jMA0GCSqGSIb3DQEBCwUAMFMxKzApBgNVBAMTIkVsYXN0aWNzZWFyY2ggVGVzdCBJbnRlcm1lZGlhdGUgQ0ExFjAUBgNVBAsTDUVsYXN0aWNzZWFyY2gxDDAKBgNVBAoTA29yZzAeFw0xOTA3MTkxMzMzNDFaFw0yMzA3MTgxMzMzNDFaMEoxIjAgBgNVBAMTGUVsYXN0aWNzZWFyY2ggVGVzdCBDbGllbnQxFjAUBgNVBAsTDUVsYXN0aWNzZWFyY2gxDDAKBgNVBAoTA29yZzCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBANHgMX2aX8t0nj4sGLNuKISmmXIYCj9RwRqS7L03l9Nng7kOKnhHu/nXDt7zMRJyHj+q6FAt5khlavYSVCQyrDybRuA5z31gOdqXerrjs2OXS5HSHNvoDAnHFsaYX/5geMewVTtc/vqpd7Ph/QtaKfmG2FK0JNQo0k24tcgCIcyMtBh6BA70yGBM0OT8GdOgd/d/mA7mRhaxIUMNYQzRYRsp4hMnnWoOTkR5Q8KSO3MKw9dPSpPe8EnwtJE10S3s5aXmgytru/xQqrFycPBNj4KbKVmqMP0G60CzXik5pr2LNvOFz3Qb6sYJtqeZF+JKgGWdaTC89m63+TEnUHqk0lcCAwEAAaNNMEswCQYDVR0TBAIwADAdBgNVHQ4EFgQU/+aAD6Q4mFq1vpHorC25/OY5zjcwHwYDVR0jBBgwFoAU8siFCiMiYZZm/95qFC75AG/LRE0wDQYJKoZIhvcNAQELBQADggEBAIRpCgDLpvXcgDHUk10uhxev21mlIbU+VP46ANnCuj0UELhTrdTuWvO1PAI4z+WbDUxryQfOOXO9R6D0dE5yR56L/J7d+KayW34zU7yRDZM7+rXpocdQ1Ex8mjP9HJ/Bf56YZTBQJpXeDrKow4FvtkI3bcIMkqmbG16LHQXeG3RS4ds4S4wCnE2nA6vIn9y+4R999q6y1VSBORrYULcDWxS54plHLEdiMr1vVallg82AGobS9GMcTL2U4Nx5IYZG7sbTk3LrDxVpVg/S2wLofEdOEwqCeHug/iOihNLJBabEW6z4TDLJAVW5KCY1DfhkYlBfHn7vxKkfKoCUK/yLWWI="] }
Which returns the following response:
{ "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" } }