mirror of
https://github.com/minio/docs.git
synced 2025-07-31 18:04:52 +03:00
DOCS-476: OIDC, Keycloak, Dex, and Policy Variables (#735)
This commit is contained in:
Ravind Kumar
GitHub
@ -56,6 +56,12 @@ Defaults to ``policy``.
|
||||
|
||||
.. 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
|
||||
|
||||
Specify the
|
||||
@ -74,33 +80,70 @@ Defaults to those scopes advertised in the discovery document.
|
||||
|
||||
.. start-minio-openid-redirect-uri
|
||||
|
||||
Specify the redirect URI the MinIO Console uses when authenticating against the
|
||||
configured provider. Include the console port and ``/oauth_callback``
|
||||
as part of the URL:
|
||||
.. important::
|
||||
|
||||
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
|
||||
|
||||
http://minio.example.net:consoleport/oauth_callback
|
||||
|
||||
MinIO defaults to using the hostname of the node making the authentication
|
||||
request. MinIO deployments behind a load balancer or reverse proxy *may*
|
||||
need to specify this field to ensure the OIDC provider returns the
|
||||
authentication response to the correct URL.
|
||||
Ensure you start the MinIO Server with the :mc-cmd:`~minio server --console-address` option to set a static Console listen port.
|
||||
The default behavior with that option omitted is to select a random port number at startup.
|
||||
|
||||
The specified URI *must* match one of the approved
|
||||
redirect / callback URIs on the provider. See the OpenID `Authentication Request
|
||||
<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.
|
||||
The specified URI *must* match one of the approved redirect / callback URIs on the provider.
|
||||
See the OpenID `Authentication Request <https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest>`__ for more information.
|
||||
|
||||
.. 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
|
||||
|
||||
Specify a comment to associate with the :abbr:`OIDC (OpenID Connect)` compatible
|
||||
@ -271,4 +314,39 @@ Defaults to ``off``
|
||||
|
||||
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
|
||||
@ -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
|
||||
@ -1,81 +1,77 @@
|
||||
.. tab-set::
|
||||
.. dropdown:: Port Forwarding
|
||||
:open:
|
||||
|
||||
.. tab-item:: Port Forwarding
|
||||
.. 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.
|
||||
|
||||
.. note::
|
||||
|
||||
Some Kubernetes deployments may experience issues with timeouts during port-forwarding operations with the Operator Console.
|
||||
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 the :ref:`MinIO Operator Console <minio-operator-console>` service to your local machine:
|
||||
|
||||
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:
|
||||
|
||||
.. 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.
|
||||
.. cond:: k8s and not openshift
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
kubectl get svc/console -n minio-operator -o json | jq -r '.spec.ports'
|
||||
kubectl minio proxy
|
||||
|
||||
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:
|
||||
.. cond:: openshift
|
||||
|
||||
.. code-block:: shell
|
||||
: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
112
source/includes/common/common-minio-oidc.rst
Normal 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
|
||||
|
||||
@ -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.
|
||||
@ -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.
|
||||
|
||||
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:
|
||||
|
||||
|
||||
@ -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.
|
||||
@ -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.
|
||||
|
||||
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:
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user