Authorizing Regional endpoint APIs with IAM
AWS Identity and Access Management (IAM) is an AWS service that helps administrators securely control access to AWS resources. IAM administrators control who can be authenticated (signed in) and authorized (have permissions) to use Amazon S3 resources in S3 Express One Zone. You can use IAM for no additional charge.
By default, users don't have permissions for directory buckets and S3 Express One Zone operations. To grant access permissions for directory buckets, you can use IAM to create users, groups, or roles and attach permissions to those identities. For more information about IAM, see Security best practices in IAM in the IAM User Guide.
To provide access, you can add permissions to your users, groups, or roles through the following means:
-
Users and groups in AWS IAM Identity Center – Create a permission set. Follow the instructions in Create a permission set in the AWS IAM Identity Center User Guide.
-
Users managed in IAM through an identity provider – Create a role for identity federation. Follow the instructions in Creating a role for a third-party identity provider (federation) in the IAM User Guide.
-
IAM roles and users – Create a role that your user can assume. Follow the instructions in Creating a role to delegate permissions to an IAM user in the IAM User Guide.
For more information about IAM for S3 Express One Zone, see the following topics.
Topics
Principals
When you create a resource-based policy to grant access to your buckets, you must use
the Principal element to specify the person or application that can make a
request for an action or operation on that resource. For directory bucket policies, you
can use the following principals:
-
An AWS account
-
An IAM user
-
An IAM role
-
A federated user
For more information, see Principal in the IAM User Guide.
Resources
Amazon Resource Names (ARNs) for directory buckets contain the s3express
namespace, the AWS Region, the AWS account ID, and the directory bucket name,
which includes the Availability Zone ID. To access and perform actions on your
directory bucket, you must use the following ARN format:
arn:aws:s3express:region:account-id:bucket/base-bucket-name--zone-id--x-s3
For more information about ARNs, see Amazon Resource Names (ARNs) in the IAM User Guide. For more information about resources, see IAM JSON Policy Elements: Resource in the IAM User Guide.
Actions for directory buckets
In an IAM identity-based policy or resource-based policy, you define which S3
actions are allowed or denied. Actions correspond to specific API
operations. When using directory buckets, you can use the S3 Express One Zone namespace to grant permissions. This namespace is s3express.
When you allow the s3express:CreateSession permission, this enables the
CreateSession API operation to retrieve session tokens when accessing
Zonal endpoint API (or object level) operations. These session tokens return
credentials that are used to grant access to all of the other Zonal endpoint API
operations. As a result, you don't have to grant access permissions to Zonal API
operations by using IAM policies. Instead, the session token enables access.
For the list of Zonal endpoint API operations and permissions, see
Authenticating and authorizing requests.
For more information about Zonal and Regional endpoint API operations, see
Networking for directory buckets. To learn more
about the CreateSession API operation, see CreateSession in the Amazon Simple Storage Service API Reference.
You can specify the following actions in the Action element of an IAM
policy statement. Use policies to grant permissions to perform an operation in AWS.
When you use an action in a policy, you usually allow or deny access to the API
operation with the same name. However, in some cases, a single action controls access to
more than one API operation. Access to bucket-level actions can be granted in only IAM
identity-based policies (user or role) and not bucket policies.
The following table shows actions and condition keys.
| Action | API | Description | Access level | Condition keys |
|---|---|---|---|---|
s3express:CreateBucket
|
CreateBucket |
Grants permission to create a new bucket. |
Write |
|
s3express:CreateSession |
Zonal endpoint API operations |
Grants permission to create a session token, which is used for
granting access to all Zonal (object-level) API operations, such as
|
Write |
|
s3express:DeleteBucket |
DeleteBucket |
Grants permission to delete the bucket named in the URI. |
Write |
|
s3express:DeleteBucketPolicy |
DeleteBucketPolicy |
Grants permission to delete the policy on a specified bucket. |
Permissions management |
|
s3express:GetBucketPolicy |
GetBucketPolicy |
Grants permission to return the policy of the specified bucket. |
Read |
|
s3express:GetEncryptionConfiguration |
GetBucketEncryption |
Grants permission to return the default encryption configuration of a directory bucket. |
Read |
|
s3express:ListAllMyDirectoryBuckets |
ListDirectoryBuckets |
Grants permission to list all directory buckets owned by the authenticated sender of the request. |
List |
|
s3express:PutBucketPolicy |
PutBucketPolicy |
Grants permission to add or replace a bucket policy on a bucket. |
Permissions management |
|
s3express:PutBucketPolicy |
PutBucketPolicy |
Grants permission to add or replace a bucket policy on a bucket. |
Permissions management |
|
s3express:PutEncryptionConfiguration |
PutBucketEncryption or DeleteBucketEncryption |
Grants permission to set the encryption configuration for a directory bucket |
Write |
|
Condition keys for directory buckets
The following are condition keys that can be used in the Condition
element of an IAM policy. You can use these keys to further refine the conditions
under which the policy statement applies.
| Condition key | Description | Type |
|---|---|---|
s3express:authType |
Filters access by authentication method. To restrict incoming requests to
use a specific authentication method, you can use this optional condition
key. For example, you can use this condition key to allow only the HTTP
Valid values:
|
String |
s3express:LocationName |
Filters access to the Example value:
|
String |
s3express:ResourceAccount |
Filters access by the resource owner's AWS account ID. To restrict user, role, or application access to the directory buckets
that are owned by a specific AWS account ID, you can use either the
Example value:
|
String |
s3express:SessionMode |
Filters access by the permission requested by the
Valid values:
|
String |
s3express:signatureAge |
Filters access by the age in milliseconds of the request signature. This condition works only for presigned URLs. In AWS Signature Version 4, the signing key is valid for up to seven days. Therefore, the signatures are also valid for up to seven days. For more information, see Introduction to signing requests in the Amazon Simple Storage Service API Reference. You can use this condition to further limit the signature age. Example value:
|
Numeric |
s3express:signatureversion |
Identifies the version of AWS Signature that you want to support for authenticated requests. For authenticated requests, Signature Version 4 is supported. Valid value:
|
String |
s3express:TlsVersion |
Filters access by the TLS version that's used by the client. You can use the Example
value:
|
Numeric |
s3express:x-amz-content-sha256 |
Filters access by unsigned content in your bucket. You can use this condition key to disallow unsigned content in your bucket. When you use Signature Version 4 for requests that use the
You can use this condition key in your bucket policy to deny any uploads where the payloads aren't signed. For example:
Valid value:
|
String |
s3express:x-amz-server-side-encryption |
Filters access by server-side encryption Valid values:
|
String |
s3express:x-amz-server-side-encryption-aws-kms-key-id |
Filters access by AWS KMS customer managed key for server-side encryption Example
value:
|
ARN |
