github.com/minio/minio@v0.0.0-20240328213742-3f72439b8a27/docs/sts/tls.md (about)

     1  # AssumeRoleWithCertificate [![Slack](https://slack.min.io/slack?type=svg)](https://slack.min.io)
     2  
     3  ## Introduction
     4  
     5  MinIO provides a custom STS API that allows authentication with client X.509 / TLS certificates.
     6  
     7  A major advantage of certificate-based authentication compared to other STS authentication methods, like OpenID Connect or LDAP/AD, is that client authentication works without any additional/external component that must be constantly available. Therefore, certificate-based authentication may provide better availability / lower operational complexity.
     8  
     9  The MinIO TLS STS API can be configured via MinIO's standard configuration API (i.e. using `mc admin config set/get`). Further, it can be configured via the following environment variables:
    10  
    11  ```
    12  mc admin config set myminio identity_tls --env
    13  KEY:
    14  identity_tls  enable X.509 TLS certificate SSO support
    15  
    16  ARGS:
    17  MINIO_IDENTITY_TLS_SKIP_VERIFY  (on|off)    trust client certificates without verification. Defaults to "off" (verify)
    18  ```
    19  
    20  The MinIO TLS STS API is disabled by default. However, it can be *enabled* by setting environment variable:
    21  
    22  ```
    23  export MINIO_IDENTITY_TLS_ENABLE=on
    24  ```
    25  
    26  ## Example
    27  
    28  MinIO exposes a custom S3 STS API endpoint as `Action=AssumeRoleWithCertificate`. A client has to send an HTTP `POST` request to `https://<host>:<port>?Action=AssumeRoleWithCertificate&Version=2011-06-15`. Since the authentication and authorization happens via X.509 certificates the client has to send the request over **TLS** and has to provide
    29  a client certificate.
    30  
    31  The following curl example shows how to authenticate to a MinIO server with client certificate and obtain STS access credentials.
    32  
    33  ```curl
    34  curl -X POST --key private.key --cert public.crt "https://minio:9000?Action=AssumeRoleWithCertificate&Version=2011-06-15&DurationSeconds=3600"
    35  ```
    36  
    37  ```xml
    38  <?xml version="1.0" encoding="UTF-8"?>
    39  <AssumeRoleWithCertificateResponse xmlns="https://sts.amazonaws.com/doc/2011-06-15/">
    40     <AssumeRoleWithCertificateResult>
    41        <Credentials>
    42           <AccessKeyId>YC12ZBHUVW588BQAE5BM</AccessKeyId>
    43           <SecretAccessKey>Zgl9+zdE0pZ88+hLqtfh0ocLN+WQTJixHouCkZkW</SecretAccessKey>
    44           <Expiration>2021-07-19T20:10:45Z</Expiration
    45           <SessionToken>eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhY2Nlc3NLZXkiOiJZQzEyWkJIVVZXNTg4QlFBRTVCTSIsImV4cCI6MTYyNjcyNTQ0NX0.wvMUf3w_x16qpVWgua8WxnV1Sgtv1jOnSu03vbrwOMzV3cI4q3_9WZD9LwlP-34DTsvbsg7gCBGh6YNriMMiQw</SessionToken>
    46        </Credentials>
    47     </AssumeRoleWithCertificateResult>
    48     <ResponseMetadata>
    49        <RequestId>169339CD8B3A6948</RequestId>
    50     </ResponseMetadata>
    51  </AssumeRoleWithCertificateResponse>
    52  ```
    53  
    54  ## Authentication Flow
    55  
    56  A client can request temp. S3 credentials via the STS API. It can authenticate via a client certificate and obtain a access/secret key pair as well as a session token. These credentials are associated to an S3 policy at the MinIO server.
    57  
    58  In case of certificate-based authentication, MinIO has to map the client-provided certificate to an S3 policy. MinIO does this via the subject common name field of the X.509 certificate. So, MinIO will associate a certificate with a subject `CN = foobar` to a S3 policy named `foobar`.
    59  
    60  The following self-signed certificate is issued for `consoleAdmin`. So, MinIO would associate it with the pre-defined `consoleAdmin` policy.
    61  
    62  ```
    63  Certificate:
    64      Data:
    65          Version: 3 (0x2)
    66          Serial Number:
    67              35:ac:60:46:ad:8d:de:18:dc:0b:f6:98:14:ee:89:e8
    68          Signature Algorithm: ED25519
    69          Issuer: CN = consoleAdmin
    70          Validity
    71              Not Before: Jul 19 15:08:44 2021 GMT
    72              Not After : Aug 18 15:08:44 2021 GMT
    73          Subject: CN = consoleAdmin
    74          Subject Public Key Info:
    75              Public Key Algorithm: ED25519
    76                  ED25519 Public-Key:
    77                  pub:
    78                      5a:91:87:b8:77:fe:d4:af:d9:c7:c7:ce:55:ae:74:
    79                      aa:f3:f1:fe:04:63:9b:cb:20:97:61:97:90:94:fa:
    80                      12:8b
    81          X509v3 extensions:
    82              X509v3 Key Usage: critical
    83                  Digital Signature
    84              X509v3 Extended Key Usage: 
    85                  TLS Web Client Authentication
    86              X509v3 Basic Constraints: critical
    87                  CA:FALSE
    88      Signature Algorithm: ED25519
    89           7e:aa:be:ed:47:4d:b9:2f:fc:ed:7f:5a:fc:6b:c0:05:5b:f5:
    90           a0:31:fe:86:e3:8e:3f:49:af:6d:d5:ac:c7:c4:57:47:ce:97:
    91           7d:ab:b8:e9:75:ec:b4:39:fb:c8:cf:53:16:5b:1f:15:b6:7f:
    92           5a:d1:35:2d:fc:31:3a:10:e7:0c
    93  ```
    94  
    95  > Observe the `Subject: CN = consoleAdmin` field.
    96  
    97  Also, note that the certificate has to contain the `Extended Key Usage: TLS Web Client Authentication`. Otherwise, MinIO would not accept the certificate as client certificate.
    98  
    99  Now, the STS certificate-based authentication happens in 4 steps:
   100  
   101  - Client sends HTTP `POST` request over a TLS connection hitting the MinIO TLS STS API.
   102  - MinIO verifies that the client certificate is valid.
   103  - MinIO tries to find a policy that matches the `CN` of the client certificate.
   104  - MinIO returns temp. S3 credentials associated to the found policy.
   105  
   106  The returned credentials expiry after a certain period of time that can be configured via `&DurationSeconds=3600`. By default, the STS credentials are valid for 1 hour. The minimum expiration allowed is 15 minutes.
   107  
   108  Further, the temp. S3 credentials will never out-live the client certificate. For example, if the `MINIO_IDENTITY_TLS_STS_EXPIRY` is 7 days but the certificate itself is only valid for the next 3 days, then MinIO will return S3 credentials that are valid for 3 days only.
   109  
   110  ## Caveat
   111  
   112  *Applications that use direct S3 API will work fine, however interactive users uploading content using (when POSTing to the presigned URL an app generates) a popup becomes visible on browser to provide client certs, you would have to manually cancel and continue. This may be annoying to use but there is no workaround for now.*
   113  
   114  ## Explore Further
   115  
   116  - [MinIO Admin Complete Guide](https://min.io/docs/minio/linux/reference/minio-mc-admin.html)
   117  - [The MinIO documentation website](https://min.io/docs/minio/linux/index.html)