AssumeRoleWithCertificate

The MinIO AIStor Security Token Service (STS) AssumeRoleWithCertificate API endpoint generates temporary access credentials using a client X.509 (TLS) certificate. This page documents the AIStor Server AssumeRoleWithCertificate endpoint. For instructions on implementing STS using an S3-compatible SDK, defer to the documentation for that SDK.

Unlike OpenID Connect or AD/LDAP, certificate-based authentication does not depend on an external identity provider being continuously available. AIStor authenticates the request using only the client certificate, which can reduce operational complexity and improve availability.

The TLS STS API is disabled by default. Enable it by setting the MINIO_IDENTITY_TLS_ENABLE environment variable to on and restarting the deployment.

Because authentication and authorization rely on the client certificate, all AssumeRoleWithCertificate requests must use TLS (HTTPS) and the client must present exactly one leaf client certificate.

The TLS STS API supports the following environment variables:

You can also configure these values using the standard configuration API with the identity_tls subsystem:

mc admin config set ALIAS identity_tls skip_verify="off"

The AssumeRoleWithCertificate endpoint has the following form:

POST https://aistor.example.net?Action=AssumeRoleWithCertificate[&ARGS]

The following example uses all supported arguments. Replace the aistor.example.net hostname with the appropriate URL for your AIStor Server, and provide the client certificate and private key with the request:

curl -X POST --key private.key --cert public.crt \
  "https://aistor.example.net?Action=AssumeRoleWithCertificate&Version=2011-06-15&DurationSeconds=3600"

This endpoint supports the following query parameters:

AIStor maps the client certificate to an S3 policy using the subject common name (CN) of the X.509 certificate. A certificate with the subject CN = consoleAdmin is associated with the policy named consoleAdmin.

The certificate must meet the following requirements:

• The subject common name (CN) must not be empty and must match an existing policy name.
• The certificate must include the TLS Web Client Authentication extended key usage. AIStor rejects certificates that cannot be used for client authentication.
• Unless MINIO_IDENTITY_TLS_SKIP_VERIFY is set to on, the certificate must be issued by a CA that the AIStor server trusts.

The following self-signed certificate is issued for consoleAdmin, so AIStor associates it with the pre-defined consoleAdmin policy:

Certificate:
    Data:
        Version: 3 (0x2)
        Signature Algorithm: ED25519
        Issuer: CN = consoleAdmin
        Validity
            Not Before: Jul 19 15:08:44 2021 GMT
            Not After : Aug 18 15:08:44 2021 GMT
        Subject: CN = consoleAdmin
        X509v3 extensions:
            X509v3 Key Usage: critical
                Digital Signature
            X509v3 Extended Key Usage:
                TLS Web Client Authentication
            X509v3 Basic Constraints: critical
                CA:FALSE

Group mapping is not possible with standard X.509 certificates.

Certificate-based authentication proceeds in four steps:

1. The client sends an HTTP POST request over a TLS connection to the AIStor TLS STS endpoint, presenting its client certificate.
2. AIStor verifies that the client certificate is valid.
3. AIStor finds the policy whose name matches the certificate’s subject common name (CN).
4. AIStor returns temporary S3 credentials associated with the matched policy.

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

• AccessKeyId - The access key applications use for authentication.
• SecretAccessKey - The secret key applications use for authentication.
• Expiration - The ISO-8601 date-time after which the credentials expire.
• SessionToken - The session token applications use for authentication. Some SDKs may require this field when using temporary credentials.

The following example is similar to the response returned by the AIStor Server STS AssumeRoleWithCertificate endpoint:

<?xml version="1.0" encoding="UTF-8"?>
<AssumeRoleWithCertificateResponse xmlns="https://sts.amazonaws.com/doc/2011-06-15/">
   <AssumeRoleWithCertificateResult>
      <Credentials>
         <AccessKeyId>YC12ZBHUVW588BQAE5BM</AccessKeyId>
         <SecretAccessKey>Zgl9+zdE0pZ88+hLqtfh0ocLN+WQTJixHouCkZkW</SecretAccessKey>
         <Expiration>2021-07-19T20:10:45Z</Expiration>
         <SessionToken>eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...</SessionToken>
      </Credentials>
   </AssumeRoleWithCertificateResult>
   <ResponseMetadata>
      <RequestId>169339CD8B3A6948</RequestId>
   </ResponseMetadata>
</AssumeRoleWithCertificateResponse>

Applications that use the S3 API directly work without issue. However, interactive users uploading content from a browser (for example, when a browser POSTs to a presigned URL the application generates) may see a prompt to provide a client certificate. The user must cancel that prompt to continue. There is no workaround for this behavior at this time.

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