mirror of
https://github.com/minio/docs.git
synced 2025-07-30 07:03:26 +03:00
Adds information about role policy and roleARN for OpenID docs. (#983)
Closes #933 - Adds envvar and config param - Adds Role Policy openID authentication flow
This commit is contained in:
Daryl White
GitHub
@ -15,33 +15,78 @@ MinIO supports using an OpenID Connect (OIDC) compatible IDentity Provider (IDP)
|
||||
such as Okta, KeyCloak, Dex, Google, or Facebook for external management of user
|
||||
identities.
|
||||
|
||||
For identities managed by the external OpenID Connect (OIDC) compatible provider, MinIO uses the `JSON Web Token claim <https://datatracker.ietf.org/doc/html/rfc7519#section-4>`__ returned as part of the OIDC authentication flow to identify the :ref:`policies <minio-policy>` to assign to the authenticated user.
|
||||
For identities managed by the external OpenID Connect (OIDC) compatible provider, MinIO can use either of two methods to assign policies to the authenticated user.
|
||||
|
||||
1. Use the `JSON Web Token claim <https://datatracker.ietf.org/doc/html/rfc7519#section-4>`__ returned as part of the OIDC authentication flow to identify the :ref:`policies <minio-policy>` to assign to the authenticated user.
|
||||
2. Use the ``RoleARN`` specified in the authorization request to assign the policies attached to the provider's RolePolicy.
|
||||
|
||||
MinIO by default denies access to all actions or resources not explicitly allowed by a user's assigned or inherited :ref:`policies <minio-policy>`.
|
||||
Users managed by an OIDC provider must specify the necessary policies as part of the JWT claim. If the user JWT claim has no matching MinIO policies, that user has no permissions to access any action or resource on the MinIO deployment.
|
||||
|
||||
The specific claim which MinIO looks for is configured as part of :ref:`deploying the cluster with OIDC identity management <minio-external-iam-oidc>`. This page focuses on creating MinIO policies to match the configured OIDC claims.
|
||||
|
||||
Authentication and Authorization Flow
|
||||
Authentication and Authorization Flow
|
||||
-------------------------------------
|
||||
|
||||
MinIO supports two OIDC authentication and authorization flows:
|
||||
|
||||
1. The RolePolicy flow sets the assigned policies for an authenticated user in the MinIO configuration.
|
||||
|
||||
MinIO recommends using the RolePolicy method for authenticating with an OpenID provider.
|
||||
|
||||
2. The JWT flow sets the assigned policies for an authenticated user as part of the OIDC configuration.
|
||||
|
||||
MinIO supports multiple OIDC provider configurations.
|
||||
However, you can configure only **one** JWT claim-based OIDC provider per deployment.
|
||||
All other providers must use RolePolicy.
|
||||
|
||||
RolePolicy and RoleARN
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
With a RolePolicy, all clients which generate an STS credential using a given RoleARN receive the :ref:`policy or policies <minio-policy>` associated to the RolePolicy configuration for that RoleARN.
|
||||
|
||||
You can use :ref:`OpenID Policy Variables <minio-policy-variables-oidc>` to create policies that programmatically manage what each individual user has access to.
|
||||
|
||||
The login flow for an application using :abbr:`OIDC (OpenID Connect)` credentials with a RolePolicy claim flow is as follows:
|
||||
|
||||
1. Create an OIDC Configuration.
|
||||
2. Record the RoleARN assigned to the configuration either at time of creation or at MinIO start.
|
||||
Use this RoleARN with the :ref:`AssumeRoleWithWebIdentity <minio-sts-assumerolewithwebidentit>` STS API.
|
||||
3. Create a RolePolicy to use with the RoleARN.
|
||||
Use either the :envvar:`MINIO_IDENTITY_OPENID_ROLE_POLICY` environment variable or the :mc-conf:`identity_openid role_policy <identity_openid.role_policy>` configuration setting to define the list of policies to use for the provider
|
||||
4. Users select the configured OIDC provider when logging in to MinIO.
|
||||
5. Users complete authentication to the configured :abbr:`OIDC (OpenID Connect)` provider and redirect back to MinIO.
|
||||
|
||||
MinIO only supports the `OpenID Authorization Code Flow <https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth>`__.
|
||||
Authentication using Implicit Flow is not supported.
|
||||
|
||||
6. MinIO verifies the ``RoleARN`` in the API call and checks for the :ref:`RolePolicy <minio-external-identity-management-openid-access-control>` to use.
|
||||
Any authentication request with the RoleARN receives the same policy access permissions.
|
||||
7. MinIO returns temporary credentials in the STS API response in the form of an access key, secret key, and session token.
|
||||
The credentials have permissions matching those policies specified in the RolePolicy.
|
||||
|
||||
8. Applications use the temporary credentials returned by the STS endpoint to perform authenticated S3 operations on MinIO.
|
||||
|
||||
|
||||
JSON Web Token Claim
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Using JSON Web Tokens allows you to have individual assignment of policies.
|
||||
However, the use of web tokens also comes at the increased cost of managing multiple policies for separate claims.
|
||||
|
||||
The login flow for an application using :abbr:`OIDC (OpenID Connect)`
|
||||
credentials is as follows:
|
||||
credentials with a JSON Web Token Claim flow is as follows:
|
||||
|
||||
1. Authenticate to the configured :abbr:`OIDC (OpenID Connect)`
|
||||
provider and retrieve a
|
||||
`JSON Web Token (JWT) <https://jwt.io/introduction>`__.
|
||||
provider and retrieve a `JSON Web Token (JWT) <https://jwt.io/introduction>`__.
|
||||
|
||||
MinIO only supports the
|
||||
`OpenID Authorization Code Flow
|
||||
<https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth>`__.
|
||||
MinIO only supports the `OpenID Authorization Code Flow <https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth>`__.
|
||||
Authentication using Implicit Flow is not supported.
|
||||
|
||||
2. Specify the :abbr:`JWT (JSON Web Token)` to the MinIO Security Token Service
|
||||
(STS) :ref:`minio-sts-assumerolewithwebidentity` API endpoint.
|
||||
|
||||
MinIO verifies the :abbr:`JWT (JSON Web Token)` against the
|
||||
configured OIDC provider.
|
||||
MinIO verifies the :abbr:`JWT (JSON Web Token)` against the configured OIDC provider.
|
||||
|
||||
If the JWT is valid, MinIO checks for a :ref:`claim
|
||||
<minio-external-identity-management-openid-access-control>` specifying a list
|
||||
@ -55,9 +100,7 @@ credentials is as follows:
|
||||
4. Applications use the temporary credentials returned by the STS endpoint to
|
||||
perform authenticated S3 operations on MinIO.
|
||||
|
||||
MinIO provides an example Go application
|
||||
:minio-git:`web-identity.go <minio/blob/master/docs/sts/web-identity.go>` that
|
||||
handles the full login flow.
|
||||
MinIO provides an example Go application :minio-git:`web-identity.go <minio/blob/master/docs/sts/web-identity.go>` that handles the full login flow.
|
||||
|
||||
OIDC users can alternatively create :ref:`access keys <minio-idp-service-account>`.
|
||||
Access Keys are long-lived credentials which inherit their privileges from the parent user.
|
||||
@ -66,7 +109,7 @@ To create a new access key, log into the :ref:`MinIO Console <minio-console>` us
|
||||
From the :guilabel:`Identity` section of the left navigation, select :guilabel:`Access Keys` followed by the :guilabel:`Create access keys +` button.
|
||||
|
||||
Identifying the JWT Claim Value
|
||||
-------------------------------
|
||||
+++++++++++++++++++++++++++++++
|
||||
|
||||
MinIO uses the JWT token returned as part of the OIDC authentication flow to identify the specific policies to assign to the authenticated user.
|
||||
|
||||
|
||||
@ -48,6 +48,8 @@ cluster:
|
||||
&DurationSeconds=86000
|
||||
&Policy={}
|
||||
|
||||
.. _minio-assumerolewithwebidentity-query-parameters:
|
||||
|
||||
Request Query Parameters
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
@ -117,6 +119,18 @@ This endpoint supports the following query parameters:
|
||||
See :ref:`minio-access-management` for more information on MinIO
|
||||
authentication and authorization.
|
||||
|
||||
* - ``RoleARN``
|
||||
- string
|
||||
- *Optional*
|
||||
|
||||
The role Amazon Resource Number (ARN) to use for all user authentication requests.
|
||||
If used, there must be a matching OIDC RolePolicy defined for the RoleARN's provider by the ``role_policy`` configuration parameter or the ``MINIO_IDENTITY_OPENID_ROLE_POLICY`` environment variable.
|
||||
|
||||
When used, all valid authorization requests assume the same set of permissions provided by the RolePolicy.
|
||||
You can use :ref:`OpenID Policy Variables <minio-policy-variables-oidc>` to create policies that programmatically manage what each individual user has access to.
|
||||
|
||||
If you do not supply a RoleARN, MinIO attempts to authorize through a JWT-based claim.
|
||||
|
||||
Response Elements
|
||||
-----------------
|
||||
|
||||
|
||||
@ -24,6 +24,17 @@ may be optional depending on the provider.
|
||||
|
||||
.. end-minio-openid-client-secret
|
||||
|
||||
|
||||
.. start-minio-openid-role-policy
|
||||
|
||||
Specify a comma-separated list of :ref:`policy names <minio-policy>` to use for the request's ``RoleARN`` for all authentication requests for the provider.
|
||||
The specified policy or policies must already exist on the MinIO Server.
|
||||
|
||||
To use this OIDC configuration, you must specify the corresponding :ref:`RoleARN <minio-assumerolewithwebidentity-query-parameters>` in the STS request body.
|
||||
|
||||
.. end-minio-openid-role-policy
|
||||
|
||||
|
||||
.. start-minio-openid-jwks-url
|
||||
|
||||
Specify the URL for the JSON Web Key Set (JWKS) for MinIO to use when verifying
|
||||
|
||||
@ -2466,6 +2466,18 @@ configuration settings.
|
||||
|
||||
This configuration setting corresponds with the :envvar:`MINIO_IDENTITY_OPENID_CLIENT_SECRET` environment variable.
|
||||
|
||||
.. mc-conf:: role_policy
|
||||
:delimiter: " "
|
||||
|
||||
*Optional*
|
||||
|
||||
.. include:: /includes/common-minio-external-auth.rst
|
||||
:start-after: start-minio-openid-role-policy
|
||||
:end-before: end-minio-openid-role-policy
|
||||
|
||||
This configuration setting corresponds with the :envvar:`MINIO_IDENTITY_OPENID_ROLE_POLICY` environment variable.
|
||||
This setting is mutually exclusive with the :mc-conf:`identity_openid claim_name <identity_openid.claim_name>` configuration setting.
|
||||
|
||||
.. mc-conf:: claim_name
|
||||
:delimiter: " "
|
||||
|
||||
@ -2476,7 +2488,8 @@ configuration settings.
|
||||
:end-before: end-minio-openid-claim-name
|
||||
|
||||
This configuration setting corresponds with the :envvar:`MINIO_IDENTITY_OPENID_CLAIM_NAME` environment variable.
|
||||
|
||||
This setting is mutually exclusive with the :mc-conf:`identity_openid role_policy <identity_openid.role_policy>` configuration setting.
|
||||
|
||||
.. mc-conf:: claim_prefix
|
||||
:delimiter: " "
|
||||
|
||||
|
||||
@ -2451,7 +2451,7 @@ endpoints as ``PRIMARY`` and ``SECONDARY`` respectively:
|
||||
.. _minio-server-envvar-object-lambda-webhook:
|
||||
|
||||
Object Lambda
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
The following section documents environment variables for configuring MinIO to publish data to an HTTP webhook endpoint and trigger an Object Lambda function.
|
||||
See :ref:`developers-object-lambda` for more complete documentation and tutorials on using these environment variables.
|
||||
@ -2667,6 +2667,17 @@ identity management using an OpenID Connect (OIDC)-compatible provider. See
|
||||
|
||||
This environment variable corresponds with the :mc-conf:`identity_openid client_secret <identity_openid.client_secret>` configuration setting.
|
||||
|
||||
.. envvar:: MINIO_IDENTITY_OPENID_ROLE_POLICY
|
||||
|
||||
*Optional*
|
||||
|
||||
.. include:: /includes/common-minio-external-auth.rst
|
||||
:start-after: start-minio-openid-role-policy
|
||||
:end-before: end-minio-openid-role-policy
|
||||
|
||||
This environment variable corresponds with the :mc-conf:`identity_openid role_policy <identity_openid.role_policy>` configuration setting.
|
||||
This variable is mutually exclusive with the :envvar:`MINIO_IDENTITY_OPENID_CLAIM_NAME` environment variable.
|
||||
|
||||
.. envvar:: MINIO_IDENTITY_OPENID_CLAIM_NAME
|
||||
|
||||
*Optional*
|
||||
@ -2676,6 +2687,8 @@ identity management using an OpenID Connect (OIDC)-compatible provider. See
|
||||
:end-before: end-minio-openid-claim-name
|
||||
|
||||
This environment variable corresponds with the :mc-conf:`identity_openid claim_name <identity_openid.claim_name>` configuration setting.
|
||||
This variable is mutually exclusive with the :envvar:`MINIO_IDENTITY_OPENID_ROLE_POLICY` environment variable.
|
||||
|
||||
|
||||
.. envvar:: MINIO_IDENTITY_OPENID_CLAIM_PREFIX
|
||||
|
||||
|
||||
Reference in New Issue
Block a user