From 5cba0951fbbae6d5e1002ee27a26984473e55595 Mon Sep 17 00:00:00 2001 From: Ravind Kumar Date: Tue, 30 Jan 2024 11:15:25 -0500 Subject: [PATCH] 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 --- .../identity-access-management.rst | 4 + .../pluggable-authorization.rst | 126 ++++++++++++++++ .../includes/common-minio-external-auth.rst | 28 ++++ .../reference/minio-server/settings/iam.rst | 4 +- .../settings/iam/minio-access-plugin.rst | 136 ++++++++++++++++++ .../settings/iam/minio-identity-plugin.rst | 2 +- 6 files changed, 298 insertions(+), 2 deletions(-) create mode 100644 source/administration/identity-access-management/pluggable-authorization.rst create mode 100644 source/reference/minio-server/settings/iam/minio-access-plugin.rst diff --git a/source/administration/identity-access-management.rst b/source/administration/identity-access-management.rst index 8e6f9cbb..d0efb02d 100644 --- a/source/administration/identity-access-management.rst +++ b/source/administration/identity-access-management.rst @@ -50,6 +50,9 @@ MinIO supports both internal and external identity management: ` - Supports managing identities through an Active Directory or LDAP service. + * - :ref:`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 diff --git a/source/administration/identity-access-management/pluggable-authorization.rst b/source/administration/identity-access-management/pluggable-authorization.rst new file mode 100644 index 00000000..2981d03a --- /dev/null +++ b/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 `. + +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 ` 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 } } diff --git a/source/includes/common-minio-external-auth.rst b/source/includes/common-minio-external-auth.rst index e8743a04..b99d573b 100644 --- a/source/includes/common-minio-external-auth.rst +++ b/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 `__ as a string value, such as ``"Bearer TOKEN"``. +MinIO sends the token using the HTTP `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 \ No newline at end of file diff --git a/source/reference/minio-server/settings/iam.rst b/source/reference/minio-server/settings/iam.rst index 717b2fdd..40f10eb8 100644 --- a/source/reference/minio-server/settings/iam.rst +++ b/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 ` - :ref:`OpenID ` - :ref:`MinIO Identity Management Plugin ` +- :ref:`MinIO Access 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 \ No newline at end of file + /reference/minio-server/settings/iam/minio-identity-plugin + /reference/minio-server/settings/iam/minio-access-plugin \ No newline at end of file diff --git a/source/reference/minio-server/settings/iam/minio-access-plugin.rst b/source/reference/minio-server/settings/iam/minio-access-plugin.rst new file mode 100644 index 00000000..74890f94 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/source/reference/minio-server/settings/iam/minio-identity-plugin.rst b/source/reference/minio-server/settings/iam/minio-identity-plugin.rst index daa7a5e2..b038db01 100644 --- a/source/reference/minio-server/settings/iam/minio-identity-plugin.rst +++ b/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.