Reference DOCS for proxied PKI

docs/reference/settings/security-settings.asciidoc

@@ -858,10 +858,13 @@ Defaults to `100000`.
 `delegation.enabled`::
 Generally, in order for the clients to be authenticated by the PKI realm they
 must connect directly to {es}. That is, they must not pass through proxies
-which terminate the TLS connection.  In order to allow for a *trusted* and
+which terminate the TLS connection. In order to allow for a *trusted* and
 *smart* proxy, such as Kibana, to sit before {es} and terminate TLS
 connections, but still allow clients to be authenticated on {es} by this realm,
-you need to toggle this to `true`. Defaults to `false`.
+you need to toggle this to `true`. Defaults to `false`. If delegation is
+enabled, then either `truststore.path` or `certificate_authorities` setting
+must be defined. For more details, see <<pki-realm-for-proxied-clients,
+Configuring authentication delegation for PKI realms>>.
 
 [[ref-saml-settings]]
 [float]

x-pack/docs/build.gradle

@@ -34,6 +34,7 @@ project.copyRestSpec.from(xpackResources) {
 
 testClusters.integTest {
     extraConfigFile 'op-jwks.json', xpackProject('test:idp-fixture').file("oidc/op-jwks.json")
+    extraConfigFile 'testClient.crt', xpackProject('plugin:security').file("src/test/resources/org/elasticsearch/xpack/security/action/pki_delegation/testClient.crt")
     setting 'xpack.security.enabled', 'true'
     setting 'xpack.security.authc.api_key.enabled', 'true'
     setting 'xpack.security.authc.token.enabled', 'true'
@@ -53,6 +54,9 @@ testClusters.integTest {
     keystore 'xpack.security.authc.realms.oidc.oidc1.rp.client_secret', 'b07efb7a1cf6ec9462afe7b6d3ab55c6c7880262aa61ac28dded292aca47c9a2'
     setting 'xpack.security.authc.realms.oidc.oidc1.rp.response_type', 'id_token'
     setting 'xpack.security.authc.realms.oidc.oidc1.claims.principal', 'sub'
+    setting 'xpack.security.authc.realms.pki.pki1.order', '3'
+    setting 'xpack.security.authc.realms.pki.pki1.certificate_authorities', '[ "testClient.crt" ]'
+    setting 'xpack.security.authc.realms.pki.pki1.delegation.enabled', 'true'
     user username: 'test_admin'
 }
 

x-pack/docs/en/rest-api/security.asciidoc

@@ -6,6 +6,7 @@ You can use the following APIs to perform security activities.
 
 * <<security-api-authenticate>>
 * <<security-api-clear-cache>>
+* <<security-api-delegate-pki-authentication>>
 * <<security-api-has-privileges>>
 * <<security-api-ssl>>
 * <<security-api-get-builtin-privileges>>
@@ -98,6 +99,7 @@ include::security/put-app-privileges.asciidoc[]
 include::security/create-role-mappings.asciidoc[]
 include::security/create-roles.asciidoc[]
 include::security/create-users.asciidoc[]
+include::security/delegate-pki-authentication.asciidoc[]
 include::security/delete-app-privileges.asciidoc[]
 include::security/delete-role-mappings.asciidoc[]
 include::security/delete-roles.asciidoc[]

x-pack/docs/en/rest-api/security/delegate-pki-authentication.asciidoc

@@ -0,0 +1,96 @@
+[role="xpack"]
+[[security-api-delegate-pki-authentication]]
+=== Delegate PKI authentication API
+++++
+<titleabbrev>Delegate PKI authentication</titleabbrev>
+++++
+
+Implements the exchange of an {@code 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 {stack-ov}/security-privileges.html[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, js]
+------------------------------------------------------------
+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="] <1>
+}
+------------------------------------------------------------
+// CONSOLE
+<1>  A one element certificate chain.
+
+Which returns the following response:
+
+[source,js]
+--------------------------------------------------
+{
+  "access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
+  "type" : "Bearer",
+  "expires_in" : 1200
+}
+--------------------------------------------------
+// TESTRESPONSE[s/dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==/$body.access_token/]