Map IAM Policies and S3 ACLs to Backblaze B2 Access Controls

Backblaze B2 Cloud Storage provides two ways to reproduce common Amazon S3 access-control patterns. Most accounts use application keys with specific capabilities and optional bucket, file name prefix, and expiration restrictions. Eligible enterprise web console customers can instead use the AWS-compatible Backblaze IAM and STS API for users, roles, policies, access keys, and temporary credentials.

Note

The Backblaze IAM and STS API is available only to customers with access to the Backblaze enterprise web console. For more information, contact the Backblaze Sales team.

Chose a Backblaze B2 Access-Control Model

Use application keys unless your organization has access to the IAM and STS API and specifically needs AWS-compatible identities, policy documents, or temporary role credentials.

Map Common IAM Policy Patterns to Application Keys

An application key combines three types of controls:

• Capabilities determine which operations the key can perform, such as listing, reading, writing, or deleting files.

• Bucket restrictions limit the key to one bucket or a defined group of buckets.

• File name prefix restrictions limit the key to objects whose names begin with a specified prefix.

A key can also have an expiration time. These controls are enforced when the key is used with either the S3-Compatible API or the Backblaze B2 Native API.

When you use the S3-Compatible API, the application key values map to AWS credential fields as follows:

You cannot use a master application key with the S3-Compatible API. Create a standard application key for the integration.

Map IAM and ACL Patterns to Application Key Settings

Use the following table to identify the application key capabilities and restrictions that correspond to common IAM policies and S3 ACL patterns.

Create Least-Privilege Application Keys with the Backblaze B2 CLI

1. Install the current B2 CLI, and authorize it with a master application key or another key that has the writeKeys capability.

   b2 account authorize

2. Create a read-only key for one bucket:

   b2 key create \
     --bucket <bucket-name> \
     tenant-123-read-only \
     listBuckets,listAllBucketNames,listFiles,readFiles

3. Create an upload-only key for one bucket:

   b2 key create \
     --bucket <bucket-name> \
     tenant-123-upload-only \
     listBuckets,listAllBucketNames,writeFiles

4. Create a read-and-write key that is limited to one tenant prefix:

   b2 key create \
     --bucket <bucket-name> \
     --name-prefix "tenants/tenant-123/" \
     tenant-123-read-write \
     listBuckets,listAllBucketNames,listFiles,readFiles,writeFiles

5. Create a key that can read, write, and delete objects and that expires after 24 hours:

   b2 key create \
     --bucket <bucket-name> \
     --duration 86400 \
     tenant-123-temporary \
     listBuckets,listAllBucketNames,listFiles,readFiles,writeFiles,deleteFiles

The CLI returns the application key ID and the secret application key. The secret is displayed only once. Store it in a secrets-management system and do not record it in logs, source code, tenant identifiers, or support tickets.

Create the same keys with the Backblaze B2 Native API

1. Call b2_authorize_account with a master application key or another key that has the writeKeys capability. Save the returned account ID, API URL, and authorization token.

   curl --user "$B2_APPLICATION_KEY_ID:$B2_APPLICATION_KEY" \
     https://api.backblazeb2.com/b2api/v4/b2_authorize_account

2. Then call b2_create_key. The following example creates a read-only key that is restricted to one bucket:

   curl --request POST \
     "$B2_API_URL/b2api/v4/b2_create_key" \
     --header "Authorization: $B2_AUTH_TOKEN" \
     --header "Content-Type: application/json" \
     --data '{
       "accountId": "<account-id>",
       "capabilities": [
         "listBuckets",
         "listAllBucketNames",
         "listFiles",
         "readFiles"
       ],
       "keyName": "tenant-123-read-only",
       "bucketIds": ["<bucket-id>"]
     }'

3. Change the request fields to create the other common patterns:

   Pattern	capabilities	Additional fields
   Upload only	["listBuckets", "listAllBucketNames", "writeFiles"]	"bucketIds": ["<bucket-id>"]
   Read and write	["listBuckets", "listAllBucketNames", "listFiles", "readFiles", "writeFiles"]	"bucketIds": ["<bucket-id>"]
   Read, write, and delete	["listBuckets", "listAllBucketNames", "listFiles", "readFiles", "writeFiles", "deleteFiles"]	"bucketIds": ["<bucket-id>"]
   One tenant prefix	Use the capabilities required by the tenant	"bucketIds": ["<bucket-id>"] and "namePrefix": "tenants/tenant-123/"
   Multiple buckets	Use the capabilities required by the workload	"bucketIds": ["<bucket-id-1>", "<bucket-id-2>"]
   Temporary key	Use the capabilities required by the workload	"validDurationInSeconds": 86400

Map S3 ACLs to Backblaze B2

Use the following table to identify how common S3 ACL requirements correspond to Backblaze B2 bucket access settings.

The Backblaze B2 S3-Compatible API supports only the private and public-read canned ACL values at the bucket level. Objects inherit the ACL of their bucket.

A Put Object ACL request succeeds only when the requested object ACL matches the bucket ACL. Attempting to apply a different ACL to an object returns an error.

Implement Per-Tenant Access in a Custom Control Plane

Maintain the tenant-to-storage mapping in your own control plane. When you provision a tenant, assign that tenant a separate bucket, a separate prefix, or a separate Backblaze B2 account, and issue a distinct credential for that scope.

1. Create or select the tenant's bucket.

2. If tenants share a bucket, assign a nonoverlapping file name prefix such as tenants/<internal-tenant-id>/.

3. Create an application key with only the capabilities that the tenant's workload requires.

4. Restrict the key to the tenant's bucket or prefix.

5. Store the application key ID and application key in a secrets-management system.

6. Record the key ID, scope, creation time, and tenant mapping in your control-plane database. Do not store the secret in routine operational logs.

7. Rotate the key by creating a replacement, updating the tenant workload, testing the replacement, and deleting the old key.

Do not use email addresses, customer names, or other personally identifiable information in bucket names, key names, prefixes, or metadata. Use an internal tenant identifier.

Use the Backblaze IAM and STS API

Use the IAM and STS API when an eligible enterprise implementation requires AWS-compatible IAM users, roles, inline policies, access keys, or short-lived role credentials. Common AWS tools and SDKs can call the Backblaze IAM, STS, and S3-compatible endpoints.

The following example session policy limits an assumed role session to uploads beneath one tenant prefix:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "TenantUploadOnly",
      "Effect": "Allow",
      "Action": ["s3:PutObject"],
      "Resource": [
        "arn:aws:s3:::<bucket-name>/tenants/tenant-123/*"
      ]
    }
  ]
}

Use AssumeRole against https://sts.backblazeb2.com to request temporary credentials. Sessions can last from 900 to 43,200 seconds. You can also pass a restrictive session policy when you assume the role.

The first release does not support all AWS IAM features. Managed policies, policy attachments, permissions boundaries, IAM resource tags, and regional STS endpoints are not supported. Supported policies are limited to inline user policies, inline role policies, session policies, and bucket policies. At launch, supported conditions include IpAddress, NotIpAddress, and aws:SourceIp.

IAM changes are eventually consistent. Temporary STS credentials contain a snapshot of the permissions that applied when the session was issued. Later policy changes do not alter existing sessions.

Apply Least Privilege

• Create a separate credential for each application, service, or tenant.

• Grant only the capabilities or policy actions that the workload requires.

• Restrict access to specific buckets and prefixes whenever possible.

• Do not grant deleteFiles unless the workload must permanently delete object versions.

• Do not grant writeKeys to a tenant or data-plane credential.

• Use expiration for temporary integrations, migrations, and support access.

• Keep production, test, and development credentials separate.

• Store secrets outside of source code and rotate them according to your organization's credential policy.

Rotate or Revoke Application Keys

You cannot change an existing application key's secret, capabilities, buckets, prefix, or expiration. Create a replacement key with the required settings, deploy the replacement, verify access, and then delete the old key.

b2 key delete <application-key-id>

Deleting an application key revokes future authorization with that key. Plan for a short overlap between the old and new keys so that you can update dependent applications without an outage.

Understand the Limits of Each Access Pattern

Review the following limitations before you select an access-control pattern for your implementation.

• Application keys do not evaluate AWS IAM policy documents. They use fixed capabilities and resource restrictions.

• A file name prefix restriction is not a general policy expression. It matches only the beginning of an object name.

• One application key cannot assign different capabilities to different prefixes. Create separate keys when workloads need different permissions.

• Application keys do not provide STS-style role sessions. Use the IAM and STS API when short-lived role credentials are required and your organization has access.

• Backblaze B2 S3-compatible ACLs apply at the bucket level. Per-object ACL overrides and complex XML ACLs are not supported.

• The IAM and STS API supports a reduced AWS-compatible feature set and is available only to eligible enterprise web console customers.

• Some S3-compatible tools test permissions by listing buckets. A bucket-restricted key may need listAllBucketNames even when the application uses only one bucket.

Frequently asked questions

What is the Backblaze B2 equivalent of an AWS access key?

For the S3-Compatible API, the Backblaze B2 application key ID is the AWS access key ID, and the Backblaze B2 Application Key is the AWS secret access key. Configure the client to use the S3 endpoint for your Backblaze B2 region.

Does Backblaze B2 support IAM policies?

Standard Backblaze B2 application keys do not use IAM policy documents. Eligible enterprise web console customers can use the limited-availability Backblaze IAM and STS API, which supports a defined subset of AWS-compatible IAM and STS features.

Can an Application Key be restricted to one folder?

Backblaze B2 object storage does not use physical folders. You can restrict an application key to object names that begin with a specific file name prefix, such as tenants/tenant-123/.

Can different objects in one bucket have different ACLs?

No. Backblaze B2 supports private and public-read canned ACLs at the bucket level. Objects inherit the bucket ACL.

Can I create temporary Backblaze B2 credentials?

You can create an application key that expires after a specified duration. Eligible enterprise web console customers can use AssumeRole to obtain short-lived STS credentials.

Additional Resources

• Application Keys

• Application Key Capabilities

• Use S3-Compatible Application Keys

• b2_create_key

• S3-Compatible API

• Backblaze IAM and STS API

• AssumeRole