minio/docs
1
0
Fork 0
mirror of https://github.com/minio/docs.git synced 2025-07-28 19:42:10 +03:00
Code Activity

DOCS-476: OIDC, Keycloak, Dex, and Policy Variables (#735)

Browse Source
This commit is contained in:
Ravind Kumar
2023-03-24 18:39:50 -04:00
committed by GitHub
parent 12177544ba
commit b32d6167db
21 changed files with 1922 additions and 121 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@ -43,6 +43,9 @@ MinIO supports both internal and external identity management:
- Supports managing identities through an OpenID Connect (OIDC) compatible - Supports managing identities through an OpenID Connect (OIDC) compatible
service. service.
* - :ref:`MinIO Authentation Plugin <minio-external-identity-management-plugin>`
- Supports a custom external identity manager using the MinIO Authentication Plugin extension.
* - :ref:`Active Directory / LDAP * - :ref:`Active Directory / LDAP
<minio-external-identity-management-ad-ldap>` <minio-external-identity-management-ad-ldap>`
- Supports managing identities through an Active Directory or LDAP service. - Supports managing identities through an Active Directory or LDAP service.
@ -138,4 +141,5 @@ JSON syntax.
/administration/identity-access-management/minio-identity-management /administration/identity-access-management/minio-identity-management
/administration/identity-access-management/oidc-access-management /administration/identity-access-management/oidc-access-management
/administration/identity-access-management/ad-ldap-access-management /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/policy-based-access-control

7
source/administration/identity-access-management/oidc-access-management.rst
View File

@ -83,4 +83,9 @@ Creating Policies to Match Claims
Use either the MinIO Console *or* the :mc:`mc admin policy` command to create policies that match one or more claim values. Use either the MinIO Console *or* the :mc:`mc admin policy` command to create policies that match one or more claim values.
.. todo - instructions OIDC Policy Variables
---------------------
.. include:: /includes/common/common-minio-oidc.rst
:start-after: start-minio-oidc-policy-variables
:end-before: end-minio-oidc-policy-variables

111
source/administration/identity-access-management/pluggable-authentication.rst Normal file
View File

@ -0,0 +1,111 @@
.. _minio-external-identity-management-plugin:
=========================================
MinIO External Identity Management Plugin
=========================================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 1
Overview
--------
The MinIO Identity Management Plugin provides a REST interface for offloading authentication to an external identity manager through a webhook service.
Once enabled, client applications use the ``AssumeRoleWithCustomToken`` STS API extension to generate access tokens for MinIO.
MinIO verifies this token by making a POST request to the configured plugin endpoint and uses the returned response to determine the authentication status of the client.
Configuration Settings
----------------------
You can configure the MinIO Identity Management Plugin using the following environment variables or configuration settings:
.. tab-set::
.. tab-item:: Environment Variables
Specify the following :ref:`environment variables <minio-server-envvar-external-identity-management-plugin>` to each MinIO server in the deployment:
.. code-block:: shell
:class: copyable
MINIO_IDENTITY_PLUGIN_URL="https://external-auth.example.net:8080/auth"
MINIO_IDENTITY_PLUGIN_ROLE_POLICY="consoleAdmin"
# All other envvars are optional
MINIO_IDENTITY_PLUGIN_TOKEN="Bearer TOKEN"
MINIO_IDENTITY_PLUGIN_ROLE_ID="external-auth-provider"
MINIO_IDENTITY_PLUGIN_COMMENT="External Identity 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 identity_plugin \
url="https://external-auth.example.net:8080/auth" \
role_policy="consoleAdmin" \
# All other config settings are optional
token="Bearer TOKEN" \
role_id="external-auth-provider" \
comment="External Identity Management using PROVIDER"
Authentication and Authorization Flow
-------------------------------------
The login flow for an application is as follows:
1. Make a POST request using the :ref:`minio-sts-assumerolewithcustomtoken` API.
The request includes a token used by the configured external identity manager for authenticating the client.
2. MinIO makes a POST call to the configured identity plugin URL using the token specified to the STS API.
3. On successful authentication, the identity manager returns a ``200 OK`` response with an ``application/json`` content-type and body with the following structure:
.. code-block:: json
{
"user": "<string>",
"maxValiditySeconds": 3600,
"claims": "KEY=VALUE,[KEY=VALUE,...]"
}
.. list-table::
:stub-columns: 1
:widths: 30 70
:width: 100%
* - ``user``
- The owner of the requested credentials
* - ``maxValiditySeconds``
- The maximum allowed expiry duration for the returned credentials
* - ``claims``
- A list of key-value pair claims associated with the requested credentials.
MinIO reserves and ignores the ``exp``, ``parent``, and ``sub`` claims objects if present.
4. MinIO returns a response to the STS API request that includes temporary credentials for use with making authenticated requests.
If the identity manager rejects the authentication request or otherwise encounters an error, the response *must* return a ``403 FORBIDDEN`` HTTP status code with an ``application/json`` content-type and body with the following structure:
.. code-block:: json
{
"reason": "<string>"
}
The ``"reason"`` field should include the reason for the 403.
Creating Policies to Match Claims
---------------------------------
Use either the :ref:`MinIO Console <minio-console-admin-policies>` *or* the :mc:`mc admin policy` command to create policies that match one or more claim values.

125
source/administration/identity-access-management/policy-based-access-control.rst
View File

@ -816,3 +816,128 @@ MinIO supports the following conditions for use with defining policies for
For complete information on any listed condition key, see the :iam-docs:`IAM For complete information on any listed condition key, see the :iam-docs:`IAM
Condition Element Documentation <reference_policies_elements_condition.html>` Condition Element Documentation <reference_policies_elements_condition.html>`
Policy Variables
----------------
MinIO supports using policy variables for automatically substituting context from the authenticated user and/or the operation into the user's assigned policy or policies.
Use the ``${POLICYVARIABLE}`` format to specify the variable to the policy as part of the ``Condition`` or ``Resource`` definition.
MinIO policy variables function similarly to :iam-docs:`AWS IAM policy elements: Variables and tags <reference_policies_variables.html>`.
Each MinIO :ref:`identity provider <minio-authentication-and-identity-management>` supports its own set of policy variables:
- :ref:`minio-policy-variables-internal`
- :ref:`minio-policy-variables-oidc`
- :ref:`minio-policy-variables-ad-ldap`
.. _minio-policy-variables-internal:
MinIO Policy Variables
~~~~~~~~~~~~~~~~~~~~~~
The following table contains a list of recommended policy variables for use in authorizing :ref:`MinIO-managed users <minio-internal-idp>`:
.. list-table::
:header-rows: 1
:widths: 40 60
:width: 100%
* - Variable
- Description
* - :iam-docs:`aws:referrer <reference_policies_condition-keys.html#condition-keys-referer>`
- The referrer in the HTTP header for the authenticated API call.
* - :iam-docs:`aws:SourceIp <reference_policies_condition-keys.html#condition-keys-sourceip>`
- The source IP in the HTTP header for the authenticated API call.
* - :iam-docs:`aws:username <reference_policies_condition-keys.html#condition-keys-username>`
- The name of the user associated with the authenticated API call.
For example, the following policy uses variables to substitute the authenticated user's username as part of the ``Resource`` field such that the user can only access those prefixes which match their username:
.. code-block:: json
{
"Version": "2012-10-17",
"Statement": [
{
"Action": ["s3:ListBucket"],
"Effect": "Allow",
"Resource": ["arn:aws:s3:::mybucket"],
"Condition": {"StringLike": {"s3:prefix": ["${aws:username}/*"]}}
},
{
"Action": [
"s3:GetObject",
"s3:PutObject"
],
"Effect": "Allow",
"Resource": ["arn:aws:s3:::mybucket/${aws:username}/*"]
}
]
}
MinIO replaces the ``${aws:username}`` variable in the ``Resource`` field with the username.
MinIO then evaluates the policy and grants or revokes access to the requested API and resource.
.. _minio-policy-variables-oidc:
OpenID Policy Variables
~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-minio-oidc.rst
:start-after: start-minio-oidc-policy-variables
:end-before: end-minio-oidc-policy-variables
.. _minio-policy-variables-ad-ldap:
Active Directory / LDAP Policy Variables
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following table contains a list of supported policy variables for use in authorizing :ref:`AD/LDAP users <minio-external-identity-management-ad-ldap>`:
.. list-table::
:header-rows: 1
:widths: 40 60
:width: 100%
* - Variable
- Description
* - ``ldap:username``
- The simple username (``name``) for the authenticated user.
This is distinct from the user's DistinguishedName or CommonName.
* - ``ldap:user``
- The Distinguished Name used by the authenticated user.
* - ``ldap:groups``
- The Group Distinguished Name for the authenticated user.
For example, the following policy uses variables to substitute the authenticated user's ``name`` as part of the ``Resource`` field such that the user can only access those prefixes which match their name:
.. code-block:: json
{
"Version": "2012-10-17",
"Statement": [
{
"Action": ["s3:ListBucket"],
"Effect": "Allow",
"Resource": ["arn:aws:s3:::mybucket"],
"Condition": {"StringLike": {"s3:prefix": ["${ldap:username}/*"]}}
},
{
"Action": [
"s3:GetObject",
"s3:PutObject"
],
"Effect": "Allow",
"Resource": ["arn:aws:s3:::mybucket/${ldap:username}/*"]
}
]
}
MinIO replaces the ``${ldap:username}`` variable in the ``Resource`` field with the value of the authenticated user's ``name``.
MinIO then evaluates the policy and grants or revokes access to the requested API and resource.

8
source/developers/security-token-service.rst
View File

@ -24,14 +24,18 @@ MinIO supports the following STS API endpoints:
- Supported IDP - Supported IDP
- Description - Description
* - AssumeRoleWithWebIdentity * - :ref:`AssumeRoleWithWebIdentity <minio-sts-assumerolewithwebidentity>`
- OpenID Connect - OpenID Connect
- Generates an access key and secret key using the JWT token returned by the OIDC provider - Generates an access key and secret key using the JWT token returned by the OIDC provider
* - AssumeRoleWithLDAPIdentity * - :ref:`AssumeRoleWithLDAPIdentity <minio-sts-assumerolewithldapidentity>`
- Active Directory / LDAP - Active Directory / LDAP
- Generates an access key and secret key using the AD/LDAP credentials specified to the API endpoint. - Generates an access key and secret key using the AD/LDAP credentials specified to the API endpoint.
* - :ref:`AssumeRoleWithCustomToken <minio-sts-assumerolewithcustomtoken>`
- MinIO Identity Plugin
- Generates a token for use with an external identity provider and the :ref:`MinIO Identity Plugin <minio-external-identity-management-plugin>`.
.. toctree:: .. toctree::
:titlesonly: :titlesonly:
:hidden: :hidden:

115
source/developers/security-token-service/AssumeRoleWithCustomToken.rst Normal file
View File

@ -0,0 +1,115 @@
.. _minio-sts-assumerolewithcustomtoken:
=============================
``AssumeRoleWithCustomToken``
=============================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
The MinIO Security Token Service (STS) ``AssumeRoleWithCustomToken`` API endpoint generates a token for use with the :ref:`minio-external-identity-management-plugin`.
Request Endpoint
----------------
The ``AssumeRoleWithCustomToken`` endpoint has the following form:
.. code-block:: shell
POST https://minio.example.net?Action=AssumeRoleWithCustomToken[&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=AssumeRoleWithCustomToken
&Token=TOKEN
&Version=2011-06-15
&DurationSeconds=86000
&RoleArn="external-auth-provider"
Request Query Parameters
~~~~~~~~~~~~~~~~~~~~~~~~
This endpoint supports the following query parameters:
.. list-table::
:header-rows: 1
:widths: 20 20 60
:width: 100%
* - Parameter
- Type
- Description
* - ``Token``
- string
- *Required*
Specify the JSON Token to present to the external identity manager.
MinIO expects the identity manager to parse the token and determine whether to authenticate client requests using that token.
* - ``Version``
- string
- *Required*
Specify ``2011-06-15``.
* - ``RoleArn``
- string
- *Required*
Specify the ARN for the Identity Manager Plugin configuration to associate with this STS request.
See :envvar:`MINIO_IDENTITY_PLUGIN_ROLE_ID` or :mc-conf:`identity_plugin role_id <identity_plugin.role_id>` for more information.
* - ``DurationSeconds``
- integer
- *Optional*
Specify the number of seconds after which the temporary credentials expire.
Defaults to ``3600``.
- The minimum value is ``900`` or 15 minutes.
- The maximum value is ``604800`` or 7 days.
Response Elements
-----------------
MinIO returns an ``AssumeRoleWithCustomTokenResult`` 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
``AssumeRoleWithCustomToken`` endpoint:
.. code-block:: xml
<?xml version="1.0" encoding="UTF-8"?>
<AssumeRoleWithCustomTokenResponse xmlns="https://sts.amazonaws.com/doc/2011-06-15/">
<AssumeRoleWithCustomTokenResult>
<Credentials>
<AccessKeyId>ACCESS_KEY</AccessKeyId>
<SecretAccessKey>SECRET_KEY</SecretAccessKey>
<Expiration>YYYY-MM-DDTHH:MM:SSZ</Expiration>
<SessionToken>TOKEN</SessionToken>
</Credentials>
<AssumedUser>custom:Alice</AssumedUser>
</AssumeRoleWithCustomTokenResult>
<ResponseMetadata>
<RequestId>UNIQUE_ID</RequestId>
</ResponseMetadata>
</AssumeRoleWithCustomTokenResponse>
Error Elements
--------------
The XML error response for this API endpoint is similar to the AWS :aws-docs:`AssumeRoleWithWebIdentity response <STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html#API_AssumeRoleWithWebIdentity_Errors>`.

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

@ -56,6 +56,12 @@ Defaults to ``policy``.
.. end-minio-openid-claim-name .. end-minio-openid-claim-name
.. start-minio-openid-display-name
Specify the user-facing name the MinIO Console displays on the login screen.
.. end-minio-openid-display-name
.. start-minio-openid-claim-prefix .. start-minio-openid-claim-prefix
Specify the Specify the
@ -74,33 +80,70 @@ Defaults to those scopes advertised in the discovery document.
.. start-minio-openid-redirect-uri .. start-minio-openid-redirect-uri
Specify the redirect URI the MinIO Console uses when authenticating against the .. important::
configured provider. Include the console port and ``/oauth_callback``
as part of the URL: This parameter is **deprecated** and will be removed in a future release.
Use :envvar:`MINIO_BROWSER_REDIRECT_URL` instead.
The MinIO Console defaults to using the hostname of the node making the authentication request.
For MinIO deployments behind a load balancer or reverse proxy, specify this field to ensure the OIDC provider returns the authentication response to the correct MinIO Console URL.
Include the Console hostname, port, and ``/oauth_callback``:
.. code-block:: shell .. code-block:: shell
http://minio.example.net:consoleport/oauth_callback http://minio.example.net:consoleport/oauth_callback
MinIO defaults to using the hostname of the node making the authentication Ensure you start the MinIO Server with the :mc-cmd:`~minio server --console-address` option to set a static Console listen port.
request. MinIO deployments behind a load balancer or reverse proxy *may* The default behavior with that option omitted is to select a random port number at startup.
need to specify this field to ensure the OIDC provider returns the
authentication response to the correct URL.
The specified URI *must* match one of the approved The specified URI *must* match one of the approved redirect / callback URIs on the provider.
redirect / callback URIs on the provider. See the OpenID `Authentication Request See the OpenID `Authentication Request <https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest>`__ for more information.
<https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest>`__ for
more information.
.. note::
The embedded MinIO Console by default uses a random port number selected at
server startup. Start the MinIO server process with the
:mc-cmd:`~minio server --console-address` option to specify a static
port number.
.. end-minio-openid-redirect-uri .. end-minio-openid-redirect-uri
.. start-minio-openid-redirect-uri-dynamic
The MinIO Console defaults to using the hostname of the node making the authentication request as part of the redirect URI provided to the OIDC provider.
For MinIO deployments behind a load balancer using a round-robin protocol, this may result in the load balancer returning the response to a different MinIO Node than the originating client.
Specify this option as ``true`` to direct the MinIO Console to use the ``Host`` header of the originating request to construct the redirect URI passed to the OIDC provider.
.. end-minio-openid-redirect-uri-dynamic
.. start-minio-openid-claim-userinfo
Specify the OpenID User info API endpoint for the OIDC service.
For example, ``https://oidc-endpoint:port/realms/REALM/protocol/openid-connect/userinfo``
Some OIDC providers do not provide group information as part of the JWT response after authentication.
Specify this URL to direct MinIO to make an additional API call to construct the complete JWT token.
.. end-minio-openid-claim-userinfo
.. start-minio-openid-vendor
Specify the OIDC Vendor to enable specific supported behaviors for that vendor.
Supports the following value:
- ``keycloak``
.. end-minio-openid-vendor
.. start-minio-openid-keycloak-realm
Specify the Keycloak Realm to use as part of Keycloak Admin API Operations, such as ``main``.
.. end-minio-openid-keycloak-realm
.. start-minio-openid-keycloak-admin-url
Specify the Keycloak Admin API URL.
MinIO can use this URL if configured to periodically validate authenticated Keycloak users as active/existing.
For example, ``https://keycloak-endpoint:port/admin/``.
.. end-minio-openid-keycloak-admin-url
.. start-minio-openid-comment .. start-minio-openid-comment
Specify a comment to associate with the :abbr:`OIDC (OpenID Connect)` compatible Specify a comment to associate with the :abbr:`OIDC (OpenID Connect)` compatible
@ -272,3 +315,38 @@ Defaults to ``off``
Specify a comment to associate to the AD/LDAP configuration. Specify a comment to associate to the AD/LDAP configuration.
.. end-minio-ad-ldap-comment .. end-minio-ad-ldap-comment
.. start-minio-identity-management-plugin-url
The webhook endpoint for the external identity management service (``https://authservice.example.net:8080/auth``).
.. end-minio-identity-management-plugin-url
.. start-minio-identity-management-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-identity-management-auth-token
.. start-minio-identity-management-role-policy
Specify a comma separated list of MinIO :ref:`policies <minio-policy>` to assign to authenticated users.
.. end-minio-identity-management-role-policy
.. start-minio-identity-management-role-id
Specify a unique ID MinIO uses to generate an ARN for this identity manager.
If omitted, MinIO automatically generates the ID and prints the full ARN to the server log.
.. end-minio-identity-management-role-id
.. start-minio-identity-management-comment
Specify a comment to associate to the identity configuration.
.. end-minio-identity-management-comment

370
source/includes/common/common-configure-keycloak-identity-management.rst Normal file
View File

@ -0,0 +1,370 @@
.. start-configure-keycloak-client
Select :guilabel:`Create client` and follow the instructions to create a new Keycloak client for MinIO.
Fill in the specified inputs as follows:
.. list-table::
:stub-columns: 1
:widths: 30 70
:width: 100%
* - :guilabel:`Client ID`
- Set to a unique identifier for MinIO (``minio``)
* - :guilabel:`Client type`
- Set to ``OpenID Connect``
* - :guilabel:`Always display in console`
- Toggle to ``On``
* - :guilabel:`Client authentication`
- Toggle to ``On``
* - :guilabel:`Authentication flow`
- Toggle on ``Standard flow``
* - (Optional) :guilabel:`Authentication flow`
- Toggle on ``Direct access grants`` (API testing)
Keycloak deploys the client with a default set of configuration values.
Modify these values as necessary for your Keycloak setup and desired behavior.
The following table provides a baseline of settings and values to configure:
.. list-table::
:stub-columns: 1
:widths: 30 70
:width: 100%
* - :guilabel:`Root URL`
- Set to ``${authBaseUrl}``
* - :guilabel:`Home URL`
- Set to the Realm you want MinIO to use (``/realms/master/account/``)
* - :guilabel:`Valid Redirect URI`
- Set to ``*``
* - :guilabel:`Keys -> Use JWKS URL`
- Toggle to ``On``
* - :guilabel:`Advanced -> Advanced Settings -> Access Token Lifespan`
- Set to ``1 Hour``.
.. end-configure-keycloak-client
.. start-configure-keycloak-client-scope
Navigate to the :guilabel:`Client scopes` view and create a new client scope for MinIO authorization:
.. list-table::
:stub-columns: 1
:widths: 30 70
:width: 100%
* - :guilabel:`Name`
- Set to any recognizable name for the policy (``minio-authorization``)
* - :guilabel:`Include in token scope`
- Toggle to ``On``
Once created, select the scope from the list and navigate to :guilabel:`Mappers`.
Select :guilabel:`Configure a new mapper` to create a new mapping:
.. list-table::
:stub-columns: 1
:widths: 30 70
:width: 100%
* - :guilabel:`User Attribute`
- Select the Mapper Type
* - :guilabel:`Name`
- Set to any recognizable name for the mapping (``minio-policy-mapper``)
* - :guilabel:`User Attribute`
- Set to ``policy``
* - :guilabel:`Token Claim Name`
- Set to ``policy``
* - :guilabel:`Add to ID token`
- Set to ``On``
* - :guilabel:`Claim JSON Type`
- Set to ``String``
* - :guilabel:`Multivalued`
- Set to ``On``
This allows setting multiple ``policy`` values in the single claim.
* - :guilabel:`Aggregate attribute values`
- Set to ``On``
This allows users to inherit any ``policy`` set in their Groups
Once created, assign the Client Scope to the MinIO client.
1. Navigate to :guilabel:`Clients` and select the MinIO client.
2. Select :guilabel:`Client scopes`, then select :guilabel:`Add client scope`.
3. Select the previously created scope and set the :guilabel:`Assigned type` to ``default``.
.. end-configure-keycloak-client-scope
.. start-configure-keycloak-user-group-attributes
For Users, navigate to :guilabel:`Users` and select or create the User:
.. list-table::
:stub-columns: 1
:widths: 30 70
:width: 100%
* - :guilabel:`Credentials`
- Set the user password to a permanent value if not already set
* - :guilabel:`Attributes`
- Create a new attribute with key ``policy`` and value of any :ref:`policy <minio-policy>` (``consoleAdmin``)
For Groups, navigate to :guilabel:`Groups` and select or create the Group:
.. list-table::
:stub-columns: 1
:widths: 30 70
:width: 100%
* - :guilabel:`Attributes`
- Create a new attribute with key ``policy`` and value of any :ref:`policy <minio-policy>` (``consoleAdmin``)
You can assign users to groups such that they inherit the specified ``policy`` attribute.
If you set the Mapper settings to enable :guilabel:`Aggregate attribute values`, Keycloak includes the aggregated array of policies as part of the authenticated user's JWT token.
MinIO can use this list of policies when authorizing the user.
You can test the configured policies of a user by using the Keycloak API:
.. code-block:: shell
:class: copyable
:substitutions:
curl -d "client_id=minio" \
-d "client_secret=secretvalue" \
-d "grant_type=password" \
-d "username=minio-user-1" \
-d "password=minio-user-1-password" \
http://|KEYCLOAK_URL|/realms/REALM/protocol/openid-connect/token
If successful, the ``access_token`` contains the JWT necessary to use the MinIO :ref:`minio-sts-assumerolewithwebidentity` STS API and generate S3 credentials.
You can use a JWT decoder to review the payload and ensure it contains the ``policy`` key with one or more MinIO policies listed.
.. end-configure-keycloak-user-group-attributes
.. start-configure-keycloak-sts
Applications using an S3-compatible SDK must specify credentials in the form of an access key and secret key.
The MinIO :ref:`minio-sts-assumerolewithwebidentity` API returns the necessary temporary credentials, including a required session token, using a JWT returned by Keycloak after authentication.
You can test this workflow using the following sequence of HTTP calls and the ``curl`` utility:
1. Authenticate as a Keycloak user and retrieve the JWT token
.. code-block:: shell
:class: copyable
:substitutions:
curl -X POST "https://|KEYCLOAK_URL|/realms/REALM/protocol/openid-connect/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "username=USER" \
-d "password=PASSWORD" \
-d "grant_type=password" \
-d "client_id=CLIENT" \
-d "client_secret=SECRET"
- Replace the ``USER`` and ``PASSWORD`` with the credentials of a Keycloak user on the ``REALM``.
- Replace the ``CLIENT`` and ``SECRET`` with the client ID and secret for the MinIO-specific Keycloak client on the ``REALM``
You can process the results using ``jq`` or a similar JSON-formatting utility.
Extract the ``access_token`` field to retrieve the necessary access token.
Pay attention to the ``expires_in`` field to note the number of seconds before the token expires.
2. Generate MinIO Credentials using the ``AssumeRoleWithWebIdentity`` API
.. code-block:: shell
:class: copyable
:substitutions:
curl -X POST "https://|MINIO_S3_URL|" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "Action=AssumeRoleWithWebIdentity" \
-d "Version=2011-06-15" \
-d "DurationSeconds=86000" \
-d "WebIdentityToken=TOKEN"
Replace the ``TOKEN`` with the ``access_token`` value returned by Keycloak.
The API returns an XML document on success containing the following keys:
- ``Credentials.AccessKeyId`` - the Access Key for the Keycloak User
- ``Credentials.SecretAccessKey`` - the Secret Key for the Keycloak User
- ``Credentials.SessionToken`` - the Session Token for the Keycloak User
- ``Credentials.Expiration`` - the Expiration Date for the generated credentials
3. Test the Credentials
Use your preferred S3-compatible SDK to connect to MinIO using the generated credentials.
For example, the following Python code using the MinIO :ref:`Python SDK <minio-python-quickstart>` connects to the MinIO deployment and returns a list of buckets:
.. code-block:: python
:substitutions:
from minio import Minio
client = MinIO(
"|MINIO_S3_URL|",
access_key = "ACCESS_KEY",
secret_key = "SECRET_KEY",
session_token = "SESSION_TOKEN"
secure = True
)
client.list_buckets()
.. end-configure-keycloak-sts
.. start-configure-keycloak-minio-console
Log in as a user with administrative privileges for the MinIO deployment such as a user with the :userpolicy:`consoleAdmin` policy.
Select :guilabel:`Identity` from the left-hand navigation bar, then select :guilabel:`OpenID`.
Select :guilabel:`Create Configuration` to create a new configuration.
Enter the following information into the modal:
.. list-table::
:stub-columns: 1
:widths: 30 70
:width: 100%
* - :guilabel:`Name`
- Enter a unique name for the Keycloak instance
* - :guilabel:`Config URL`
- Specify the address of the Keycloak OpenID configuration document (|KEYCLOAK_URL|)
Ensure the ``REALM`` matches the Keycloak realm you want to use for authenticating users to MinIO.
* - :guilabel:`Client ID`
- Specify the name of the Keycloak client created in Step 1
* - :guilabel:`Client Secret`
- Specify the secret credential value for the Keycloak client created in Step 1
* - :guilabel:`Display Name`
- Specify the user-facing name the MinIO Console displays as part of the Single-Sign On (SSO) workflow for the configured Keycloak service
* - :guilabel:`Scopes`
- Specify the OpenID scopes to include in the JWT, such as ``preferred_username`` or ``email``
You can reference these scopes using supported OpenID policy variables for the purpose of programmatic policy .
* - :guilabel:`Redirect URI Dynamic`
- Toggle to ``on``
Substitutes the MinIO Console address used by the client as part of the Keycloak redirect URI.
Keycloak returns authenticated users to the Console using the provided URI.
For MinIO Console deployments behind a reverse proxy, load balancer, or similar network control plane, you can instead use the :envvar:`MINIO_BROWSER_REDIRECT_URL` variable to set the redirect address for Keycloak to use.
Select :guilabel:`Save` to apply the configuration.
.. end-configure-keycloak-minio-console
.. start-configure-keycloak-minio-cli
You can use the :mc:`mc admin idp openid add` command to create a new configuration for the Keycloak service.
The command takes all supported :ref:`OpenID Configuration Settings <minio-open-id-config-settings>`:
.. code-block:: shell
:class: copyable
:substitutions:
mc admin idp openid add ALIAS PRIMARY_IAM \
client_id=MINIO_CLIENT \
client_secret=MINIO_CLIENT_SECRET \
config_url="https://|KEYCLOAK_URL|/realms/REALM/.well-known/openid-configuration" \
display_name="SSO_IDENTIFIER"
scopes="openid,email,preferred_username" \
redirect_uri_dynamic="on"
.. list-table::
:stub-columns: 1
:widths: 30 70
:width: 100%
* - ``PRIMARY_IAM``
- Set to a unique identifier for the Keycloak service, such as ``keycloak_primary``
* - | ``MINIO_CLIENT``
| ``MINIO_CLIENT_SECRET``
- Set to the Keycloak client ID and secret configured in Step 1
* - ``config_url``
- Set to the address of the Keycloak OpenID configuration document (|KEYCLOAK_URL|)
* - ``display_name``
- Set to a user-facing name the MinIO Console displays as part of the Single-Sign On (SSO) workflow for the configured Keycloak service
* - ``scopes``
- Set to a list of OpenID scopes you want to include in the JWT, such as ``preferred_username`` or ``email``
* - ``redirect_uri_dynamic``
- Set to ``on``
Substitutes the MinIO Console address used by the client as part of the Keycloak redirect URI.
Keycloak returns authenticated users to the Console using the provided URI.
For MinIO Console deployments behind a reverse proxy, load balancer, or similar network control plane, you can instead use the :envvar:`MINIO_BROWSER_REDIRECT_URL` variable to set the redirect address for Keycloak to use.
.. end-configure-keycloak-minio-cli
.. start-configure-keycloak-minio-envvar
Set the following :ref:`environment variables <minio-server-envvar-external-identity-management-openid>` prior to starting the container using the ``-e ENVVAR=VALUE`` flag.
The following example code sets the minimum required environment variables related to configuring Keycloak as an external identity management provider.
.. code-block:: shell
:class: copyable
:substitutions:
MINIO_IDENTITY_OPENID_CONFIG_URL_PRIMARY_IAM="https://|KEYCLOAK_URL|/.well-known/openid-configuration"
MINIO_IDENTITY_OPENID_CLIENT_ID_PRIMARY_IAM="MINIO_CLIENT"
MINIO_IDENTITY_OPENID_CLIENT_SECRET_PRIMARY_IAM="MINIO_CLIENT_SECRET"
MINIO_IDENTITY_OPENID_DISPLAY_NAME_PRIMARY_IAM="SSO_IDENTIFIER"
MINIO_IDENTITY_OPENID_SCOPES_PRIMARY_IAM="openid,email,preferred_username"
MINIO_IDENTITY_OPENID_REDIRECT_URI_DYNAMIC_PRIMARY_IAM="on"
.. list-table::
:stub-columns: 1
:widths: 30 70
:width: 100%
* - ``_PRIMARY_IAM``
- Replace the suffix ``_PRIMARY_IAM`` with a unique identifier for this Keycloak configuration.
For example, ``MINIO_IDENTITY_OPENID_CONFIG_URL_KEYCLOAK_PRIMARY``.
You can omit the suffix if you intend to only configure a single OIDC provider for the deployment.
* - :envvar:`CONFIG_URL <MINIO_IDENTITY_OPENID_CONFIG_URL>`
- Specify the address of the Keycloak OpenID configuration document (|KEYCLOAK_URL|)
Ensure the ``REALM`` matches the Keycloak realm you want to use for authenticating users to MinIO
* - | :envvar:`CLIENT_ID <MINIO_IDENTITY_OPENID_CLIENT_ID>`
| :envvar:`CLIENT_SECRET <MINIO_IDENTITY_OPENID_CLIENT_SECRET>`
- Specify the Keycloak client ID and secret configured in Step 1
* - :envvar:`DISPLAY_NAME <MINIO_IDENTITY_OPENID_DISPLAY_NAME>`
- Specify the user-facing name the MinIO Console displays as part of the Single-Sign On (SSO) workflow for the configured Keycloak service
* - :envvar:`OPENID_SCOPES <MINIO_IDENTITY_OPENID_SCOPES>`
- Specify the OpenID scopes you want to include in the JWT, such as ``preferred_username`` or ``email``
* - :envvar:`REDIRECT_URI_DYNAMIC <MINIO_IDENTITY_OPENID_REDIRECT_URI_DYNAMIC>`
- Set to ``on``
Substitutes the MinIO Console address used by the client as part of the Keycloak redirect URI.
Keycloak returns authenticated users to the Console using the provided URI.
For MinIO Console deployments behind a reverse proxy, load balancer, or similar network control plane, you can instead use the :envvar:`MINIO_BROWSER_REDIRECT_URL` variable to set the redirect address for Keycloak to use.
For complete documentation on these variables, see :ref:`minio-server-envvar-external-identity-management-openid`
.. end-configure-keycloak-minio-envvar

132
source/includes/common/common-k8s-connect-operator-console.rst
View File

@ -1,81 +1,77 @@
.. tab-set:: .. dropdown:: Port Forwarding
:open:
.. tab-item:: Port Forwarding .. note::
.. note:: Some Kubernetes deployments may experience issues with timeouts during port-forwarding operations with the Operator Console.
Select the :guilabel:`NodePorts` section to view instructions for alternative access.
You can alternatively configure your preferred Ingress to grant access to the Operator Console service.
See https://github.com/kubernetes/kubectl/issues/1368 for more information.
Some Kubernetes deployments may experience issues with timeouts during port-forwarding operations with the Operator Console. Run the :mc:`kubectl minio proxy` command to temporarily forward traffic from the :ref:`MinIO Operator Console <minio-operator-console>` service to your local machine:
Use one of the methods in the other tabs on this section as a work-around.
See https://github.com/kubernetes/kubectl/issues/1368 for more information.
Run the :mc:`kubectl minio proxy` command to temporarily forward traffic from .. cond:: k8s and not openshift
the :ref:`MinIO Operator Console <minio-operator-console>` service to your
local machine:
.. cond:: k8s and not openshift
.. code-block:: shell
:class: copyable
kubectl minio proxy
.. cond:: openshift
.. code-block:: shell
:class: copyable
oc minio proxy
The command output includes a JWT token you must use to log into the
Operator Console.
.. image:: /images/k8s/operator-dashboard.png
:align: center
:width: 70%
:class: no-scaled-link
:alt: MinIO Operator Console
You can deploy a new :ref:`MinIO Tenant <minio-k8s-deploy-minio-tenant>` from
the Operator Dashboard.
.. tab-item:: Node Ports
Use the following command to identify the :kube-docs:`NodePorts <concepts/services-networking/service/#type-nodeport>` configured for the Operator Console.
If your local host does not have the ``jq`` utility installed, you can run the first command and locate the ``spec.ports`` section of the output.
.. code-block:: shell .. code-block:: shell
:class: copyable :class: copyable
kubectl get svc/console -n minio-operator -o json | jq -r '.spec.ports' kubectl minio proxy
The output resembles the following: .. cond:: openshift
.. code-block:: json
[
{
"name": "http",
"nodePort": 31055,
"port": 9090,
"protocol": "TCP",
"targetPort": 9090
},
{
"name": "https",
"nodePort": 31388,
"port": 9443,
"protocol": "TCP",
"targetPort": 9443
}
]
Use the ``http`` or ``https`` port depending on whether you deployed the Operator with Console TLS enabled via :mc-cmd:`kubectl minio init --console-tls`.
Append the ``nodePort`` value to the externally-accessible IP address of a worker node in your Kubernetes cluster.
Use the following command to retrieve the JWT token necessary for logging into the Operator Console:
.. code-block:: shell .. code-block:: shell
:class: copyable :class: copyable
kubectl get secret/console-sa-secret -n minio-operator -o json | jq -r '.data.token' | base64 -d oc minio proxy
The command output includes a required token for logging into the Operator Console.
.. image:: /images/k8s/operator-dashboard.png
:align: center
:width: 70%
:class: no-scaled-link
:alt: MinIO Operator Console
You can deploy a new :ref:`MinIO Tenant <minio-k8s-deploy-minio-tenant>` from the Operator Dashboard.
.. dropdown:: NodePorts
Use the following command to identify the :kube-docs:`NodePorts <concepts/services-networking/service/#type-nodeport>` configured for the Operator Console.
If your local host does not have the ``jq`` utility installed, you can run the first command and locate the ``spec.ports`` section of the output.
.. code-block:: shell
:class: copyable
kubectl get svc/console -n minio-operator -o json | jq -r '.spec.ports'
The output resembles the following:
.. code-block:: json
[
{
"name": "http",
"nodePort": 31055,
"port": 9090,
"protocol": "TCP",
"targetPort": 9090
},
{
"name": "https",
"nodePort": 31388,
"port": 9443,
"protocol": "TCP",
"targetPort": 9443
}
]
Use the ``http`` or ``https`` port depending on whether you deployed the Operator with Console TLS enabled via :mc-cmd:`kubectl minio init --console-tls`.
Append the ``nodePort`` value to the externally-accessible IP address of a worker node in your Kubernetes cluster.
Use the following command to retrieve the JWT token necessary for logging into the Operator Console:
.. code-block:: shell
:class: copyable
kubectl get secret/console-sa-secret -n minio-operator -o json | jq -r '.data.token' | base64 -d

112
source/includes/common/common-minio-oidc.rst Normal file
View File

@ -0,0 +1,112 @@
.. start-minio-oidc-policy-variables
The following table contains a list of supported policy variables for use in authorizing :ref:`OIDC-managed users <minio-external-identity-management-openid>`.
Each variable corresponds to a claim returned as part of the authenticated user's JWT token:
.. list-table::
:header-rows: 1
:widths: 40 60
:width: 100%
* - Variable
- Description
* - ``jwt:sub``
- Returns the ``sub`` claim for the user.
* - ``jwt:iss``
- Returns the Issuer Identifier claim from the ID token.
* - ``jwt:aud``
- Returns the Audience claim from the ID token.
* - ``jwt:jti``
- Returns the JWT ID claim from the client authentication information.
* - ``jwt:upn``
- Returns the User Principal Name claim from the client authentication information.
* - ``jwt:name``
- Returns the ``name`` claim for the user.
* - ``jwt:groups``
- Returns the ``groups`` claim for the user.
* - ``jwt:given_name``
- Returns the ``given_name`` claim for the user.
* - ``jwt:family_name``
- Returns the ``family_name`` claim for the user.
* - ``jwt:middle_name``
- Returns the ``middle_name`` claim for the user.
* - ``jwt:nickname``
- Returns the ``nickname`` claim for the user.
* - ``jwt:preferred_username``
- Returns the ``preferred_username`` claim for the user.
* - ``jwt:profile``
- Returns the ``profile`` claim for the user.
* - ``jwt:picture``
- Returns the ``picture`` claim for the user.
* - ``jwt:website``
- Returns the ``website`` claim for the user.
* - ``jwt:email``
- Returns the ``email`` claim for the user.
* - ``jwt:gender``
- Returns the ``gender`` claim for the user.
* - ``jwt:birthdate``
- Returns the ``birthdate`` claim for the user.
* - ``jwt:phone_number``
- Returns the ``phone_number`` claim for the user.
* - ``jwt:address``
- Returns the ``address`` claim for the user.
* - ``jwt:scope``
- Returns the ``scope`` claim for the user.
* - ``jwt:client_id``
- Returns the ``client_id`` claim for the user.
See the `OpenID Connect Core 1.0 <https://openid.net/specs/openid-connect-core-1_0.html>`__ document for more information on these scopes.
Your OIDC provider of choice may have more specific documentation.
For example, the following policy uses variables to substitute the authenticated user's ``PreferredUsername`` as part of the ``Resource`` field such that the user can only access those prefixes which match their username:
.. code-block:: json
{
"Version": "2012-10-17",
"Statement": [
{
"Action": ["s3:ListBucket"],
"Effect": "Allow",
"Resource": ["arn:aws:s3:::mybucket"],
"Condition": {"StringLike": {"s3:prefix": ["${jwt:PreferredUsername}/*"]}}
},
{
"Action": [
"s3:GetObject",
"s3:PutObject"
],
"Effect": "Allow",
"Resource": ["arn:aws:s3:::mybucket/${jwt:PreferredUsername}/*"]
}
]
}
MinIO replaces the ``${jwt:PreferredUsername}`` variable in the ``Resource`` field with the value of the ``PreferredUsername`` in the JWT token.
MinIO then evaluates the policy and grants or revokes access to the requested API and resource.
.. end-minio-oidc-policy-variables

142
source/includes/container/steps-configure-keycloak-identity-management.rst Normal file
View File

@ -0,0 +1,142 @@
.. |KEYCLOAK_URL| replace:: localhost:8080
.. |MINIO_S3_URL| replace:: localhost:9000
.. |MINIO_CONSOLE_URL| replace:: localhost:9090
1) Create the Podman Pod
~~~~~~~~~~~~~~~~~~~~~~~~
Create a Podman Pod to deploy the Keycloak and MinIO containers in a Pod with shared networking.
This ensures both containers can communicate normally.
.. code-block:: shell
:class: copyable
podman pod create \
-p 9000:9000 -p 9090:9090 -p 8080:8080 \
-v ~/minio-keycloak/minio:/mnt/minio \
-n minio-keycloak
Replace ``~/minio-keycloak/minio`` with a path to an empty folder in which the MinIO container stores data.
You can alternatively deploy the Containers as Root to allow access to the host network for the purpose of inter-container networking.
Deploying via Docker Compose is out of scope for this tutorial.
2) Start the Keycloak Container
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Follow the instructions for running `Keycloak in a container <https://www.keycloak.org/server/containers>`__.
The `Try Keycloak in development mode <https://www.keycloak.org/server/containers#_trying_keycloak_in_development_mode>`__ steps are sufficient for this procedure.
.. code-block:: shell
:class: copyable
podman run -dt \
--name keycloak \
--pod minio-keycloak \
-e KEYCLOAK_ADMIN=keycloakadmin \
-e KEYCLOAK_ADMIN_PASSWORD=keycloakadmin123 \
quay.io/keycloak/keycloak:latest start-dev
Go to ``localhost:8080`` to access the Keycloak container.
3) Configure or Create a Client for Accessing Keycloak
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Authenticate to the Keycloak :guilabel:`Administrative Console` and navigate to :guilabel:`Clients`.
.. include:: /includes/common/common-configure-keycloak-identity-management.rst
:start-after: start-configure-keycloak-client
:end-before: end-configure-keycloak-client
4) Create Client Scope for MinIO Client
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Client scopes allow Keycloak to map user attributes as part of the JSON Web Token (JWT) returned in authentication requests.
This allows MinIO to reference those attributes when assigning policies to the user.
This step creates the necessary client scope to support MinIO authorization after successful Keycloak authentication.
.. include:: /includes/common/common-configure-keycloak-identity-management.rst
:start-after: start-configure-keycloak-client-scope
:end-before: end-configure-keycloak-client-scope
5) Apply the Necessary Attribute to Keycloak Users/Groups
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You must assign an attribute named ``policy`` to the Keycloak Users or Groups.
Set the value to any :ref:`policy <minio-policy>` on the MinIO deployment.
.. include:: /includes/common/common-configure-keycloak-identity-management.rst
:start-after: start-configure-keycloak-user-group-attributes
:end-before: end-configure-keycloak-user-group-attributes
6) Start the MinIO Container
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following command starts the MinIO Container and attaches it to the ``minio-keycloak`` pod.
.. code-block:: shell
:class: copyable
podman run -dt \
--name minio-server \
--pod minio-keycloak \
quay.io/minio/minio:RELEASE.2023-02-22T18-23-45Z server /mnt/data --console-address :9090
Go to ``localhost:9090`` to access the MinIO Console.
Log in using the default credentials ``minioadmin:minioadmin``.
7) Configure MinIO for Keycloak Authentication
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
MinIO supports multiple methods for configuring Keycloak authentication:
- Using the MinIO Console
- Using a terminal/shell and the :mc:`mc admin idp openid` command
- Using environment variables set prior to starting MinIO
.. tab-set::
.. tab-item:: MinIO Console
.. include:: /includes/common/common-configure-keycloak-identity-management.rst
:start-after: start-configure-keycloak-minio-console
:end-before: end-configure-keycloak-minio-console
.. tab-item:: CLI
.. include:: /includes/common/common-configure-keycloak-identity-management.rst
:start-after: start-configure-keycloak-minio-cli
:end-before: end-configure-keycloak-minio-cli
.. tab-item:: Environment Variables
.. include:: /includes/common/common-configure-keycloak-identity-management.rst
:start-after: start-configure-keycloak-minio-envvar
:end-before: end-configure-keycloak-minio-envvar
You must restart the MinIO deployment for the changes to apply.
Check the :ref:`MinIO server logs <minio-logging>` and verify that startup succeeded with no errors related to the Keycloak configuration.
If you attempt to log in with the Console, you should now see an (SSO) button using the configured :guilabel:`Display Name`.
Specify a configured user and attempt to log in.
MinIO should automatically redirect you to the Keycloak login entry.
Upon successful authentication, Keycloak should redirect you back to the MinIO Console.
8) Generate Application Credentials using the Security Token Service (STS)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-configure-keycloak-identity-management.rst
:start-after: start-configure-keycloak-sts
:end-before: end-configure-keycloak-sts
Next Steps
~~~~~~~~~~~~~
Applications should implement the :ref:`STS <minio-security-token-service>` flow using their :ref:`SDK <minio-drivers>` of choice.
When STS credentials expire, applications should have logic in place to regenerate the JWT token, STS token, and MinIO credentials before retrying and continuing operations.
Alternatively, users can generate :ref:`access keys <minio-id-access-keys>` through the MinIO Console for the purpose of creating long-lived API-key like access using their Keycloak credentials.

1
source/includes/k8s/steps-configure-ad-ldap-external-identity-management.rst
View File

@ -80,7 +80,6 @@ MinIO by default assigns no :ref:`policies <minio-policy>` to AD/LDAP users or g
You must explicitly assign MinIO policies to a given user or group Distinguished Name (DN) to grant that user or group access to the MinIO deployment. You must explicitly assign MinIO policies to a given user or group Distinguished Name (DN) to grant that user or group access to the MinIO deployment.
The following example assumes an existing :ref:`alias <alias>` configured for the MinIO Tenant. The following example assumes an existing :ref:`alias <alias>` configured for the MinIO Tenant.
See the :ref:`Deploy MinIO Tenant: Forward Ports <create-tenant-cli-forward-ports>` procedure for a basic example of granting network access to the MinIO tenant from your local host machine.
Use the :mc-cmd:`mc admin policy set` command to assign a user or group DN to an existing MinIO Policy: Use the :mc-cmd:`mc admin policy set` command to assign a user or group DN to an existing MinIO Policy:

143
source/includes/k8s/steps-configure-keycloak-identity-management.rst Normal file
View File

@ -0,0 +1,143 @@
.. |KEYCLOAK_URL| replace:: keycloak-service.keycloak-namespace.svc.cluster-domain.example
.. |MINIO_S3_URL| replace:: minio.minio-tenant.svc.cluster-domain.example
.. |MINIO_CONSOLE_URL| replace:: minio-console.minio-tenant.svc.cluster-domain.example
1) Configure or Create a Client for Accessing Keycloak
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Authenticate to the Keycloak :guilabel:`Administrative Console` and navigate to :guilabel:`Clients`.
.. include:: /includes/common/common-configure-keycloak-identity-management.rst
:start-after: start-configure-keycloak-client
:end-before: end-configure-keycloak-client
2) Create Client Scope for MinIO Client
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Client scopes allow Keycloak to map user attributes as part of the JSON Web Token (JWT) returned in authentication requests.
This allows MinIO to reference those attributes when assigning policies to the user.
This step creates the necessary client scope to support MinIO authorization after successful Keycloak authentication.
.. include:: /includes/common/common-configure-keycloak-identity-management.rst
:start-after: start-configure-keycloak-client-scope
:end-before: end-configure-keycloak-client-scope
3) Apply the Necessary Attribute to Keycloak Users/Groups
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You must assign an attribute named ``policy`` to the Keycloak Users or Groups.
Set the value to any :ref:`policy <minio-policy>` on the MinIO deployment.
.. include:: /includes/common/common-configure-keycloak-identity-management.rst
:start-after: start-configure-keycloak-user-group-attributes
:end-before: end-configure-keycloak-user-group-attributes
4) Configure MinIO for Keycloak Authentication
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
MinIO supports multiple methods for configuring Keycloak authentication:
- Using the MinIO Operator Console
- Using the MinIO Tenant Console
- Using a terminal/shell and the :mc:`mc admin idp openid` command
.. tab-set::
.. tab-item:: MinIO Operator Console
You can use the MinIO Operator Console to configure Keycloak as the External Identity Provider for the MinIO Tenant.
See :ref:`minio-operator-console-connect` for specific instructions.
Select :guilabel:`Identity Provider` from the left-hand navigation bar, then select :guilabel:`OpenID`.
Select :guilabel:`Create Configuration` to create a new configuration.
Enter the following information into the modal:
.. list-table::
:stub-columns: 1
:widths: 30 70
:width: 100%
* - :guilabel:`Name`
- Enter a unique name for the Keycloak instance
* - :guilabel:`Config URL`
- Specify the address of the Keycloak OpenID configuration document (|KEYCLOAK_URL|)
Ensure the ``REALM`` matches the Keycloak realm you want to use for authenticating users to MinIO
* - :guilabel:`Client ID`
- Specify the name of the Keycloak client created in Step 1
* - :guilabel:`Client Secret`
- Specify the secret credential value for the Keycloak client created in Step 1
* - :guilabel:`Display Name`
- Specify the user-facing name the MinIO Console should display as part of the Single-Sign On (SSO) workflow for the configured Keycloak service
* - :guilabel:`Scopes`
- Specify the OpenID scopes to include in the JWT, such as ``preferred_username`` or ``email``
You can reference these scopes using supported OpenID policy variables for the purpose of programmatic policy configurations
* - :guilabel:`Redirect URI Dynamic`
- Toggle to ``on``
Substitutes the MinIO Console address used by the client as part of the Keycloak redirect URI.
Keycloak returns authenticated users to the Console using the provided URI.
For MinIO Console deployments behind a reverse proxy, load balancer, or similar network control plane, you can instead use the :envvar:`MINIO_BROWSER_REDIRECT_URL` variable to set the redirect address for Keycloak to use.
Select :guilabel:`Save` to apply the configuration.
.. tab-item:: MinIO Tenant Console
You can use the MinIO Tenant Console to configure Keycloak as the External Identity Provider for the MinIO Tenant.
Access the Console service using the NodePort, Ingress, or Load Balancer endpoint.
You can use the following command to review the Console configuration:
.. code-block:: shell
:class: copyable
kubectl describe svc/TENANT_NAME-console -n TENANT_NAMESPACE
Replace ``TENANT_NAME`` and ``TENANT_NAMESPACE`` with the name of the MinIO Tenant and it's Namespace, respectively.
.. include:: /includes/common/common-configure-keycloak-identity-management.rst
:start-after: start-configure-keycloak-minio-console
:end-before: end-configure-keycloak-minio-console
Select :guilabel:`Save` to apply the configuration.
.. tab-item:: CLI
.. include:: /includes/common/common-configure-keycloak-identity-management.rst
:start-after: start-configure-keycloak-minio-cli
:end-before: end-configure-keycloak-minio-cli
Restart the MinIO deployment for the changes to apply.
Check the MinIO logs and verify that startup succeeded with no errors related to the OIDC configuration.
If you attempt to log in with the Console, you should now see an (SSO) button using the configured :guilabel:`Display Name`.
Specify a configured user and attempt to log in.
MinIO should automatically redirect you to the Keycloak login entry.
Upon successful authentication, Keycloak should redirect you back to the MinIO Console using either the originating Console URL *or* the :guilabel:`Redirect URI` if configured.
5) Generate Application Credentials using the Security Token Service (STS)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-configure-keycloak-identity-management.rst
:start-after: start-configure-keycloak-sts
:end-before: end-configure-keycloak-sts
Next Steps
~~~~~~~~~~
Applications should implement the :ref:`STS AssumeRoleWithWebIdentity <minio-sts-assumerolewithwebidentity>` flow using their :ref:`SDK <minio-drivers>` of choice.
When STS credentials expire, applications should have logic in place to regenerate the JWT token, STS token, and MinIO credentials before retrying and continuing operations.
Alternatively, users can generate :ref:`access keys <minio-id-access-keys>` through the MinIO Console for the purpose of creating long-lived API-key like access using their Keycloak credentials.

1
source/includes/k8s/steps-configure-openid-external-identity-management.rst
View File

@ -78,7 +78,6 @@ MinIO uses the specified user Claim to identify one or more policies to attach t
If the Claim is empty or specifies policies which do not exist on the deployment, the authenticated user has no permissions on the Tenant. If the Claim is empty or specifies policies which do not exist on the deployment, the authenticated user has no permissions on the Tenant.
The following example assumes an existing :ref:`alias <alias>` configured for the MinIO Tenant. The following example assumes an existing :ref:`alias <alias>` configured for the MinIO Tenant.
See the :ref:`Deploy MinIO Tenant: Forward Ports <create-tenant-cli-forward-ports>` procedure for a basic example of granting network access to the MinIO tenant from your local host machine.
Consider the following example policy that grants general S3 API access on only the ``data`` bucket: Consider the following example policy that grants general S3 API access on only the ``data`` bucket:

91
source/includes/linux/steps-configure-keycloak-identity-management.rst Normal file
View File

@ -0,0 +1,91 @@
.. |KEYCLOAK_URL| replace:: keycloak-url.example.net:8080
.. |MINIO_S3_URL| replace:: minio-url.example.net:9000
.. |MINIO_CONSOLE_URL| replace:: minio-url.example.net:9090
1) Configure or Create a Client for Accessing Keycloak
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Authenticate to the Keycloak :guilabel:`Administrative Console` and navigate to :guilabel:`Clients`.
.. include:: /includes/common/common-configure-keycloak-identity-management.rst
:start-after: start-configure-keycloak-client
:end-before: end-configure-keycloak-client
2) Create Client Scope for MinIO Client
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Client scopes allow Keycloak to map user attributes as part of the JSON Web Token (JWT) returned in authentication requests.
This allows MinIO to reference those attributes when assigning policies to the user.
This step creates the necessary client scope to support MinIO authorization after successful Keycloak authentication.
.. include:: /includes/common/common-configure-keycloak-identity-management.rst
:start-after: start-configure-keycloak-client-scope
:end-before: end-configure-keycloak-client-scope
3) Apply the Necessary Attribute to Keycloak Users/Groups
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You must assign an attribute named ``policy`` to the Keycloak Users or Groups.
Set the value to any :ref:`policy <minio-policy>` on the MinIO deployment.
.. include:: /includes/common/common-configure-keycloak-identity-management.rst
:start-after: start-configure-keycloak-user-group-attributes
:end-before: end-configure-keycloak-user-group-attributes
4) Configure MinIO for Keycloak Authentication
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
MinIO supports multiple methods for configuring Keycloak authentication:
- Using the MinIO Console
- Using a terminal/shell and the :mc:`mc admin idp openid` command
- Using environment variables set prior to starting MinIO
.. tab-set::
.. tab-item:: MinIO Console
.. include:: /includes/common/common-configure-keycloak-identity-management.rst
:start-after: start-configure-keycloak-minio-console
:end-before: end-configure-keycloak-minio-console
.. tab-item:: CLI
.. include:: /includes/common/common-configure-keycloak-identity-management.rst
:start-after: start-configure-keycloak-minio-cli
:end-before: end-configure-keycloak-minio-cli
.. tab-item:: Environment Variables
.. include:: /includes/common/common-configure-keycloak-identity-management.rst
:start-after: start-configure-keycloak-minio-envvar
:end-before: end-configure-keycloak-minio-envvar
Restart the MinIO deployment for the changes to apply.
Check the MinIO logs and verify that startup succeeded with no errors related to the OIDC configuration.
If you attempt to log in with the Console, you should now see an (SSO) button using the configured :guilabel:`Display Name`.
Specify a configured user and attempt to log in.
MinIO should automatically redirect you to the Keycloak login entry.
Upon successful authentication, Keycloak should redirect you back to the MinIO Console using either the originating Console URL *or* the :guilabel:`Redirect URI` if configured.
5) Generate Application Credentials using the Security Token Service (STS)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-configure-keycloak-identity-management.rst
:start-after: start-configure-keycloak-sts
:end-before: end-configure-keycloak-sts
Next Steps
~~~~~~~~~~
Applications should implement the :ref:`STS AssumeRoleWithWebIdentity <minio-sts-assumerolewithwebidentity>` flow using their :ref:`SDK <minio-drivers>` of choice.
When STS credentials expire, applications should have logic in place to regenerate the JWT token, STS token, and MinIO credentials before retrying and continuing operations.
Alternatively, users can generate :ref:`access keys <minio-id-access-keys>` through the MinIO Console for the purpose of creating long-lived API-key like access using their Keycloak credentials.

12
source/operations/external-iam.rst
View File

@ -10,14 +10,18 @@ External Identity Management
:local: :local:
:depth: 2 :depth: 2
MinIO supports offloading identity management onto one of the following supported IDentity Providers (IDP): MinIO supports multiple external identity managers through the following IDentity Providers (IDP):
- :ref:`OpenID Connect <minio-external-iam-oidc>` - :ref:`OpenID Connect-Compatible <minio-external-iam-oidc>`
- :ref:`Active Directory / LDAP <minio-external-iam-ad-ldap>` - :ref:`Active Directory / LDAP <minio-external-iam-ad-ldap>`
The following tutorials provide specific guidance for select IDP software:
The external :abbr:`IDP (IDentity Provider)` must have *at least* one configured user identity with the required :ref:`policy claims <minio-external-identity-management-ad-ldap-access-control>`. - :ref:`Configure MinIO Authentication with KeyCloak <minio-authenticate-using-keycloak>`
If no such user exists, the MinIO server is effectively inaccessible outside of using the :ref:`root <minio-users-root>` user.
Users can authenticate against MinIO using their externally managed credentials and the related :ref:`minio-security-token-service` API.
Once authenticated, MinIO attempts to associate the user with one or more configured :ref:`policies <minio-policy>`.
A user with no associated policies has no permissions on the MinIO deployment.
.. _minio-external-iam-oidc: .. _minio-external-iam-oidc:

266
source/operations/external-iam/configure-keycloak-identity-management.rst Normal file
View File

@ -0,0 +1,266 @@
.. _minio-authenticate-using-keycloak:
=================================================
Configure MinIO for Authentication using Keycloak
=================================================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 1
Overview
--------
This procedure configures MinIO to use `Keycloak <https://www.keycloak.org/>`__ as an external IDentity Provider (IDP) for authentication of users via the OpenID Connect (OIDC) protocol.
This procedure specifically covers the following steps:
.. cond:: k8s
- Configure Keycloak for use with MinIO authentication and authorization
- Configure a new or existing MinIO Tenant to use Keycloak as the OIDC provider
- Create policies to control access of Keycloak-authenticated users
- Log into the MinIO Tenant Console using SSO and a Keycloak-managed identity
- Generate temporary S3 access credentials using the ``AssumeRoleWithWebIdentity`` Security Token Service (STS) API
.. cond:: linux or macos or windows
- Configure Keycloak for use with MinIO authentication and authorization
- Configure a new or existing MinIO cluster to use Keycloak as the OIDC provider
- Create policies to control access of Keycloak-authenticated users
- Log into the MinIO Console using SSO and a Keycloak-managed identity
- Generate temporary S3 access credentials using the ``AssumeRoleWithWebIdentity`` Security Token Service (STS) API
.. cond:: container
- Deploy a Keycloak and MinIO Container
- Configure Keycloak for use with MinIO authentication and authorization
- Configure MinIO to use Keycloak as the OIDC provider
- Create policies to control access of Keycloak-authenticated users
- Log into the MinIO Console using SSO and a Keycloak-managed identity
- Generate temporary S3 access credentials using the ``AssumeRoleWithWebIdentity`` Security Token Service (STS) API
This procedure was written and tested against Keycloak ``21.0.0``.
The provided instructions may work against other Keycloak versions.
This procedure assumes you have prior experience with Keycloak and have reviewed `their documentation <https://www.keycloak.org/documentation>`__ for guidance and best practices in deploying, configuring, and managing the service.
Prerequisites
-------------
.. cond:: k8s
MinIO Kubernetes Operator and Plugin
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/k8s/common-operator.rst
:start-after: start-requires-operator-plugin
:end-before: end-requires-operator-plugin
MinIO Tenant
~~~~~~~~~~~~
This procedure assumes your Kubernetes cluster has sufficient resources to :ref:`deploy a new MinIO Tenant <minio-k8s-deploy-minio-tenant>`.
You can also use this procedure as guidance for modifying an existing MinIO Tenant to enable Keycloak Identity Management.
.. cond:: linux or container or macos or windows
MinIO Deployment
~~~~~~~~~~~~~~~~
This procedure assumes an existing MinIO cluster running the :minio-git:`latest stable MinIO version <minio/releases/latest>`.
Refer to the :ref:`minio-installation` for more complete documentation on new MinIO deployments.
This procedure *may* work as expected for older versions of MinIO.
.. cond:: not container
Keycloak Deployment and Realm Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This procedure assumes an existing Keycloak deployment to which you have administrative access.
Specifically, you must have permission to create and configure Realms, Clients, Client Scopes, Realm Roles, Users, and Groups on the Keycloak deployment.
.. cond:: k8s
For Keycloak deployments within the same Kubernetes cluster as the MinIO Tenant, this procedure assumes bidirectional access between the Keycloak and MinIO pods/services.
For Keycloak deployments external to the Kubernetes cluster, this procedure assumes an existing Ingress, Load Balancer, or similar Kubernetes network control component that manages network access to and from the MinIO Tenant.
.. cond:: not k8s
This procedure assumes bidirectional access between the Keycloak and MinIO deployments.
Install and Configure ``mc`` with Access to the MinIO Cluster
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This procedure uses :mc:`mc` for performing operations on the MinIO cluster.
Install ``mc`` on a machine with network access to the cluster.
.. cond:: k8s
Your local host must have access to the MinIO Tenant, such as through Ingress, a Load Balancer, or a similar Kubernetes network control component.
See the ``mc`` :ref:`Installation Quickstart <mc-install>` for instructions on downloading and installing ``mc``.
This procedure assumes a configured :mc:`alias <mc alias>` for the MinIO cluster.
.. _minio-external-identity-management-keycloak-configure:
Configure MinIO for Keycloak Identity Management
------------------------------------------------
.. cond:: linux or macos or windows
.. include:: /includes/linux/steps-configure-keycloak-identity-management.rst
.. cond:: k8s
.. include:: /includes/k8s/steps-configure-keycloak-identity-management.rst
.. cond:: container
.. include:: /includes/container/steps-configure-keycloak-identity-management.rst
Enable the Keycloak Admin REST API
----------------------------------
MinIO supports using the Keycloak Admin REST API for checking if an authenticated user exists *and* is enabled on the Keycloak realm.
This functionality allows MinIO to more quickly remove access from previously authenticated Keycloak users.
Without this functionality, the earliest point in time that MinIO could disable access for a disabled or removed user is when the last retrieved authentication token expires.
This procedure assumes an existing MinIO deployment configured with Keycloak as an external identity manager.
1) Create the Necessary Client Scopes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Navigate to the :guilabel:`Client scopes` view and create a new scope:
.. list-table::
:stub-columns: 1
:widths: 30 70
:width: 100%
* - :guilabel:`Name`
- Set to a recognizable name for the scope (``minio-admin-API-access``)
* - :guilabel:`Mappers`
- Select :guilabel:`Configure a new mapper`
* - :guilabel:`Audience`
- Set the :guilabel:`Name` to any recognizable name for the mapping (``minio-admin-api-access-mapper``)
* - :guilabel:`Included Client Audience`
- Set to ``security-admin-console``.
Navigate to :guilabel:`Clients` and select the MinIO client
1. From :guilabel:`Service account roles`, select :guilabel:`Assign role` and assign the ``admin`` role
2. From :guilabel:`Client scopes`, select :guilabel:`Add client scope` and add the previously created scope
Navigate to :guilabel:`Settings` and ensure :guilabel:`Authentication flow` includes ``Service accounts roles``.
2) Validate Admin API Access
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can validate the functionality by using the Admin REST API with the MinIO client credentials to retrieve a bearer token and user data:
1. Retrieve the bearer token:
.. code-block:: shell
:class: copyable
curl -d "client_id=minio" \
-d "client_secret=secretvalue" \
-d "grant_type=password" \
http://keycloak-url:port/admin/realms/REALM/protocol/openid-connect/token
2. Use the value returned as the ``access_token`` to access the Admin API:
.. code-block:: shell
:class: copyable
curl -H "Authentication: Bearer ACCESS_TOKEN_VALUE" \
http://keycloak-url:port/admin/realms/REALM/users/UUID
Replace ``UUID`` with the unique ID for the user which you want to retrieve.
The response should resemble the following:
.. code-block:: json
{
"id": "954de141-781b-4eaf-81bf-bf3751cdc5f2",
"createdTimestamp": 1675866684976,
"username": "minio-user-1",
"enabled": true,
"totp": false,
"emailVerified": false,
"firstName": "",
"lastName": "",
"attributes": {
"policy": [
"readWrite"
]
},
"disableableCredentialTypes": [],
"requiredActions": [],
"notBefore": 0,
"access": {
"manageGroupMembership": true,
"view": true,
"mapRoles": true,
"impersonate": true,
"manage": true
}
}
MinIO would revoke access for an authenticated user if the returned value has ``enabled: false`` or ``null`` (user was removed from Keycloak).
3) Enable Keycloak Admin Support on MinIO
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
MinIO supports multiple methods for configuring Keycloak Admin API Support:
- Using a terminal/shell and the :mc-cmd:`mc admin idp openid` command
- Using environment variables set prior to starting MinIO
.. tab-set::
.. tab-item:: CLI
You can use the :mc-cmd:`mc admin idp openid update` command to modify the configuration settings for an existing Keycloak service.
You can alternatively include the following configuration settings when setting up Keycloak for the first time.
The command takes all supported :ref:`OpenID Configuration Settings <minio-open-id-config-settings>`:
.. code-block:: shell
:class: copyable
mc admin idp openid update ALIAS KEYCLOAK_IDENTIFIER \
vendor="keycloak" \
keycloak_admin_url="https://keycloak-url:port/admin"
keycloak_realm="REALM"
- Replace ``KEYCLOAK_IDENTIFIER`` with the name of the configured Keycloak IDP.
You can use :mc-cmd:`mc admin idp openid list` to view all configured IDP configurations on the MinIO deployment
- Specify the Keycloak admin URL in the :mc-conf:`keycloak_admin_url <identity_openid.keycloak_admin_url>` configuration setting
- Specify the Keycloak Realm name in the :mc-conf:`keycloak_realm <identity_openid.keycloak_realm>`
.. tab-item:: Environment Variables
Set the following :ref:`environment variables <minio-server-envvar-external-identity-management-openid>` in the appropriate configuration location, such as ``/etc/default/minio``.
The following example code sets the minimum required environment variables related to enabling the Keycloak Admin API for an existing Keycloak configuration.
Replace the suffix ``_PRIMARY_IAM`` with the unique identifier for the target Keycloak configuration.
.. code-block:: shell
:class: copyable
MINIO_IDENTITY_OPENID_VENDOR_PRIMARY_IAM="keycloak"
MINIO_IDENTITY_OPENID_KEYCLOAK_ADMIN_URL_PRIMARY_IAM="https://keycloak-url:port/admin"
MINIO_IDENTITY_OPENID_KEYCLOAK_REALM_PRIMARY_IAM="REALM"
- Specify the Keycloak admin URL in the :envvar:`MINIO_IDENTITY_OPENID_KEYCLOAK_ADMIN_URL`
- Specify the Keycloak Realm name in the :envvar:`MINIO_IDENTITY_OPENID_KEYCLOAK_REALM`

22
source/operations/install-deploy-manage/minio-operator-console.rst
View File

@ -23,26 +23,12 @@ installs and configures the Operator Console.
This page summarizes the functions available with the MinIO Operator Console. This page summarizes the functions available with the MinIO Operator Console.
Use the :mc-cmd:`kubectl minio proxy` command to temporarily forward .. _minio-operator-console-connect:
traffic between the local host machine and the MinIO Operator Console:
.. code-block:: shell Connect to the Operator Console
:class: copyable -------------------------------
kubectl minio proxy .. include:: /includes/common/common-k8s-connect-operator-console.rst
The command returns output similar to the following:
.. code-block:: shell
Starting port forward of the Console UI.
To connect open a browser and go to http://localhost:9090
Current JWT to login: TOKEN
Open your browser to the specified URL and enter the JWT Token into the
login page.
Tenant Management Tenant Management
----------------- -----------------

146
source/reference/minio-mc-admin/mc-admin-config.rst
View File

@ -2213,6 +2213,8 @@ configuration settings.
.. mc-conf:: claim_name .. mc-conf:: claim_name
:delimiter: " " :delimiter: " "
*Optional*
.. include:: /includes/common-minio-external-auth.rst .. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-openid-claim-name :start-after: start-minio-openid-claim-name
:end-before: end-minio-openid-claim-name :end-before: end-minio-openid-claim-name
@ -2223,6 +2225,8 @@ configuration settings.
.. mc-conf:: claim_prefix .. mc-conf:: claim_prefix
:delimiter: " " :delimiter: " "
*Optional*
.. include:: /includes/common-minio-external-auth.rst .. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-openid-claim-prefix :start-after: start-minio-openid-claim-prefix
:end-before: end-minio-openid-claim-prefix :end-before: end-minio-openid-claim-prefix
@ -2230,6 +2234,15 @@ configuration settings.
This configuration setting corresponds with the This configuration setting corresponds with the
:envvar:`MINIO_IDENTITY_OPENID_CLAIM_PREFIX` environment variable. :envvar:`MINIO_IDENTITY_OPENID_CLAIM_PREFIX` environment variable.
.. mc-conf:: display_name
:delimiter: " "
*Optional*
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-openid-display-name
:end-before: end-minio-openid-display-name
.. mc-conf:: scopes .. mc-conf:: scopes
:delimiter: " " :delimiter: " "
@ -2245,7 +2258,6 @@ configuration settings.
*Optional* *Optional*
.. include:: /includes/common-minio-external-auth.rst .. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-openid-redirect-uri :start-after: start-minio-openid-redirect-uri
:end-before: end-minio-openid-redirect-uri :end-before: end-minio-openid-redirect-uri
@ -2253,6 +2265,66 @@ configuration settings.
This configuration setting corresponds with the This configuration setting corresponds with the
:envvar:`MINIO_IDENTITY_OPENID_REDIRECT_URI` environment variable. :envvar:`MINIO_IDENTITY_OPENID_REDIRECT_URI` environment variable.
.. mc-conf:: redirect_uri_dynamic
:delimiter: " "
*Optional*
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-openid-redirect-uri-dynamic
:end-before: end-minio-openid-redirect-uri-dynamic
This configuration setting corresponds with the :envvar:`MINIO_IDENTITY_OPENID_REDIRECT_URI_DYNAMIC` environment variable.
.. mc-conf:: claim_userinfo
:delimiter: " "
*Optional*
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-openid-claim-userinfo
:end-before: end-minio-openid-claim-userinfo
This configuration setting corresponds with the :envvar:`MINIO_IDENTITY_OPENID_CLAIM_USERINFO` environment variable.
.. mc-conf:: vendor
:delimiter: " "
*Optional*
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-openid-vendor
:end-before: end-minio-openid-vendor
This configuration setting corresponds with the :envvar:`MINIO_IDENTITY_OPENID_VENDOR` environment variable.
.. mc-conf:: keycloak_realm
:delimiter: " "
*Optional*
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-openid-keycloak-realm
:end-before: end-minio-openid-keycloak-realm
This configuration setting corresponds with the :envvar:`MINIO_IDENTITY_OPENID_KEYCLOAK_REALM` environment variable.
Requires :mc-conf:`identity_openid.vendor` set to ``keycloak``.
.. mc-conf:: keycloak_admin_url
:delimiter: " "
*Optional*
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-openid-keycloak-admin-url
:end-before: end-minio-openid-keycloak-admin-url
This configuration setting corresponds with the :envvar:`MINIO_IDENTITY_OPENID_KEYCLOAK_ADMIN_URL` environment variable.
Requires :mc-conf:`identity_openid.vendor` set to ``keycloak``.
.. mc-conf:: comment .. mc-conf:: comment
:delimiter: " " :delimiter: " "
@ -2263,3 +2335,75 @@ configuration settings.
This configuration setting corresponds with the This configuration setting corresponds with the
:envvar:`MINIO_IDENTITY_OPENID_COMMENT` environment variable. :envvar:`MINIO_IDENTITY_OPENID_COMMENT` environment variable.
.. _minio-identity-management-plugin-settings:
Identity Management Plugin
~~~~~~~~~~~~~~~~~~~~~~~~~~
The following section documents settings for enabling external identity management using the MinIO Identity Management Plugin.
See :ref:`minio-external-identity-management-plugin` for a tutorial on using these configuration settings.
.. mc-conf:: identity_plugin
The top-level configuration key for enabling :ref:`minio-external-identity-management-plugin`.
Use :mc-cmd:`mc admin config set` to set or update the configuration.
The :mc-conf:`~identity_plugin.url` and :mc-conf:`~identity_plugin.role_policy` arguments are *required*.
Specify additional optional arguments as a whitespace (``" "``)-delimited list.
.. code-block:: shell
:class: copyable
mc admin config set identity_plugin \
url="https://external-auth.example.net:8080/auth" \
role_policy="consoleAdmin" \
[ARGUMENT=VALUE] ... \
The :mc-conf:`identity_plugin` configuration key supports the following arguments:
.. mc-conf:: url
:delimiter: " "
*Required*
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-identity-management-plugin-url
:end-before: end-minio-identity-management-plugin-url
.. mc-conf:: role_policy
:delimiter: " "
*Required*
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-identity-management-role-policy
:end-before: end-minio-identity-management-role-policy
.. mc-conf:: token
:delimiter: " "
*Optional*
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-identity-management-auth-token
:end-before: end-minio-identity-management-auth-token
.. mc-conf:: role_id
:delimiter: " "
:debug:
*Optional*
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-identity-management-role-id
:end-before: end-minio-identity-management-role-id
.. mc-conf:: comment
:delimiter: " "
*Optional*
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-identity-management-comment
:end-before: end-minio-identity-management-comment

4
source/reference/minio-mc/mc-ping.rst
View File

@ -13,11 +13,11 @@
Syntax Syntax
------ ------
.. start-mc-pipe-desc .. start-mc-ping-desc
The :mc:`mc ping` command performs a liveness check on a specified target. The :mc:`mc ping` command performs a liveness check on a specified target.
.. end-mc-pipe-desc .. end-mc-ping-desc
.. tab-set:: .. tab-set::

107
source/reference/minio-server/minio-server.rst
View File

@ -2433,6 +2433,14 @@ identity management using an OpenID Connect (OIDC)-compatible provider. See
:mc-conf:`identity_openid claim_prefix :mc-conf:`identity_openid claim_prefix
<identity_openid.claim_prefix>` setting. <identity_openid.claim_prefix>` setting.
.. envvar:: MINIO_IDENTITY_OPENID_DISPLAY_NAME
*Optional*
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-openid-display-name
:end-before: end-minio-openid-display-name
.. envvar:: MINIO_IDENTITY_OPENID_SCOPES .. envvar:: MINIO_IDENTITY_OPENID_SCOPES
*Optional* *Optional*
@ -2457,6 +2465,60 @@ identity management using an OpenID Connect (OIDC)-compatible provider. See
:mc-conf:`identity_openid scopes :mc-conf:`identity_openid scopes
<identity_openid.redirect_uri>` setting. <identity_openid.redirect_uri>` setting.
.. envvar:: MINIO_IDENTITY_OPENID_REDIRECT_URI_DYNAMIC
*Optional*
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-openid-redirect-uri-dynamic
:end-before: end-minio-openid-redirect-uri-dynamic
This environment variable corresponds with the :mc-conf:`identity_openid redirect_uri_dynamic <identity_openid.redirect_uri_dynamic>` setting.
.. envvar:: MINIO_IDENTITY_OPENID_CLAIM_USERINFO
*Optional*
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-openid-claim-userinfo
:end-before: end-minio-openid-claim-userinfo
This environment variable corresponds with the :mc-conf:`identity_openid claim_userinfo <identity_openid.claim_userinfo>` setting.
.. envvar:: MINIO_IDENTITY_OPENID_VENDOR
*Optional*
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-openid-vendor
:end-before: end-minio-openid-vendor
This environment variable corresponds with the :mc-conf:`identity_openid vendor <identity_openid.vendor>` setting.
.. envvar:: MINIO_IDENTITY_OPENID_KEYCLOAK_REALM
*Optional*
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-openid-keycloak-realm
:end-before: end-minio-openid-keycloak-realm
This environment variable corresponds with the :mc-conf:`identity_openid keycloak_realm <identity_openid.keycloak_realm>` setting.
Requires :envvar:`MINIO_IDENTITY_OPENID_VENDOR` set to ``keycloak``.
.. envvar:: MINIO_IDENTITY_OPENID_KEYCLOAK_ADMIN_URL
*Optional*
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-openid-keycloak-admin-url
:end-before: end-minio-openid-keycloak-admin-url
This environment variable corresponds with the :mc-conf:`identity_openid keycloak_admin_url <identity_openid.keycloak_admin_url>` setting.
Requires :envvar:`MINIO_IDENTITY_OPENID_VENDOR` set to ``keycloak``.
.. envvar:: MINIO_IDENTITY_OPENID_COMMENT .. envvar:: MINIO_IDENTITY_OPENID_COMMENT
@ -2470,6 +2532,51 @@ identity management using an OpenID Connect (OIDC)-compatible provider. See
:mc-conf:`identity_openid comment :mc-conf:`identity_openid comment
<identity_openid.comment>` setting. <identity_openid.comment>` setting.
.. _minio-server-envvar-external-identity-management-plugin:
MinIO Identity Management Plugin
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. envvar:: MINIO_IDENTITY_PLUGIN_URL
*Required*
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-identity-management-plugin-url
:end-before: end-minio-identity-management-plugin-url
.. envvar:: MINIO_IDENTITY_PLUGIN_ROLE_POLICY
*Required*
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-identity-management-role-policy
:end-before: end-minio-identity-management-role-policy
.. envvar:: MINIO_IDENTITY_PLUGIN_TOKEN
*Optional*
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-identity-management-auth-token
:end-before: end-minio-identity-management-auth-token
.. envvar:: MINIO_IDENTITY_PLUGIN_ROLE_ID
*Optional*
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-identity-management-role-id
:end-before: end-minio-identity-management-role-id
.. envvar:: MINIO_IDENTITY_PLUGIN_COMMENT
*Optional*
.. include:: /includes/common-minio-external-auth.rst
:start-after: start-minio-identity-management-comment
:end-before: end-minio-identity-management-comment
Batch Replication Batch Replication
~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~