diff --git a/src/content/docs/workers/authorization/index.mdx b/src/content/docs/workers/authorization/index.mdx new file mode 100644 index 00000000000..616b65e5a42 --- /dev/null +++ b/src/content/docs/workers/authorization/index.mdx @@ -0,0 +1,101 @@ +--- +title: Permissions and access +description: Learn how Developer Platform permissions apply across platform, product, and resource scopes. +pcx_content_type: concept +sidebar: + order: 8.5 +products: + - workers +--- + +You can control who can access your Developer Platform resources and what they can do with them by assigning [roles](/fundamentals/manage-members/roles/) and [scopes](/fundamentals/manage-members/scope/) through [permission policies](/fundamentals/manage-members/policies/). Each policy combines a role, which defines the actions allowed, with a scope, which defines where those actions apply. + +For Developer Platform products, scopes can be set at three levels: + +| Level | Scope | Use when | +| -------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Platform | All products on an account | You want to grant access across Workers, R2, D1, KV, Durable Objects, Queues, Workers AI, Vectorize, Hyperdrive, and other Developer Platform resources. | +| Product | All resources in one product | You want to grant access to all Workers, all R2 buckets, or all D1 databases, without granting access to other products. | +| Resource | One resource inside a product | You want to grant access to a specific resource, such as an individual Worker or R2 bucket. | + +## Roles + +Assign one of these roles to define the level of permission you want to grant: + +| Role | What it allows | +| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | +| Metadata Read-Only | View resource lists, settings, metrics, logs, and traces. Cannot view product content such as code, data, or stored objects. | +| Content Read-Only | Everything in Metadata Read-Only, plus read product content such as Worker code, D1 database rows, or R2 objects. Cannot make changes. | +| Editor | Everything in Content Read-Only, plus update product content and settings. Cannot create, delete, or rename resources. | +| Admin | Full control, including creating, deleting, and renaming resources. | + +## Members, User Groups, and API tokens + +Developer Platform permissions can be granted in two ways: + +| Grant type | Best for | How it works | +| ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------- | +| [Members](/fundamentals/manage-members/manage/) and [User Groups](/fundamentals/manage-members/user-groups/) | People using the dashboard, Wrangler, or the API | Permissions are inherited when the member signs in to the Cloudflare dashboard or authenticates Wrangler. | +| [API tokens](/fundamentals/api/get-started/create-token/) | CI/CD systems, automation, and service accounts | The token receives only the product and resource permissions selected when the token is created. | + +### Members and User Groups + +When you assign a [role](/fundamentals/manage-members/roles/) to a [member](/fundamentals/manage-members/manage/) or [User Group](/fundamentals/manage-members/user-groups/), that permission applies whenever the user uses the Cloudflare dashboard, Wrangler, or the API. + +For example, if you assign a member **Metadata Read-Only** at the platform level, they can view settings, metrics, logs, and traces for all Developer Platform products on the account — Workers, R2, D1, and everything else — but cannot view product content like code, data, or stored objects. + +If you assign **Metadata Read-Only** at the Workers product level, they can view settings and observability data for all Workers on the account, but have no visibility into R2, D1, or other products. + +If you assign **Metadata Read-Only** for a single Worker, they can only see settings and observability data for that one Worker. They will not see any other Workers or any other products. + +### API tokens + +Use [API tokens](/fundamentals/api/get-started/create-token/) for CI/CD pipelines, agents, scripts, and other automated systems that need to access Developer Platform resources programmatically. + +For example, create an API token with **Workers Editor** for a deployment pipeline that needs to update and deploy Worker code. + +API tokens support product-level and, where available, resource-level permissions. They do not support platform-level permissions. To grant an API token broad Developer Platform access, select the product-level permissions for each product the token needs. + +### Use Wrangler with member or token authentication + +[Wrangler](/workers/wrangler/) authorizes commands using the permissions of the authenticated member or API token. + +For interactive use, run [`wrangler login`](/workers/wrangler/commands/general/#login). Wrangler uses the roles and scopes assigned to your member account. + +For CI/CD pipelines, agents, scripts, and other automated systems, use an API token instead of a member login. Create a token with only the permissions the system needs, then set these environment variables before running Wrangler: + +```bash +export CLOUDFLARE_API_TOKEN="" +export CLOUDFLARE_ACCOUNT_ID="" +``` + +Wrangler uses the token's permissions. If the token is scoped to a specific Worker, Wrangler can only perform actions allowed for that Worker. + +Wrangler commands can require different permissions depending on what they manage: + +| What you want to do | Example Wrangler command | Required access | +| --------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | +| Deploy an existing Worker | `wrangler deploy` | `Editor` scoped to that Worker, or `Editor` at the Workers product scope. | +| Create a new Worker | `wrangler deploy` for a Worker that does not exist yet | `Admin` at the Workers product scope. | +| Tail logs for one Worker | `wrangler tail` | `Metadata Read-Only` scoped to that Worker, or `Metadata Read-Only` at the Workers product scope. | +| List KV namespaces | `wrangler kv namespace list` | Developer Platform `Metadata Read-Only` at a scope that includes KV. | +| Create a KV namespace | `wrangler kv namespace create` | Developer Platform `Admin` at a scope that includes KV. | +| Deploy a Worker with routes | `wrangler deploy` | `Editor` for the Worker, plus the [zone-level permissions](/fundamentals/manage-members/scope/#specific-domains/) for routes. | + +## Bindings + +To deploy a Worker that has [bindings](/workers/runtime-apis/bindings/) to resources like [Workers KV](/kv/), [R2](/r2/), or [D1](/d1/), you need **Editor** access to the Worker. You do not need separate permissions on the bound resources to deploy the Worker. + +Permissions on bound resources are only required if you need to access those resources directly, for example, reading KV keys, querying a D1 database, or listing R2 objects. + +## Common access patterns + +| Use case | Scope | Role | +| ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | +| View settings, logs, and metrics across all products | Platform | Metadata Read-Only | +| Read Worker code without modifying it | Workers product | Content Read-Only | +| Deploy any existing Worker, no access to other products | Workers product | Editor | +| Deploy a Worker that uses routes | Workers product and [domain-level permissions](/fundamentals/manage-members/scope/#specific-domains) for each domain referenced by the routes | Editor | +| Create or delete Workers | Workers product | Admin | +| Automated deployments from CI/CD or agents | API token with Workers product | Editor | +| Automated deployments to one specific Worker | API token with individual Worker | Editor | diff --git a/src/content/docs/workers/authorization/r2.mdx b/src/content/docs/workers/authorization/r2.mdx new file mode 100644 index 00000000000..e7727273ca0 --- /dev/null +++ b/src/content/docs/workers/authorization/r2.mdx @@ -0,0 +1,74 @@ +--- +title: R2 permissions and access +description: Learn how to manage R2 access through member roles, R2 API tokens, and account API token permission groups. +pcx_content_type: reference +sidebar: + order: 16 +products: + - workers +--- + +[R2](/r2/) permissions control who or what can read, edit, and manage [buckets](/r2/buckets/), [objects](/r2/objects/), warehouses, and associated configuration in your Cloudflare account. Access is granted by assigning an R2 role or permission to a [member](/fundamentals/manage-members/manage/), [User Group](/fundamentals/manage-members/user-groups/), or [API token](/fundamentals/api/get-started/create-token/). + +## Members and User Groups + +Use R2 roles when a person needs dashboard or user-based access. + +| Role | Access | +| ------------------- | -------------------------------------------------------------------- | +| Cloudflare R2 Read | Read R2 buckets, objects, warehouses, and associated configurations. | +| Cloudflare R2 Admin | Edit R2 buckets, objects, warehouses, and associated configurations. | + +## API tokens + +R2 has two types of API tokens. Choose based on how your application connects to R2: + +| How you access R2 | Token type to create | +| ------------------------------------------------------------------------------------ | -------------------- | +| S3-compatible SDKs, CLI tools, or [S3 API](/r2/api/s3/) calls | R2 API token | +| [Cloudflare API](/api/), [Wrangler](/workers/wrangler/), or [Terraform](/terraform/) | Account API token | + +To create an R2 API token, refer to [R2 API tokens](/r2/api/tokens/). To create an account API token, refer to [Create API tokens](/fundamentals/api/get-started/create-token/). + +### R2 API tokens + +Use R2 API tokens when an application needs S3-compatible access to R2. + +| Permission | Scope | Access | +| ------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Admin Read & Write | Account | Create, list, and delete buckets, edit bucket configuration, read, write, and list objects, and read and write to data catalog tables and associated metadata. | +| Admin Read only | Account | List buckets and view bucket configuration, read and list objects, and read from data catalog tables and associated metadata. | +| Object Read & Write | Bucket | Read, write, and list objects in selected buckets. | +| Object Read only | Bucket | Read and list objects in selected buckets. | + +Account-scoped permissions apply to all buckets. Bucket-scoped permissions apply only to the buckets you select when creating the token. + +:::note +[R2 Data Catalog](/r2/data-catalog/) currently requires `Admin Read & Write` or `Admin Read only`. +::: + +### Account API token permission groups + +Use account API token permission groups when an automated system needs access to R2 through the Cloudflare API. + +**Storage** + +| Permission group | Scope | Access | +| ------------------------------------ | ------- | ----------------------------------------------------------------------------------------------- | +| Workers R2 Storage Read | Account | List buckets, view bucket configuration, and read and list objects. | +| Workers R2 Storage Write | Account | Create, delete, and list buckets, edit bucket configuration, and read, write, and list objects. | +| Workers R2 Storage Bucket Item Read | Bucket | Read and list objects in buckets. | +| Workers R2 Storage Bucket Item Write | Bucket | Read, write, and list objects in buckets. | + +**Data Catalog** + +| Permission group | Scope | Access | +| ----------------------------- | ------- | ----------------------------------------------------------------------------------------------------- | +| Workers R2 Data Catalog Read | Account | Read from data catalogs through the [Iceberg REST catalog interface](/r2/data-catalog/). | +| Workers R2 Data Catalog Write | Account | Read from and write to data catalogs through the [Iceberg REST catalog interface](/r2/data-catalog/). | + +**SQL** + +| Permission group | Scope | Access | +| ------------------- | ------- | ---------------------------------- | +| Workers R2 SQL Read | Account | Read [R2 SQL](/r2-sql/) resources. | diff --git a/src/content/docs/workers/authorization/workers.mdx b/src/content/docs/workers/authorization/workers.mdx new file mode 100644 index 00000000000..638fea43d0a --- /dev/null +++ b/src/content/docs/workers/authorization/workers.mdx @@ -0,0 +1,128 @@ +--- +title: Workers permissions and access +description: Manage Workers roles, scopes, Wrangler permissions, and API token access for deploying and managing Workers. +pcx_content_type: reference +sidebar: + label: Workers + order: 1 +products: + - workers +--- + +Workers permissions control who or what can view, deploy, and manage Workers in your Cloudflare account. Access is granted by assigning a Workers role to a member, User Group, or API token at a specific scope. + +Workers roles define what actions are allowed. Scopes define where those actions apply: across all Workers in the account or only to selected Workers. + +For the platform-wide permission model, refer to the [Permissions and access overview](/workers/authorization/). + +## Workers roles + +Workers roles can be assigned to members, User Groups, and API tokens. + +| Role | Access level | Description | +| ------------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Metadata Read-Only | Read metadata | Can view Workers metadata, settings, and observability data such as metrics, logs, and traces. Cannot view script source content or secret values. | +| Content Read-Only | Read content | Can view Workers metadata and script source content. Cannot modify Workers. | +| Editor | Edit | Can read, update, and deploy existing Workers, including script content, settings, routes, schedules, versions, deployments, and observability. Cannot create, delete, or rename Workers. | +| Admin | Full manage | Full control over Workers, including creating, reading, updating, deploying, deleting, and renaming Workers when granted at the product scope. Per-Worker Admin applies only to the selected Worker. | + +## Role scopes + +Workers roles can be granted at different scopes depending on how broadly the access should apply. + +| Scope | Applies to | Use when | +| ------------------ | -------------------------- | ---------------------------------------------------------------------------- | +| Workers product | All Workers in the account | A member, User Group, or API token needs the same access across all Workers. | +| Individual Workers | Only selected Workers | A member, User Group, or API token should only access specific Workers. | + +Product-level roles apply to every current and future Worker in the account. + +Per-Worker roles apply only to the Workers you select. You cannot grant per-Worker access to a Worker that does not exist yet. Creating new Workers requires product-level `Admin` access. + +## Combine product-level and per-Worker access + +You can combine product-level and per-Worker roles to give broad visibility but limited edit access. + +For example, grant `Metadata Read-Only` at the Workers product scope so someone can browse Workers and view observability data across the account. Then grant `Editor` only for the specific Workers they should deploy. + +## Members, User Groups, and API tokens + +You can assign Workers roles to members, User Groups, and API tokens. + +Members and User Groups are for people who need dashboard or user-based access. API tokens are for CI/CD pipelines, agents, scripts, and Wrangler automation. + +API tokens use the same Workers roles and scopes as members and User Groups, but they have their own permissions. A token can only perform actions allowed by the Workers role and scope assigned to that token. + +## Wrangler + +Wrangler authorizes commands using the Workers permissions of the authenticated member or API token. + +Here are examples of the scope required to run Wrangler commands: + +| Action | Wrangler command | Minimum role required | +| ------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| Tail logs for a Worker | `wrangler tail` | `Metadata Read-Only` for that Worker | +| Deploy an existing Worker | `wrangler deploy` | `Editor` for that Worker | +| Deploy an existing Worker with routes | `wrangler deploy` | `Editor` for that Worker, plus [zone-level permissions](/fundamentals/manage-members/scope/#specific-domains) for each zone referenced by routes | +| Create a new Worker | `wrangler deploy` for a Worker that does not exist yet | Product-level `Admin` | +| Upload a version | `wrangler versions upload` | `Editor` for that Worker | +| Deploy a version | `wrangler versions deploy` | `Editor` for that Worker | +| Roll back a deployment | `wrangler rollback` | `Editor` for that Worker | +| Manage secrets for an existing Worker | `wrangler secret put`, `wrangler secret delete` | `Editor` for that Worker | + +## Legacy Workers permissions + +These legacy permissions are being replaced by the new Workers roles. There is no deprecation date right now. Existing permissions continue to work, and customers will receive advance notice before any deprecation. + +These legacy permissions were account-level permissions. To preserve the same behavior, assign the replacement role at the Workers product scope, which applies across all Workers in the account. Use per-Worker scopes only when you intentionally want to limit access to selected Workers. + +| Legacy permission | Replaced by | +| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | +| Workers CI Read | `Content Read-Only` | +| Workers CI Edit | `Editor` | +| Workers Observability Read | `Metadata Read-Only` | +| Workers Observability Edit | `Editor` | +| Workers Observability Telemetry Edit | `Editor` | +| Workers Routes Read | `Metadata Read-Only` | +| Workers Routes Edit | `Editor`, plus [zone-level permission](/fundamentals/manage-members/scope/#specific-domains) for each zone referenced by routes | +| Workers Tail Read | `Metadata Read-Only` | +| Workers Scripts Read | `Content Read-Only` | +| Workers Scripts Edit | `Editor` | + +## Cloudflare Pages + +For members and User Groups, use [Developer Platform roles](/workers/authorization/) to grant [Cloudflare Pages](/pages/) access. Do not use Workers product roles or per-Worker roles for Pages access. + +For API tokens, use Pages-specific roles. These roles are available when creating account-owned API tokens. + +| API token role | Access | +| ------------------- | ----------------------------------------------------------------------------- | +| Pages Metadata Read | View Pages metadata and configuration. Does not include Pages content access. | +| Pages Read | View Pages metadata and content. | +| Pages Write | Create, update, and delete Pages projects and Pages content. | + +## Bindings + +To deploy a Worker that has [bindings](/workers/runtime-apis/bindings/) to resources like [Workers KV](/kv/), [R2](/r2/), or [D1](/d1/), you need `Editor` access to the Worker. You do not need separate permissions on the bound resources to deploy the Worker. + +Permissions on bound resources are only required if you need to access those resources directly, for example, reading KV keys, querying a D1 database, or listing R2 objects. + +## Limitations + +- Product-level Workers roles do not grant access to other Developer Platform products such as [R2](/r2/), [D1](/d1/), [KV](/kv/), [Queues](/queues/), [Vectorize](/vectorize/), or [Hyperdrive](/hyperdrive/). +- API tokens do not support platform-level Developer Platform permissions. +- Creating a new Worker requires Workers Admin because per-Worker permissions can only apply to Workers that already exist. +- Deploying a Worker with routes also requires [zone-level permissions](/fundamentals/manage-members/scope/#specific-domains) for each zone referenced by those routes. +- Durable Objects permissions are inherited from Workers roles and are not assigned separately. +- Legacy Workers permissions may appear in older configuration or API references, but new documentation should use the replacement Workers roles. + +## Related resources + +- [Permissions and access overview](/workers/authorization/) +- Durable Objects permissions and access — coming soon +- [R2 permissions and access](/r2/api/tokens/#permissions) +- [Roles](/fundamentals/manage-members/roles/) +- [Role scopes](/fundamentals/manage-members/scope/) +- [API token permissions](/fundamentals/api/reference/permissions/) +- [User Groups](/fundamentals/manage-members/user-groups/) +- [Wrangler authentication](/workers/wrangler/commands/general/#login)