diff --git a/deploy-manage/api-keys.md b/deploy-manage/api-keys.md index ed5f89245f..747da4a0d3 100644 --- a/deploy-manage/api-keys.md +++ b/deploy-manage/api-keys.md @@ -13,13 +13,15 @@ navigation_title: API keys 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/). +They ensure that only authorized users or applications interact with these resources through [Elastic APIs]({{apis}}). 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 +| Type | Applicability | Purpose | +| --- | --- | --- | +| [](api-keys/elasticsearch-api-keys.md) | {applies_to}`stack: ga` | • Use [{{es}}]({{es-apis}}) and [{{kib}}]({{kib-apis}}) APIs in stack-versioned deployments, including ECH, ECE, ECK, and self-managed clusters.

• Manage remote cluster connections. | +| [](api-keys/serverless-project-api-keys.md) | {applies_to}`serverless: ga`| Use [{{es}}]({{es-serverless-apis}}) and [{{kib}}]({{kib-serverless-apis}}) serverless APIs. | +| [](api-keys/elastic-cloud-api-keys.md) | {applies_to}`ess: ga` {applies_to}`serverless: ga` | • Manage your {{ecloud}} organization, {{ech}} deployments, and serverless projects using the [{{ecloud}}]({{cloud-apis}}) and [{{ecloud}} serverless]({{cloud-serverless-apis}}) APIs.

• {applies_to}`serverless: ga` Use [{{es}}]({{es-serverless-apis}}) and [{{kib}}]({{kib-serverless-apis}}) serverless APIs. Using {{ecloud}} keys for project-level API access allows you to create keys that can interact with multiple projects,and manage API access centrally from the {{ecloud}} console. | +|[](api-keys/elastic-cloud-enterprise-api-keys.md) | {applies_to}`ece: ga` | Manage your {{ece}} platform and deployments using the [{{ece}}]({{ece-apis}}) 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 93da17705b..1f3c0adc2c 100644 --- a/deploy-manage/api-keys/elastic-cloud-api-keys.md +++ b/deploy-manage/api-keys/elastic-cloud-api-keys.md @@ -11,33 +11,39 @@ products: # {{ecloud}} API keys [ec-api-authentication] -{{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`. +{{ecloud}} API keys allow you to programmatically access the following resources: + +* [{{ecloud}}]({{cloud-apis}}) APIs +* [{{ecloud}} serverless]({{cloud-serverless-apis}}) APIs +* {applies_to}`serverless: ga` Optionally, [{{es}} serverless]({{es-serverless-apis}}) and [{{kib}} serverless]({{kib-serverless-apis}}) APIs 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. +You can have multiple API keys for different purposes, and you can revoke them when you no longer need them. Each organization can have up to 500 active API keys. + +:::{admonition} {{es}} and {{kib}} API access +:applies_to: ech: + +By default, {{ecloud}} API keys provide access to the APIs for managing your organization, deployments, and projects. + +In the case of {{ech}} deployments, {{ecloud}} API keys do not provide access to {{es}} or {{kib}} APIs. [Learn how to create an {{es}} API key for ECH deployments](elasticsearch-api-keys.md). + +In the case of {{serverless-full}} deployments, you can optionally grant access to [{{es}}]({{es-serverless-apis}}) and [{{kib}}]({{kib-serverless-apis}}) serverless APIs when you [assign roles to the API key](#roles). +::: + -::::{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 [{{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**. -4. On the **Create API key** flyout, 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. - Each organization can have up to 500 active API keys. - - ::::{note} - When an API key is nearing expiration, Elastic sends an email to the creator of the API key and each of the operational contacts. When you use an API key to authenticate, the API response header `X-Elastic-Api-Key-Expiration` indicates the key’s expiration date. You can log this value to detect API keys that are nearing expiration. - - Once an API key expires, it will automatically be removed from the API Keys tab. - :::: +4. On the **Create API key** flyout, you can configure your new key: + 1. Add a unique name for the key. + 2. Set the [expiration](#expiration) for the key. + 3. Assign [roles](#roles). +5. 6. Click **Create API key**, copy the generated API key, and store it in a safe place. You can also download the key as a CSV file. @@ -47,7 +53,6 @@ The API key needs to be supplied in the `Authorization` header of a request, in Authorization: ApiKey $EC_API_KEY ``` - ## Revoke an API key [ec_revoke_an_api_key] 1. Log in to the [{{ecloud}} Console](https://cloud.elastic.co?page=docs&placement=docs-body). @@ -56,3 +61,47 @@ Authorization: ApiKey $EC_API_KEY The keys currently associated with your organization are listed under the API keys tab of the **Organization** page. 3. Find the key you want to revoke, and click the trash icon under **Actions**. + +## API key expiration [expiration] + +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. + +When an API key is nearing expiration, Elastic sends an email to the creator of the API key and each of the operational contacts. When you use an API key to authenticate, the API response header `X-Elastic-Api-Key-Expiration` indicates the key’s expiration date. You can log this value to detect API keys that are nearing expiration. + +Once an API key expires, it is automatically removed from the **API keys** tab. + +## Applying roles to API keys [roles] + +Roles grant an API key specific privileges to your {{ecloud}} organization and resources. + +You can grant a cloud API key [the same types of roles that you assign to users](deploy-manage/users-roles/cloud-organization/user-roles.md#types-of-roles): organization-level roles, cloud resource access roles, and connected cluster roles. + +### Granting {{es}} and {{kib}} API access +```{applies_to} +serverless: ga +``` + +When you grant **Organization owner** access, or **Cloud resource** access for one or more Serverless projects, you can select your level of API access: + +* **Cloud API**: Grants access to only [{{ecloud}} serverless]({{cloud-serverless-apis}}) APIs +* **Cloud, {{es}} and {{kib}} API**: Grants access to [{{ecloud}} serverless]({{cloud-serverless-apis}}), [{{es}} serverless]({{es-serverless-apis}}), and [{{kib}} serverless]({{kib-serverless-apis}}) APIs. + +Using {{ecloud}} keys for project-level API access, rather than [granting keys from within each Serverless project](serverless-project-api-keys.md), allows you to create keys that can interact with multiple projects, and manage API access centrally from the {{ecloud}} console. + +When granting cloud resource access, you can apply a [predefined role](/deploy-manage/users-roles/cloud-organization/user-roles.md#general-assign-user-roles-table) or [custom role](/deploy-manage/users-roles/serverless-custom-roles.md) to granularly control access to the specified resources. The role that you select controls the resources that you can access in all relevant APIs. + +#### Considerations + +Your **API access** selection impacts the behavior of your selected role. To take full effect, most roles need **Cloud, {{es}} and {{kib}} API** access to be granted. + +When **Cloud, {{es}} and {{kib}} API** access is not granted, roles that are designed to interact with the project directly have limited access. For example: + +* If you select the **Admin** role: + + *Has full access to project management, properties, and security privileges. Admins log into projects with superuser role privileges.* + + The API key won't be able to interact with the project as a superuser unless you select **Cloud, {{es}} and {{kib}} API** access. + +* Several predefined roles that are intended for project users, such as Security project analyst roles, will only have **Viewer** access to the project through the {{ecloud}} Serverless API. + +If you apply a custom role, then you must always select **Cloud, {{es}} and {{kib}} API** for API access for the role to take full effect. This is because custom roles are intended to work within the project itself, which is represented programmatically by the {{es}} and {{kib}} APIs. If you don't grant full access, the key only has the equivalent of **Viewer** access to the project in the {{ecloud}} serverless API. diff --git a/deploy-manage/api-keys/elasticsearch-api-keys.md b/deploy-manage/api-keys/elasticsearch-api-keys.md index c992ca1459..322d7abadd 100644 --- a/deploy-manage/api-keys/elasticsearch-api-keys.md +++ b/deploy-manage/api-keys/elasticsearch-api-keys.md @@ -11,10 +11,15 @@ products: Several types of {{es}} API keys exist: -* **Personal/User** API key: allows external services to access the {{stack}} on behalf of a user. +* **Personal/User** API key: allows external services to access the {{stack}}, including the [{{es}}]({{es-apis}}) and [{{kib}}]({{kib-apis}}) APIs, on behalf of a user. * **Cross-cluster** API key: allows other clusters to connect to this cluster. * **Managed** API key: created and managed by {{kib}} to run background tasks. +:::{tip} +:applies_to: serverless: +To create equivalent keys for {{serverless-full}} projects, refer to [](serverless-project-api-keys.md). For Serverless projects, you can also create [{{ecloud}} API keys](/deploy-manage/api-keys/elastic-cloud-api-keys.md) that include access to {{es}} and {{kib}} APIs. +::: + To manage API keys in {{kib}}, go to the **API keys** management page in the navigation menu or use the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md). ![API Keys UI](/deploy-manage/images/kibana-api-keys.png "") @@ -33,7 +38,7 @@ To manage roles, go to the **Roles** management page using the navigation menu o ## Create an API key [create-api-key] -Two methods are available to create an API key: +The following are available to create an API key: * As a quick option to create a personal API key from anywhere in {{kib}}: 1. From the **Help menu** (![help icon](/deploy-manage/images/help-icon.svg)), select **Connection details > API key**. @@ -56,6 +61,9 @@ From the **Create API key** pane, you can configure your new key: * For a cross-cluster API key, you can control the indices that other clusters have access to. Refer to the [Create cross-cluster API key](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-cross-cluster-api-key) API documentation to learn more. 4. Add any additional metadata about the API as one or more key-value pairs. Refer to the [Create API key](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-api-key) API documentation for examples. +:::{tip} +You can also create an API key [using the {{es}} API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-api-key). + ## Update an API key [update-api-key] To update an API key, go to the **API keys** management page in the navigation menu or use the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md). From the **API keys** page, click on the name of the key you want to update. diff --git a/deploy-manage/api-keys/serverless-project-api-keys.md b/deploy-manage/api-keys/serverless-project-api-keys.md index 1581f03812..dce2d20e51 100644 --- a/deploy-manage/api-keys/serverless-project-api-keys.md +++ b/deploy-manage/api-keys/serverless-project-api-keys.md @@ -9,19 +9,22 @@ products: # Serverless project API keys [api-keys] -In serverless projects, the following types of API keys exist: +In Serverless projects, the following types of API keys exist: -- **Personal** API keys, that you can create to allow external services to access your serverless project on behalf of a user. +- **Personal** API keys, that you can create to allow external services to access your serverless project, including the [{{es}}]({{es-apis}}) and [{{kib}}]({{kib-apis}}) APIs, 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**: +:::{admonition} Manage serverless project API access using {{ecloud}} API keys +As an alternative to using Serverless project API keys, which are tied to a single project, you can create [{{ecloud}} API keys](/deploy-manage/api-keys/elastic-cloud-api-keys.md) that include access to projects' {{es}} and {{kib}} APIs. This allows you to create keys that can interact with multiple projects, and manage API access centrally from the {{ecloud}} console. +::: + +To manage API keys in {{kib}}, go to the **API keys** management page in the navigation menu or use the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md). :::{image} /deploy-manage/images/serverless-api-key-management.png :alt: API keys UI :screenshot: ::: - ## Create an API key [api-keys-create-an-api-key] In **API keys**, click **Create API key**: @@ -44,8 +47,6 @@ API keys are intended for programmatic access. Don’t use API keys to authentic :::: - - ### Control security privileges [api-keys-restrict-privileges] When you create or update an API key, use **Control security privileges** to configure access to specific {{es}} APIs and resources. Define the permissions using a JSON `role_descriptors` object, where you specify one or more roles and the associated privileges. @@ -74,12 +75,10 @@ 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-serverless/operation/operation-security-create-api-key) docs. For supported privileges, check [Security privileges](elasticsearch://reference/elasticsearch/security-privileges.md#privileges-list-indices). - ## Update an API key [api-keys-update-an-api-key] In **API keys**, click on the name of the key. You can update only **Restrict privileges** and **Include metadata**. - ## View and delete API keys [api-keys-view-and-delete-api-keys] The **API keys** app lists your API keys, including the name, date created, and status. When API keys expire, the status changes from `Active` to `Expired`. diff --git a/deploy-manage/cloud-organization.md b/deploy-manage/cloud-organization.md index 419ce9fea3..08cbf8f3fa 100644 --- a/deploy-manage/cloud-organization.md +++ b/deploy-manage/cloud-organization.md @@ -3,8 +3,8 @@ mapped_pages: - https://www.elastic.co/guide/en/cloud/current/ec-organizations.html applies_to: deployment: - ess: all - serverless: all + ess: ga + serverless: ga products: - id: cloud-hosted --- @@ -21,7 +21,7 @@ You can perform the following tasks to manage your Cloud organization: * [Assign roles and privileges](/deploy-manage/users-roles/cloud-organization/user-roles.md) * [Create custom roles](/deploy-manage/users-roles/cloud-enterprise-orchestrator.md) ({{serverless-short}} only) * [Configure SAML single sign-on](/deploy-manage/users-roles/cloud-organization/configure-saml-authentication.md) to your organization -* [Manage API keys](/deploy-manage/api-keys.md) to use with the [{{ecloud}}](https://www.elastic.co/docs/api/doc/cloud), [{{ecloud}} Billing](https://www.elastic.co/docs/api/doc/cloud-billing/), and [{{serverless-full}}](https://www.elastic.co/docs/api/doc/elastic-cloud-serverless) APIs +* [Manage API keys](/deploy-manage/api-keys.md) to use with the [{{ecloud}}](https://www.elastic.co/docs/api/doc/cloud), [{{ecloud}} Billing](https://www.elastic.co/docs/api/doc/cloud-billing/), and [{{serverless-full}}](https://www.elastic.co/docs/api/doc/elastic-cloud-serverless) APIs. For {{serverless-full}} projects, you can also create {{ecloud}} API keys that grant access to project-level {{es}} and {{kib}} APIs. * Configure who receives [operational emails](/deploy-manage/cloud-organization/operational-emails.md) related to your organization * Track the [status of {{ecloud}} services](/deploy-manage/cloud-organization/service-status.md). diff --git a/deploy-manage/users-roles/cloud-organization.md b/deploy-manage/users-roles/cloud-organization.md index 6d056df64a..fa58a6b438 100644 --- a/deploy-manage/users-roles/cloud-organization.md +++ b/deploy-manage/users-roles/cloud-organization.md @@ -4,8 +4,8 @@ mapped_pages: - https://www.elastic.co/guide/en/cloud/current/ec-organizations.html applies_to: deployment: - ess: all - serverless: all + ess: ga + serverless: ga products: - id: cloud-hosted --- @@ -22,6 +22,8 @@ You can perform the following tasks to control access to your Cloud organization * If you have {{serverless-full}} projects, assign project-level roles and create custom roles. * Configure [SAML single sign-on](/deploy-manage/users-roles/cloud-organization/configure-saml-authentication.md) for your organization. +You can also control programmatic access to {{ecloud}}, your deployments, and your projects using [API keys](/deploy-manage/api-keys.md). + :::{tip} If you're using {{ech}}, then you can also manage users and control access [at the deployment level](/deploy-manage/users-roles/cluster-or-deployment-auth.md). ::: @@ -29,7 +31,7 @@ If you're using {{ech}}, then you can also manage users and control access [at t ## Should I use organization-level or deployment-level SSO? [organization-deployment-sso] ```{applies_to} -ess: all +ess: ga ``` :::{include} _snippets/org-vs-deploy-sso.md