Configure managed S3 access
This guide covers Gateman-assisted provisioning of a dedicated AWS S3 runtime identity. It is separate from the Use S3 Capability Reference, which documents authenticated runtime presigning.
Scope
Managed provisioning exists only to enable the supported S3 capability. It does not create buckets, bucket policies, ACLs, or objects, and it is not a general AWS or IAM administration service.
Gateman creates or verifies one app-scoped IAM runtime user, applies an inline policy restricted to the configured buckets, prefixes, and selected s3:GetObject/s3:PutObject actions, and stores the runtime credential in encrypted application secret storage. AWS IAM remains authoritative for the resulting permissions.
Customer-managed S3 credentials are not provisioned or changed by Gateman. They can be supplied separately for runtime use.
One-time setup credential
The setup flow requires a temporary access key for an IAM user named exactly Gateman-Setup. The setup identity must have the restricted bootstrap policy shown by the application. It is used only to create or reconcile the runtime identity and IAM policy.
Before Gateman creates or changes any IAM runtime resource, it validates each configured bucket with AWS s3:GetBucketLocation. The bootstrap policy grants only this bucket-location metadata action; it does not grant bucket listing, object reads, or object writes. The exact bucket name and selected region must match AWS before provisioning can continue.
Gateman verifies the setup identity before using it. After successful setup it attempts to revoke the supplied setup access key and does not retain it for later S3 administration. If revocation cannot be confirmed, setup records the cleanup as pending so the key can be addressed rather than silently treated as gone. An incomplete setup credential is encrypted temporarily and has a task-scoped expiry/cleanup path.
Do not put the setup key or secret in source, commits, logs, or customer-facing documentation. AWS shows a secret access key only once.
Provisioned runtime access
The runtime user is dedicated to the Gateman application. Its policy contains the configured object actions and resource ARNs, plus only the narrow operations needed for runtime identity verification and self-revocation. The permissions boundary does not grant broad IAM administration.
Gateman stores the runtime access key and secret encrypted and uses them for the application's S3 presigning calls. The runtime identity has the narrowly scoped ability to revoke access keys belonging to its own runtime IAM user. Gateman targets only the managed access key it recorded. It does not delete the IAM user, its policy, the permissions boundary, buckets, bucket policies, or objects.
The runtime region is recorded during setup. Managed runtime presigning uses that recorded region; ordinary managed access changes do not select a different region.
Updating managed access
An update replaces the managed inline resource policy using the setup credential and the new explicitly selected resources. It does not rotate the runtime access key. Existing managed metadata is updated only after the new policy is applied; if the policy update fails, the previous policy is restored where possible and the managed state remains available for recovery.
The temporary setup key is revoked after the update. A failure to verify that cleanup leaves a pending cleanup state for follow-up.
Recovery and transitions
If managed metadata exists but the runtime credential is unavailable, the console can restore a credential only after AWS STS confirms that it belongs to the recorded runtime IAM user. If the recorded user no longer exists, or its identity/boundary no longer matches, reprovisioning is the supported recovery path.
Switching to customer-managed AWS credentials follows the same safety rule: the new credential is not made authoritative until the recorded managed key's revocation is confirmed. If revocation cannot be confirmed, the existing managed state is preserved and the recovery path remains available.
Removing managed access
When managed access is removed, Gateman verifies the recorded runtime identity and revokes the recorded managed access key before removing the encrypted local credential and managed metadata. A confirmed already-absent key is treated as revoked. Timeouts, identity mismatches, provider errors, and other uncertain results remain unresolved.
Removal of Gateman's local state is not deletion of AWS resources. The runtime IAM user and related Gateman-created IAM resources may remain in the customer's AWS account after access-key revocation. The customer owns and administers those remaining AWS resources.
Application deletion
Application deletion attempts managed S3 key revocation before deleting the Gateman application record. If AWS cleanup cannot be verified, the app remains in a pending-deletion state and the owning account can reopen the cleanup confirmation workflow. An explicit customer acknowledgement means that the customer has checked AWS; it is not a Gateman verification result.
Boundary with runtime use
Managed provisioning may configure restricted IAM permissions. It does not make Gateman an S3 authorization layer. At runtime, POST /s3/presign only authenticates the application, checks s3:use, obtains the configured credential, and signs a native GetObject or PutObject request. AWS IAM decides whether the eventual request is allowed.
See the Use S3 Capability Reference for the request, response, signed-header, native-parameter, accounting, and error contracts.