Add token based authn documentation in stack docs (#195)

This commit adds documentation for token-based
authentication services like token-service and
api-key-service.

Author: bizybot

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}. 
+The {stack-security-features} provide 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 in.
 
 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.
+
+The {security-features} provide two services: the token service and the api key
+service. You can use these services to exchange the current authentication for
+a token or key. This token or key can then be used as credentials for authenticating
+new requests. These services are enabled by default when TLS/SSL is enabled for HTTP.

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

@@ -2,15 +2,17 @@
 [[realms]]
 === Realms
 
-Authentication in {security} is handled by one or more authentication services
-called _realms_. A _realm_ is used to resolve and authenticate users based on
-authentication tokens. {security} provides the following built-in realms:
+The {stack-security-features} authenticate users by using realms and one or more
+<<token-authentication-services,token-based authentication services>>.
+
+A _realm_ is used to resolve and authenticate users based on authentication
+tokens. The {security-features} provide the following built-in realms:
 
 _native_::
 An internal realm where users are stored in a dedicated {es} index.
 This realm supports an authentication token in the form of username and password,
 and is available by default when no realms are explicitly configured. The users
-are managed via the {ref}/security-api.html#security-user-apis[user management APIs]. 
+are managed via the {ref}/security-api.html#security-user-apis[user management APIs].
 See <<native-realm>>.
 
 _ldap_::
@@ -43,23 +45,23 @@ _kerberos_::
 A realm that authenticates a user using Kerberos authentication. Users are
 authenticated on the basis of Kerberos tickets. See <<kerberos-realm>>.
 
-{security} also supports custom realms. If you need to integrate with another
-authentication system, you can build a custom realm plugin. For more information,
-see <<custom-realms, Integrating with Other Authentication Systems>>.
+The {security-features} also support custom realms. If you need to integrate
+with another authentication system, you can build a custom realm plugin. For
+more information, see <<custom-realms>>.
 
 ==== Internal and external realms
 
 Realm types can roughly be classified in two categories:
 
 Internal::  Realms that are internal to Elasticsearch and don't require any
-            communication with external parties. They are fully managed by
-            {security}. There can only be a maximum of one configured realm
-            per internal realm type. {security} provides two internal realm
+            communication with external parties. They are fully managed by the
+            {security-features}. There can only be a maximum of one configured
+            realm per internal realm type. {security} provides two internal realm
             types: `native` and `file`.
 
 External::  Realms that require interaction with parties/components external to
             {es}, typically, with enterprise grade identity management
             systems. Unlike internal realms, there can be as many external realms
             as one would like - each with its own unique name and configuration.
-            {security} provides the following external realm types: `ldap`,
-            `active_directory`, `saml`, `kerberos` and `pki`.
+            The {security-features} provide the following external realm types:
+            `ldap`, `active_directory`, `saml`, `kerberos` and `pki`.

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

@@ -0,0 +1,58 @@
+[role="xpack"]
+[[token-authentication-services]]
+=== Token-based authentication services
+
+The {stack-security-features} authenticate users by using realms and one or more token-based
+authentication services. The token-based authentication services are used for
+authentication and for the management of tokens. These tokens can be used as
+credentials attached to requests that are sent to {es}. When {es} receives a request
+that must be authenticated, it consults first the token-based authentication
+services then the realm chain.
+
+The {security-features} provide the following built-in token-based authentication
+services, which are listed in the order they are consulted:
+
+_token-service_::
+The token service uses the {ref}/security-api-get-token.html[get token API] to
+generate access tokens and refresh tokens based on the OAuth2 specification.
+The access token is a short-lived token. By default, it expires after 20 minutes
+but it can be configured to last a maximum of 1 hour. It can be refreshed by
+using a refresh token, which has a lifetime of 24 hours. The access token is a
+bearer token. You can use it by sending a request with an `Authorization`
+header with a value that has the prefix "Bearer " followed by the value of the
+access token. For example:
++
+--
+[source,shell]
+--------------------------------------------------
+curl -H "Authorization: Bearer dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==" http://localhost:9200/_cluster/health
+--------------------------------------------------
+// NOTCONSOLE
+--
+
+_api-key-service_::
+The API key service uses the
+{ref}/security-api-create-api-key.html[create API key API] to generate API keys.
+By default, the API keys do not expire. When you make a request to create API
+keys, you can specify an expiration and permissions for the API key. The
+permissions are limited by the authenticated user's permissions. You can use the
+API key by sending a request with an `Authorization` header with a value that
+has the prefix "ApiKey " followed by the credentials. The credentials are the
+base64 encoding of the API key ID and the API key joined by a colon. For example:
++
+--
+[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. You can then use this information to decide which
+service to use to generate and manage the tokens. Non-expiring API keys may seem
+like the easy option but you must consider the security implications that come
+with non-expiring keys. Both the _token-service_ and _api-key-service_ permit
+you to invalidate the tokens. See
+{ref}/security-api-invalidate-token.html[invalidate token API] and
+{ref}/security-api-invalidate-api-key.html[invalidate API key API].