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.

In addition to classic X.509 common name (CN) authentication, AIStor validates SPIFFE SVIDs presented as client certificates for AssumeRoleWithCertificate. A SPIFFE SVID is an X.509 certificate that carries a SPIFFE ID (for example, spiffe://example.org/myservice) in a URI Subject Alternative Name (SAN).

When the leaf client certificate contains any URI SAN with the spiffe scheme, AIStor treats the certificate as a SPIFFE SVID and validates it accordingly:

• AIStor validates the certificate as a SPIFFE X.509 SVID using the SPIFFE reference library (github.com/spiffe/go-spiffe/v2). The certificate must contain exactly one valid SPIFFE ID URI SAN.
• If the SVID is invalid, AIStor rejects the request. There is no fallback to the certificate’s subject common name (CN) for a certificate that presents a spiffe URI.
• The SPIFFE ID must include a workload path. A SPIFFE ID with an empty path (for example, spiffe://example.org/) is rejected because no policy name can be derived from it.

SVID validation runs in addition to the existing certificate checks. Unless MINIO_IDENTITY_TLS_SKIP_VERIFY is set to on, the certificate must still be issued by a CA that AIStor trusts and must include the TLS Web Client Authentication extended key usage.

AIStor derives the S3 policy name from the workload path of the SPIFFE ID:

• By default, AIStor uses only the path component of the SPIFFE ID, with the leading / removed. The SPIFFE ID spiffe://example.org/myservice maps to a policy named myservice.
• When MINIO_IDENTITY_TLS_SPIFFE_MULTI_DOMAIN is set to on, AIStor qualifies the policy name with the trust domain in the form <trust-domain>/<path>. The SPIFFE ID spiffe://example.org/myservice maps to a policy named example.org/myservice. Use this option when identical workload paths exist in different trust domains and must map to different policies.

The derived policy name must match an existing policy exactly. As with CN-based authentication, group mapping is not possible with SPIFFE SVIDs.

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.