Skip to content

Commit 2cbbeaf

Browse files
lcawllcawl
authored
[DOCS] Add token based authn documentation (#55964)
1 parent ffe1712 commit 2cbbeaf

File tree

4 files changed

+70
-4
lines changed

4 files changed

+70
-4
lines changed

‎x-pack/docs/en/security/authentication/index.asciidoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
include::overview.asciidoc[]
33
include::built-in-users.asciidoc[]
44
include::internal-users.asciidoc[]
5+
include::token-authentication-services.asciidoc[]
56
include::realms.asciidoc[]
67
include::realm-chains.asciidoc[]
78
include::active-directory-realm.asciidoc[]

‎x-pack/docs/en/security/authentication/overview.asciidoc

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,3 +24,9 @@ When {security-features} are enabled, depending on the realms you've configured,
2424
you must attach your user credentials to the requests sent to {es}. For example,
2525
when using realms that support usernames and passwords you can simply attach
2626
{wikipedia}/Basic_access_authentication[basic auth] header to the requests.
27+
28+
The {security-features} provide two services: the token service and the api key
29+
service. You can use these services to exchange the current authentication for
30+
a token or key. This token or key can then be used as credentials for
31+
authenticating new requests. These services are enabled by default when TLS/SSL
32+
is enabled for HTTP.

‎x-pack/docs/en/security/authentication/realms.asciidoc

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,11 @@
22
[[realms]]
33
=== Realms
44

5-
Authentication in the {stack} {security-features} is handled by one or more
6-
authentication services called _realms_. A _realm_ is used to resolve and
7-
authenticate users based on authentication tokens. The {security-features}
8-
provide the following built-in realms:
5+
The {stack-security-features} authenticate users by using realms and one or more
6+
<<token-authentication-services,token-based authentication services>>.
7+
8+
A _realm_ is used to resolve and authenticate users based on authentication
9+
tokens. The {security-features} provide the following built-in realms:
910

1011
_native_::
1112
An internal realm where users are stored in a dedicated {es} index.

‎x-pack/docs/en/security/authentication/token-authentication-services.asciidoc

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
[role="xpack"]
2+
[[token-authentication-services]]
3+
=== Token-based authentication services
4+
5+
The {stack-security-features} authenticate users by using realms and one or more token-based
6+
authentication services. The token-based authentication services are used for
7+
authentication and for the management of tokens. These tokens can be used as
8+
credentials attached to requests that are sent to {es}. When {es} receives a request
9+
that must be authenticated, it consults first the token-based authentication
10+
services then the realm chain.
11+
12+
The {security-features} provide the following built-in token-based authentication
13+
services, which are listed in the order they are consulted:
14+
15+
_token-service_::
16+
The token service uses the <<security-api-get-token,get token API>> to
17+
generate access tokens and refresh tokens based on the OAuth2 specification.
18+
The access token is a short-lived token. By default, it expires after 20 minutes
19+
but it can be configured to last a maximum of 1 hour. It can be refreshed by
20+
using a refresh token, which has a lifetime of 24 hours. The access token is a
21+
bearer token. You can use it by sending a request with an `Authorization`
22+
header with a value that has the prefix "Bearer " followed by the value of the
23+
access token. For example:
24+
+
25+
--
26+
[source,shell]
27+
--------------------------------------------------
28+
curl -H "Authorization: Bearer dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==" http://localhost:9200/_cluster/health
29+
--------------------------------------------------
30+
// NOTCONSOLE
31+
--
32+
33+
_api-key-service_::
34+
The API key service uses the
35+
<<security-api-create-api-key,create API key API>> to generate API keys.
36+
By default, the API keys do not expire. When you make a request to create API
37+
keys, you can specify an expiration and permissions for the API key. The
38+
permissions are limited by the authenticated user's permissions. You can use the
39+
API key by sending a request with an `Authorization` header with a value that
40+
has the prefix "ApiKey " followed by the credentials. The credentials are the
41+
base64 encoding of the API key ID and the API key joined by a colon. For example:
42+
+
43+
--
44+
[source,shell]
45+
--------------------------------------------------
46+
curl -H "Authorization: ApiKey VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw==" http://localhost:9200/_cluster/health
47+
--------------------------------------------------
48+
// NOTCONSOLE
49+
--
50+
51+
Depending on your use case, you may want to decide on the lifetime of the tokens
52+
generated by these services. You can then use this information to decide which
53+
service to use to generate and manage the tokens. Non-expiring API keys may seem
54+
like the easy option but you must consider the security implications that come
55+
with non-expiring keys. Both the _token-service_ and _api-key-service_ permit
56+
you to invalidate the tokens. See
57+
<<security-api-invalidate-token,invalidate token API>> and
58+
<<security-api-invalidate-api-key,invalidate API key API>>.

0 commit comments

Comments
 (0)