.. _minio-sts-assumerolewithldapidentity:

==============================
``AssumeRoleWithLDAPIdentity``
==============================

.. default-domain:: minio

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

The MinIO Security Token Service (STS) ``AssumeRoleWithLDAPIdentity`` API 
endpoint generates temporary access credentials using Active Directory
or LDAP user credentials. This page documents the MinIO 
server ``AssumeRoleWithLDAPIdentity`` endpoint. For instructions on 
implementing STS using an S3-compatible SDK, defer to the documentation
for that SDK.

The MinIO STS ``AssumeRoleWithLDAPIdentity`` 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 ``AssumeRoleWithLDAPIdentity`` endpoint has the following form:

.. code-block:: shell

   POST https://minio.example.net?Action=AssumeRoleWithLDAPIdentity[&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=AssumeRoleWithLDAPIdentity
   &LDAPUsername=USERNAME
   &LDAPPassword=PASSWORD
   &Version=2011-06-15
   &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

   * - ``LDAPUsername``
     - string
     - *Required*

       Specify the username of the AD/LDAP user as whom you want to
       authenticate.

   * - ``LDAPPassword``
     - string
     - *Required*

       Specify the password for the ``LDAPUsername``.

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

       Specify ``2011-06-15``.


   * - ``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 :ref:`policy
       <minio-external-identity-management-ad-ldap-access-control>` matching the Distinguished
       Name (DN) of the ``LDAPUsername`` 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 DN policy. Applications can never assume
       more privileges than those specified in the DN policy.

       Omit to use only the DN 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:`AssumeRoleWithLDAPIdentity response
<STS/latest/APIReference/API_AssumeRoleWithLDAPIdentity.html#API_AssumeRoleWithLDAPIdentity_ResponseElements>`.
Specifically, MinIO returns an ``AssumeRoleWithLDAPIdentityResult`` 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
``AssumeRoleWithLDAPIdentity`` endpoint:

.. code-block:: xml

   <?xml version="1.0" encoding="UTF-8"?>
   <AssumeRoleWithLDAPIdentityResponse xmlns="https://sts.amazonaws.com/doc/2011-06-15/">
   <AssumeRoleWithLDAPIdentityResult>
      <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>
   </AssumeRoleWithLDAPIdentityResult>
   <ResponseMetadata/>
   </AssumeRoleWithLDAPIdentityResponse>

Error Elements
--------------

The XML error response for this API endpoint is similar to the AWS
:aws-docs:`AssumeRoleWithLDAPIdentity response
<STS/latest/APIReference/API_AssumeRoleWithLDAPIdentity.html#API_AssumeRoleWithLDAPIdentity_Errors>`.