Cleanup pass + reorg

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

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:::*"
             ]
          }
       ]

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="cn=miniolookupuser,dc=example,dc=net" \
-         lookUP-bind_dn_password="userpassword"
+         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: " "
 

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 
    <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 
+   <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 
    <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 
+   <identity_openid.redirect_uri>` setting.
+   
+
 .. envvar:: MINIO_IDENTITY_OPENID_COMMENT
 
    *Optional*

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 <minio-external-identity-management-ad-ldap-lookup-bind>` to perform
 authenticated user and group queries.
 
+Ensure each AD/LDAP user and group intended for use with MinIO has a
+corresponding :ref:`policy
+<minio-external-identity-management-ad-ldap-access-control>` 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 <identity_ldap.lookup_bind_dn>`
 
       - :mc-conf:`identity_ldap lookup_bind_password <identity_ldap.lookup_bind_password>`
+      
+      - :mc-conf:`identity_ldap user_dn_search_base_dn <identity_ldap.user_dn_search_base_dn>`
+      
+      - :mc-conf:`identity_ldap user_dn_search_filter <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`.

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
+      See the :ref:`minio-server-envvar-external-identity-management-ad-ldap`
-      variables. The :ref:`` tutorial includes complete instructions on
+      reference documentation for more information on these variables. The
-      setting these values.
+      :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 <identity_ldap.group_search_filter>`
 
       See the :mc-conf:`identity_ldap` reference documentation for more
-      information on these settings. The :ref:`` tutorial includes
+      information on these settings. The
-      complete instructions on setting these variables.
+      :ref:`minio-authenticate-using-openid-generic` tutorial includes complete
+      instructions on setting these variables.
 
 
 .. toctree::

source/security/minio-identity-management/basic-authentication-with-minio-identity-provider.rst

@@ -1,9 +1,6 @@
-.. _minio-internal-idp:
+====================================
-.. _minio-users:
+MinIO Identity and Access Management
-
+====================================
-==================================
-MinIO Internal Identity 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 <sig-v4-authenticating-requests.html>` 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) <minio-internal-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 <minio-policy-actions>` and 
+:ref:`conditions <minio-policy-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
+Each user consists of a unique access key (username) and corresponding secret
-user consists of a unique access key (username) and corresponding secret key
+key (password). Clients must authenticate their identity by specifying both
-(password).  The access key and secret key support *authentication* on the MinIO
+a valid access key (username) and the corresponding secret key (password) of
-deployment, similar to a username and password. Clients must specify both a
+an existing MinIO user.
-valid access key (username) and the corresponding secret key (password) to
-access the MinIO deployment.
 
 Administrators use the :mc-cmd:`mc admin user` command to create and manage
 MinIO users. The :minio-git:`MinIO Console <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-idp-service-account>`.
 
-.. _minio-users-root:
+.. _minio-access-management:
 
-MinIO ``root`` User
+Access Management
-~~~~~~~~~~~~~~~~~~~
+-----------------
 
-MinIO deployments have a ``root`` user with access to all actions and resources
+MinIO uses Policy-Based Access Control (PBAC) to define the authorized actions
-on the deployment, regardless of the configured :ref:`identity manager
+and resources to which an authenticated user has access. Each policy describes
-<minio-authentication-and-identity-management>`. When a :mc:`minio` server first
+one or more :ref:`actions <minio-policy-actions>` and :ref:`conditions
-starts, it sets the ``root`` user credentials by checking the value of the
+<minio-policy-conditions>` that outline the permissions of a 
-following environment variables:
+:ref:`user <minio-users>` or :ref:`group <minio-groups>` of
+users. 
 
-- :envvar:`MINIO_ROOT_USER`
+MinIO manages the creation and storage of policies. The process for 
-- :envvar:`MINIO_ROOT_PASSWORD`
+assigning a policy to a user or group depends on the configured
+:ref:`IDentity Provider (IDP) <minio-authentication-and-identity-management>`.
 
-Rotating the root user credentials requires updating either or both variables
+MinIO deployments using the :ref:`MinIO Internal IDP <minio-internal-idp>`
-for all MinIO servers in the deployment. Specify *long, unique, and random*
+require explicitly associating a user to a policy or policies using the
-strings for root credentials. Exercise all possible precautions in storing the
+:mc-cmd:`mc admin policy set`  command. A user can also inherit the policies
-access key and secret key, such that only known and trusted individuals who
+attached to the :ref:`groups <minio-groups>` in which they have membership.
-*require* superuser access to the deployment can retrieve the ``root``
-credentials.
 
-- MinIO *strongly discourages* using the ``root`` user for regular client access
+By default, MinIO *denies* access to actions or resources not explicitly allowed
-  regardless of the environment (development, staging, or production).
+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
+For MinIO deployments using an External IDP, policy assignment depends on the
-  the minimal set of actions and resources required to perform their assigned
+choice of IDP:
-  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 <minio-access-management>`.
-You must either explicitly assign a :ref:`policy <minio-policy>` describing
-the user's authorized actions and resources *or* assign the user to 
-:ref:`groups <minio-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 <minio-policy-built-in>` or
-a supported :ref:`action <minio-policy-actions>`. The table
-describes a subset of operations a client could perform if authenticated
-as that user:
 
 .. list-table::
-   :header-rows: 1
+   :stub-columns: 1
-   :widths: 20 40 40
+   :widths: 30 70
    :width: 100%
 
-   * - User
+   * - :ref:`OpenID Connect (OIDC)  <minio-external-identity-management-openid>`
-     - Policy
+     - MinIO checks for a JSON Web Token (JWT) claim (``policy`` by default)
-     - Operations
+       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``
+       MinIO does not support assigning OIDC user identities to 
-     - | :userpolicy:`readwrite` on ``finance`` bucket
+       :ref:`groups <minio-groups>`. The IDP administrator must instead
-       | :userpolicy:`readonly` on ``audit`` bucket
+       assign all necessary policies to the user's policy claim.
+
+       See :ref:`Access Control for Externally Managed Identities 
+       <minio-external-identity-management-openid-access-control>` for
+       more information.
+
+   * - :ref:`Active Directory / LDAP (AD/LDAP)
+       <minio-external-identity-management-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
+       <minio-external-identity-management-ad-ldap-access-control>` for more
+       information.
      
-     - | ``PUT`` and ``GET`` on ``finance`` bucket.
+MinIO PBAC is built for compatibility with AWS IAM policy syntax, structure, and
-       | ``PUT`` on ``audit`` bucket
+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``
+.. admonition:: ``Deny`` overrides ``Allow``
-     - | :userpolicy:`readonly` on ``audit`` bucket
+   :class: note
-     - ``GET`` on ``audit`` bucket
 
-   * - ``Admin``
+   MinIO follows AWS IAM policy evaluation rules where a ``Deny`` rule overrides
-     - :policy-action:`admin:*`
+   ``Allow`` rule on the same action/resource. For example, if a user has an
-     - All :mc-cmd:`mc admin` commands.
+   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*
+   For more information on IAM policy evaluation logic, see the IAM
-granted by the built-in role. MinIO denies access to any other resource or
+   documentation on 
-action by default.
+   :iam-docs:`Determining Whether a Request is Allowed or Denied Within an Account 
+   <reference_policies_evaluation-logic.html#policy-eval-denyallow>`.
 
-.. _minio-idp-service-account:
+   .. toctree::
+      :titlesonly:
+      :hidden:
 
-Service Accounts
+      /security/minio-identity-management/user-management
-----------------
+      /security/minio-identity-management/group-management
-
+      /security/minio-identity-management/policy-based-access-control
-MinIO service accounts are child identities of a MinIO User. Each 
-service account inherits its privileges based on the 
-:ref:`policies <minio-policy>` 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 
-<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 <mc admin user add TARGET>` with the
-  :mc-cmd:`alias <mc alias>` of the MinIO deployment.
-
-- Replace :mc-cmd:`ACCESSKEY <mc admin user add 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 <mc admin user add 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 <minio-policy>` 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 <mc admin user remove TARGET>` with the
-  :mc-cmd:`alias <mc alias>` of the MinIO deployment.
-
-- Replace :mc-cmd:`USERNAME <mc admin user remove USERNAME>` with the name of
-  the user to remove.
 

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 <minio-users>`. Each group
+can have one or more assigned :ref:`policies <minio-policy>`
+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 <minio-policy-built-in>` or supported
+:ref:`policy action <minio-policy-actions>`. 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.
+

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 <minio-policy-actions>` and :ref:`conditions
 <minio-policy-conditions>` that outline the permissions of a 
 :ref:`user <minio-users>` or :ref:`group <minio-groups>` of
-users. By default, MinIO *denies* access to actions or resources not explicitly
+users. 
-referenced in a user's assigned or inherited policies.
 
-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-authentication-and-identity-management>`.
-
-MinIO deployments using the :ref:`MinIO Internal IDP <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 <minio-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-external-identity-management-openid>`
-     - 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 <minio-groups>`. The IDP administrator must instead
-       assign all necessary policies to the user's policy claim.
-
-       See :ref:`Access Control for Externally Managed Identities 
-       <minio-external-identity-management-openid-access-control>` for
-       more information.
-
-   * - :ref:`Active Directory / LDAP (AD/LDAP)
-       <minio-external-identity-management-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
-       <minio-external-identity-management-ad-ldap-access-control>` 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
+documentation <>` for more complete documentation on AWS IAM-specific topics.
-JSON syntax.
 
-.. admonition:: ``Deny`` overrides ``Allow``
+The :mc-cmd:`mc admin policy` command supports creation and management of
-   :class: note
+policies on the MinIO deployment. See the command reference for examples of
-
+usage.
-   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 
-   <reference_policies_evaluation-logic.html#policy-eval-denyallow>`.
 
 .. _minio-policy-built-in:
 
@@ -189,13 +128,13 @@ policy elements, see the :aws-docs:`IAM JSON Policy Elements Reference
          {
             "Effect" : "Allow",
             "Action" : [ "s3:<ActionName>", ... ],
-            "Resource" : "arn:minio:s3:::*",
+            "Resource" : "arn:aws:s3:::*",
             "Condition" : { ... }
          },
          {
             "Effect" : "Deny",
             "Action" : [ "s3:<ActionName>", ... ],
-            "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 <reference_policies_elements_condition.html>`
+Condition Element Documentation <reference_policies_elements_condition.html>`
-
-.. _minio-groups:
-
-MinIO Groups
-------------
-
-A *group* is a collection of :ref:`users <minio-users>`. Each group
-can have one or more assigned :ref:`policies <minio-policy>`
-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 <minio-policy-built-in>` or supported
-:ref:`policy action <minio-policy-actions>`. 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 
-   <reference_policies_evaluation-logic.html#policy-eval-denyallow>`.

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 <minio-policy>` that
+explicitly list the actions and resources to which that user has access. 
+Users can also inherit policies from the :ref:`groups <minio-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 <minio-policy>`. You
+must either explicitly assign a :ref:`policy <minio-policy>` describing the
+user's authorized actions and resources *or* assign the user to :ref:`groups
+<minio-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>`.
+
+.. _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 <minio-policy>` 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 
+<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
+<minio-authentication-and-identity-management>`. 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 <mc admin user add TARGET>` with the
+  :mc-cmd:`alias <mc alias>` of the MinIO deployment.
+
+- Replace :mc-cmd:`ACCESSKEY <mc admin user add 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 <mc admin user add 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 <minio-policy>` 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 <mc admin user remove TARGET>` with the
+  :mc-cmd:`alias <mc alias>` of the MinIO deployment.
+
+- Replace :mc-cmd:`USERNAME <mc admin user remove USERNAME>` with the name of
+  the user to remove.

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"
+         export MINIO_IDENTITY_OPENID_CONFIG_URL="https://openid-provider.example.net/.well-known/openid-configuration"
-         set MINIO_IDENTITY_OPENID_CLIENT_ID="<string>"
+         export MINIO_IDENTITY_OPENID_CLIENT_ID="<string>"
-         set MINIO_IDENTITY_OPENID_CLAIM_NAME="<string>"
+         export MINIO_IDENTITY_OPENID_CLAIM_NAME="<string>"
-         set MINIO_IDENTITY_OPENID_CLAIM_PREFIX="<string>"
+         export MINIO_IDENTITY_OPENID_CLAIM_PREFIX="<string>"
-         set MINIO_IDENTITY_OPENID_SCOPES="<string>"
+         export MINIO_IDENTITY_OPENID_SCOPES="<string>"
-         set MINIO_IDENTITY_OPENID_COMMENT="<string>"
+         export MINIO_IDENTITY_OPENID_REDIRECT_URI="<string>"
+         export MINIO_IDENTITY_OPENID_COMMENT="<string>"
 
       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="<string>" \
             claim_prefix="<string>" \
             scopes="<string>" \
+            redirect_uri="<string>" \
             comment="<string>"
 
       Replace the ``config_url`` with the URL endpoint of the 

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) <https://jwt.io/introduction>`__. 
+   
+   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. 

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 
+MinIO requires clients authenticate using :s3-api:`AWS Signature Version 4
-:s3-api:`AWS Signature Version 4 protocol <sig-v4-authenticating-requests.html>`
+protocol <sig-v4-authenticating-requests.html>` with support for the deprecated
-with support for the deprecated Signature Version 2 protocol. Specifically,
+Signature Version 2 protocol. Specifically, clients must *authenticate* by
-clients must present a valid access key and secret key to access any 
+presenting a valid access key and secret key to access any S3 or MinIO
-S3 or MinIO administrative API, such as ``PUT``, ``GET``, and 
+administrative API, such as ``PUT``, ``GET``, and ``DELETE`` operations. 
-``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:
        <minio-external-identity-management-ad-ldap>` 
      - Supports managing identities through an Active Directory or LDAP service.
 
-.. _minio-authorization-and-access-management:
+Once authenticated, MinIO either allows or rejects the client request depending
-
+on whether or not the authenticated identity is *authorized* to perform the
-Authorization and Access Management
+operation on the specified resource.
------------------------------------
-
-MinIO requires each client to :ref:`authenticate
-<minio-authentication-and-identity-management>` 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*. 
 
 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 <minio-policy-actions>` and :ref:`conditions
-<minio-policy-conditions>` that outline the permissions of a 
+<minio-policy-conditions>` that outline the permissions of a :ref:`user
-:ref:`user <minio-users>` or :ref:`group <minio-groups>` of
+<minio-users>` or :ref:`group <minio-groups>` of users. By default, MinIO
-users. By default, MinIO *denies* access to actions or resources not explicitly
+*denies* access to actions or resources not explicitly referenced in a user's
-referenced in a user's assigned or inherited policies.
+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