OpenSearch/x-pack/docs/en/rest-api/security.asciidoc

145 lines
5.0 KiB
Plaintext
Raw Normal View History

[role="xpack"]
[[security-api]]
== Security APIs
You can use the following APIs to perform security activities.
* <<security-api-authenticate>>
* <<security-api-clear-cache>>
* <<security-api-delegate-pki-authentication>>
* <<security-api-has-privileges>>
* <<security-api-ssl>>
* <<security-api-get-builtin-privileges>>
[discrete]
[[security-api-app-privileges]]
=== Application privileges
You can use the following APIs to add, update, retrieve, and remove application
privileges:
* <<security-api-put-privileges,Create or update privileges>>
* <<security-api-clear-privilege-cache,Clear privileges cache>>
* <<security-api-delete-privilege,Delete privileges>>
* <<security-api-get-privileges,Get privileges>>
[discrete]
[[security-role-mapping-apis]]
=== Role mappings
You can use the following APIs to add, remove, update, and retrieve role mappings:
* <<security-api-put-role-mapping,Create or update role mappings>>
* <<security-api-delete-role-mapping,Delete role mappings>>
* <<security-api-get-role-mapping,Get role mappings>>
[discrete]
[[security-role-apis]]
=== Roles
You can use the following APIs to add, remove, update, and retrieve roles in the native realm:
* <<security-api-put-role,Create or update roles>>
* <<security-api-clear-role-cache,Clear roles cache>>
* <<security-api-delete-role,Delete roles>>
* <<security-api-get-role,Get roles>>
[discrete]
[[security-token-apis]]
=== Tokens
You can use the following APIs to create and invalidate bearer tokens for access
without requiring basic authentication:
* <<security-api-get-token,Get token>>
* <<security-api-invalidate-token,Invalidate token>>
[discrete]
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
[[security-api-keys]]
=== API Keys
You can use the following APIs to create, retrieve and invalidate API keys for access
without requiring basic authentication:
* <<security-api-create-api-key,Create API key>>
* <<security-api-get-api-key,Get API key>>
* <<security-api-invalidate-api-key,Invalidate API key>>
* <<security-api-clear-api-key-cache,Clear API key cache>>
* <<security-api-grant-api-key,Grant API key>>
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
[discrete]
[[security-user-apis]]
=== Users
You can use the following APIs to add, remove, update, or retrieve users in the
native realm:
* <<security-api-put-user,Create or update users>>
* <<security-api-change-password,Change passwords>>
* <<security-api-delete-user,Delete users>>
* <<security-api-disable-user,Disable users>>
* <<security-api-enable-user,Enable users>>
* <<security-api-get-user,Get users>>
[discrete]
[[security-openid-apis]]
=== OpenID Connect
You can use the following APIs to authenticate users against an OpenID Connect
authentication realm when using a custom web application other than Kibana
* <<security-api-oidc-prepare-authentication, Prepare an authentication request>>
* <<security-api-oidc-authenticate, Submit an authentication response>>
* <<security-api-oidc-logout, Logout an authenticated user>>
[discrete]
[[security-saml-apis]]
=== SAML
You can use the following APIs to authenticate users against a SAML authentication
realm when using a custom web application other than Kibana
* <<security-api-saml-prepare-authentication, Prepare an authentication request>>
* <<security-api-saml-authenticate, Submit an authentication response>>
* <<security-api-saml-logout, Logout an authenticated user>>
* <<security-api-saml-invalidate, Submit a logout request from the IdP>>
include::security/authenticate.asciidoc[]
include::security/change-password.asciidoc[]
include::security/clear-cache.asciidoc[]
include::security/clear-roles-cache.asciidoc[]
include::security/clear-privileges-cache.asciidoc[]
include::security/clear-api-key-cache.asciidoc[]
2019-03-04 18:06:00 -05:00
include::security/create-api-keys.asciidoc[]
2018-12-20 13:23:28 -05:00
include::security/put-app-privileges.asciidoc[]
include::security/create-role-mappings.asciidoc[]
include::security/create-roles.asciidoc[]
include::security/create-users.asciidoc[]
include::security/delegate-pki-authentication.asciidoc[]
include::security/delete-app-privileges.asciidoc[]
include::security/delete-role-mappings.asciidoc[]
include::security/delete-roles.asciidoc[]
include::security/delete-users.asciidoc[]
include::security/disable-users.asciidoc[]
include::security/enable-users.asciidoc[]
2019-03-04 18:06:00 -05:00
include::security/get-api-keys.asciidoc[]
include::security/get-app-privileges.asciidoc[]
include::security/get-builtin-privileges.asciidoc[]
include::security/get-role-mappings.asciidoc[]
include::security/get-roles.asciidoc[]
include::security/get-tokens.asciidoc[]
include::security/get-users.asciidoc[]
include::security/grant-api-keys.asciidoc[]
include::security/has-privileges.asciidoc[]
2019-03-04 18:06:00 -05:00
include::security/invalidate-api-keys.asciidoc[]
include::security/invalidate-tokens.asciidoc[]
include::security/oidc-prepare-authentication-api.asciidoc[]
include::security/oidc-authenticate-api.asciidoc[]
include::security/oidc-logout-api.asciidoc[]
include::security/saml-prepare-authentication-api.asciidoc[]
include::security/saml-authenticate-api.asciidoc[]
include::security/saml-logout-api.asciidoc[]
include::security/saml-invalidate-api.asciidoc[]
include::security/ssl.asciidoc[]