Add security.delegate_pki

Author: lcawl

docs/overlays/elasticsearch-openapi-overlays.yaml

@@ -471,3 +471,20 @@ actions:
                 $ref: "../../specification/search_application/render_query/SearchApplicationsRenderQueryRequestExample1.yaml"
                 renderSearchApplicationQueryResponseExample1:
                   $ref: "../../specification/search_application/render_query/SearchApplicationsRenderQueryResponseExample1.yaml"
+
+  - target: "$.paths['/_security/delegate_pki']['post']"
+    description: "Add examples for delegate PKI operation"
+    update:
+      requestBody: 
+        content: 
+          application/json: 
+            examples: 
+              delegatePkiRequestExample1: 
+                $ref: "../../specification/security/delegate_pki/SecurityDelegatePkiRequestExample1.yaml"
+      responses:
+        200:
+          content:
+            application/json:
+              examples:
+                delegatePkiResponseExample1:
+                  $ref: "../../specification/security/delegate_pki/SecurityDelegatePkiResponseExample1.yaml"

output/openapi/elasticsearch-openapi.json

@@ -634,6 +634,12 @@
       ],
       "response": []
     },
+    "security.delegate_pki": {
+      "request": [
+        "Request: should not have a body"
+      ],
+      "response": []
+    },
     "security.get_settings": {
       "request": [
         "Missing request & response"

output/schema/schema.json

@@ -383,6 +383,7 @@ paginate-search-results,https://www.elastic.co/guide/en/elasticsearch/reference/
 painless-contexts,https://www.elastic.co/guide/en/elasticsearch/painless/{branch}/painless-contexts.html
 painless-execute-api,https://www.elastic.co/guide/en/elasticsearch/painless/{branch}/painless-execute-api.html
 pipeline-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/pipeline-processor.html
+pki-realm,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/pki-realm.html
 point-in-time-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/point-in-time-api.html
 preview-dfanalytics,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/preview-dfanalytics.html
 preview-transform,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/preview-transform.html

output/schema/validation-errors.json

@@ -0,0 +1,22 @@
+{
+  "security.delegate_pki": {
+    "documentation": {
+      "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/security-api-delegate-pki-authentication.html",
+      "description": "Delegate PKI authentication."
+    },
+    "stability": "stable",
+    "visibility": "public",
+    "headers": {
+      "accept": ["application/json"]
+    },
+    "url": {
+      "paths": [
+        {
+          "path": "/_security/delegate_pki",
+          "methods": ["POST"]
+        }
+      ]
+    },
+    "params": {}
+  }
+}

output/typescript/types.ts

@@ -0,0 +1,49 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { RequestBase } from '@_types/Base'
+
+/**
+ * Delegate PKI authentication.
+ * This 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`.
+ * A successfully trusted client certificate is also subject to the validation of the subject distinguished name according to thw `username_pattern` of the respective realm.
+ *
+ * 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.
+ *
+ * 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 Elasticsearch access token.
+ * @rest_spec_name security.delegate_pki
+ * @availability stack since=7.4.0 stability=stable
+ * @cluster_privileges all
+ * @ext_doc_id pki-realm
+ */
+export interface Request extends RequestBase {
+  body: {
+    /**
+     * 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 that 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.
+     */
+    x509_certificate_chain: string[]
+  }
+}

specification/_doc_ids/table.csv

@@ -0,0 +1,5 @@
+# summary: 
+description: Delegate a one element certificate chain.
+# type": "response",
+# response_code": 200,
+value: "{\n\"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==\"]\n}"

specification/_json_spec/security.delegate_pki.json

@@ -0,0 +1,37 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { integer } from '@_types/Numeric'
+
+export class Response {
+  body: {
+    /**
+     * An access token associated with the subject distinguished name of the client's certificate.
+     */
+    access_token: string
+    /**
+     * The amount of time (in seconds) before the token expires.
+     */
+    expires_in: integer
+    /**
+     * The type of token.
+     */
+    type: string
+  }
+}