diff --git a/docs.json b/docs.json index 02ea373c31..fe4fdfb49a 100644 --- a/docs.json +++ b/docs.json @@ -141,6 +141,7 @@ "platform/hosting/iam/ldap", "platform/hosting/iam/sso", "platform/hosting/iam/identity_federation", + "platform/hosting/iam/api-keys", "platform/hosting/iam/service-accounts" ] }, diff --git a/platform/app/settings-page/user-settings.mdx b/platform/app/settings-page/user-settings.mdx index 401226bedc..8e87a8bb0d 100644 --- a/platform/app/settings-page/user-settings.mdx +++ b/platform/app/settings-page/user-settings.mdx @@ -77,6 +77,10 @@ To create or manage a team, see [Manage teams](/platform/app/settings-page/teams The **API Keys** section lets you manage your personal API keys for authenticating with W&B services. From this section, you can review existing keys, create new ones, and revoke keys you no longer need. + +This section shows only your personal API keys. To see every key in your organization, including organization-scoped keys and service account keys, use the **API Keys** tab described in [Manage API keys](/platform/hosting/iam/api-keys). + + ### View your API keys The API keys table displays: diff --git a/platform/hosting/iam/advanced_env_vars.mdx b/platform/hosting/iam/advanced_env_vars.mdx index 56621d6902..466e6e98f6 100644 --- a/platform/hosting/iam/advanced_env_vars.mdx +++ b/platform/hosting/iam/advanced_env_vars.mdx @@ -19,7 +19,7 @@ Choose any of the following environment variables for your instance depending on | `GORILLA_USE_IDENTIFIER_CLAIMS` | If you use OIDC-based SSO, set this variable to `true` to enforce the username and full name of your users using specific OIDC claims from your identity provider. If set, ensure that you configure the enforced username and full name in the `preferred_username` and `name` OIDC claims respectively. Usernames can only contain alphanumeric characters along with underscores and hyphens as special characters. | | `GORILLA_DISABLE_PERSONAL_ENTITY` | When set to `true`, turns off [personal entities](/support/models/articles/what-is-the-difference-between-team-and-). Prevents creation of new personal projects in their personal entities and prevents writing to existing personal projects. | | `GORILLA_DISABLE_ADMIN_TEAM_ACCESS` | Set this to `true` to restrict Organization or Instance Admins from self-joining or adding themselves to a W&B team, ensuring that only Data and AI personas have access to the projects within the teams. | -| `GORILLA_DISABLE_TEAM_SERVICE_ACCOUNT_CREATION` | Set this to `true` to prevent the creation of new [team-scoped service accounts](/platform/hosting/iam/service-accounts#team-scoped-service-accounts). Available in Dedicated Cloud and Self-Managed v0.83.0+. | +| `GORILLA_DISABLE_TEAM_SERVICE_ACCOUNT_CREATION` | Set this to `true` to prevent the creation of new [team-scoped service accounts](/platform/hosting/iam/service-accounts#team-scoped-service-accounts). Available in Dedicated Cloud and Self-Managed v0.83.0+. To prevent members from creating new API keys, see [Disable API key creation](/platform/hosting/iam/api-keys#disable-api-key-creation), which is an organization setting rather than an environment variable. | | `WANDB_IDENTITY_TOKEN_FILE` | For [identity federation](/platform/hosting/iam/identity_federation/), the absolute path to the local directory where Java Web Tokens (JWTs) are stored. | diff --git a/platform/hosting/iam/api-keys.mdx b/platform/hosting/iam/api-keys.mdx new file mode 100644 index 0000000000..bd96470b4a --- /dev/null +++ b/platform/hosting/iam/api-keys.mdx @@ -0,0 +1,203 @@ +--- +title: Manage API keys +description: "Find, create, and delete W&B API keys, and restrict how members of your organization create and use them." +keywords: ["organization-scoped API key", "revoke API key", "API Keys tab", "disable API key creation", "key rotation"] +--- + +import ApiKeySecurity from "/snippets/_includes/api-key-security.mdx"; +import ApiKeyViewOnceWarning from "/snippets/_includes/api-key-view-once-warning.mdx"; + +An API key authenticates a person or a service account to W&B. This page describes the kinds of API keys W&B issues, where to find and manage them, and the organization settings that restrict how members create and use them. It's intended for organization admins and team admins who govern credentials, and for members who manage their own keys. + +To store keys safely once you have them, see [Store and handle API keys securely](#store-and-handle-api-keys-securely). + +## Types of API keys + +W&B issues API keys to both people and service accounts. + +| Key type | Belongs to | Scope | +| --- | --- | --- | +| Personal API key | A user | Every organization the user belongs to | +| Organization-scoped API key | A user, within one organization | Only that organization's resources | +| [Team service account](/platform/hosting/iam/service-accounts#team-scoped-service-accounts) key | A service account | One team | +| [Organization service account](/platform/hosting/iam/service-accounts#organization-scoped-service-accounts) key | A service account | All teams in the organization | + + +An **organization-scoped API key** and an **organization-scoped service account** are different things. An organization-scoped API key belongs to a person and authenticates that person, limited to a single organization. An organization-scoped service account is a non-human identity used for automation, and it has its own API keys. A user can hold an organization-scoped API key without any service account being involved. + + +Organization-scoped API keys limit the damage a leaked key can do. A personal API key works in every organization its owner belongs to, so a key exposed in a public repository can reach resources in an unrelated organization. An organization-scoped key only works in the organization it was created for. + +Organization-scoped API keys are available in Multi-tenant Cloud for Enterprise organizations, and W&B enables them per organization. If you don't see the options described in the following sections, contact your W&B account team. + +## Find and manage API keys + +Organization admins, team admins, and members manage keys from the **API Keys** tab. + + + +1. Click your profile icon in the upper right, then select your organization. +2. Navigate to `https://wandb.ai/account-settings/[ORGANIZATION]/api-keys`. Replace `[ORGANIZATION]` with your organization name. + + The **API Keys** tab lists the keys you have permission to see. + + +1. Navigate to the **Organization Dashboard**: + - **Dedicated Cloud**: `https://[ORG-NAME].io/org/dashboard/`. Replace `[ORG-NAME]` with your organization name. + - **Self-Managed**: `https://[YOUR-W&B-SERVER-IP]/org/dashboard`. Replace `[YOUR-W&B-SERVER-IP]` with your deployment's IP address. +2. Click the **API Keys** tab. + + The tab lists the keys you have permission to see. + + + +To find only your own personal API keys, click your profile icon, then click **User Settings** and scroll to **API Keys**. See [User settings](/platform/app/settings-page/user-settings#api-keys). + + +In Multi-tenant Cloud, users whose organization role is billing admin can't see the **API Keys** tab. In Dedicated Cloud and Self-Managed, the tab isn't restricted by billing role. + + +### Key visibility by role + +The keys listed in the **API Keys** tab depend on your role: + +| Role | Can see | +| --- | --- | +| Member | Their own organization-scoped keys | +| Team admin | Their own organization-scoped keys, and keys for service accounts in teams they administer. | +| Organization admin | All organization-scoped keys in the organization, including organization service account keys. | +| Billing admin | In Multi-tenant Cloud, nothing. The **API Keys** tab is hidden for this role. In Dedicated Cloud and Self-Managed, the same keys as a member. | + +### Read the API keys table + +The table lists each key with the following columns: + +- **Key name**: The descriptive name given to the key when it was created. +- **Key ID**: The first part of the key, used for identification. +- **Owner**: The user or service account that owns the key. +- **Last used**: When the key most recently authenticated a request. +- **Created on**: When the key was created. + + +For security, the table shows only the key ID. W&B displays the full secret key once, when you create it. If you no longer have the full secret for a key, [rotate the key](#rotate-an-api-key). + + +To narrow the list, type in the search field to match a key name, key ID, or owner, or click **Filters** to filter by attributes such as key type. + +### Create an API key + +1. Go to the **API Keys** tab. +2. Click **New key**. +3. Give the key a descriptive name. +4. Click **Create**. +5. Copy the key immediately and store it securely. + + + +In Multi-tenant Cloud, keys you create from this tab are scoped to the organization you're viewing. Create a separate key for each organization you work in. + +### Rename an API key + +Rename a key to record what uses it, which makes an unfamiliar key easier to trace later. Renaming doesn't change the key's secret and doesn't interrupt anything that uses it. + +1. Find the key in the table. +2. Click the actions menu at the end of the key's row, then click **Edit**. +3. Enter a new name, then save. + +### Delete API keys + +Delete a key when you no longer need it, or immediately if it may have been exposed. + +To delete a single key, find it in the table, click the actions menu at the end of its row, then click **Delete** and confirm. + +To delete several keys at once: + +1. Select the checkbox next to each key you want to delete. +2. Click **Delete**. The button shows the number of keys you selected. +3. Confirm the deletion. + + +Deleting a key immediately revokes access for any script or service that uses it. Update your systems to use a replacement key before you delete the old one. + + +### Rotate an API key + +Rotate a key on a schedule that matches your security policy, and immediately if a key may have been exposed. Rotate a key rather than delete it when the workloads that use it must keep running. + +W&B has no single rotate action. Because a key's full secret is shown only at creation, you rotate a key by replacing it: + +1. Create a new API key. Give it a name that distinguishes it from the key you're replacing. +2. Update every script, job, and stored secret that uses the old key. For storage options, see [Store and handle API keys securely](#store-and-handle-api-keys-securely). +3. Confirm that your workloads authenticate with the new key. +4. Delete the old key. + +Until you complete the last step, both keys work. This overlap is what lets you rotate without downtime, so keep it short. + + +If a key was exposed publicly, delete it immediately rather than waiting to update your systems. An exposed key stays valid until you delete it. + + +## Restrict how members use API keys + +Organization admins can restrict key creation and use. The available restrictions differ by deployment type, and each is set through the `updateOrganizationPrivacySettings` GraphQL mutation rather than through the W&B App. + +### Require organization-scoped API keys + +Available in **Multi-tenant Cloud** for Enterprise organizations. + +When enabled, only organization-scoped API keys can access the organization's resources. Personal API keys that a member uses across several organizations no longer work against this organization, which prevents a key leaked from elsewhere from reaching your data. + +Replace `[ORGANIZATION-ID]` with the ID of your organization. + +```graphql +mutation RequireOrgScopedAPIKeys { + updateOrganizationPrivacySettings( + input: {organizationId: "[ORGANIZATION-ID]", requireOrgScopedAPIKeys: true} + ) { + success + } +} +``` + +This setting requires that organization-scoped API keys are already enabled for your organization. Contact your W&B account team to confirm. + +### Disable API key creation + +Available in **Dedicated Cloud** and **Self-Managed** v0.84.0 and above. + +When enabled, members of the organization can't create new API keys. Existing keys keep working, so turning this on doesn't interrupt running jobs. Use it when your organization issues keys through a controlled process and you want to prevent members from creating their own. + +Replace `[ORGANIZATION-ID]` with the ID of your organization. + +```graphql +mutation DisableAPIKeyCreation { + updateOrganizationPrivacySettings( + input: {organizationId: "[ORGANIZATION-ID]", disableApiKeyCreation: true} + ) { + success + } +} +``` + +A member who tries to create a key after you enable this setting receives the following error: + +```text +API key creation has been disabled by your organization administrator +``` + +To restrict service account creation as well, see [`GORILLA_DISABLE_TEAM_SERVICE_ACCOUNT_CREATION`](/platform/hosting/iam/advanced_env_vars), which prevents the creation of new team-scoped service accounts in Dedicated Cloud and Self-Managed v0.83.0 and above. + +## Availability + +API key capabilities differ by deployment type and, in Multi-tenant Cloud, by subscription. The following table summarizes where each capability is available. + +| Capability | Multi-tenant Cloud | Dedicated Cloud | Self-Managed | +| --- | --- | --- | --- | +| Search and filter the API keys table | Yes | v0.84.0+ | v0.84.0+ | +| Create a key from the **API Keys** tab | Enterprise organizations | v0.84.0+ | v0.84.0+ | +| Delete several keys at once | Enterprise organizations | v0.84.0+ | v0.84.0+ | +| Organization-scoped API keys | Enterprise organizations | Not available | Not available | +| Require organization-scoped API keys | Enterprise organizations | Not available | Not available | +| Disable API key creation | Not available | v0.84.0+ | v0.84.0+ | + + diff --git a/platform/hosting/iam/service-accounts.mdx b/platform/hosting/iam/service-accounts.mdx index 758d1456bb..9482678c4a 100644 --- a/platform/hosting/iam/service-accounts.mdx +++ b/platform/hosting/iam/service-accounts.mdx @@ -26,7 +26,11 @@ Service accounts provide a secure way to automate W&B workflows without using pe - **Organization-scoped**: Created by org admins, with access across all teams. - **Team-scoped**: Created by team admins, with access limited to a specific team. - + + +An organization-scoped service account is not the same as an [organization-scoped API key](/platform/hosting/iam/api-keys#types-of-api-keys). A service account is a non-human identity that holds its own keys. An organization-scoped API key belongs to a person and authenticates that person within a single organization. + + A service account's API key lets the caller read from or write to projects within the service account's scope. This enables centralized management of automated workflows for experiment tracking in W&B Models or logging traces in W&B Weave. Service accounts are useful for: