DOCS-476: OIDC, Keycloak, Dex, and Policy Variables (#735)

source/developers/security-token-service.rst

@@ -24,14 +24,18 @@ MinIO supports the following STS API endpoints:
      - Supported IDP
      - Description
 
-   * - AssumeRoleWithWebIdentity
+   * - :ref:`AssumeRoleWithWebIdentity <minio-sts-assumerolewithwebidentity>`
      - OpenID Connect
      - Generates an access key and secret key using the JWT token returned by the OIDC provider
 
-   * - AssumeRoleWithLDAPIdentity
+   * - :ref:`AssumeRoleWithLDAPIdentity <minio-sts-assumerolewithldapidentity>`
      - Active Directory / LDAP
      - Generates an access key and secret key using the AD/LDAP credentials specified to the API endpoint.
 
+   * - :ref:`AssumeRoleWithCustomToken <minio-sts-assumerolewithcustomtoken>`
+     - MinIO Identity Plugin
+     - Generates a token for use with an external identity provider and the :ref:`MinIO Identity Plugin <minio-external-identity-management-plugin>`.
+
 .. toctree::
    :titlesonly:
    :hidden:

source/developers/security-token-service/AssumeRoleWithCustomToken.rst

@@ -0,0 +1,115 @@
+.. _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>`.