How to create an access key - Genbox/SimpleS3 GitHub Wiki

Use temporary credentials by default. Prefer a role or federated identity that lets the application obtain short-lived credentials and refresh them automatically. Long-lived API keys are a fallback when the provider or client cannot use temporary credentials.

A leaked long-lived key can remain usable until it is revoked. Temporary credentials expire, limiting how long a leaked credential can be used. They still need to be protected, and all credentials should grant only the permissions needed. Narrow permissions complement expiration; they do not replace it.

Choose the authentication method for your provider:

  • Amazon S3: use temporary credentials from IAM roles, federation, or IAM Identity Center.
  • Wasabi: use STS temporary credentials. Keep the source key used to obtain sessions in a trusted environment.
  • Google Cloud Storage: use short-lived OAuth 2.0 tokens with a compatible client. Use HMAC keys only when the client requires S3 access-key signing.
  • Backblaze B2 S3-Compatible API: use a scoped application key with a short expiration; this API does not provide an AWS STS session-token flow.

For AWS and Wasabi STS, temporary credentials include an access key ID, a secret access key, and a session token. Supply all three values to a client that supports session credentials. An OAuth token cannot be substituted for an S3 secret key or STS session token. Check the client's authentication and refresh support before choosing a flow.

Amazon S3

Recommended: temporary credentials

Use IAM roles for AWS-hosted workloads and federation for workloads outside AWS. For local development, use IAM Identity Center with a compatible SDK or CLI credential provider. These options avoid distributing long-lived IAM user keys to applications.

AWS STS credentials contain three values:

  • AccessKeyId
  • SecretAccessKey
  • SessionToken

They also have an expiration time. Refresh them before they expire. When signing S3 requests manually or through an S3-compatible client, include the session token in the x-amz-security-token header, or in the X-Amz-Security-Token query parameter for a presigned URL.

To create temporary credentials by assuming an IAM role from an authenticated AWS identity:

  1. Open the IAM console at https://console.aws.amazon.com/iam/.
  2. Create or choose an IAM policy that grants only the required S3 actions and resources.
  3. Go to Roles and click Create role.
  4. Choose AWS account and specify the account containing the caller. Configure the role's trust policy to allow the intended caller to assume it.
  5. Attach the S3 permissions policy from step 2.
  6. Name and create the role.
  7. If a user, CI job, or application will assume the role directly, grant it sts:AssumeRole permission for the role ARN.
  8. Configure the AWS CLI with the caller's credentials, then run aws sts assume-role --role-arn ROLE_ARN --role-session-name SESSION_NAME --duration-seconds 3600. Supply any additional parameters required by the trust policy, such as MFA or an external ID.
  9. Use the returned AccessKeyId, SecretAccessKey, and SessionToken until the expiration time.

For AWS-hosted applications, configure a role for the specific service and associate it with the workload (for example, an EC2 instance profile or an ECS task role). Creating a role alone does not attach it to a workload. Use a client credential provider that obtains and refreshes the role credentials.

Fallback: long-lived IAM user access key

Only create a long-term IAM user access key when the application cannot use temporary credentials.

An IAM user access key consists of an access key ID and a secret access key. These are example values:

  • Access key ID: AKIAIOSFODNN7EXAMPLE
  • Secret access key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

To create a long-term access key for an IAM user:

  1. Go to https://console.aws.amazon.com/iam/home#/users and click Create user.
  2. Enter a username that is related to your project. For example, it could be something like file_transfer_app.
  3. Do not enable console access unless this user also needs to sign in to the AWS Management Console.
  4. On the permissions step, grant only the S3 permissions the application needs. Prefer a custom bucket-scoped policy. Use broad policies such as AmazonS3FullAccess only when the application really needs account-wide S3 administration.
  5. Finish creating the user.
  6. Open the user, go to Security credentials, then click Create access key under Access keys.
  7. Select the use case that matches your application, review the alternatives that AWS shows, and continue only if a long-term access key is still required.
  8. Create the key and store both the access key ID and secret access key securely. You cannot retrieve the secret access key again after leaving the page.

Rotate access keys regularly and delete keys that are no longer used.

References: IAM role creation, temporary credentials, and access key management.

Backblaze B2 S3-Compatible API

Recommended for this API: an expiring application key

Backblaze B2 does not use AWS STS session tokens for the S3-Compatible API. Its alternative is a standard application key with limited permissions and an expiration. This is still an application key, not an STS session. The master application key is not supported by the S3-Compatible API.

To create a Backblaze B2 application key:

  1. Sign in to the Backblaze web console at https://secure.backblaze.com/user_signin.htm.
  2. In the left navigation menu under B2 Cloud Storage, click Application Keys.
  3. Click Add a New Application Key.
  4. Enter a key name that identifies the application or temporary task.
  5. In Allow Access to Bucket (s), select the specific bucket the application needs. Choose All only if required.
  6. If the key is restricted to one bucket and the application must call ListBuckets, enable Allow List All Bucket Names. Some SDKs and integrations list buckets during setup, so they also need this option.
  7. Choose the access type, such as Read and Write, Read Only, or Write Only.
  8. Optionally enter a file name prefix to restrict access to matching object names.
  9. Enter a short, positive integer duration in seconds, such as 3600 for one hour, so the key expires automatically. The value must be less than 86,400,000 seconds (1000 days). Arrange to replace the key before it expires if needed.
  10. Click Create New Key.
  11. Save the returned keyID and applicationKey securely. The applicationKey is shown only once.

Use the keyID as the S3 access key ID and the applicationKey as the S3 secret key. There is no SessionToken value for Backblaze S3-compatible requests. Delete the key when the temporary access period is over.

Fallback: leave the duration blank only when the application requires a non-expiring key. Store it securely, rotate it, and delete it when no longer needed.

References: creating application keys and S3-compatible key restrictions.

Wasabi S3

Recommended: STS temporary credentials

Wasabi supports temporary credentials through STS at https://sts.wasabisys.com. Use this flow when the client supports session tokens. The flow below still requires a source access key: protect it in a trusted backend or credential service and give consuming applications only the temporary credentials.

To obtain temporary credentials:

  1. Create a sub-user access key using the steps below, and configure it in an AWS SDK credentials profile.
  2. Configure the SDK's STS client to use https://sts.wasabisys.com and that profile.
  3. Call GetSessionToken with DurationSeconds set to 900 for a 15-minute session with the source key's permissions. To scope the session to a role, configure a Wasabi IAM role and call AssumeRole with its ARN, a session name, and the duration instead. AssumeRole requires sub-user credentials; root credentials are not supported. An inline session policy can further restrict permissions.
  4. Pass all three returned values (AccessKeyId, SecretAccessKey, and SessionToken) to the S3 client's session credential configuration. Use the Wasabi S3 endpoint for the bucket's region.
  5. Obtain new credentials before the returned expiration time. A static credential configuration does not refresh them automatically.

See Wasabi STS documentation and SDK examples.

Source key for STS, or fallback for clients without session-token support

Create a sub-user key for the trusted component that obtains STS sessions. Give this long-lived key directly to the S3 application only if it cannot use temporary credentials.

To create the sub-user access key:

  1. Sign in to the Wasabi Console.
  2. Create or choose a group for the application or user.
  3. Attach a policy to the group that grants only the required S3 actions and buckets. Prefer a custom policy or a narrow predefined policy over full access.
  4. Go to Users and click Create User.
  5. Enter a user name for the application or temporary task.
  6. Select Programmatic access so the user can receive an access key and secret key.
  7. Do not enable console access unless the person also needs to sign in to the Wasabi Console.
  8. Assign the user to the group from step 2.
  9. Review the user settings and click Create User.
  10. Save the generated access key ID and secret access key securely. The secret is shown only when the key is created.

For clients that require long-term keys, use the generated access key ID and secret access key directly with the Wasabi S3 endpoint for the bucket's region. Delete keys when they are no longer needed.

Reference: creating a Wasabi user and access key.

Google Cloud Storage S3/XML API

Recommended: short-lived OAuth 2.0 tokens

Use a client that supports Google authentication and refreshes OAuth 2.0 access tokens. For production on Google Cloud, use an attached service account with Application Default Credentials. For external workloads, use Workload Identity Federation. Service account impersonation is another option for identities authorized to act as the service account. Configure Application Default Credentials for the chosen identity flow instead of downloading a service account private key.

Both the JSON and XML APIs accept OAuth 2.0 bearer tokens. A client that only supports S3 access-key signing cannot use this flow; it needs the HMAC fallback below.

Fallback: HMAC keys for S3 access-key signing

Cloud Storage HMAC keys have an access ID and secret, separate from service account RSA keys. They are long-lived credentials without an STS session token or automatic expiration. Manually deleting a key after a task does not make it a temporary token. Use a dedicated service account with limited permissions, protect the key, and deactivate it when it is no longer needed. A key must be inactive before it can be deleted.

The identity creating keys needs storage.hmacKeys.create in the project (included in roles/storage.hmacKeyAdmin). This is separate from the service account's permissions to access buckets and objects.

To create a Cloud Storage HMAC key in the console:

  1. Create or choose a service account for the application.
  2. Grant the service account only the Cloud Storage IAM roles it needs.
  3. Make sure HMAC key creation and authentication are allowed by your organization policies.
  4. Open the Cloud Storage Settings page at https://console.cloud.google.com/storage/settings.
  5. Select the Interoperability tab.
  6. Click Create a key for a service account.
  7. Select the service account from step 1.
  8. Click Create key.
  9. Save the returned HMAC access ID and secret securely. The secret cannot be recovered later.
  10. Wait up to 60 seconds for the key to become usable.

To create a Cloud Storage HMAC key with the Google Cloud CLI:

  1. Install and initialize the Google Cloud CLI.
  2. Authenticate with an identity that has permission to manage HMAC keys.
  3. Create or choose a service account for the application.
  4. Grant the service account only the Cloud Storage IAM roles it needs.
  5. Select the project containing the service account and ensure organization policies allow HMAC key creation and use. Run gcloud storage hmac create SERVICE_ACCOUNT_EMAIL --project=PROJECT_ID with that project's ID.
  6. Save the returned accessId and secret securely. The secret cannot be recovered later.
  7. Wait up to 60 seconds for the key to become usable.

Use the HMAC access ID as the S3 access key ID and the HMAC secret as the S3 secret key. Use https://storage.googleapis.com as the S3-compatible endpoint.

References: managing HMAC keys, HMAC key restrictions, and Cloud Storage authentication.