.. _minio-sts-assumerolewithwebidentity:

=============================
``AssumeRoleWithWebIdentity``
=============================

.. default-domain:: minio

.. contents:: Table of Contents
   :local:
   :depth: 2

The MinIO Security Token Service (STS) ``AssumeRoleWithWebIdentity`` API 
endpoint generates temporary access credentials using a 
JSON Web Token (JWT) returned from a 
:ref:`configured OpenID IDentity Provider (IDP)
<minio-external-identity-management-openid-configure>`. 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 :aws-docs:`AssumeRoleWithWebIdentity 
<STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html>` 
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:

.. code-block:: shell

   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:

.. code-block:: shell

   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:

.. list-table::
   :header-rows: 1
   :widths: 20 20 60
   :width: 100%

   * - Parameter
     - Type
     - Description

   * - ``WebIdentityToken``
     - string
     - *Required*

       Specify the JSON Web Token (JWT) returned by the 
       :ref:`configured OpenID IDentity Provider 
       <minio-external-identity-management-openid-configure>`. 

   * - ``Version``
     - string
     - *Required*

       Specify ``2011-06-15``.

   * - ``DurationSeconds``
     - integer
     - *Optional*
     
       Specify the number of seconds after which the temporary credentials
       expire. Defaults to ``3600``.
       
       - The minimum value is ``900`` or 15 minutes.
       - The maximum value is ``604800`` or 7 days.

       If ``DurationSeconds`` is omitted, MinIO checks the JWT token for an
       ``exp`` claim before using the default duration. See
       `RFC 7519 4.1.4: Expiration Time Claim 
       <https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4>`__ 
       for more information on JSON web token expiration.

   * - ``Policy``
     - string
     - *Optional*

       Specify the URL-encoded JSON-formatted :ref:`policy <minio-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 :ref:`JWT claim
       <minio-external-identity-management-openid-access-control>` 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 :ref:`minio-access-management` for more information on MinIO
       authentication and authorization.

Response Elements
-----------------

The XML response for this API endpoint is similar to the AWS
:aws-docs:`AssumeRoleWithWebIdentity response
<STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html#API_AssumeRoleWithWebIdentity_ResponseElements>`.
Specifically, MinIO returns an ``AssumeRoleWithWebIdentityResult`` object,
where the ``AssumedRoleUser.Credentials`` object contains the temporary
credentials generated by MinIO:

- ``AccessKeyId`` - The access key applications use for authentication.
- ``SecretKeyId`` - 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 MinIO STS
``AssumeRoleWithWebIdentity`` endpoint:

.. code-block:: xml

   <?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
:aws-docs:`AssumeRoleWithWebIdentity response
<STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html#API_AssumeRoleWithWebIdentity_Errors>`.