honeymoose
/
OpenSearch
mirror of https://github.com/honeymoose/OpenSearch.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
OpenSearch/x-pack/docs/en/rest-api/security/get-api-keys.asciidoc

119 lines
3.7 KiB
Plaintext
Raw Normal View History

Add support for API keys to access Elasticsearch (#38291) X-Pack security supports built-in authentication service `token-service` that allows access tokens to be used to access Elasticsearch without using Basic authentication. The tokens are generated by `token-service` based on OAuth2 spec. The access token is a short-lived token (defaults to 20m) and refresh token with a lifetime of 24 hours, making them unsuitable for long-lived or recurring tasks where the system might go offline thereby failing refresh of tokens. This commit introduces a built-in authentication service `api-key-service` that adds support for long-lived tokens aka API keys to access Elasticsearch. The `api-key-service` is consulted after `token-service` in the authentication chain. By default, if TLS is enabled then `api-key-service` is also enabled. The service can be disabled using the configuration setting. The API keys:- - by default do not have an expiration but expiration can be configured where the API keys need to be expired after a certain amount of time. - when generated will keep authentication information of the user that generated them. - can be defined with a role describing the privileges for accessing Elasticsearch and will be limited by the role of the user that generated them - can be invalidated via invalidation API - information can be retrieved via a get API - that have been expired or invalidated will be retained for 1 week before being deleted. The expired API keys remover task handles this. Following are the API key management APIs:- 1. Create API Key - `PUT/POST /_security/api_key` 2. Get API key(s) - `GET /_security/api_key` 3. Invalidate API Key(s) `DELETE /_security/api_key` The API keys can be used to access Elasticsearch using `Authorization` header, where the auth scheme is `ApiKey` and the credentials, is the base64 encoding of API key Id and API key separated by a colon. Example:- ``` curl -H "Authorization: ApiKey YXBpLWtleS1pZDphcGkta2V5" http://localhost:9200/_cluster/health ``` Closes #34383
2019-02-04 22:21:57 -05:00
[role="xpack"]
[[security-api-get-api-key]]
=== Get API Key information API
++++
<titleabbrev>Get API key information</titleabbrev>
++++
Retrieves information for one or more API keys.
==== Request
`GET /_security/api_key`
==== Description
The information for the API keys created by <<security-api-create-api-key,create API Key>> can be retrieved
using this API.
==== Request Body
The following parameters can be specified in the query parameters of a GET request and
pertain to retrieving api keys:
`id` (optional)::
(string) An API key id. This parameter cannot be used with any of `name`, `realm_name` or
`username` are used.
`name` (optional)::
(string) An API key name. This parameter cannot be used with any of `id`, `realm_name` or
`username` are used.
`realm_name` (optional)::
(string) The name of an authentication realm. This parameter cannot be used with either `id` or `name`.
`username` (optional)::
(string) The username of a user. This parameter cannot be used with either `id` or `name`.
NOTE: While all parameters are optional, at least one of them is required.
==== Examples
The following example to retrieve the API key identified by specified `id`:
[source,js]
--------------------------------------------------
GET /_security/api_key?id=dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==
--------------------------------------------------
// NOTCONSOLE
whereas the following example to retrieve the API key identified by specified `name`:
[source,js]
--------------------------------------------------
GET /_security/api_key?name=hadoop_myuser_key
--------------------------------------------------
// NOTCONSOLE
The following example retrieves all API keys for the `native1` realm:
[source,js]
--------------------------------------------------
[DOCS] Corrected API path for /_security/api_key (#39521)
2019-02-28 14:08:39 -05:00
GET /_security/api_key?realm_name=native1
Add support for API keys to access Elasticsearch (#38291) X-Pack security supports built-in authentication service `token-service` that allows access tokens to be used to access Elasticsearch without using Basic authentication. The tokens are generated by `token-service` based on OAuth2 spec. The access token is a short-lived token (defaults to 20m) and refresh token with a lifetime of 24 hours, making them unsuitable for long-lived or recurring tasks where the system might go offline thereby failing refresh of tokens. This commit introduces a built-in authentication service `api-key-service` that adds support for long-lived tokens aka API keys to access Elasticsearch. The `api-key-service` is consulted after `token-service` in the authentication chain. By default, if TLS is enabled then `api-key-service` is also enabled. The service can be disabled using the configuration setting. The API keys:- - by default do not have an expiration but expiration can be configured where the API keys need to be expired after a certain amount of time. - when generated will keep authentication information of the user that generated them. - can be defined with a role describing the privileges for accessing Elasticsearch and will be limited by the role of the user that generated them - can be invalidated via invalidation API - information can be retrieved via a get API - that have been expired or invalidated will be retained for 1 week before being deleted. The expired API keys remover task handles this. Following are the API key management APIs:- 1. Create API Key - `PUT/POST /_security/api_key` 2. Get API key(s) - `GET /_security/api_key` 3. Invalidate API Key(s) `DELETE /_security/api_key` The API keys can be used to access Elasticsearch using `Authorization` header, where the auth scheme is `ApiKey` and the credentials, is the base64 encoding of API key Id and API key separated by a colon. Example:- ``` curl -H "Authorization: ApiKey YXBpLWtleS1pZDphcGkta2V5" http://localhost:9200/_cluster/health ``` Closes #34383
2019-02-04 22:21:57 -05:00
--------------------------------------------------
// NOTCONSOLE
The following example retrieves all API keys for the user `myuser` in all realms:
[source,js]
--------------------------------------------------
[DOCS] Corrected API path for /_security/api_key (#39521)
2019-02-28 14:08:39 -05:00
GET /_security/api_key?username=myuser
Add support for API keys to access Elasticsearch (#38291) X-Pack security supports built-in authentication service `token-service` that allows access tokens to be used to access Elasticsearch without using Basic authentication. The tokens are generated by `token-service` based on OAuth2 spec. The access token is a short-lived token (defaults to 20m) and refresh token with a lifetime of 24 hours, making them unsuitable for long-lived or recurring tasks where the system might go offline thereby failing refresh of tokens. This commit introduces a built-in authentication service `api-key-service` that adds support for long-lived tokens aka API keys to access Elasticsearch. The `api-key-service` is consulted after `token-service` in the authentication chain. By default, if TLS is enabled then `api-key-service` is also enabled. The service can be disabled using the configuration setting. The API keys:- - by default do not have an expiration but expiration can be configured where the API keys need to be expired after a certain amount of time. - when generated will keep authentication information of the user that generated them. - can be defined with a role describing the privileges for accessing Elasticsearch and will be limited by the role of the user that generated them - can be invalidated via invalidation API - information can be retrieved via a get API - that have been expired or invalidated will be retained for 1 week before being deleted. The expired API keys remover task handles this. Following are the API key management APIs:- 1. Create API Key - `PUT/POST /_security/api_key` 2. Get API key(s) - `GET /_security/api_key` 3. Invalidate API Key(s) `DELETE /_security/api_key` The API keys can be used to access Elasticsearch using `Authorization` header, where the auth scheme is `ApiKey` and the credentials, is the base64 encoding of API key Id and API key separated by a colon. Example:- ``` curl -H "Authorization: ApiKey YXBpLWtleS1pZDphcGkta2V5" http://localhost:9200/_cluster/health ``` Closes #34383
2019-02-04 22:21:57 -05:00
--------------------------------------------------
// NOTCONSOLE
Finally, the following example retrieves all API keys for the user `myuser` in
the `native1` realm immediately:
[source,js]
--------------------------------------------------
[DOCS] Corrected API path for /_security/api_key (#39521)
2019-02-28 14:08:39 -05:00
GET /_security/api_key?username=myuser&realm_name=native1
Add support for API keys to access Elasticsearch (#38291) X-Pack security supports built-in authentication service `token-service` that allows access tokens to be used to access Elasticsearch without using Basic authentication. The tokens are generated by `token-service` based on OAuth2 spec. The access token is a short-lived token (defaults to 20m) and refresh token with a lifetime of 24 hours, making them unsuitable for long-lived or recurring tasks where the system might go offline thereby failing refresh of tokens. This commit introduces a built-in authentication service `api-key-service` that adds support for long-lived tokens aka API keys to access Elasticsearch. The `api-key-service` is consulted after `token-service` in the authentication chain. By default, if TLS is enabled then `api-key-service` is also enabled. The service can be disabled using the configuration setting. The API keys:- - by default do not have an expiration but expiration can be configured where the API keys need to be expired after a certain amount of time. - when generated will keep authentication information of the user that generated them. - can be defined with a role describing the privileges for accessing Elasticsearch and will be limited by the role of the user that generated them - can be invalidated via invalidation API - information can be retrieved via a get API - that have been expired or invalidated will be retained for 1 week before being deleted. The expired API keys remover task handles this. Following are the API key management APIs:- 1. Create API Key - `PUT/POST /_security/api_key` 2. Get API key(s) - `GET /_security/api_key` 3. Invalidate API Key(s) `DELETE /_security/api_key` The API keys can be used to access Elasticsearch using `Authorization` header, where the auth scheme is `ApiKey` and the credentials, is the base64 encoding of API key Id and API key separated by a colon. Example:- ``` curl -H "Authorization: ApiKey YXBpLWtleS1pZDphcGkta2V5" http://localhost:9200/_cluster/health ``` Closes #34383
2019-02-04 22:21:57 -05:00
--------------------------------------------------
// NOTCONSOLE
A successful call returns a JSON structure that contains the information of one or more API keys that were retrieved.
[source,js]
--------------------------------------------------
{
"api_keys": [ <1>
{
"id": "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==", <2>
"name": "hadoop_myuser_key", <3>
"creation": 1548550550158, <4>
"expiration": 1548551550158, <5>
"invalidated": false, <6>
"username": "myuser", <7>
"realm": "native1" <8>
},
{
"id": "api-key-id-2",
"name": "api-key-name-2",
"creation": 1548550550158,
"invalidated": false,
"username": "user-y",
"realm": "realm-2"
}
]
}
--------------------------------------------------
// NOTCONSOLE
<1> The list of API keys that were retrieved for this request.
<2> Id for the API key
<3> Name of the API key
<4> Creation time for the API key in milliseconds
<5> optional expiration time for the API key in milliseconds
<6> invalidation status for the API key, `true` if the key has been invalidated else `false`
<7> principal for which this API key was created
<8> realm name of the principal for which this API key was created