# S3 Gateway Temporary Credentials

> [!NOTE]
>
> **Available in lakeFS Enterprise. [Start a free trial](<https://lakefs.io/try/>) or [contact us](<https://lakefs.io/book-a-demo/>).**

Most S3 clients can sign requests to the [S3 Gateway](<https://docs.lakefs.io/security/authentication/index.md#s3-gateway-authentication>) with temporary credentials, which spares a workload from holding a long-lived lakeFS access key that has to be provisioned, stored and rotated by hand. lakeFS serves the AWS STS `AssumeRoleWithWebIdentity` action, so a workload that already holds an identity token can exchange it for short-lived S3 credentials and use them wherever S3 credentials are accepted, while lakeFS keeps enforcing the permissions of the principal behind the token.

## How the exchange works

The client calls `AssumeRoleWithWebIdentity` on the lakeFS server URL, for example `https://lakefs.example.com`, and passes its identity token as the `WebIdentityToken` parameter. lakeFS verifies the token and returns an access key ID starting with `ASIA`, a secret access key, a session token and an expiration time. The client signs its S3 Gateway requests with these credentials and sends the session token with every request, as it would with credentials issued by AWS STS.

lakeFS accepts two kinds of identity tokens:

- A lakeFS login token, which carries the permissions of the lakeFS user who logged in.
- A JWT issued by the identity provider configured for [JWT Login](<https://docs.lakefs.io/security/jwt-login/index.md>), which carries the policies of the lakeFS groups that its groups claim maps to. A lakeFS bearer token returned by JWT Login is accepted as well.

The STS API requires a `RoleArn` parameter, and AWS clients will not start the exchange without one, but lakeFS ignores its value, so any well-formed value such as `arn:aws:iam::000000000000:role/lakefs` will do. Session policies passed in `Policy` or `PolicyArns` are rejected, because lakeFS cannot narrow the principal's permissions with them.

Clients built on an AWS SDK usually perform the exchange on their own when they find a token file and an STS endpoint in their environment:

```bash
export AWS_WEB_IDENTITY_TOKEN_FILE=/path/to/token
export AWS_ROLE_ARN=arn:aws:iam::000000000000:role/lakefs
export AWS_ENDPOINT_URL_STS=https://lakefs.example.com
export AWS_ENDPOINT_URL_S3=https://lakefs.example.com
```

Point the STS endpoint at the lakeFS server URL rather than at the [`gateways.s3.domain_name`](<https://docs.lakefs.io/reference/configuration/index.md#gateways>) host, since lakeFS serves every request to that host as an S3 request, and keep the STS request unsigned, which is the default for this action in the AWS SDKs. Some clients only call STS endpoints over HTTPS, so serve lakeFS over TLS when a client does not pick up the endpoint.

## Credential lifetime and revocation

Credentials expire after one hour by default, and a client can request between 15 minutes and 12 hours through the `DurationSeconds` parameter. They never outlive the identity token they were exchanged for, so a token that expires in ten minutes yields credentials that expire at the same time, and credentials exchanged for an identity provider JWT are also capped by the JWT Login `session_max_ttl` setting.

lakeFS stores nothing when it issues temporary credentials, so how they are revoked depends on the token they were exchanged for. Credentials issued for a lakeFS user stop working once the user is disabled or deleted, and changes to the user's policies apply to the next request. Credentials exchanged for a JWT Login bearer token stop working once its session is deleted or expires, as described under [Revocation](<https://docs.lakefs.io/security/jwt-login/index.md#revocation>), while credentials exchanged for an identity provider JWT carry the group policies resolved at the exchange and stay valid until they expire.

## Disabling temporary credentials

The exchange is enabled by default. Set [`gateways.s3.sts.enabled`](<https://docs.lakefs.io/reference/configuration/index.md#gateways>) to `false` to stop serving `AssumeRoleWithWebIdentity`, which also makes the S3 Gateway reject temporary credentials that were issued earlier. When [`auth.allowed_authentication_methods`](<https://docs.lakefs.io/reference/enterprise-configuration/index.md#auth>) does not include `access_key`, lakeFS refuses the exchange as well.
