github.com/minio/minio@v0.0.0-20240328213742-3f72439b8a27/docs/iam/identity-management-plugin.md (about)

     1  # Identity Management Plugin Guide [![Slack](https://slack.minio.io/slack?type=svg)](https://slack.minio.io)
     2  
     3  ## Introduction
     4  
     5  To enable the integration of custom authentication methods, MinIO can be configured with an Identity Management Plugin webhook. When configured, this plugin enables the `AssumeRoleWithCustomToken` STS API extension. A user or application can now present a token to the `AssumeRoleWithCustomToken` API, and MinIO verifies this token by sending it to the Identity Management Plugin webhook. This plugin responds with some information and MinIO is able to generate temporary STS credentials to interact with object storage.
     6  
     7  The authentication flow is similar to that of OpenID, however the token is "opaque" to MinIO - it is simply sent to the plugin for verification. CAVEAT: There is no console UI integration for this method of authentication and it is intended primarily for machine authentication.
     8  
     9  It can be configured via MinIO's standard configuration API (i.e. using `mc admin config set/get`), or equivalently with environment variables. For brevity we show only environment variables here:
    10  
    11  ```sh
    12  $ mc admin config set myminio identity_plugin --env
    13  KEY:
    14  identity_plugin  enable Identity Plugin via external hook
    15  
    16  ARGS:
    17  MINIO_IDENTITY_PLUGIN_URL*          (url)       plugin hook endpoint (HTTP(S)) e.g. "http://localhost:8181/path/to/endpoint"
    18  MINIO_IDENTITY_PLUGIN_AUTH_TOKEN    (string)    authorization token for plugin hook endpoint
    19  MINIO_IDENTITY_PLUGIN_ROLE_POLICY*  (string)    policies to apply for plugin authorized users
    20  MINIO_IDENTITY_PLUGIN_ROLE_ID       (string)    unique ID to generate the ARN
    21  MINIO_IDENTITY_PLUGIN_COMMENT       (sentence)  optionally add a comment to this setting
    22  ```
    23  
    24  If provided, the auth token parameter is sent as an authorization header.
    25  
    26  `MINIO_IDENTITY_PLUGIN_ROLE_POLICY` is a required parameter and can be list of comma separated policy names.
    27  
    28  On setting up the plugin, the MinIO server prints the Role ARN to its log. The Role ARN is generated by default based on the given plugin URL. To avoid this and use a configurable value set a unique role ID via `MINIO_IDENTITY_PLUGIN_ROLE_ID`.
    29  
    30  ## REST API call to plugin
    31  
    32  To verify the custom token presented in the `AssumeRoleWithCustomToken` API, MinIO makes a POST request to the configured identity management plugin endpoint and expects a response with some details as shown below:
    33  
    34  ### Request `POST` to plugin endpoint
    35  
    36  Query parameters:
    37  
    38  | Parameter Name | Value Type | Purpose                                                                 |
    39  |----------------|------------|-------------------------------------------------------------------------|
    40  | token          | string     | Token from the AssumeRoleWithCustomToken call for external verification |
    41  
    42  ### Response
    43  
    44  If the token is valid and access is approved, the plugin must return a `200` (OK) HTTP status code.
    45  
    46  A `200 OK` Response should have `application/json` content-type and body with the following structure:
    47  
    48  ```json
    49  {
    50      "user": <string>,
    51      "maxValiditySeconds": <integer>,
    52      "claims": <key-value-pairs>
    53  }
    54  ```
    55  
    56  | Parameter Name     | Value Type                              | Purpose                                                |
    57  |--------------------|-----------------------------------------|--------------------------------------------------------|
    58  | user               | string                                  | Identifier for owner of requested credentials          |
    59  | maxValiditySeconds | integer (>= 900 seconds and < 365 days) | Maximum allowed expiry duration for the credentials    |
    60  | claims             | key-value pairs                         | Claims to be associated with the requested credentials |
    61  
    62  The keys "exp", "parent" and "sub" in the `claims` object are reserved and if present are ignored by MinIO.
    63  
    64  If the token is not valid or access is not approved, the plugin must return a `403` (forbidden) HTTP status code. The body must have an `application/json` content-type with the following structure:
    65  
    66  ```json
    67  {
    68      "reason": <string>
    69  }
    70  ```
    71  
    72  The reason message is returned to the client.
    73  
    74  ## Example Plugin Implementation
    75  
    76  A toy example for the Identity Management Plugin is given [here](./identity-manager-plugin.go).