diff --git a/source/includes/common-minio-external-auth.rst b/source/includes/common-minio-external-auth.rst index f2f3949a..62949cc9 100644 --- a/source/includes/common-minio-external-auth.rst +++ b/source/includes/common-minio-external-auth.rst @@ -12,6 +12,14 @@ credentials against the :abbr:`OIDC (OpenID Connect)` compatible provider. .. end-minio-openid-client-id +.. start-minio-openid-client-secret + +Specify the client secret MinIO uses when authenticating user credentials +against the :abbr:`OIDC (OpenID Connect)` compatible provider. This field +may be optional depending on the provider. + +.. end-minio-openid-client-secret + .. start-minio-openid-jwks-url Specify the URL for the JSON Web Key Set (JWKS) for MinIO to use when verifying @@ -64,6 +72,35 @@ Defaults to those scopes advertised in the discovery document. .. end-minio-openid-scopes +.. 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: + +.. 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. + +The specified URI *must* match one of the approved +redirect / callback URIs on the provider. See the OpenID `Authentication Request +`__ 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-option:`~minio server console-address` option to specify a static + port number. + +.. end-minio-openid-redirect-uri + .. start-minio-openid-comment Specify a comment to associate with the :abbr:`OIDC (OpenID Connect)` compatible diff --git a/source/reference/minio-cli/minio-mc-admin/mc-admin-policy.rst b/source/reference/minio-cli/minio-mc-admin/mc-admin-policy.rst index 8cb30466..87e435c8 100644 --- a/source/reference/minio-cli/minio-mc-admin/mc-admin-policy.rst +++ b/source/reference/minio-cli/minio-mc-admin/mc-admin-policy.rst @@ -49,7 +49,7 @@ Consider the following JSON policy document: "s3:ListAllMyBuckets" ], "Resource": [ - "arn:minio:s3:::*" + "arn:aws:s3:::*" ] } ] diff --git a/source/reference/minio-cli/minio-mc-admin/mc-admin.config.rst b/source/reference/minio-cli/minio-mc-admin/mc-admin.config.rst index b5e36c6d..49d9a6f2 100644 --- a/source/reference/minio-cli/minio-mc-admin/mc-admin.config.rst +++ b/source/reference/minio-cli/minio-mc-admin/mc-admin.config.rst @@ -1949,14 +1949,19 @@ configuration settings. - :mc-conf:`~identity_ldap.server_addr` - :mc-conf:`~identity_ldap.lookup_bind_dn` + - :mc-conf:`~identity_ldap.lookup_bind_password` + - :mc-conf:`~identity_ldap.user_dn_search_base_dn` + - :mc-conf:`~identity_ldap.user_dn_search_filter` .. code-block:: shell :class: copyable mc admin config set identity_ldap \ server_addr="https://ad-ldap.example.net/" \ - lookup_bind_dn="cn=miniolookupuser,dc=ldapserver,dc=com" - lookUP-bind_dn_password="userpassword" + lookup_bind_dn="cn=miniolookupuser,dc=example,dc=net" \ + lookup_bind_dn_password="userpassword" \ + user_dn_search_base_dn="dc=example,dc=net" \ + user_dn_search_filter="(&(objectCategory=user)(sAMAccountName=%s))" The :mc-conf:`identity_ldap` configuration key supports the following arguments: @@ -2000,7 +2005,7 @@ configuration settings. .. mc-conf:: lookup_bind_password :delimiter: " " - *Optional* + *Required* .. include:: /includes/common-minio-external-auth.rst :start-after: start-minio-ad-ldap-lookup-bind-password @@ -2012,7 +2017,7 @@ configuration settings. .. mc-conf:: user_dn_search_base_dn :delimiter: " " - *Optional* + *Required* .. include:: /includes/common-minio-external-auth.rst :start-after: start-minio-ad-ldap-user-dn-search-base-dn @@ -2024,7 +2029,7 @@ configuration settings. .. mc-conf:: user_dn_search_filter :delimiter: " " - *Optional* + *Required* .. include:: /includes/common-minio-external-auth.rst :start-after: start-minio-ad-ldap-user-dn-search-filter @@ -2165,6 +2170,16 @@ configuration settings. This configuration setting corresponds with the :envvar:`MINIO_IDENTITY_OPENID_CLIENT_ID` environment variable. + + .. mc-conf:: client_secret + :delimiter: " " + + .. include:: /includes/common-minio-external-auth.rst + :start-after: start-minio-openid-client-secret + :end-before: end-minio-openid-client-secret + + This configuration setting corresponds with the + :envvar:`MINIO_IDENTITY_OPENID_CLIENT_SECRET` environment variable. .. mc-conf:: claim_name :delimiter: " " @@ -2196,6 +2211,19 @@ configuration settings. This configuration setting corresponds with the :envvar:`MINIO_IDENTITY_OPENID_SCOPES` environment variable. + .. mc-conf:: redirect_uri + :delimiter: " " + + *Optional* + + + .. include:: /includes/common-minio-external-auth.rst + :start-after: start-minio-openid-redirect-uri + :end-before: end-minio-openid-redirect-uri + + This configuration setting corresponds with the + :envvar:`MINIO_IDENTITY_OPENID_REDIRECT_URI` environment variable. + .. mc-conf:: comment :delimiter: " " diff --git a/source/reference/minio-server/minio-server.rst b/source/reference/minio-server/minio-server.rst index fa434c01..717e1829 100644 --- a/source/reference/minio-server/minio-server.rst +++ b/source/reference/minio-server/minio-server.rst @@ -2326,6 +2326,18 @@ identity management using an OpenID Connect (OIDC)-compatible provider. See :mc-conf:`identity_openid client_id ` setting. +.. envvar:: MINIO_IDENTITY_OPENID_CLIENT_SECRET + + *Optional* + + .. include:: /includes/common-minio-external-auth.rst + :start-after: start-minio-openid-client-secret + :end-before: end-minio-openid-client-secret + + This environment variable corresponds with the + :mc-conf:`identity_openid client_secret + ` setting. + .. envvar:: MINIO_IDENTITY_OPENID_CLAIM_NAME *Optional* @@ -2362,6 +2374,19 @@ identity management using an OpenID Connect (OIDC)-compatible provider. See :mc-conf:`identity_openid scopes ` setting. +.. envvar:: MINIO_IDENTITY_OPENID_REDIRECT_URI + + *Optional* + + .. include:: /includes/common-minio-external-auth.rst + :start-after: start-minio-openid-redirect-uri + :end-before: end-minio-openid-redirect-uri + + This environment variable corresponds with the + :mc-conf:`identity_openid scopes + ` setting. + + .. envvar:: MINIO_IDENTITY_OPENID_COMMENT *Optional* diff --git a/source/security/ad-ldap-external-identity-management/configure-ad-ldap-external-identity-management.rst b/source/security/ad-ldap-external-identity-management/configure-ad-ldap-external-identity-management.rst index 37431ccd..5e134e16 100644 --- a/source/security/ad-ldap-external-identity-management/configure-ad-ldap-external-identity-management.rst +++ b/source/security/ad-ldap-external-identity-management/configure-ad-ldap-external-identity-management.rst @@ -38,6 +38,13 @@ MinIO requires a read-only service account with which it :ref:`binds ` to perform authenticated user and group queries. +Ensure each AD/LDAP user and group intended for use with MinIO has a +corresponding :ref:`policy +` on the MinIO +deployment. An AD/LDAP user with no assigned policy *and* with membership in +groups with no assigned policy has no permission to access any action or +resource on the MinIO cluster. + MinIO Cluster ~~~~~~~~~~~~~ @@ -88,10 +95,17 @@ environment variables and configuration settings respectively: - :envvar:`MINIO_IDENTITY_LDAP_SERVER_ADDR` - :envvar:`MINIO_IDENTITY_LDAP_LOOKUP_BIND_DN` - :envvar:`MINIO_IDENTITY_LDAP_LOOKUP_BIND_PASSWORD` + - :envvar:`MINIO_IDENTITY_LDAP_USER_DN_SEARCH_BASE_DN` + - :envvar:`MINIO_IDENTITY_LDAP_USER_DN_SEARCH_FILTER` .. code-block:: shell :class: copyable + export MINIO_IDENTITY_LDAP_SERVER_ADDR="ldaps.example.net:636" + export MINIO_IDENTITY_LDAP_LOOKUP_BIND_DN="CN=xxxxx,OU=xxxxx,OU=xxxxx,DC=example,DC=net" + export MINIO_IDENTITY_LDAP_USER_DN_SEARCH_BASE_DN="dc=example,dc=net" + export MINIO_IDENTITY_LDAP_USER_DN_SEARCH_FILTER="(&(objectCategory=user)(sAMAccountName=%s))" + export MINIO_IDENTITY_LDAP_LOOKUP_BIND_PASSWORD="xxxxxxxxx" For complete documentation on these variables, see :ref:`minio-server-envvar-external-identity-management-ad-ldap` @@ -113,11 +127,20 @@ environment variables and configuration settings respectively: - :mc-conf:`identity_ldap lookup_bind_dn ` - :mc-conf:`identity_ldap lookup_bind_password ` + + - :mc-conf:`identity_ldap user_dn_search_base_dn ` + + - :mc-conf:`identity_ldap user_dn_search_filter ` .. code-block:: shell :class: copyable mc admin config set ALIAS/ identity_ldap \ + server_addr="ldaps.example.net:636" \ + lookup_bind_dn="CN=xxxxx,OU=xxxxx,OU=xxxxx,DC=example,DC=net" \ + lookup_bind_password="xxxxxxxx" \ + user_dn_search_base_dn="DC=example,DC=net" \ + user_dn_search_filter="(&(objectCategory=user)(sAMAccountName=%s))" For more complete documentation on these settings, see :mc-conf:`identity_ldap`. diff --git a/source/security/ad-ldap-external-identity-management/external-authentication-with-ad-ldap-identity-provider.rst b/source/security/ad-ldap-external-identity-management/external-authentication-with-ad-ldap-identity-provider.rst index 1cbd4cc2..01950d11 100644 --- a/source/security/ad-ldap-external-identity-management/external-authentication-with-ad-ldap-identity-provider.rst +++ b/source/security/ad-ldap-external-identity-management/external-authentication-with-ad-ldap-identity-provider.rst @@ -229,9 +229,10 @@ configuration settings required for enabling group lookups: - :envvar:`MINIO_IDENTITY_LDAP_GROUP_SEARCH_BASE_DN` - :envvar:`MINIO_IDENTITY_LDAP_GROUP_SEARCH_FILTER` - See the :ref:`` reference documentation for more information on these - variables. The :ref:`` tutorial includes complete instructions on - setting these values. + See the :ref:`minio-server-envvar-external-identity-management-ad-ldap` + reference documentation for more information on these variables. The + :ref:`minio-authenticate-using-openid-generic` tutorial includes complete + instructions on setting these values. .. tab:: Configuration Setting @@ -240,8 +241,9 @@ configuration settings required for enabling group lookups: - :mc-conf:`identity_ldap group_search_filter ` See the :mc-conf:`identity_ldap` reference documentation for more - information on these settings. The :ref:`` tutorial includes - complete instructions on setting these variables. + information on these settings. The + :ref:`minio-authenticate-using-openid-generic` tutorial includes complete + instructions on setting these variables. .. toctree:: diff --git a/source/security/minio-identity-management/basic-authentication-with-minio-identity-provider.rst b/source/security/minio-identity-management/basic-authentication-with-minio-identity-provider.rst index d42a824a..58e79e0c 100644 --- a/source/security/minio-identity-management/basic-authentication-with-minio-identity-provider.rst +++ b/source/security/minio-identity-management/basic-authentication-with-minio-identity-provider.rst @@ -1,9 +1,6 @@ -.. _minio-internal-idp: -.. _minio-users: - -================================== -MinIO Internal Identity Management -================================== +==================================== +MinIO Identity and Access Management +==================================== .. default-domain:: minio @@ -14,16 +11,41 @@ MinIO Internal Identity Management Overview -------- +MinIO provides an internal Identity and Access Management subsystem that +supports the creation of user identities, groups, and policies in support of +authentication and authorization of client operations. + +*Authentication* is the process of verifying the identity of a connecting +client. MinIO requires clients authenticate using :s3-api:`AWS Signature Version +4 protocol ` with support for the +deprecated Signature Version 2 protocol. Specifically, clients must present a +valid access key and secret key to access any S3 or MinIO administrative API, +such as ``PUT``, ``GET``, and ``DELETE`` operations. MinIO provides +a built-in :ref:`IDentity Provider (IDP) ` for creating and +managing user identities in support of client authentication. + +*Authorization* is the process of restricting the actions and resources the +authenticated client can perform on the deployment. MinIO uses Policy-Based +Access Control (PBAC), where each policy describes one or more rules that +outline the permissions of a user or group of users. MinIO supports a subset of +:ref:`actions ` and +:ref:`conditions ` when creating policies. +By default, MinIO *denies* access to actions or resources not explicitly +referenced in a user's assigned or inherited policies. + +.. _minio-internal-idp: + +Identity Management +------------------- + MinIO includes a built-in IDentity Provider (IDP) that provides core identity -management functionality. The MiNIO IDP supports creating an arbitrary number of +management functionality. The MinIO IDP supports creating an arbitrary number of long-lived users on the deployment for supporting client authentication. -A *user* is an identity with associated privileges on a MinIO deployment. Each -user consists of a unique access key (username) and corresponding secret key -(password). The access key and secret key support *authentication* on the MinIO -deployment, similar to a username and password. Clients must specify both a -valid access key (username) and the corresponding secret key (password) to -access the MinIO deployment. +Each user consists of a unique access key (username) and corresponding secret +key (password). Clients must authenticate their identity by specifying both +a valid access key (username) and the corresponding secret key (password) of +an existing MinIO user. Administrators use the :mc-cmd:`mc admin user` command to create and manage MinIO users. The :minio-git:`MinIO Console ` provides a graphical @@ -54,167 +76,94 @@ user's authorized actions and resources *or* assign the user to :ref:`groups the exception of creating :ref:`service accounts `. -.. _minio-users-root: +.. _minio-access-management: -MinIO ``root`` User -~~~~~~~~~~~~~~~~~~~ +Access Management +----------------- -MinIO deployments have a ``root`` user with access to all actions and resources -on the deployment, regardless of the configured :ref:`identity manager -`. When a :mc:`minio` server first -starts, it sets the ``root`` user credentials by checking the value of the -following environment variables: +MinIO uses Policy-Based Access Control (PBAC) to define the authorized actions +and resources to which an authenticated user has access. Each policy describes +one or more :ref:`actions ` and :ref:`conditions +` that outline the permissions of a +:ref:`user ` or :ref:`group ` of +users. -- :envvar:`MINIO_ROOT_USER` -- :envvar:`MINIO_ROOT_PASSWORD` +MinIO manages the creation and storage of policies. The process for +assigning a policy to a user or group depends on the configured +:ref:`IDentity Provider (IDP) `. -Rotating the root user credentials requires updating either or both variables -for all MinIO servers in the deployment. Specify *long, unique, and random* -strings for root credentials. Exercise all possible precautions in storing the -access key and secret key, such that only known and trusted individuals who -*require* superuser access to the deployment can retrieve the ``root`` -credentials. +MinIO deployments using the :ref:`MinIO Internal IDP ` +require explicitly associating a user to a policy or policies using the +:mc-cmd:`mc admin policy set` command. A user can also inherit the policies +attached to the :ref:`groups ` in which they have membership. -- MinIO *strongly discourages* using the ``root`` user for regular client access - regardless of the environment (development, staging, or production). +By default, MinIO *denies* access to actions or resources not explicitly allowed +by an attached or inherited policy. A user with no explicitly assigned or +inherited policies cannot perform any S3 or MinIO administrative API operations. -- MinIO *strongly recommends* creating users such that each client has access to - the minimal set of actions and resources required to perform their assigned - workloads. - -If these variables are unset, :mc:`minio` defaults to ``minioadmin`` and -``minioadmin`` as the access key and secret key respectively. MinIO *strongly -discourages* use of the default credentials regardless of deployment -environment. - -.. admonition:: Deprecation of Legacy Root User Environment Variables - :class: dropdown, important - - MinIO :minio-release:`RELEASE.2021-04-22T15-44-28Z` and later deprecates the - following variables used for setting or updating root user - credentials: - - - :envvar:`MINIO_ACCESS_KEY` to the new access key. - - :envvar:`MINIO_SECRET_KEY` to the new secret key. - - :envvar:`MINIO_ACCESS_KEY_OLD` to the old access key. - - :envvar:`MINIO_SECRET_KEY_OLD` to the old secret key. - -Access Control --------------- - -A user by default has no associated :ref:`privileges `. -You must either explicitly assign a :ref:`policy ` describing -the user's authorized actions and resources *or* assign the user to -:ref:`groups ` which have associated policies. A user with -no explicitly assigned or inherited policies cannot perform any S3 or -MinIO administrative API operations. - -For example, consider the following table of users. Each user is assigned -a :ref:`built-in policy ` or -a supported :ref:`action `. The table -describes a subset of operations a client could perform if authenticated -as that user: +For MinIO deployments using an External IDP, policy assignment depends on the +choice of IDP: .. list-table:: - :header-rows: 1 - :widths: 20 40 40 + :stub-columns: 1 + :widths: 30 70 :width: 100% - * - User - - Policy - - Operations + * - :ref:`OpenID Connect (OIDC) ` + - MinIO checks for a JSON Web Token (JWT) claim (``policy`` by default) + containing the name of the policy or policies to attach to the + authenticated user. If the policies do not exist, the user cannot + perform any action on the MinIO deployment. - * - ``Operations`` - - | :userpolicy:`readwrite` on ``finance`` bucket - | :userpolicy:`readonly` on ``audit`` bucket + MinIO does not support assigning OIDC user identities to + :ref:`groups `. The IDP administrator must instead + assign all necessary policies to the user's policy claim. + + See :ref:`Access Control for Externally Managed Identities + ` for + more information. + + * - :ref:`Active Directory / LDAP (AD/LDAP) + ` + - MinIO checks for a policy whose name matches the Distinguished Name (DN) + of the authenticated AD/LDAP user. + + MinIO also supports querying for the authenticated AD/LDAP user's + group memberships. MinIO assigns any policy whose name matches the + DN for each returned group. + + If no policies match either the user DN *or* any of the user's group DNs, + the user cannot perform any action on the MinIO deployment. + + See :ref:`Access Control for Externally Managed Identities + ` for more + information. - - | ``PUT`` and ``GET`` on ``finance`` bucket. - | ``PUT`` on ``audit`` bucket +MinIO PBAC is built for compatibility with AWS IAM policy syntax, structure, and +behavior. The MinIO documentation makes a best-effort to cover IAM-specific +behavior and functionality. Consider deferring to the :iam-docs:`IAM +documentation <>` for more complete documentation on IAM, IAM policies, or IAM +JSON syntax. - * - ``Auditing`` - - | :userpolicy:`readonly` on ``audit`` bucket - - ``GET`` on ``audit`` bucket +.. admonition:: ``Deny`` overrides ``Allow`` + :class: note - * - ``Admin`` - - :policy-action:`admin:*` - - All :mc-cmd:`mc admin` commands. + MinIO follows AWS IAM policy evaluation rules where a ``Deny`` rule overrides + ``Allow`` rule on the same action/resource. For example, if a user has an + explicitly assigned policy with an ``Allow`` rule for an action/resource + while one of its groups has an assigned policy with a ``Deny`` rule for that + action/resource, MinIO would apply only the ``Deny`` rule. -Each user can access only those resources and operations which are *explicitly* -granted by the built-in role. MinIO denies access to any other resource or -action by default. + For more information on IAM policy evaluation logic, see the IAM + documentation on + :iam-docs:`Determining Whether a Request is Allowed or Denied Within an Account + `. -.. _minio-idp-service-account: + .. toctree:: + :titlesonly: + :hidden: -Service Accounts ----------------- - -MinIO service accounts are child identities of a MinIO User. Each -service account inherits its privileges based on the -:ref:`policies ` attached to it's parent user *or* those -groups in which the parent user has membership. Service accounts also support -an optional inline policy which further restricts access to a subset of -actions and resources available to the parent user. - -A MinIO user can generate any number of service accounts. This allows -application owners to generate arbitrary service accounts for their applications -without requiring action from the MinIO administrators. Since the generated -service accounts have the same or fewer permissions as the parents, -administrators can focus on managing the top-level parent users without -micro-managing generated service accounts. - -Service accounts are only available through the :minio-git:`MinIO Console -`. After logging into the Console, click :guilabel:`Account` -from the left navigation to view all service accounts associated to the -authenticated user. Click :guilabel:`Create Service Account` to create -new service accounts. - -User Management ---------------- - -Create a User -~~~~~~~~~~~~~ - -Use the :mc-cmd:`mc admin user add` command to create a new user on the -MinIO deployment: - -.. code-block:: shell - :class: copyable - - mc admin user add ALIAS ACCESSKEY SECRETKEY - -- Replace :mc-cmd:`ALIAS ` with the - :mc-cmd:`alias ` of the MinIO deployment. - -- Replace :mc-cmd:`ACCESSKEY ` with the - access key for the user. MinIO allows retrieving the access key after - user creation through the :mc-cmd:`mc admin user info` command. - -- Replace :mc-cmd:`SECRETKEY ` with the - secret key for the user. MinIO *does not* provide any method for retrieving - the secret key once set. - -Specify a unique, random, and long string for both the ``ACCESSKEY`` and -``SECRETKEY``. Your organization may have specific internal or regulatory -requirements around generating values for use with access or secret keys. - -After creating the user, use :mc-cmd:`mc admin policy set` to associate -a :ref:`MinIO Policy Based Access Control ` to the new user. You can also use -:mc-cmd:`mc admin group add` to add the user to a :ref:`minio-groups`. - -Delete a User -~~~~~~~~~~~~~ - -Use the :mc-cmd:`mc admin user remove` command to remove a user on a -MinIO deployment: - -.. code-block:: shell - :class: copyable - - mc admin user remove ALIAS USERNAME - -- Replace :mc-cmd:`ALIAS ` with the - :mc-cmd:`alias ` of the MinIO deployment. - -- Replace :mc-cmd:`USERNAME ` with the name of - the user to remove. + /security/minio-identity-management/user-management + /security/minio-identity-management/group-management + /security/minio-identity-management/policy-based-access-control diff --git a/source/security/minio-identity-management/group-management.rst b/source/security/minio-identity-management/group-management.rst new file mode 100644 index 00000000..607585b4 --- /dev/null +++ b/source/security/minio-identity-management/group-management.rst @@ -0,0 +1,60 @@ +.. _minio-groups: + +================ +Group Management +================ + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 2 + +Overview +-------- + +A *group* is a collection of :ref:`users `. Each group +can have one or more assigned :ref:`policies ` +that explicitly list the actions and resources to which group members are +allowed or denied access. + +For example, consider the following groups. Each group is assigned a +:ref:`built-in policy ` or supported +:ref:`policy action `. Each group also has one or +more assigned users. Each user's total set of permissions consists of their +explicitly assigned permission *and* the inherited permissions from each of +their assigned groups. MinIO by default *denies* access to any resource or +operation not explicitly allowed by a user's assigned or inherited policies. + +.. list-table:: + :header-rows: 1 + :widths: 20 40 40 + :width: 100% + + * - Group + - Policy + - Members + + * - ``Operations`` + - | :userpolicy:`readwrite` on ``finance`` bucket + | :userpolicy:`readonly` on ``audit`` bucket + + - ``john.doe``, ``jane.doe`` + + * - ``Auditing`` + - | :userpolicy:`readonly` on ``audit`` bucket + - ``jen.doe``, ``joe.doe`` + + * - ``Admin`` + - :policy-action:`admin:*` + - ``greg.doe``, ``jen.doe`` + +Groups provide a simplified method for managing shared permissions among +users with common access patterns and workloads. Client's *cannot* authenticate +to a MinIO deployment using a group as an identity. + + +The :mc-cmd:`mc admin group` command supports the creation and management of +groups on the MinIO deployment. See the command reference for examples of +usage. + diff --git a/source/security/access-management/access-management-overview.rst b/source/security/minio-identity-management/policy-based-access-control.rst similarity index 77% rename from source/security/access-management/access-management-overview.rst rename to source/security/minio-identity-management/policy-based-access-control.rst index 2a69c19e..be468283 100644 --- a/source/security/access-management/access-management-overview.rst +++ b/source/security/minio-identity-management/policy-based-access-control.rst @@ -1,7 +1,7 @@ -.. _minio-access-management: +.. _minio-policy: ================= -Access Management +Policy Management ================= .. default-domain:: minio @@ -10,8 +10,6 @@ Access Management :local: :depth: 2 -.. _minio-policy: - Overview -------- @@ -20,75 +18,16 @@ and resources to which an authenticated user has access. Each policy describes one or more :ref:`actions ` and :ref:`conditions ` that outline the permissions of a :ref:`user ` or :ref:`group ` of -users. By default, MinIO *denies* access to actions or resources not explicitly -referenced in a user's assigned or inherited policies. +users. -MinIO manages the creation and storage of policies. The process for -assigning a policy to a user or group depends on the configured -:ref:`IDentity Provider (IDP) `. - -MinIO deployments using the :ref:`MinIO Internal IDP ` -require explicitly associating a user to a policy or policies using the -:mc-cmd:`mc admin policy set` command. A user can also inherit the policies -attached to the :ref:`groups ` in which they have membership. - -For MinIO deployments using an External IDP, policy assignment depends on the -choice of IDP: - -.. list-table:: - :stub-columns: 1 - :widths: 30 70 - :width: 100% - - * - :ref:`OpenID Connect (OIDC) ` - - MinIO checks for a JSON Web Token (JWT) claim (``policy`` by default) - containing the name of the policy or policies to attach to the - authenticated user. If the policies do not exist, the user cannot - perform any action on the MinIO deployment. - - MinIO does not support assigning OIDC user identities to - :ref:`groups `. The IDP administrator must instead - assign all necessary policies to the user's policy claim. - - See :ref:`Access Control for Externally Managed Identities - ` for - more information. - - * - :ref:`Active Directory / LDAP (AD/LDAP) - ` - - MinIO checks for a policy whose name matches the Distinguished Name (DN) - of the authenticated AD/LDAP user. - - MinIO also supports querying for the authenticated AD/LDAP user's - group memberships. MinIO assigns any policy whose name matches the - DN for each returned group. - - If no policies match either the user DN *or* any of the user's group DNs, - the user cannot perform any action on the MinIO deployment. - - See :ref:`Access Control for Externally Managed Identities - ` for more - information. - MinIO PBAC is built for compatibility with AWS IAM policy syntax, structure, and behavior. The MinIO documentation makes a best-effort to cover IAM-specific behavior and functionality. Consider deferring to the :iam-docs:`IAM -documentation <>` for more complete documentation on IAM, IAM policies, or IAM -JSON syntax. +documentation <>` for more complete documentation on AWS IAM-specific topics. -.. admonition:: ``Deny`` overrides ``Allow`` - :class: note - - MinIO follows AWS IAM policy evaluation rules where a ``Deny`` rule overrides - ``Allow`` rule on the same action/resource. For example, if a user has an - explicitly assigned policy with an ``Allow`` rule for an action/resource - while one of its groups has an assigned policy with a ``Deny`` rule for that - action/resource, MinIO would apply only the ``Deny`` rule. - - For more information on IAM policy evaluation logic, see the IAM - documentation on - :iam-docs:`Determining Whether a Request is Allowed or Denied Within an Account - `. +The :mc-cmd:`mc admin policy` command supports creation and management of +policies on the MinIO deployment. See the command reference for examples of +usage. .. _minio-policy-built-in: @@ -189,13 +128,13 @@ policy elements, see the :aws-docs:`IAM JSON Policy Elements Reference { "Effect" : "Allow", "Action" : [ "s3:", ... ], - "Resource" : "arn:minio:s3:::*", + "Resource" : "arn:aws:s3:::*", "Condition" : { ... } }, { "Effect" : "Deny", "Action" : [ "s3:", ... ], - "Resource" : "arn:minio:s3:::*", + "Resource" : "arn:aws:s3:::*", "Condition" : { ... } } ] @@ -761,64 +700,4 @@ MinIO supports the following conditions for use with defining policies for - ``aws:EpochTime`` For complete information on any listed condition key, see the :iam-docs:`IAM -Condition Element Documentation ` - -.. _minio-groups: - -MinIO Groups ------------- - -A *group* is a collection of :ref:`users `. Each group -can have one or more assigned :ref:`policies ` -that explicitly list the actions and resources to which group members are -allowed or denied access. - -For example, consider the following groups. Each group is assigned a -:ref:`built-in policy ` or supported -:ref:`policy action `. Each group also has one or -more assigned users. Each user's total set of permissions consists of their -explicitly assigned permission *and* the inherited permissions from each of -their assigned groups. MinIO by default *denies* access to any resource or -operation not explicitly allowed by a user's assigned or inherited policies. - -.. list-table:: - :header-rows: 1 - :widths: 20 40 40 - :width: 100% - - * - Group - - Policy - - Members - - * - ``Operations`` - - | :userpolicy:`readwrite` on ``finance`` bucket - | :userpolicy:`readonly` on ``audit`` bucket - - - ``john.doe``, ``jane.doe`` - - * - ``Auditing`` - - | :userpolicy:`readonly` on ``audit`` bucket - - ``jen.doe``, ``joe.doe`` - - * - ``Admin`` - - :policy-action:`admin:*` - - ``greg.doe``, ``jen.doe`` - -Groups provide a simplified method for managing shared permissions among -users with common access patterns and workloads. Client's *cannot* authenticate -to a MinIO deployment using a group as an identity. Use the -:mc-cmd:`mc admin group` command to create and manage groups on MinIO. - -.. admonition:: ``Deny`` overrides ``Allow`` - :class: note - - MinIO follows the IAM standard where a ``Deny`` rule overrides ``Allow`` rule - on the same action or resource. For example, if a user has an explicitly - assigned policy with an ``Allow`` rule for an action/resource while one of - its groups has an assigned policy with a ``Deny`` rule for that - action/resource, MinIO would apply only the ``Deny`` rule. - - For more information on IAM policy evaluation logic, see the IAM - documentation on - :iam-docs:`Determining Whether a Request is Allowed or Denied Within an Account - `. +Condition Element Documentation ` \ No newline at end of file diff --git a/source/security/minio-identity-management/user-management.rst b/source/security/minio-identity-management/user-management.rst new file mode 100644 index 00000000..1c588483 --- /dev/null +++ b/source/security/minio-identity-management/user-management.rst @@ -0,0 +1,170 @@ +.. _minio-users: + +=============== +User Management +=============== + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 2 + +Overview +-------- + +A MinIO user consists of a unique access key (username) and corresponding secret +key (password). Clients must authenticate their identity by specifying both +a valid access key (username) and the corresponding secret key (password) of +an existing MinIO user. + +Each user can have one or more assigned :ref:`policies ` that +explicitly list the actions and resources to which that user has access. +Users can also inherit policies from the :ref:`groups ` in which +they have membership. + +MinIO by default denies access to all actions or resources not explicitly +allowed by a user's assigned or inherited :ref:`policies `. You +must either explicitly assign a :ref:`policy ` describing the +user's authorized actions and resources *or* assign the user to :ref:`groups +` which have associated policies. See +:ref:`minio-access-management` for more information. + +This page documents user management for the MinIO internal IDentity Provider +(IDP). MinIO also external management of identities using either an +OpenID Connect (OIDC) or Active Directory/LDAP IDentity Provider (IDP). +For more information, see: + +- :ref:`minio-external-identity-management-openid` +- :ref:`minio-external-identity-management-ad-ldap` + +Enabling external identity management disables the MinIO internal IDP, with +the exception of creating :ref:`service accounts +`. + +.. _minio-idp-service-account: + +Service Accounts +---------------- + +MinIO service accounts are child identities of a MinIO User. Each +service account inherits its privileges based on the +:ref:`policies ` attached to it's parent user *or* those +groups in which the parent user has membership. Service accounts also support +an optional inline policy which further restricts access to a subset of +actions and resources available to the parent user. + +A MinIO user can generate any number of service accounts. This allows +application owners to generate arbitrary service accounts for their applications +without requiring action from the MinIO administrators. Since the generated +service accounts have the same or fewer permissions as the parents, +administrators can focus on managing the top-level parent users without +micro-managing generated service accounts. + +Service accounts are only available through the :minio-git:`MinIO Console +`. After logging into the Console, click :guilabel:`Account` +from the left navigation to view all service accounts associated to the +authenticated user. Click :guilabel:`Create Service Account` to create +new service accounts. + +.. _minio-users-root: + +MinIO ``root`` User +------------------- + +MinIO deployments have a ``root`` user with access to all actions and resources +on the deployment, regardless of the configured :ref:`identity manager +`. When a :mc:`minio` server first +starts, it sets the ``root`` user credentials by checking the value of the +following environment variables: + +- :envvar:`MINIO_ROOT_USER` +- :envvar:`MINIO_ROOT_PASSWORD` + +Rotating the root user credentials requires updating either or both variables +for all MinIO servers in the deployment. Specify *long, unique, and random* +strings for root credentials. Exercise all possible precautions in storing the +access key and secret key, such that only known and trusted individuals who +*require* superuser access to the deployment can retrieve the ``root`` +credentials. + +- MinIO *strongly discourages* using the ``root`` user for regular client access + regardless of the environment (development, staging, or production). + +- MinIO *strongly recommends* creating users such that each client has access to + the minimal set of actions and resources required to perform their assigned + workloads. + +If these variables are unset, :mc:`minio` defaults to ``minioadmin`` and +``minioadmin`` as the access key and secret key respectively. MinIO *strongly +discourages* use of the default credentials regardless of deployment +environment. + +.. admonition:: Deprecation of Legacy Root User Environment Variables + :class: dropdown, important + + MinIO :minio-release:`RELEASE.2021-04-22T15-44-28Z` and later deprecates the + following variables used for setting or updating root user + credentials: + + - :envvar:`MINIO_ACCESS_KEY` to the new access key. + - :envvar:`MINIO_SECRET_KEY` to the new secret key. + - :envvar:`MINIO_ACCESS_KEY_OLD` to the old access key. + - :envvar:`MINIO_SECRET_KEY_OLD` to the old secret key. + +User Management +--------------- + +Create a User +~~~~~~~~~~~~~ + +Use the :mc-cmd:`mc admin user add` command to create a new user on the +MinIO deployment: + +.. code-block:: shell + :class: copyable + + mc admin user add ALIAS ACCESSKEY SECRETKEY + +- Replace :mc-cmd:`ALIAS ` with the + :mc-cmd:`alias ` of the MinIO deployment. + +- Replace :mc-cmd:`ACCESSKEY ` with the + access key for the user. MinIO allows retrieving the access key after + user creation through the :mc-cmd:`mc admin user info` command. + +- Replace :mc-cmd:`SECRETKEY ` with the + secret key for the user. MinIO *does not* provide any method for retrieving + the secret key once set. + +Specify a unique, random, and long string for both the ``ACCESSKEY`` and +``SECRETKEY``. Your organization may have specific internal or regulatory +requirements around generating values for use with access or secret keys. + +After creating the user, use :mc-cmd:`mc admin policy set` to associate a +:ref:`MinIO Policy Based Access Control ` to the new user. +The following command assigns the built-in :userpolicy:`readwrite` policy: + +.. code-block:: shell + :class: copyable + + mc admin policy set ALIAS readwrite user=USERNAME + +Replace ``USERNAME`` with the ``ACCESSKEY`` created in the previous step. + +Delete a User +~~~~~~~~~~~~~ + +Use the :mc-cmd:`mc admin user remove` command to remove a user on a +MinIO deployment: + +.. code-block:: shell + :class: copyable + + mc admin user remove ALIAS USERNAME + +- Replace :mc-cmd:`ALIAS ` with the + :mc-cmd:`alias ` of the MinIO deployment. + +- Replace :mc-cmd:`USERNAME ` with the name of + the user to remove. \ No newline at end of file diff --git a/source/security/openid-external-identity-management/configure-openid-external-identity-management.rst b/source/security/openid-external-identity-management/configure-openid-external-identity-management.rst index 36df0a59..2bc8b854 100644 --- a/source/security/openid-external-identity-management/configure-openid-external-identity-management.rst +++ b/source/security/openid-external-identity-management/configure-openid-external-identity-management.rst @@ -93,12 +93,13 @@ environment variables and configuration settings respectively: .. code-block:: shell :class: copyable - set MINIO_IDENTITY_OPENID_CONFIG_URL="https://openid-provider.example.net/.well-known/openid-configuration" - set MINIO_IDENTITY_OPENID_CLIENT_ID="" - set MINIO_IDENTITY_OPENID_CLAIM_NAME="" - set MINIO_IDENTITY_OPENID_CLAIM_PREFIX="" - set MINIO_IDENTITY_OPENID_SCOPES="" - set MINIO_IDENTITY_OPENID_COMMENT="" + export MINIO_IDENTITY_OPENID_CONFIG_URL="https://openid-provider.example.net/.well-known/openid-configuration" + export MINIO_IDENTITY_OPENID_CLIENT_ID="" + export MINIO_IDENTITY_OPENID_CLAIM_NAME="" + export MINIO_IDENTITY_OPENID_CLAIM_PREFIX="" + export MINIO_IDENTITY_OPENID_SCOPES="" + export MINIO_IDENTITY_OPENID_REDIRECT_URI="" + export MINIO_IDENTITY_OPENID_COMMENT="" Replace the ``MINIO_IDENTITY_OPENID_CONFIG_URL`` with the URL endpoint of the :abbr:`OIDC (OpenID Connect)` provider discovery document. @@ -128,6 +129,7 @@ environment variables and configuration settings respectively: claim_name="" \ claim_prefix="" \ scopes="" \ + redirect_uri="" \ comment="" Replace the ``config_url`` with the URL endpoint of the diff --git a/source/security/openid-external-identity-management/external-authentication-with-openid-identity-provider.rst b/source/security/openid-external-identity-management/external-authentication-with-openid-identity-provider.rst index 05f2b068..e7bb1694 100644 --- a/source/security/openid-external-identity-management/external-authentication-with-openid-identity-provider.rst +++ b/source/security/openid-external-identity-management/external-authentication-with-openid-identity-provider.rst @@ -52,6 +52,11 @@ credentials is as follows: 1. Authenticate to the configured :abbr:`OIDC (OpenID Connect)` provider and retrieve a `JSON Web Token (JWT) `__. + + MinIO only supports the + `OpenID Authorization Code Flow + `__. + 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. diff --git a/source/security/security-overview.rst b/source/security/security-overview.rst index 5140587c..b510a580 100644 --- a/source/security/security-overview.rst +++ b/source/security/security-overview.rst @@ -10,15 +10,17 @@ Security .. _minio-authentication-and-identity-management: -Authentication and Identity Management --------------------------------------- +Identity and Access Management +------------------------------ -MinIO requires clients authenticate using -:s3-api:`AWS Signature Version 4 protocol ` -with support for the deprecated Signature Version 2 protocol. Specifically, -clients must present a valid access key and secret key to access any -S3 or MinIO administrative API, such as ``PUT``, ``GET``, and -``DELETE`` operations. +MinIO requires clients authenticate using :s3-api:`AWS Signature Version 4 +protocol ` with support for the deprecated +Signature Version 2 protocol. Specifically, clients must *authenticate* by +presenting a valid access key and secret key to access any S3 or MinIO +administrative API, such as ``PUT``, ``GET``, and ``DELETE`` operations. +S3-compatible SDKs, including those provided by MinIO, typically include +built-in helpers for creating the necessary signatures using an access key +and secret key. MinIO supports both internal and external identity management: @@ -41,24 +43,18 @@ MinIO supports both internal and external identity management: ` - Supports managing identities through an Active Directory or LDAP service. -.. _minio-authorization-and-access-management: - -Authorization and Access Management ------------------------------------ - -MinIO requires each client to :ref:`authenticate -` its identity for all S3 API -operations, such as ``PUT``, ``GET``, and ``DELETE``. Once a client successfully -authenticates, MinIO allows that client to perform only those operations for -which they are explicitly *authorized*. +Once authenticated, MinIO either allows or rejects the client request depending +on whether or not the authenticated identity is *authorized* to perform the +operation on the specified resource. MinIO uses Policy-Based Access Control (PBAC) to define the authorized actions and resources to which an authenticated user has access. Each policy describes one or more :ref:`actions ` and :ref:`conditions -` that outline the permissions of a -:ref:`user ` or :ref:`group ` of -users. By default, MinIO *denies* access to actions or resources not explicitly -referenced in a user's assigned or inherited policies. +` that outline the permissions of a :ref:`user +` or :ref:`group ` of users. By default, MinIO +*denies* access to actions or resources not explicitly referenced in a user's +assigned or inherited policies. MinIO manages the creation and storage of +policies and does not support external authorization management. MinIO PBAC is built for compatibility with AWS IAM policy syntax, structure, and behavior. The MinIO documentation makes a best-effort to cover IAM-specific @@ -66,8 +62,6 @@ behavior and functionality. Consider deferring to the :iam-docs:`IAM documentation <>` for more complete documentation on IAM, IAM policies, or IAM JSON syntax. -For more complete documentation, see :ref:`minio-access-management`. - Encryption ---------- @@ -101,6 +95,5 @@ See :ref:`minio-sse` for more complete documentation. /security/minio-identity-management/basic-authentication-with-minio-identity-provider /security/openid-external-identity-management/external-authentication-with-openid-identity-provider /security/ad-ldap-external-identity-management/external-authentication-with-ad-ldap-identity-provider - /security/access-management/access-management-overview /security/encryption/encryption-key-management