.. _minio-sts-assumerolewithcustomtoken:

=============================
``AssumeRoleWithCustomToken``
=============================

.. default-domain:: minio

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

The MinIO Security Token Service (STS) ``AssumeRoleWithCustomToken`` API endpoint generates a token for use with the :ref:`minio-external-identity-management-plugin`.

Request Endpoint
----------------

The ``AssumeRoleWithCustomToken`` endpoint has the following form:

.. code-block:: shell

   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:

.. code-block:: shell

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

Request Query Parameters
~~~~~~~~~~~~~~~~~~~~~~~~

This endpoint supports the following query parameters:

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

   * - 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 :envvar:`MINIO_IDENTITY_PLUGIN_ROLE_ID` or :mc-conf:`identity_plugin role_id <identity_plugin.role_id>` for more information.

   * - ``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.

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

MinIO returns an ``AssumeRoleWithCustomTokenResult`` 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
``AssumeRoleWithCustomToken`` endpoint:

.. code-block:: xml

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