S3 Gateway Temporary Credentials¶

Most S3 clients can sign requests to the S3 Gateway 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, 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:

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 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, 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 to false to stop serving AssumeRoleWithWebIdentity, which also makes the S3 Gateway reject temporary credentials that were issued earlier. When auth.allowed_authentication_methods does not include access_key, lakeFS refuses the exchange as well.