Add token based authn documentation in stack docs

docs/en/stack/security/authentication/index.asciidoc

@@ -3,6 +3,7 @@
 include::overview.asciidoc[]
 include::built-in-users.asciidoc[]
 include::internal-users.asciidoc[]
+include::token-authentication-services.asciidoc[]
 include::realms.asciidoc[]
 include::realm-chains.asciidoc[]
 include::active-directory-realm.asciidoc[]

docs/en/stack/security/authentication/overview.asciidoc

@@ -9,17 +9,22 @@ means (typically referred to as authentication tokens).
 The {stack} authenticates users by identifying the users behind the requests
 that hit the cluster and verifying that they are who they claim to be. The
 authentication process is handled by one or more authentication services called
-<<realms,_realms_>>. 
+<<realms,_realms_>>.
 
 You can use the native support for managing and authenticating users, or
 integrate with external user management systems such as LDAP and Active
-Directory. 
+Directory.
 
-{security} provides built-in realms such as `native`,`ldap`, `active_directory`, 
-`pki`, `file`, and `saml`. If none of the built-in realms meet your needs, you 
-can also build your own custom realm and plug it into the {stack}. 
+{security} provides built-in realms such as `native`,`ldap`, `active_directory`,
+`pki`, `file`, and `saml`. If none of the built-in realms meet your needs, you
+can also build your own custom realm and plug it into the {stack}.
 
 When {security-features} are enabled, depending on the realms you've configured,
 you must attach your user credentials to the requests sent to {es}. For example,
-when using realms that support usernames and passwords you can simply attach 
+when using realms that support usernames and passwords you can simply attach
 {wikipedia}/Basic_access_authentication[basic auth] header to the requests.
+
+{security} provides two services, the token service and the api key service,
+which allow the exchange of the current authentication for a token/key to be
+used for authentication without providing other means of authentication.
+These are enabled by default when TLS/SSL is enabled for http.

docs/en/stack/security/authentication/token-authentication-services.asciidoc

@@ -0,0 +1,49 @@
+[role="xpack"]
+[[token-authentication-services]]
+=== Token based Authentication services
+
+Authentication in {security} is handled by one or more token based authentication
+services and _realms_ defined in _realm-chain_. The token based Authentication
+services are used for authentication and management of tokens. These tokens can
+be used as credentials attached to the request sent to {es}.
+{security} provides the following built-in token based authentication
+services listed by order in which they are consulted for authentication:
+
+_token-service_::
+The Token Service generates access tokens and refresh tokens based on the OAuth2 specification using the
+{ref}/security-api-get-token.html[get token API].
+The access token is a short-lived token (defaults to 20 minutes and configurable
+to maximum 1 hour) and can be refreshed using a refresh token.
+The refresh token has a lifetime of 24 hours. The access token is a Bearer token and as such can be used by
+sending a request with an `Authorization` header with a value having the prefix
+`Bearer ` followed by the value of the access token.
+
+[source,shell]
+--------------------------------------------------
+curl -H "Authorization: Bearer dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==" http://localhost:9200/_cluster/health
+--------------------------------------------------
+// NOTCONSOLE
+
+_api-key-service_::
+The API key service generates API keys using {ref}/security-api-create-api-key.html[create API key API].
+By default, the API keys do not expire. The request to create API keys
+allows for an expiration to be specified. The permissions for the
+API key can be specified during the creation of the API key and are limited by the
+authenticated user's permissions.
+The API key can be used by sending a request with an `Authorization` header
+with a value having the prefix `ApiKey ` followed by the _credentials_,
+where _credentials_ is the base64 encoding of API key id and API key joined by a colon.
+
+[source,shell]
+--------------------------------------------------
+curl -H "Authorization: ApiKey VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw==" http://localhost:9200/_cluster/health
+--------------------------------------------------
+// NOTCONSOLE
+
+Depending on your use case you may want to decide on the lifetime of the tokens
+generated by these services. This information can then be used to decide which
+service you want to use to generate and manage the tokens. Non-expiring API keys
+may seem like the easy option but care must be taken considering the security implications that come with non-expiring keys.
+Both _token-service_ and _api-key-service_ allow invalidation of the tokens, see
+{ref}/security-api-invalidate-token.html[invalidate token API] and
+{ref}/security-api-invalidate-api-key.html[invalidate API key API].