Skip to content

This is the multi-page printable view of this section. .

Return to the regular view of this page.

Security Token Service (STS)

The MinIO Security Token Service (STS) APIs allow applications to generate temporary credentials for accessing the MinIO deployment.

The STS API is required for MinIO deployments configured to use external identity managers, as the API allows conversion of the external IDP credentials into AWS Signature v4-compatible credentials.

STS API Endpoints

MinIO supports the following STS API endpoints:

Endpoint Supported IDP Description
AssumeRoleWithWebIdentity OpenID Connect Generates an access key and secret key using the JWT token returned by the OIDC provider
AssumeRoleWithLDAPIdentity Active Directory / LDAP Generates an access key and secret key using the AD/LDAP credentials specified to the API endpoint.
AssumeRoleWithCustomToken MinIO Identity Plugin Exchanges a token from an external identity provider for temporary S3 credentials using the MinIO Identity Plugin.

All three APIs return an access key, secret key, and session token. Pass all three to the S3 SDK. Session lifetimes follow each endpoint’s contract; LDAP, OIDC, and the identity plugin do not share one universal duration limit.

1 - AssumeRoleWithCustomToken

The MinIO Security Token Service (STS) AssumeRoleWithCustomToken API endpoint exchanges a token validated by the MinIO External Identity Management Plugin for temporary S3 credentials.

Request Endpoint

The AssumeRoleWithCustomToken endpoint has the following form:

POST https://minio.example.net?Action=AssumeRoleWithCustomToken[&ARGS]

The following example uses all supported arguments. Replace the minio.example.net hostname with the appropriate URL for your MinIO cluster:

POST https://minio.example.net?Action=AssumeRoleWithCustomToken
&Token=TOKEN
&Version=2011-06-15
&DurationSeconds=86000
&RoleArn=ROLE_ARN_FROM_PLUGIN_CONFIGURATION

Request Query Parameters

This endpoint supports the following query parameters:

Parameter

Type

Description

Token

string

Required

Specify the JSON Token to present to the external identity manager. MinIO expects the identity manager to parse the token and determine whether to authenticate client requests using that token.

Version

string

Required

Specify 2011-06-15.

RoleArn

string

Required

Specify the ARN for the Identity Manager Plugin configuration to associate with this STS request.

See MINIO_IDENTITY_PLUGIN_ROLE_ID or identity_plugin role_id for more information.

Note that MinIO automatically prepends idmp- to a configured ROLE_ID when generating the RoleArn. Include that string with the ROLE_ID if required.

DurationSeconds

integer

Optional

Specify the number of seconds after which the temporary credentials expire. If omitted, SILO uses the identity plugin's maxValiditySeconds. If supplied, the effective duration is the smaller of this request and the plugin limit. The plugin must return a limit between 900 and 31536000 seconds (15 minutes to 365 days). There is no fixed one-hour default for this endpoint. Request a positive duration suitable for the application.

Response Elements

MinIO returns an AssumeRoleWithCustomTokenResult object, where the Credentials object contains the temporary credentials generated by MinIO:

  • AccessKeyId - The access key applications use for authentication.
  • SecretAccessKey - The secret key applications use for authentication.
  • Expiration - The RFC3339 date and time after which the credentials expire.
  • SessionToken - Required with the access key and secret key when signing S3 requests with these temporary credentials.

The following example is similar to the response returned by the MinIO STS AssumeRoleWithCustomToken endpoint:

<?xml version="1.0" encoding="UTF-8"?>
<AssumeRoleWithCustomTokenResponse xmlns="https://sts.amazonaws.com/doc/2011-06-15/">
<AssumeRoleWithCustomTokenResult>
   <Credentials>
      <AccessKeyId>ACCESS_KEY</AccessKeyId>
      <SecretAccessKey>SECRET_KEY</SecretAccessKey>
      <Expiration>YYYY-MM-DDTHH:MM:SSZ</Expiration>
      <SessionToken>TOKEN</SessionToken>
   </Credentials>
   <AssumedUser>custom:Alice</AssumedUser>
</AssumeRoleWithCustomTokenResult>
<ResponseMetadata>
   <RequestId>UNIQUE_ID</RequestId>
</ResponseMetadata>
</AssumeRoleWithCustomTokenResponse>

Error Elements

The XML error response for this API endpoint is similar to the AWS AssumeRoleWithWebIdentity response.

2 - AssumeRoleWithLDAPIdentity

The MinIO Security Token Service (STS) AssumeRoleWithLDAPIdentity API endpoint generates temporary access credentials using Active Directory or LDAP user credentials. This page documents the MinIO server AssumeRoleWithLDAPIdentity endpoint. For instructions on implementing STS using an S3-compatible SDK, defer to the documentation for that SDK.

The MinIO STS AssumeRoleWithLDAPIdentity API endpoint is modeled after the AWS AssumeRoleWithWebIdentity endpoint and shares certain request/response elements. This page documents the MinIO-specific syntax and links out to the AWS reference for all shared elements.

Request Endpoint

The AssumeRoleWithLDAPIdentity endpoint has the following form:

POST https://minio.example.net?Action=AssumeRoleWithLDAPIdentity[&ARGS]

The following example shows the required arguments and an optional session duration. Replace the minio.example.net hostname with the appropriate URL for your MinIO cluster:

POST https://minio.example.net?Action=AssumeRoleWithLDAPIdentity
&LDAPUsername=USERNAME
&LDAPPassword=PASSWORD
&Version=2011-06-15
&DurationSeconds=3600

Request Query Parameters

This endpoint supports the following query parameters:

Parameter

Type

Description

LDAPUsername

string

Required

Specify the username of the AD/LDAP user as whom you want to authenticate.

LDAPPassword

string

Required

Specify the password for the LDAPUsername.

Version

string

Required

Specify 2011-06-15.

DurationSeconds

integer

Optional

Specify the number of seconds after which the temporary credentials expire. Defaults to 3600 (one hour).

  • The minimum is 900 (15 minutes).

  • The maximum is 31536000 (365 days).

This endpoint authenticates LDAP credentials, not a JWT. It does not obtain the session duration from an incoming JWT exp claim.

Policy

string

Optional

Specify the URL-encoded JSON-formatted policy to use as an inline session policy.

  • The minimum string length is 1.

  • The maximum string length is 2048.

The resulting permissions for the temporary credentials are the intersection between the policy matching the Distinguished Name (DN) of the LDAPUsername and the specified inline policy. Applications can only perform those operations for which they are explicitly authorized.

The inline policy can specify a subset of permissions allowed by the policy specified in the DN policy. Applications can never assume more privileges than those specified in the DN policy.

Omit to use only the DN policy.

See Access Management for more information on MinIO authentication and authorization.

Response Elements

AssumeRoleWithLDAPIdentity is a SILO/MinIO extension, not an AWS STS action. SILO returns an AssumeRoleWithLDAPIdentityResult containing a Credentials element with:

  • AccessKeyId - The access key applications use for authentication.
  • SecretAccessKey - The secret key applications use for authentication.
  • Expiration - The RFC3339 date and time after which the credentials expire.
  • SessionToken - Required with the access key and secret key when signing S3 requests with these temporary credentials.

The following example is similar to the response returned by the MinIO STS AssumeRoleWithLDAPIdentity endpoint:

<?xml version="1.0" encoding="UTF-8"?>
<AssumeRoleWithLDAPIdentityResponse xmlns="https://sts.amazonaws.com/doc/2011-06-15/">
<AssumeRoleWithLDAPIdentityResult>
   <Credentials>
      <AccessKeyId>Y4RJU1RNFGK48LGO9I2S</AccessKeyId>
      <SecretAccessKey>sYLRKS1Z7hSjluf6gEbb9066hnx315wHTiACPAjg</SecretAccessKey>
      <Expiration>2019-08-08T20:26:12Z</Expiration>
      <SessionToken>eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhY2Nlc3NLZXkiOiJZNFJKVTFSTkZHSzQ4TEdPOUkyUyIsImF1ZCI6IlBvRWdYUDZ1Vk80NUlzRU5SbmdEWGo1QXU1WWEiLCJhenAiOiJQb0VnWFA2dVZPNDVJc0VOUm5nRFhqNUF1NVlhIiwiZXhwIjoxNTQxODExMDcxLCJpYXQiOjE1NDE4MDc0NzEsImlzcyI6Imh0dHBzOi8vbG9jYWxob3N0Ojk0NDMvb2F1dGgyL3Rva2VuIiwianRpIjoiYTBiMjc2MjktZWUxYS00M2JmLTg3MzktZjMzNzRhNGNkYmMwIn0.ewHqKVFTaP-j_kgZrcOEKroNUjk10GEp8bqQjxBbYVovV0nHO985VnRESFbcT6XMDDKHZiWqN2vi_ETX_u3Q-w</SessionToken>
   </Credentials>
</AssumeRoleWithLDAPIdentityResult>
<ResponseMetadata/>
</AssumeRoleWithLDAPIdentityResponse>

Error Elements

The XML error response for this API endpoint is similar to the AWS STS error response.

3 - AssumeRoleWithWebIdentity

The MinIO Security Token Service (STS) AssumeRoleWithWebIdentity API endpoint generates temporary access credentials using a JSON Web Token (JWT) returned from a configured OpenID IDentity Provider (IDP). This page documents the MinIO server AssumeRoleWithWebIdentity endpoint. For instructions on implementing STS using an S3-compatible SDK, defer to the documentation for that SDK.

The MinIO STS AssumeRoleWithWebIdentity API endpoint is modeled after the AWS AssumeRoleWithWebIdentity endpoint and shares certain request/response elements. This page documents the MinIO-specific syntax and links out to the AWS reference for all shared elements.

Request Endpoint

The AssumeRoleWithWebIdentity endpoint has the following form:

POST https://minio.example.net?Action=AssumeRoleWithWebIdentity[&ARGS]

The following example uses all supported arguments. Replace the minio.example.net hostname with the appropriate URL for your MinIO cluster:

POST https://minio.example.net?Action=AssumeRoleWithWebIdentity
&WebIdentityToken=TOKEN
&Version=2011-06-15
&DurationSeconds=86000
&Policy={}

Request Query Parameters

This endpoint supports the following query parameters:

Parameter

Type

Description

WebIdentityToken

string

Required

Specify the JSON Web Token (JWT) returned by the configured OpenID IDentity Provider.

Version

string

Required

Specify 2011-06-15.

DurationSeconds

integer

Optional

Specify the number of seconds after which the temporary credentials expire. Without a server override, an explicit duration must be between 900 (15 minutes) and 31536000 (365 days). If MINIO_STS_DURATION is configured, it overrides the explicit duration using Go duration syntax such as 1h.

If omitted, SILO retains the validated JWT's exp claim; it does not substitute a fixed one-hour default. See RFC 7519 4.1.4: Expiration Time Claim for more information on JSON web token expiration.

Policy

string

Optional

Specify the URL-encoded JSON-formatted policy to use as an inline session policy.

  • The minimum string length is 1.

  • The maximum string length is 2048.

The resulting permissions for the temporary credentials are the intersection between the policy specified as part of the JWT claim and the specified inline policy. Applications can only perform those operations for which they are explicitly authorized.

The inline policy can specify a subset of permissions allowed by the policy specified in the JWT claim. Applications can never assume more privileges than those specified in the JWT claim policy.

Omit to use only the JWT claim policy.

See Access Management for more information on MinIO authentication and authorization.

RoleArn

string

Optional

The role Amazon Resource Number (ARN) to use for all user authentication requests. If used, there must be a matching OIDC RolePolicy defined for the RoleArn’s provider by the role_policy configuration parameter or the MINIO_IDENTITY_OPENID_ROLE_POLICY environment variable.

When used, all valid authorization requests assume the same set of permissions provided by the RolePolicy. You can use OpenID Policy Variables to create policies that programmatically manage what each individual user has access to.

If you do not supply a RoleArn, MinIO attempts to authorize through a JWT-based claim.

Response Elements

The XML response for this API endpoint is similar to the AWS AssumeRoleWithWebIdentity response. Specifically, MinIO returns an AssumeRoleWithWebIdentityResult object, where the Credentials object contains the temporary credentials generated by MinIO:

  • AccessKeyId - The access key applications use for authentication.
  • SecretAccessKey - The secret key applications use for authentication.
  • Expiration - The RFC3339 date and time after which the credentials expire.
  • SessionToken - Required with the access key and secret key when signing S3 requests with these temporary credentials.

The following example is similar to the response returned by the MinIO STS AssumeRoleWithWebIdentity endpoint:

<?xml version="1.0" encoding="UTF-8"?>
<AssumeRoleWithWebIdentityResponse xmlns="https://sts.amazonaws.com/doc/2011-06-15/">
<AssumeRoleWithWebIdentityResult>
   <AssumedRoleUser>
      <Arn/>
      <AssumeRoleId/>
   </AssumedRoleUser>
   <Credentials>
      <AccessKeyId>Y4RJU1RNFGK48LGO9I2S</AccessKeyId>
      <SecretAccessKey>sYLRKS1Z7hSjluf6gEbb9066hnx315wHTiACPAjg</SecretAccessKey>
      <Expiration>2019-08-08T20:26:12Z</Expiration>
      <SessionToken>eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhY2Nlc3NLZXkiOiJZNFJKVTFSTkZHSzQ4TEdPOUkyUyIsImF1ZCI6IlBvRWdYUDZ1Vk80NUlzRU5SbmdEWGo1QXU1WWEiLCJhenAiOiJQb0VnWFA2dVZPNDVJc0VOUm5nRFhqNUF1NVlhIiwiZXhwIjoxNTQxODExMDcxLCJpYXQiOjE1NDE4MDc0NzEsImlzcyI6Imh0dHBzOi8vbG9jYWxob3N0Ojk0NDMvb2F1dGgyL3Rva2VuIiwianRpIjoiYTBiMjc2MjktZWUxYS00M2JmLTg3MzktZjMzNzRhNGNkYmMwIn0.ewHqKVFTaP-j_kgZrcOEKroNUjk10GEp8bqQjxBbYVovV0nHO985VnRESFbcT6XMDDKHZiWqN2vi_ETX_u3Q-w</SessionToken>
   </Credentials>
</AssumeRoleWithWebIdentityResult>
<ResponseMetadata/>
</AssumeRoleWithWebIdentityResponse>

Error Elements

The XML error response for this API endpoint is similar to the AWS AssumeRoleWithWebIdentity response.