DOCS-1090: Document Access Management Plugin (#1115)

Closes #1090 

Simple enough - document that which was previously only on github.

Doing a minimal pass here, no core tutorial, just basics.

Staged:

-
http://192.241.195.202:9000/staging/DOCS-1090/linux/administration/identity-access-management/pluggable-authorization.html
-
http://192.241.195.202:9000/staging/DOCS-1090/linux/reference/minio-server/settings/iam/minio-access-plugin.html#

---------

Co-authored-by: Daryl White <53910321+djwfyi@users.noreply.github.com>
Co-authored-by: Andrea Longo <feorlen@users.noreply.github.com>

source/administration/identity-access-management.rst

@@ -50,6 +50,9 @@ MinIO supports both internal and external identity management:
        <minio-external-identity-management-ad-ldap>` 
      - Supports managing identities through an Active Directory or LDAP service.
 
+   * - :ref:`Access Management Plugin <minio-external-access-management-plugin>`
+     - Supports a custom external access manager using the MinIO Access Management Plugin extension.
+
 Once authenticated, MinIO either allows or rejects the client request depending
 on whether or not the authenticated identity is *authorized* to perform the
 operation on the specified resource.
@@ -143,3 +146,4 @@ JSON syntax.
    /administration/identity-access-management/ad-ldap-access-management
    /administration/identity-access-management/pluggable-authentication.rst
    /administration/identity-access-management/policy-based-access-control
+   /administration/identity-access-management/pluggable-authorization.rst

source/administration/identity-access-management/pluggable-authorization.rst

@@ -0,0 +1,126 @@
+.. _minio-external-access-management-plugin:
+
+=======================================
+MinIO External Access Management Plugin
+=======================================
+
+.. default-domain:: minio
+
+
+.. contents:: Table of Contents
+   :local:
+   :depth: 1
+
+Overview
+--------
+
+The MinIO Access Management Plugin provides a ``REST`` interface for offloading authorization through a webhook service.
+
+Once enabled, MinIO sends the request and credential details for every API call to the configured external HTTP(S) endpoint and looks for a response of ``ALLOW`` or ``DENY``.
+MinIO can therefore delegate the access management to the external system instead of relying on S3 :ref:`policy based access control <minio-policy>`.
+
+Configuration Settings
+----------------------
+
+You can configure the MinIO External Access Management Plugin using the following environment variables or configuration settings.
+
+.. tab-set::
+
+   .. tab-item:: Environment Variables
+
+      Specify the following :ref:`environmental variables <minio-server-envvar-external-access-management-plugin>` to each MinIO server in the deployment:
+
+      .. code-block:: shell
+         :class: copyable
+
+         MINIO_POLICY_PLUGIN_URL="https://external-authz.example.net:8080/authz"
+
+         # All other envvars are optional
+         MINIO_POLICY_PLUGIN_AUTH_TOKEN="Bearer TOKEN"
+         MINIO_POLICY_PLUGIN_ENABLE_HTTP2="OFF"
+         MINIO_POLICY_PLUGIN_COMMENT="External Access Management using PROVIDER"
+
+   .. tab-item:: Configuration Settings
+
+      Set the following configuration settings using the :mc-cmd:`mc admin config set` command:
+
+      .. code-block:: shell
+         :class: copyable
+
+         mc admin config set policy_plugin \
+            url="https://external-authz.example.net:8080/authz" \
+
+            # All other config settings are optional
+            auth_token="Bearer TOKEN" \
+            enable_http2="off" \
+            comment="External Access Management using PROVIDER"
+
+Authentication and Authorization Flow
+-------------------------------------
+
+The login flow for an application is as follows:
+
+1. The client includes authentication information as part of performing the API call
+
+2. The configured Identity Manager authenticates the client
+
+3. MinIO makes a ``POST`` call to the configured access management plugin URL which includes the context of the API call and authentication data
+
+4. On successful authorization, the access manager returns a ``200 OK`` response with a JSON body of either ``result true`` or ``"result" : { "allow" : true }``:
+
+If the access manager rejects the authorization request, MinIO automatically blocks and denies the API call.
+
+Request Body Example
+--------------------
+
+The following JSON resembles the request body sent as part of the POST to the configured access manager webhook.
+
+.. code-block:: json
+
+   {
+      "input": {
+         "account": "minio",
+         "groups": null,
+         "action": "s3:ListBucket",
+         "bucket": "test",
+         "conditions": {
+            "Authorization": [
+            "AWS4-HMAC-SHA256 Credential=minio/20220507/us-east-1/s3/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=62012db6c47d697620cf6c68f0f45f6e34894589a53ab1faf6dc94338468c78a"
+            ],
+            "CurrentTime": [ "2022-05-07T18:31:41Z" ],
+            "Delimiter": [ "/" ],
+            "EpochTime": [
+            "1651948301"
+            ],
+            "Prefix": [ "" ],
+            "Referer": [ "" ],
+            "SecureTransport": [ "false" ],
+            "SourceIp": [ "127.0.0.1" ],
+            "User-Agent": [ "MinIO (linux; amd64) minio-go/v7.0.24 mc/DEVELOPMENT.2022-04-20T23-07-53Z" ],
+            "UserAgent": [ "MinIO (linux; amd64) minio-go/v7.0.24 mc/DEVELOPMENT.2022-04-20T23-07-53Z" ],
+            "X-Amz-Content-Sha256": [ "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" ],
+            "X-Amz-Date": [ "20220507T183141Z" ],
+            "authType": [ "REST-HEADER" ],
+            "principaltype": [ "Account" ],
+            "signatureversion": [ "AWS4-HMAC-SHA256" ],
+            "userid": [ "minio" ],
+            "username": [ "minio" ],
+            "versionid": [ "" ]
+         },
+         "owner": true,
+         "object": "",
+         "claims": {},
+         "denyOnly": false
+      }
+   }
+
+Response Body Example
+---------------------
+
+MinIO requires the response body from the Access Management service meet one of the two following formats:
+
+.. code-block:: json
+
+   { "result" : true }
+
+   { "result" : { "allow" : true } }

source/includes/common-minio-external-auth.rst

@@ -407,3 +407,31 @@ Specify a comment to associate to the identity configuration.
 
 .. end-minio-identity-management-comment
 
+.. start-minio-access-management-plugin-url
+
+The webhook endpoint for the external access management service (``https://authzservice.example.net:8080/authz``).
+
+.. end-minio-access-management-plugin-url
+
+.. start-minio-access-management-plugin-auth-token
+
+An authentication token to present to the configured webhook endpoint.
+
+Specify a supported HTTP `Authentication scheme <https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication#authentication_schemes>`__ as a string value, such as ``"Bearer TOKEN"``.
+MinIO sends the token using the HTTP `Authorization <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization>`__ header.
+
+.. end-minio-access-management-plugin-auth-token
+
+.. start-minio-access-management-plugin-enable-http2
+
+Enable experimental HTTP2 support for connecting to the configure webhook service. 
+
+Defaults to off
+
+.. end-minio-access-management-plugin-enable-http2
+
+.. start-minio-access-management-plugin-comment
+
+Specify a comment to associate to the external access management configuration.
+
+.. end-minio-access-management-plugin-comment

source/reference/minio-server/settings/iam.rst

@@ -16,6 +16,7 @@ There is a page of settings for each of the IAM methods MinIO supports.
 - :ref:`Active Directory / LDAP <minio-server-envvar-external-identity-management-ad-ldap>`
 - :ref:`OpenID <minio-server-envvar-external-identity-management-openid>`
 - :ref:`MinIO Identity Management Plugin <minio-server-envvar-external-identity-management-plugin>`
+- :ref:`MinIO Access Management Plugin <minio-server-envvar-external-identity-management-plugin>`
 
 .. toctree::
    :titlesonly:
@@ -23,4 +24,5 @@ There is a page of settings for each of the IAM methods MinIO supports.
    
    /reference/minio-server/settings/iam/ldap
    /reference/minio-server/settings/iam/openid
-   /reference/minio-server/settings/iam/minio-identity-plugin
+   /reference/minio-server/settings/iam/minio-identity-plugin
+   /reference/minio-server/settings/iam/minio-access-plugin

source/reference/minio-server/settings/iam/minio-access-plugin.rst

@@ -0,0 +1,136 @@
+.. _minio-server-envvar-external-access-management-plugin:
+
+=======================================
+MinIO Access Management Plugin Settings
+=======================================
+
+.. default-domain:: minio
+
+.. contents:: Table of Contents
+   :local:
+   :depth: 2
+
+This page documents settings for enabling external authorization management using the MinIO Access Management Plugin.
+See :ref:`minio-external-access-management-plugin` for a tutorial on using these settings.
+
+Examples
+--------
+
+When setting up the MinIO Access Management plugin, you must define at minimum all *required* settings.
+The examples here represent the minimum required setting.
+
+.. tab-set::
+
+   .. tab-item:: Environment Variables
+      :sync: envvar
+
+      .. code-block:: shell
+
+         MINIO_POLICY_PLUGIN_URL="https://authzservice.example.net:8080/authz"
+
+   .. tab-item:: Configuration Settings
+      :sync: config
+
+      .. mc-conf:: policy_plugin
+
+      Use the :mc:`mc admin config set` command to create or update the access management plugin configuration.
+      The ``policy_plugin url`` argument is required.
+      Specify additional optional arguments as a whitespace (" ")-delimited list.
+      
+
+      .. code-block:: shell
+
+         mc admin config set policy_plugin                     \
+            url="https://authzservice.example.net:8080/authz"  \
+            [ARGUMENT=VALUE] ...
+
+Settings
+--------
+
+URL
+~~~
+
+*Required*
+
+.. tab-set::
+
+   .. tab-item:: Environment Variable
+      :sync: envvar
+
+      .. envvar:: MINIO_POLICY_PLUGIN_URL
+
+   .. tab-item:: Configuration Setting
+      :sync: config
+
+      .. mc-conf:: policy_plugin url
+         :delimiter: " "
+
+.. include:: /includes/common-minio-external-auth.rst
+   :start-after: start-minio-access-management-plugin-url
+   :end-before: end-minio-access-management-plugin-url
+
+Auth Token
+~~~~~~~~~~
+
+*Optional*
+
+.. tab-set::
+
+   .. tab-item:: Environment Variable
+      :sync: envvar
+
+      .. envvar:: MINIO_POLICY_PLUGIN_AUTH_TOKEN
+
+   .. tab-item:: Configuration Setting
+      :sync: config
+
+      .. mc-conf:: policy_plugin auth_token
+         :delimiter: " "
+
+.. include:: /includes/common-minio-external-auth.rst
+   :start-after: start-minio-access-management-plugin-auth-token
+   :end-before: end-minio-access-management-plugin-auth-token
+
+HTTP2
+~~~~~
+
+*Optional*
+
+.. tab-set::
+
+   .. tab-item:: Environment Variable
+      :sync: envvar
+
+      .. envvar:: MINIO_POLICY_PLUGIN_ENABLE_HTTP2
+
+   .. tab-item:: Configuration Setting
+      :sync: config
+
+      .. mc-conf:: policy_plugin enable_http2
+         :delimiter: " "
+
+.. include:: /includes/common-minio-external-auth.rst
+   :start-after: start-minio-access-management-plugin-enable-http2
+   :end-before: end-minio-access-management-plugin-enable-http2
+
+Comment
+~~~~~~~
+
+*Optional*
+
+.. tab-set::
+
+   .. tab-item:: Environment Variable
+      :sync: envvar
+
+      .. envvar:: MINIO_POLICY_PLUGIN_COMMENT
+
+   .. tab-item:: Configuration Setting
+      :sync: config
+
+      .. mc-conf:: policy_plugin comment
+         :delimiter: " "
+
+.. include:: /includes/common-minio-external-auth.rst
+   :start-after: start-minio-access-management-plugin-comment
+   :end-before: end-minio-access-management-plugin-comment

source/reference/minio-server/settings/iam/minio-identity-plugin.rst

@@ -34,7 +34,7 @@ The examples here represent the minimum required settings.
 
       .. mc-conf:: identity_plugin
 
-      Use :mc:`mc admin config set` to create or update the OpenID configuration. 
+      Use :mc:`mc admin config set` to create or update the identity plugin configuration. 
       The ``identity_plugin url`` argument is required. 
       Specify additional optional arguments as a whitespace (" ")-delimited list.