minio/docs
1
0
Fork 0
mirror of https://github.com/minio/docs.git synced 2025-07-30 07:03:26 +03:00
Code Activity

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

Browse Source 
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>
This commit is contained in:
Ravind Kumar
2024-01-30 11:15:25 -05:00
committed by GitHub
parent 8238ea9303
commit 5cba0951fb
6 changed files with 298 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
source/administration/identity-access-management.rst
View File

@ -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

126
source/administration/identity-access-management/pluggable-authorization.rst Normal file
View File

@ -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 } }

28
source/includes/common-minio-external-auth.rst
View File

@ -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

4
source/reference/minio-server/settings/iam.rst
View File

@ -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

136
source/reference/minio-server/settings/iam/minio-access-plugin.rst Normal file
View File

@ -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

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

@ -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.