From e2274e77567ea8da2d07d5b11b6d1ce646d110e5 Mon Sep 17 00:00:00 2001 From: Florent Le Borgne Date: Wed, 19 Feb 2025 13:18:15 +0100 Subject: [PATCH] Clean up API keys section --- deploy-manage/api-keys.md | 25 +++++++++++++++++- .../api-keys/elastic-cloud-api-keys.md | 22 +++++++++------- .../elastic-cloud-enterprise-api-keys.md | 18 ++++++------- .../api-keys/elasticsearch-api-keys.md | 26 +++++++++---------- .../api-keys/serverless-project-api-keys.md | 16 +++++------- 5 files changed, 65 insertions(+), 42 deletions(-) diff --git a/deploy-manage/api-keys.md b/deploy-manage/api-keys.md index d72c08bf33..68bd645396 100644 --- a/deploy-manage/api-keys.md +++ b/deploy-manage/api-keys.md @@ -1,3 +1,14 @@ +--- +applies_to: + stack: ga + deployment: + eck: ga + ess: ga + ece: ga + self: ga + serverless: ga +--- + # Manage API keys % What needs to be done: Write from scratch @@ -6,4 +17,16 @@ % Scope notes: Elasticsearch & Kibana authentication API Keys -⚠️ **This page is a work in progress.** ⚠️ \ No newline at end of file + +API keys are security mechanisms used to authenticate and authorize access to your deployments and {{es}} resources. + +They ensure that only authorized users or applications interact with these resources through [Elastic APIs](https://www.elastic.co/docs/api/). + +For example, if you extract data from an {{es}} cluster on a daily basis, you might create an API key tied to your credentials, configure it with minimum access, and then put the API credentials into a cron job. Or you might create API keys to automate ingestion of new data from remote sources, without a live user interaction. + +Depending on the APIs you want to use, the API keys to create are different, and managed at different locations: + +- **[](api-keys/elasticsearch-api-keys.md)**, to use [{{es}}](https://www.elastic.co/docs/api/doc/elasticsearch/) and [{{kib}}](https://www.elastic.co/docs/api/doc/kibana/) APIs, and to manage remote cluster connections. +- **[](api-keys/serverless-project-api-keys.md)**, to use [{{es}}](https://www.elastic.co/docs/api/doc/elasticsearch-serverless/) and [{{kib}}](https://www.elastic.co/docs/api/doc/serverless/) serverless APIs. +- **[](api-keys/elastic-cloud-api-keys.md)**, to manage your {{ecloud}} organization, {{ech}} deployments, and serverless projects using the [{{ecloud}}](https://www.elastic.co/docs/api/doc/cloud/) and [{{ecloud}} serverless](https://www.elastic.co/docs/api/doc/elastic-cloud-serverless/) APIs. +- **[](api-keys/elastic-cloud-enterprise-api-keys.md)**, to manage your {{ece}} platform and deployments using the [{{ece}}](https://www.elastic.co/docs/api/doc/cloud-enterprise/) API. \ No newline at end of file diff --git a/deploy-manage/api-keys/elastic-cloud-api-keys.md b/deploy-manage/api-keys/elastic-cloud-api-keys.md index 387c933e8b..ff24973aae 100644 --- a/deploy-manage/api-keys/elastic-cloud-api-keys.md +++ b/deploy-manage/api-keys/elastic-cloud-api-keys.md @@ -1,27 +1,31 @@ --- +applies_to: + deployment: + ess: ga + serverless: ga mapped_pages: - https://www.elastic.co/guide/en/cloud/current/ec-api-authentication.html --- -# Elastic Cloud API keys [ec-api-authentication] +# {{ecloud}} API keys [ec-api-authentication] -With a valid Elastic Cloud API key, you can access the API from its base URL at `api.elastic-cloud.com`. +{{ecloud}} API keys allow you to use the [{{ecloud}}](https://www.elastic.co/docs/api/doc/cloud/) and [{{ecloud}} serverless](https://www.elastic.co/docs/api/doc/elastic-cloud-serverless/) APIs. + +With a valid {{ecloud}} API key, you can access the API from its base URL at `api.elastic-cloud.com`. Only **Organization owners** can create and manage API keys. An API key is not tied to the user who created it. When creating a key, you assign it specific roles to control its access to organizational resources, including hosted deployments and serverless projects. If a user leaves the organization, the API keys they have created will still function until they expire. You can have multiple API keys for different purposes, and you can revoke them when you no longer need them. +::::{note} +These keys provides access to the API that enables you to manage your deployments. It does not provide access to {{es}}. To access {{es}} with an API key, create a key [in {{kib}}](elasticsearch-api-keys.md) or [using the {{es}} API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-api-key). +:::: ## Create an API key [ec-api-keys] -1. Log in to the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body). +1. Log in to the [{{ecloud}} Console](https://cloud.elastic.co?page=docs&placement=docs-body). 2. Go to your avatar in the upper right corner and choose **Organization**. 3. On the API keys tab of the **Organization** page, click **Create API Key**. - - ::::{note} - This key provides access to the API that enables you to manage your deployments. It does not provide access to {{es}}. To access {{es}} with an API key, create a key [in {{kib}}](elasticsearch-api-keys.md) or [using the {{es}} API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-api-key). - :::: - 4. From the **Create API Key** page, you can configure your new key by adding a name, set expiration, or assign [roles](../users-roles/cloud-organization/user-roles.md). By default, API keys expire after three months. You can set the expiration to a different preset value or to a specific date, up to one year. If you need the key to work indefinitely, you can also set its expiration to Never. In this case, the key won’t expire. @@ -41,7 +45,7 @@ Authorization: ApiKey $EC_API_KEY ## Revoke an API key [ec_revoke_an_api_key] -1. Log in to the [Elasticsearch Service Console](https://cloud.elastic.co?page=docs&placement=docs-body). +1. Log in to the [{{ecloud}} Console](https://cloud.elastic.co?page=docs&placement=docs-body). 2. Go to your avatar in the upper right corner and choose **Organization**. The keys currently associated with your organization are listed under the API keys tab of the **Organization** page. diff --git a/deploy-manage/api-keys/elastic-cloud-enterprise-api-keys.md b/deploy-manage/api-keys/elastic-cloud-enterprise-api-keys.md index f988432f88..8817a48f39 100644 --- a/deploy-manage/api-keys/elastic-cloud-enterprise-api-keys.md +++ b/deploy-manage/api-keys/elastic-cloud-enterprise-api-keys.md @@ -1,21 +1,21 @@ --- +applies_to: + deployment: + ece: ga mapped_pages: - https://www.elastic.co/guide/en/cloud-enterprise/current/ece-restful-api-authentication.html --- -# Elastic Cloud Enterprise API keys [ece-restful-api-authentication] - -::::{note} -This documentation applies to the Elastic Cloud Enterprise API only. If you are using [Elasticsearch Service](https://cloud.elastic.co/home), check the [Elastic Cloud API information](https://www.elastic.co/guide/en/cloud/current/ec-restful-api.html) instead. -:::: +# {{ece}} API keys [ece-restful-api-authentication] +The {{ece}} RESTful APIs support both key-based and token-based authentication. Key-based is generally the preferred method. -The Elastic Cloud Enterprise RESTful APIs support both key-based and token-based authentication. Key-based is generally the preferred method. +{{ece}} API keys allow you to manage your {{ece}} platform and deployments using the [{{ece}}](https://www.elastic.co/docs/api/doc/cloud-enterprise/) API. ## Authenticate using an API key [ece-api-keys] -For key-based API authentication, you can create an API key through the Elastic Cloud Enterprise UI. Once created, you can specify the key in the header of your API calls to authenticate. +For key-based API authentication, you can create an API key through the {{ece}} UI. Once created, you can specify the key in the header of your API calls to authenticate. ::::{note} API keys are not available for the built-in users (`admin` and `readonly`). Therefore, the **API Keys** settings page on the UI does not appear for these users. @@ -37,7 +37,7 @@ To create an API key: The API key has the same permissions as the API key owner. You may have multiple API keys for different purposes and you can revoke them when you no longer need them. -Currently, API keys cannot be generated for the `admin` and `readonly` users that come pre-configured with your Elastic Cloud Enterprise installation. +Currently, API keys cannot be generated for the `admin` and `readonly` users that come pre-configured with your {{ece}} installation. To revoke an API key: @@ -48,7 +48,7 @@ To revoke an API key: ## Authenticate using a bearer token [ece-restful-api-authentication-token] -For token-based API authentication, you can use the same username and password that you use to log into the Cloud UI. If you want to use the credentials that were provided when you installed Elastic Cloud Enterprise on your first host, for example `admin`, you can [retrieve them separately](../users-roles/cloud-enterprise-orchestrator/manage-system-passwords.md#ece-retrieve-passwords). +For token-based API authentication, you can use the same username and password that you use to log into the Cloud UI. If you want to use the credentials that were provided when you installed {{ece}} on your first host, for example `admin`, you can [retrieve them separately](../users-roles/cloud-enterprise-orchestrator/manage-system-passwords.md#ece-retrieve-passwords). For operations that only read information, but don’t create, update or delete, you can authenticate with a user that has restricted permissions, such as the `readonly` user. diff --git a/deploy-manage/api-keys/elasticsearch-api-keys.md b/deploy-manage/api-keys/elasticsearch-api-keys.md index 4d8f2cdfb0..7942c99213 100644 --- a/deploy-manage/api-keys/elasticsearch-api-keys.md +++ b/deploy-manage/api-keys/elasticsearch-api-keys.md @@ -1,21 +1,19 @@ --- +applies_to: + stack: ga mapped_pages: - https://www.elastic.co/guide/en/kibana/current/api-keys.html --- -# Elasticsearch API keys [api-keys] +# {{es}} API keys [api-keys] -API keys are security mechanisms used to authenticate and authorize access to {{es}} resources. They ensure that only authorized users or applications interact with {{es}}. +Several types of {{es}} API keys exist: -For example, if you extract data from an {{es}} cluster on a daily basis, you might create an API key tied to your credentials, configure it with minimum access, and then put the API credentials into a cron job. Or you might create API keys to automate ingestion of new data from remote sources, without a live user interaction. +* **Personal/User** API key: allows external services to access the Elastic Stack on behalf of a user. +* **Cross-cluster** API key: allows other clusters to connect to this cluster. +* **Managed** API key: created and managed by Kibana to run background tasks. -You can use {{kib}} to manage your different API keys: - -* User API key: allows external services to access the Elastic Stack on behalf of a user. -* Cross-cluster API key: allows other clusters to connect to this cluster. -* Managed API key: created and managed by Kibana to run background tasks. - -To manage API keys, go to the **API Keys** management page using the navigation menu or the [global search field](../../explore-analyze/find-and-organize/find-apps-and-objects.md). +To manage API keys in {{kib}}, go to the **API Keys** management page using the navigation menu or the [global search field](../../explore-analyze/find-and-organize/find-apps-and-objects.md). ![API Keys UI](../../images/kibana-api-keys.png "") @@ -37,18 +35,18 @@ To create an API key, go to the **API Keys** management page using the navigatio ![Create API Key UI](../../images/kibana-create-ccr-api-key.png "") -Refer to the [create API key](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-api-key) documentation to learn more about creating user API keys. +Refer to the [Create API key](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-api-key) documentation to learn more about creating user API keys. -Refer to the [create cross-cluster API key](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-cross-cluster-api-key) documentation to learn more about creating cross-cluster API keys. +Refer to the [Create cross-cluster API key](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-cross-cluster-api-key) documentation to learn more about creating cross-cluster API keys. ## Update an API key [udpate-api-key] To update an API key, go to the **API Keys** management page using the navigation menu or the [global search field](../../explore-analyze/find-and-organize/find-apps-and-objects.md), and then click on the name of the key. You cannot update the name or the type of API key. -Refer to the [update API key](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-update-api-key) documentation to learn more about updating user API keys. +Refer to the [Update API key](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-update-api-key) documentation to learn more about updating user API keys. -Refer to the [update cross-cluster API key](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-update-cross-cluster-api-key) documentation to learn more about updating cross-cluster API keys. +Refer to the [Update cross-cluster API key](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-update-cross-cluster-api-key) documentation to learn more about updating cross-cluster API keys. ## View and delete API keys [view-api-keys] diff --git a/deploy-manage/api-keys/serverless-project-api-keys.md b/deploy-manage/api-keys/serverless-project-api-keys.md index 46bee78b5c..b88eed7e7d 100644 --- a/deploy-manage/api-keys/serverless-project-api-keys.md +++ b/deploy-manage/api-keys/serverless-project-api-keys.md @@ -1,15 +1,16 @@ --- +applies_to: + serverless: ga mapped_pages: - https://www.elastic.co/guide/en/serverless/current/api-keys.html --- # Serverless project API keys [api-keys] -This content applies to: [![Elasticsearch](../../images/serverless-es-badge.svg "")](../../solutions/search.md) [![Observability](../../images/serverless-obs-badge.svg "")](../../solutions/observability.md) [![Security](../../images/serverless-sec-badge.svg "")](../../solutions/security/elastic-security-serverless.md) +In serverless projects, the following types of API keys exist: -API keys are security mechanisms used to authenticate and authorize access to {{stack}} resources, and ensure that only authorized users or applications are able to interact with the {{stack}}. - -For example, if you extract data from an {{es}} cluster on a daily basis, you might create an API key tied to your credentials, configure it with minimum access, and then put the API credentials into a cron job. Or, you might create API keys to automate ingestion of new data from remote sources, without a live user interaction. +- **Personal** API keys, that you can create to allow external services to access your serverless project on behalf of a user. +- **Managed** API keys, created and managed by {{kib}} to correctly run background tasks. You can manage your keys in **{{project-settings}} → {{manage-app}} → {{api-keys-app}}**: @@ -18,10 +19,6 @@ You can manage your keys in **{{project-settings}} → {{manage-app}} → {{api- :class: screenshot ::: -A *personal API key* allows external services to access the {{stack}} on behalf of a user. - -A *managed API key* is created and managed by {{kib}} to correctly run background tasks. - ## Create an API key [api-keys-create-an-api-key] @@ -30,6 +27,7 @@ In **{{api-keys-app}}**, click **Create API key**: :::{image} ../../images/serverless-create-personal-api-key.png :alt: Create API key UI :class: screenshot +:width: 50% ::: Once created, you can copy the encoded API key and use it to send requests to the {{es}} HTTP API. For example: @@ -72,7 +70,7 @@ For example, the following `role_descriptors` object defines a `books-read-only` } ``` -For the `role_descriptors` object schema, check out the [`/_security/api_key` endpoint](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-api-key) docs. For supported privileges, check [Security privileges](../users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-indices). +For the `role_descriptors` object schema, check out the [`/_security/api_key` endpoint](https://www.elastic.co/docs/api/doc/elasticsearch-serverless/operation/operation-security-create-api-key) docs. For supported privileges, check [Security privileges](../users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-indices). ## Update an API key [api-keys-update-an-api-key]