diff --git a/x-pack/docs/en/security/authentication/index.asciidoc b/x-pack/docs/en/security/authentication/index.asciidoc index 33897d5bc82b5..7b20e3220ea40 100644 --- a/x-pack/docs/en/security/authentication/index.asciidoc +++ b/x-pack/docs/en/security/authentication/index.asciidoc @@ -2,6 +2,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[] diff --git a/x-pack/docs/en/security/authentication/overview.asciidoc b/x-pack/docs/en/security/authentication/overview.asciidoc index 943a4a894dd60..dd919a5433060 100644 --- a/x-pack/docs/en/security/authentication/overview.asciidoc +++ b/x-pack/docs/en/security/authentication/overview.asciidoc @@ -24,3 +24,9 @@ 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 {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. \ No newline at end of file diff --git a/x-pack/docs/en/security/authentication/realms.asciidoc b/x-pack/docs/en/security/authentication/realms.asciidoc index 94ee1776ed948..168700a179a13 100644 --- a/x-pack/docs/en/security/authentication/realms.asciidoc +++ b/x-pack/docs/en/security/authentication/realms.asciidoc @@ -2,10 +2,11 @@ [[realms]] === Realms -Authentication in the {stack} {security-features} is handled by one or more -authentication services called _realms_. A _realm_ is used to resolve and -authenticate users based on authentication tokens. The {security-features} -provide the following built-in realms: +The {stack-security-features} authenticate users by using realms and one or more +<>. + +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. diff --git a/x-pack/docs/en/security/authentication/token-authentication-services.asciidoc b/x-pack/docs/en/security/authentication/token-authentication-services.asciidoc new file mode 100644 index 0000000000000..49621500db53d --- /dev/null +++ b/x-pack/docs/en/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 <> 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 +<> 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 +<> and +<>.