Supported IAM Policy Elements and Conditions

Backblaze IAM uses AWS-compatible JSON policies to control access to IAM resources and Backblaze B2 Cloud Storage. This article describes the supported policy elements, condition operators, condition keys, and policy variables, including limitations that differ from AWS IAM.

Availability: Your Backblaze account must have IAM enabled. Contact Backblaze Support or your account representative to request access.

Backblaze supports a subset of AWS IAM policy functionality. Support for a policy element does not mean that every AWS API operation or condition key is available for every request.

Understand Policy Evaluation

Backblaze evaluates applicable policies when a principal makes a request:

• An Allow statement can grant access when its action, resource, principal (where applicable), and conditions match.

• An applicable explicit Deny overrides an Allow.

• If no applicable statement grants permission, Backblaze denies the request by default.

Conditions limit when a statement matches. A statement whose conditions do not match does not grant access, but another applicable statement might. Consider all applicable policies when determining whether a request is authorized.

Choose a Policy Type

Backblaze also supports session policies supplied through supported STS operations. A session policy can restrict the permissions available to a role session; it cannot grant permissions beyond those available to the role.

Use Supported Policy Elements

An action pattern can match only operations that Backblaze supports. In a bucket policy, resource ARNs must refer to the bucket that owns the policy.

Specify Principals

The supported Principal format depends on the policy type.

Do not use partial wildcards within principal ARNs. The CanonicalUser principal form is not supported in the bucket-policy matching described here.

Bucket policies support NotPrincipal only with Effect: Deny. An exclusion from a Deny does not grant permission. When excluding a role session, account for both the role ARN and the relevant assumed-role session ARN. You can also use an ArnNotEquals condition on aws:PrincipalArn when that better expresses the intended restriction.

Use Policy Conditions

Place all the conditions for a statement in one Condition object. Backblaze combines different operators and condition keys with logical AND. Each JSON object must use unique keys.

For example, the following condition block matches only when the request uses TLS and the caller's existing session contains Team=blue:

"Condition": {
  "StringEquals": {
    "aws:PrincipalTag/Team": "blue"
  },
  "Bool": {
    "aws:SecureTransport": "true"
  }
}

This is a condition block for use inside a policy statement, not a complete policy document.

Supported Condition Operators

Use the operator that corresponds to the condition key's value type. For example, Bool works with registered Boolean keys, not tag values that happen to contain the text true. Numeric and date operators do not expand policy variables.

Handle Missing Condition Keys

A condition key is available only when Backblaze can determine its value for the request. For example, aws:username is available for IAM user credentials but not for assumed-role sessions.

Positive string, ARN, and IP comparisons generally do not match when the key is absent. Some negated comparisons can match an absent key. If a negated condition requires the key to exist, add a Null check with "false" for that key.

An expected-value array does not create a multivalued request key. ForAnyValue: and ForAllValues: qualifiers are not supported.

IP Address Restrictions

Backblaze supports IpAddress and NotIpAddress conditions for both IPv4 and IPv6, with limitations. Use IPv4 CIDR ranges to match IPv4 requests and IPv6 CIDR ranges to match IPv6 requests. Do not assume that a CIDR range for one address family restricts requests from the other.

The aws:SourceIp key identifies the source address available to Backblaze. When a request passes through a proxy or CDN, this may be the proxy or CDN address rather than the original client's address. Do not treat unverified forwarding headers as an authenticated client address.

Use Supported Condition Keys

Condition keys depend on the identity, credentials, operation, resource, and request. A key's presence in this table does not mean it is available for every operation.

Use Policy Variables

Policies with "Version": "2012-10-17" can substitute an available single-valued condition key by using the ${...} expression. Backblaze supports substitution for an entire policy string or within supported condition strings and resource paths.

For example, this inline role policy allows a session with Team=blue to retrieve objects under the teams/blue/ prefix:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::example-reports/teams/${aws:PrincipalTag/Team}/*",
      "Condition": {
        "Null": {
          "aws:PrincipalTag/Team": "false"
        }
      }
    }
  ]
}

The session must already contain the Team tag. The Null condition checks that the key is present. If the tag is absent, the statement does not grant access.

Variable values cannot substitute for the service, region, or account components of a resource ARN. Backblaze treats * and ? characters within substituted values as literal characters, not wildcards. If a referenced value is missing, substitution does not create an unconditional grant.

If a policy omits Version or specifies 2008-10-17, Backblaze treats variable expressions as literal text. Static policy statements can still work with those versions.

Review Policy Examples

The following examples illustrate policy matching. The final result also depends on other applicable policies and permissions.

Allow Access to a Bucket from an Identity Policy

Attach this policy to an IAM user or role to allow bucket listing and object access for example-reports:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::example-reports"
    },
    {
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject"],
      "Resource": "arn:aws:s3:::example-reports/*"
    }
  ]
}

The policy does not specify Principal because the attached identity is implicit. Other applicable policies can still restrict or deny the operations.

Require a Session Tag in a Role Trust Policy

The following role trust policy requires the IAM user report-reader to request Team=blue when calling AssumeRole. It authorizes TagSession in a separate statement:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::123456789012:user/report-reader"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "aws:RequestTag/Team": "blue"
        }
      }
    },
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::123456789012:user/report-reader"
      },
      "Action": "sts:TagSession"
    }
  ]
}

The request must include the matching session tag and satisfy the other authorization requirements. Authorizing TagSession separately avoids applying the tag-value condition to an action that does not provide that condition key.

Deny Other Principals in a Bucket Policy

This bucket policy denies s3:GetObject for principals other than the report-reader role:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Deny",
      "Principal": "*",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::example-reports/reports/summary.csv",
      "Condition": {
        "ArnNotEquals": {
          "aws:PrincipalArn": "arn:aws:iam::123456789012:role/report-reader"
        }
      }
    }
  ]
}

When a session associated with report-reader makes the request, Backblaze uses the underlying role ARN for aws:PrincipalArn. The policy denies access to the object for all other principals. The report-reader role is exempt from this denial but still requires an applicable Allow statement to access the object.

Unsupported Policy Features

Do not use the following constructs in Backblaze IAM policies:

Do not assume that support for session tags means Backblaze supports every AWS IAM tagging operation. Likewise, valid policy syntax does not guarantee that a condition key is available for a particular request or that an unsupported API operation becomes available.

Additional Resources

• IAM and STS API Reference

• How to Configure OIDC Workload Identity

• OIDC Workload Identity with Backblaze IAM