From 53c1d5e3938ee1710cd63d3675f2d9c32af1d8d9 Mon Sep 17 00:00:00 2001 From: Albert Zaharovits Date: Thu, 23 Jul 2020 15:49:29 +0300 Subject: [PATCH] DOCS audit attributes for API Key authn (#60033) This PR describes the new audit entry attributes api_key.id, api_key.name and authentication.type, as well as the meaning of existing attributes when authentication is performed using API keys. This should've been part of #58928 --- .../en/security/auditing/event-types.asciidoc | 46 +++++++++++++++---- 1 file changed, 38 insertions(+), 8 deletions(-) diff --git a/x-pack/docs/en/security/auditing/event-types.asciidoc b/x-pack/docs/en/security/auditing/event-types.asciidoc index c63f2908c76d5..198ff53ac91a6 100644 --- a/x-pack/docs/en/security/auditing/event-types.asciidoc +++ b/x-pack/docs/en/security/auditing/event-types.asciidoc @@ -157,16 +157,34 @@ There are a few events that have some more attributes in addition to those that have been previously described: * `authentication_success`: - `realm` :: The name of the realm that successfully - authenticated the user. + `realm` :: The name of the realm that successfully authenticated the user. + If authenticated using an API key, this is the special value of + `_es_api_key`. This is a shorthand attribute + for the same information that is described by the `user.realm`, + `user.run_by.realm` and `authentication.type` attributes. `user.name` :: The name of the _effective_ user. This is usually the same as the _authenticated_ user, but if using the <> this instead denotes the name of the _impersonated_ user. + If authenticated using an API key, this is + the name of the API key owner. + `user.realm` :: Name of the the realm to which the _effective_ user + belongs. If authenticated using an API key, this is + the name of the realm to which the API key owner belongs. `user.run_by.name` :: This attribute is present only if the request is using the <> and denotes the name of the _authenticated_ user, which is also known as the _impersonator_. + `user.run_by.realm` :: Name of the realm to which the _authenticated_ + (_impersonator_) user belongs. + This attribute is provided only if the request + uses the <>. + `authentication.type`:: Method used to authenticate the user. + Possible values are `REALM`, `API_KEY`, `TOKEN`, `ANONYMOUS` or `INTERNAL`. + `api_key.id` :: API key ID returned by the <> request. + This attribute is only provided for authentication using an API key. + `api_key.name` :: API key name provided in the <> request. + This attribute is only provided for authentication using an API key. * `authentication_failed`: `user.name` :: The name of the user that failed authentication. @@ -188,13 +206,19 @@ that have been previously described: action is granted or denied. `user.run_as.realm` :: The realm name of that the _impersonated_ user belongs to. -* `access_granted` or `access_denied`: - `user.roles` :: The role names of the user as an array. - `user.name` :: The name of the _effective_ user that is being - authorized or unauthorized. This is usually the _authenticated_ - user, but if using the <> +* `access_granted` and `access_denied`: + `user.roles` :: The role names of the user as an array. If authenticated + using an API key, this contains the + role names of the API key owner. + `user.name` :: The name of the _effective_ user. This is usually the + same as the _authenticated_ user, but if using the + <> this instead denotes the name of the _impersonated_ user. - `user.realm` :: The realm name that the _effective_ user belongs to. + If authenticated using an API key, this is + the name of the API key owner. + `user.realm` :: Name of the the realm to which the _effective_ user + belongs. If authenticated using an API key, this is + the name of the realm to which the API key owner belongs. `user.run_by.name` :: This attribute is present only if the request is using the <> and denoted the name of the _authenticated_ user, @@ -203,6 +227,12 @@ that have been previously described: using the <> and denotes the name of the realm that the _authenticated_ (_impersonator_) user belongs to. + `authentication.type`:: Method used to authenticate the user. + Possible values are `REALM`, `API_KEY`, `TOKEN`, `ANONYMOUS` or `INTERNAL`. + `api_key.id` :: API key ID returned by the <> request. + This attribute is only provided for authentication using an API key. + `api_key.name` :: API key name provided in the <> request. + This attribute is only provided for authentication using an API key. [float]