diff --git a/source/includes/common-minio-external-auth.rst b/source/includes/common-minio-external-auth.rst new file mode 100644 index 00000000..f2f3949a --- /dev/null +++ b/source/includes/common-minio-external-auth.rst @@ -0,0 +1,237 @@ +.. Descriptions for External Identity Management using an OpenID Connect-compatible Provider + Used in the following files: + - /source/reference/minio-server/minio-server.rst + - /source/reference/minio-cli/minio-mc-admin/mc-admin-config.rst + - /source/security/identity-management/external-identity-management-openid/* + + +.. start-minio-openid-client-id + +Specify the unique public identifier MinIO uses when authenticating user +credentials against the :abbr:`OIDC (OpenID Connect)` compatible provider. + +.. end-minio-openid-client-id + +.. start-minio-openid-jwks-url + +Specify the URL for the JSON Web Key Set (JWKS) for MinIO to use when verifying +any JSON Web Tokens (JWT) issued by the :abbr:`OIDC (OpenID Connect)` compatible +provider. + +.. end-minio-openid-jwks-url + +.. start-minio-openid-config-url + +Specify the URL for the :abbr:`OIDC (OpenID Connect)` compatible provider +`discovery document +`__. + +The :abbr:`OIDC (OpenID Connect)` Discovery URL typically resembles the +following: + +``https://openid-provider.example.net/.well-known/openid-configuration`` + +.. end-minio-openid-config-url + +.. start-minio-openid-claim-name + +Specify the name of the +`JWT Claim `__ +MinIO uses to identify the :ref:`policies ` to attach to the +authenticated user. + +The claim can contain one or more comma-separated policy names to attach to +the user. The claim must contain *at least* one policy for the user to have +any permissions on the MinIO server. + +Defaults to ``policy``. + +.. end-minio-openid-claim-name + +.. start-minio-openid-claim-prefix + +Specify the +`JWT Claim `__ +namespace prefix to apply to the specified claim name. + +.. end-minio-openid-claim-prefix + +.. start-minio-openid-scopes + +Specify a comma-separated list of +`scopes `__. +Defaults to those scopes advertised in the discovery document. + +.. end-minio-openid-scopes + +.. start-minio-openid-comment + +Specify a comment to associate with the :abbr:`OIDC (OpenID Connect)` compatible +provider configuration. + +.. end-minio-openid-comment + +.. Descriptions for External Identity Management using an AD/LDAP Provider + Used in the following files: + - /source/reference/minio-server/minio-server.rst + - /source/reference/minio-cli/minio-mc-admin/mc-admin-config.rst + - /source/security/identity-management/ad-ldap-external-identity-management/* + + +.. start-minio-ad-ldap-server-addr + +Specify the hostname for the Active Directory / LDAP server. For example: + +``https://ldapserver.com:636`` + +.. end-minio-ad-ldap-server-addr + +.. start-minio-ad-ldap-sts-expiry + +Specify the duration for which the credentials are valid as ````. +Valid time units are as follows: + +- ``s`` - seconds. +- ``m`` - minutes. +- ``h`` - hours. +- ``d`` - days + +The default is ``1h`` or 1 hour. + +.. end-minio-ad-ldap-sts-expiry + +.. start-minio-ad-ldap-lookup-bind-dn + +Specify the Distinguished Name (DN) for an AD/LDAP account MinIO uses when +querying the AD/LDAP server. Enables :ref:`Lookup-Bind +` authentication to the AD/LDAP server. + +The DN account should be a read-only service account with sufficient +privileges to support querying performing user and group lookups. + +.. end-minio-ad-ldap-lookup-bind-dn + +.. start-minio-ad-ldap-lookup-bind-password + +Specify the password for the :ref:`Lookup-Bind +` user account. + +.. end-minio-ad-ldap-lookup-bind-password + +.. start-minio-ad-ldap-user-dn-search-base-dn + +Specify the base Distinguished name (DN) MinIO uses when querying for +user credentials matching those provided by an authenticating client. +For example: + +``cn=miniousers,dc=myldapserver,dc=net`` + +Supports :ref:`Lookup-Bind ` mode. + +.. end-minio-ad-ldap-user-dn-search-base-dn + +.. start-minio-ad-ldap-user-dn-search-filter + +Specify the AD/LDAP search filter MinIO uses when querying for user credentials +matching those provided by an authenticating client. + +Use the ``%s`` substitution character to insert the client-specified +username into the search string. For example: + +.. code-block:: shell + :class: copyable + + (userPrincipalName=%s) + +.. end-minio-ad-ldap-user-dn-search-filter + +.. start-minio-ad-ldap-username-format + +Specify a comma-separated list of Distinguished Name templates used for +querying the AD/LDAP server. MinIO attempts to login to the AD/LDAP server +by applying the user credentials specified by the authenticating client to +each DN template. + +Use the ``%s`` substitution character to insert the client-specified username +into the search string. For example: + +.. code-block:: shell + :class: copyable + + uid=%s,cn=miniousers,dc=myldapserver,dc=net,userPrincipalName=%s,cn=miniousers,dc=myldapserver,dc=net + +MinIO uses the *first* DN template that results in successful login to +perform a group lookup for that user. + +.. end-minio-ad-ldap-username-format + +.. start-minio-ad-ldap-group-search-filter + +Specify an AD/LDAP search filter for performing group lookups for the +authenticated user + +Use the ``%s`` substitution character to insert the client-specified username +into the search string. Use the ``%d`` substitution character to insert the +Distinguished Name of the client-specified username into the search string. + +For example: + +.. code-block:: shell + :class: copyable + + (&(objectclass=groupOfNames)(memberUid=%s)) + +.. end-minio-ad-ldap-group-search-filter + +.. start-minio-ad-ldap-group-search-base-dn + +Specify a comma-separated list of group search base Distinguished Names +MinIO uses when performing group lookups. + +For example: + +.. code-block:: shell + :class: copyable + + cn=miniogroups,dc=myldapserver,dc=net" + +.. end-minio-ad-ldap-group-search-base-dn + +.. start-minio-ad-ldap-tls-skip-verify + +Specify ``on`` to trust the AD/LDAP server TLS certificates without +verification. This option may be required if the AD/LDAP server TLS certificates +are signed by an untrusted Certificate Authority (e.g. self-signed). + +Defaults to ``off`` + +.. end-minio-ad-ldap-tls-skip-verify + +.. start-minio-ad-ldap-server-insecure + +Specify ``on`` to allow unsecured (non-TLS encrypted) connections to +the AD/LDAP server. + +MinIO sends AD/LDAP user credentials in plain text to the AD/LDAP server, such +that enabling TLS is *required* to prevent reading credentials over the wire. +Using this option presents a security risk where any user with access to +network traffic can observe the unencrypted plaintext credentials. + +Defaults to ``off``. + +.. end-minio-ad-ldap-server-insecure + +.. start-minio-ad-ldap-server-starttls + +Specify ``on`` to enable +`StartTLS `__ connections to AD/LDAP server. + +Defaults to ``off`` + +.. end-minio-ad-ldap-server-starttls + +.. start-minio-ad-ldap-comment + +Specify a comment to associate to the AD/LDAP configuration. + +.. end-minio-ad-ldap-comment \ No newline at end of file diff --git a/source/includes/common-minio-tiering.rst b/source/includes/common-minio-tiering.rst index 10d3f572..b3586007 100644 --- a/source/includes/common-minio-tiering.rst +++ b/source/includes/common-minio-tiering.rst @@ -88,7 +88,7 @@ secret key as per your organizations best practices for password generation. This example assumes that the specified aliases have the necessary permissions for creating policies and users -on the deployment. See :ref:`minio-users` and :ref:`minio-policy` for more +on the deployment. See :ref:`minio-users` and :ref:`MinIO Policy Based Access Control ` for more complete documentation on MinIO users and policies respectively. .. end-create-transition-user-desc \ No newline at end of file diff --git a/source/reference/minio-cli/minio-mc-admin/mc-admin-group.rst b/source/reference/minio-cli/minio-mc-admin/mc-admin-group.rst index 3cdc3fe7..7cc7b533 100644 --- a/source/reference/minio-cli/minio-mc-admin/mc-admin-group.rst +++ b/source/reference/minio-cli/minio-mc-admin/mc-admin-group.rst @@ -50,7 +50,7 @@ assigned policies, use the :mc-cmd:`mc admin policy set` command. For more information on MinIO users and groups, see :ref:`minio-users` and :ref:`minio-groups`. For -more information on MinIO policies, see :ref:`minio-policy`. +more information on MinIO policies, see :ref:`MinIO Policy Based Access Control `. .. admonition:: ``Deny`` overrides ``Allow`` :class: note 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 130b20b4..8cb30466 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 @@ -23,7 +23,7 @@ documents to define rules for accessing resources on a MinIO server. For complete documentation on MinIO PBAC, including policy document JSON structure and syntax, see -:ref:`minio-auth-authz-overview`. +:ref:`minio-access-management`. Examples -------- diff --git a/source/reference/minio-cli/minio-mc-admin/mc-admin-user.rst b/source/reference/minio-cli/minio-mc-admin/mc-admin-user.rst index ccfb862f..be0dd0f6 100644 --- a/source/reference/minio-cli/minio-mc-admin/mc-admin-user.rst +++ b/source/reference/minio-cli/minio-mc-admin/mc-admin-user.rst @@ -56,7 +56,7 @@ permission *and* the inherited permissions from each of their assigned groups. For more information on MinIO users and groups, see :ref:`minio-users` and :ref:`minio-groups`. For -more information on MinIO policies, see :ref:`minio-policy`. +more information on MinIO policies, see :ref:`MinIO Policy Based Access Control `. .. admonition:: ``Deny`` overrides ``Allow`` :class: note 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 9470155f..b5e36c6d 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 @@ -1929,3 +1929,280 @@ using these environment variables. This configuration setting corresponds with the :envvar:`MINIO_NOTIFY_WEBHOOK_COMMENT` environment variable. + +Active Directory / LDAP Identity Management +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following section documents settings for enabling external identity +management using an Active Directory or LDAP service. See +:ref:`minio-external-identity-management-ad-ldap` for a tutorial on using these +configuration settings. + +.. mc-conf:: identity_ldap + + The top-level key for configuring + :ref:`external identity management using Active Directory or LDAP + `. + + Use the :mc-cmd:`mc admin config set` to set or update the + AD/LDAP configuration. The following arguments are *required*: + + - :mc-conf:`~identity_ldap.server_addr` + - :mc-conf:`~identity_ldap.lookup_bind_dn` + + .. 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" + + The :mc-conf:`identity_ldap` configuration key supports the following + arguments: + + .. mc-conf:: server_addr + :delimiter: " " + + *Required* + + .. include:: /includes/common-minio-external-auth.rst + :start-after: start-minio-ad-ldap-server-addr + :end-before: end-minio-ad-ldap-server-addr + + This environment configuration setting with the + :envvar:`MINIO_IDENTITY_LDAP_SERVER_ADDR` environment variable. + + .. mc-conf:: sts_expiry + :delimiter: " " + + *Optional* + + .. include:: /includes/common-minio-external-auth.rst + :start-after: start-minio-ad-ldap-sts-expiry + :end-before: end-minio-ad-ldap-sts-expiry + + This environment configuration setting with the + :envvar:`MINIO_IDENTITY_LDAP_STS_EXPIRY` environment variable. + + .. mc-conf:: lookup_bind_dn + :delimiter: " " + + *Required* + + .. include:: /includes/common-minio-external-auth.rst + :start-after: start-minio-ad-ldap-lookup-bind-dn + :end-before: end-minio-ad-ldap-lookup-bind-dn + + This environment configuration setting with the + :envvar:`MINIO_IDENTITY_LDAP_LOOKUP_BIND_DN` environment variable. + + .. mc-conf:: lookup_bind_password + :delimiter: " " + + *Optional* + + .. include:: /includes/common-minio-external-auth.rst + :start-after: start-minio-ad-ldap-lookup-bind-password + :end-before: end-minio-ad-ldap-lookup-bind-password + + This environment variable configuration setting the + :envvar:`MINIO_IDENTITY_LDAP_LOOKUP_BIND_PASSWORD` environment variable. + + .. mc-conf:: user_dn_search_base_dn + :delimiter: " " + + *Optional* + + .. include:: /includes/common-minio-external-auth.rst + :start-after: start-minio-ad-ldap-user-dn-search-base-dn + :end-before: end-minio-ad-ldap-user-dn-search-base-dn + + This environment variable configuration setting the + :envvar:`MINIO_IDENTITY_LDAP_USER_DN_SEARCH_BASE_DN` environment variable. + + .. mc-conf:: user_dn_search_filter + :delimiter: " " + + *Optional* + + .. include:: /includes/common-minio-external-auth.rst + :start-after: start-minio-ad-ldap-user-dn-search-filter + :end-before: end-minio-ad-ldap-user-dn-search-filter + + This environment variable configuration setting the + :envvar:`MINIO_IDENTITY_LDAP_USER_DN_SEARCH_FILTER` environment variable. + + .. mc-conf:: username_format + :delimiter: " " + + *Optional* + + .. include:: /includes/common-minio-external-auth.rst + :start-after: start-minio-ad-ldap-username-format + :end-before: end-minio-ad-ldap-username-format + + This environment configuration setting with the + :envvar:`MINIO_IDENTITY_LDAP_USERNAME_FORMAT` environment variable. + + .. mc-conf:: group_search_filter + :delimiter: " " + + *Optional* + + .. include:: /includes/common-minio-external-auth.rst + :start-after: start-minio-ad-ldap-group-search-filter + :end-before: end-minio-ad-ldap-group-search-filter + + This environment variable configuration setting the + :envvar:`MINIO_IDENTITY_LDAP_GROUP_SEARCH_FILTER` environment variable. + + .. mc-conf:: group_search_base_dn + :delimiter: " " + + *Optional* + + .. include:: /includes/common-minio-external-auth.rst + :start-after: start-minio-ad-ldap-group-search-base-dn + :end-before: end-minio-ad-ldap-group-search-base-dn + + This environment variable configuration setting the + :envvar:`MINIO_IDENTITY_LDAP_GROUP_SEARCH_BASE_DN` environment variable. + + .. mc-conf:: tls_skip_verify + :delimiter: " " + + *Optional* + + .. include:: /includes/common-minio-external-auth.rst + :start-after: start-minio-ad-ldap-tls-skip-verify + :end-before: end-minio-ad-ldap-tls-skip-verify + + This environment configuration setting with the + :envvar:`MINIO_IDENTITY_LDAP_TLS_SKIP_VERIFY` environment variable. + + .. mc-conf:: server_insecure + :delimiter: " " + + *Optional* + + .. include:: /includes/common-minio-external-auth.rst + :start-after: start-minio-ad-ldap-server-insecure + :end-before: end-minio-ad-ldap-server-insecure + + This environment configuration setting with the + :envvar:`MINIO_IDENTITY_LDAP_SERVER_INSECURE` environment variable. + + .. mc-conf:: server_starttls + :delimiter: " " + + *Optional* + + .. include:: /includes/common-minio-external-auth.rst + :start-after: start-minio-ad-ldap-server-starttls + :end-before: end-minio-ad-ldap-server-starttls + + This environment configuration setting with the + :envvar:`MINIO_IDENTITY_LDAP_SERVER_STARTTLS` environment variable. + + .. mc-conf:: comment + :delimiter: " " + + *Optional* + + .. include:: /includes/common-minio-external-auth.rst + :start-after: start-minio-ad-ldap-comment + :end-before: end-minio-ad-ldap-comment + + This configuration setting corresponds with the + :envvar:`MINIO_IDENTITY_LDAP_COMMENT` environment variable. + +OpenID Identity Management +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following section documents settings for enabling external identity +management using an OpenID Connect (OIDC)-compatible provider. +See :ref:`minio-external-identity-management-openid` for a tutorial on using these +configuration settings. + +.. mc-conf:: identity_openid + + The top-level configuration key for configuring + :ref:`external identity management using OpenID `. + + Use :mc-cmd:`mc admin config set` to set or update the OpenID configuration. + The :mc-conf:`~identity_openid.config_url` argument is *required*. Specify + additional optional arguments as a whitespace (``" "``)-delimited list. + + .. code-block:: shell + :class: copyable + + mc admin config set identity_openid \ + config_url="https://openid-provider.example.net/.well-known/openid-configuration" + [ARGUMENT="VALUE"] ... \ + + The :mc-conf:`identity_openid` configuration key supports the following + arguments: + + .. mc-conf:: config_url + :delimiter: " " + + *Required* + + .. include:: /includes/common-minio-external-auth.rst + :start-after: start-minio-openid-config-url + :end-before: end-minio-openid-config-url + + This configuration setting corresponds with the + :envvar:`MINIO_IDENTITY_OPENID_CONFIG_URL` environment variable. + + .. mc-conf:: client_id + :delimiter: " " + + .. include:: /includes/common-minio-external-auth.rst + :start-after: start-minio-openid-client-id + :end-before: end-minio-openid-client-id + + This configuration setting corresponds with the + :envvar:`MINIO_IDENTITY_OPENID_CLIENT_ID` environment variable. + + .. mc-conf:: claim_name + :delimiter: " " + + .. include:: /includes/common-minio-external-auth.rst + :start-after: start-minio-openid-claim-name + :end-before: end-minio-openid-claim-name + + This configuration setting corresponds with the + :envvar:`MINIO_IDENTITY_OPENID_CLAIM_NAME` environment variable. + + .. mc-conf:: claim_prefix + :delimiter: " " + + .. include:: /includes/common-minio-external-auth.rst + :start-after: start-minio-openid-claim-prefix + :end-before: end-minio-openid-claim-prefix + + This configuration setting corresponds with the + :envvar:`MINIO_IDENTITY_OPENID_CLAIM_PREFIX` environment variable. + + .. mc-conf:: scopes + :delimiter: " " + + .. include:: /includes/common-minio-external-auth.rst + :start-after: start-minio-openid-scopes + :end-before: end-minio-openid-scopes + + This configuration setting corresponds with the + :envvar:`MINIO_IDENTITY_OPENID_SCOPES` environment variable. + + .. mc-conf:: comment + :delimiter: " " + + .. include:: /includes/common-minio-external-auth.rst + :start-after: start-minio-openid-comment + :end-before: end-minio-openid-comment + + This configuration setting corresponds with the + :envvar:`MINIO_IDENTITY_OPENID_COMMENT` environment variable. + \ No newline at end of file diff --git a/source/reference/minio-cli/minio-mc.rst b/source/reference/minio-cli/minio-mc.rst index 4cea897f..ee9d6ed4 100644 --- a/source/reference/minio-cli/minio-mc.rst +++ b/source/reference/minio-cli/minio-mc.rst @@ -116,7 +116,7 @@ unsuccessful, check each of the following: S3 service. The user must have permission to perform actions on the service. - For MinIO deployments, see :ref:`minio-auth-authz-overview` + For MinIO deployments, see :ref:`minio-access-management` for more information on user access permissions. For other S3-compatible services, defer to the documentation for that service. diff --git a/source/reference/minio-cli/minio-mc/mc-alias.rst b/source/reference/minio-cli/minio-mc/mc-alias.rst index db18eadc..a9c1d226 100644 --- a/source/reference/minio-cli/minio-mc/mc-alias.rst +++ b/source/reference/minio-cli/minio-mc/mc-alias.rst @@ -38,7 +38,7 @@ if the specified credentials do not have read/write access to a specific bucket, :program:`mc` cannot perform read or write operations on that bucket. For more information on MinIO Access Control, see -:ref:`minio-auth-authz-overview`. +:ref:`minio-access-management`. For more complete documentation on S3 Access Control, see :s3-docs:`Amazon S3 Security `. diff --git a/source/reference/minio-server/minio-server.rst b/source/reference/minio-server/minio-server.rst index c5e4ecc0..fa434c01 100644 --- a/source/reference/minio-server/minio-server.rst +++ b/source/reference/minio-server/minio-server.rst @@ -2126,3 +2126,250 @@ endpoints as ``PRIMARY`` and ``SECONDARY`` respectively: This environment variable corresponds with the :mc-conf:`notify_webhook comment ` configuration setting. + +.. _minio-server-envvar-external-identity-management-ad-ldap: + +Active Directory / LDAP Identity Management +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following section documents environment variables for enabling +external identity management using an Active Directory or LDAP service. +See :ref:`minio-external-identity-management-ad-ldap` for a tutorial on using these +variables. + +.. envvar:: MINIO_IDENTITY_LDAP_SERVER_ADDR + + *Required* + + .. include:: /includes/common-minio-external-auth.rst + :start-after: start-minio-ad-ldap-server-addr + :end-before: end-minio-ad-ldap-server-addr + + This environment variable corresponds with the + :mc-conf:`identity_ldap server_addr + ` configuration setting. + +.. envvar:: MINIO_IDENTITY_LDAP_STS_EXPIRY + + *Optional* + + .. include:: /includes/common-minio-external-auth.rst + :start-after: start-minio-ad-ldap-sts-expiry + :end-before: end-minio-ad-ldap-sts-expiry + + This environment variable corresponds with the + :mc-conf:`identity_ldap sts_expiry + ` configuration setting. + +.. envvar:: MINIO_IDENTITY_LDAP_LOOKUP_BIND_DN + + *Required* + + .. include:: /includes/common-minio-external-auth.rst + :start-after: start-minio-ad-ldap-lookup-bind-dn + :end-before: end-minio-ad-ldap-lookup-bind-dn + + This environment variable corresponds with the + :mc-conf:`identity_ldap lookup_bind_dn + ` configuration setting. + +.. envvar:: MINIO_IDENTITY_LDAP_LOOKUP_BIND_PASSWORD + + *Optional* + + .. include:: /includes/common-minio-external-auth.rst + :start-after: start-minio-ad-ldap-lookup-bind-password + :end-before: end-minio-ad-ldap-lookup-bind-password + + This environment variable corresponds with the + :mc-conf:`identity_ldap lookup_bind_password + ` configuration setting. + +.. envvar:: MINIO_IDENTITY_LDAP_USER_DN_SEARCH_BASE_DN + + *Optional* + + .. include:: /includes/common-minio-external-auth.rst + :start-after: start-minio-ad-ldap-user-dn-search-base-dn + :end-before: end-minio-ad-ldap-user-dn-search-base-dn + + This environment variable corresponds with the + :mc-conf:`identity_ldap user_dn_search_base_dn + ` configuration setting. + +.. envvar:: MINIO_IDENTITY_LDAP_USER_DN_SEARCH_FILTER + + *Optional* + + .. include:: /includes/common-minio-external-auth.rst + :start-after: start-minio-ad-ldap-user-dn-search-filter + :end-before: end-minio-ad-ldap-user-dn-search-filter + + This environment variable corresponds with the + :mc-conf:`identity_ldap user_dn_search_filter + ` configuration setting. + +.. envvar:: MINIO_IDENTITY_LDAP_USERNAME_FORMAT + + *Optional* + + .. include:: /includes/common-minio-external-auth.rst + :start-after: start-minio-ad-ldap-username-format + :end-before: end-minio-ad-ldap-username-format + + This environment variable corresponds with the + :mc-conf:`identity_ldap username_format + ` configuration setting. + +.. envvar:: MINIO_IDENTITY_LDAP_GROUP_SEARCH_FILTER + + *Optional* + + .. include:: /includes/common-minio-external-auth.rst + :start-after: start-minio-ad-ldap-group-search-filter + :end-before: end-minio-ad-ldap-group-search-filter + + This environment variable corresponds with the + :mc-conf:`identity_ldap group_search_filter + ` configuration setting. + +.. envvar:: MINIO_IDENTITY_LDAP_GROUP_SEARCH_BASE_DN + + *Optional* + + .. include:: /includes/common-minio-external-auth.rst + :start-after: start-minio-ad-ldap-group-search-base-dn + :end-before: end-minio-ad-ldap-group-search-base-dn + + This environment variable corresponds with the + :mc-conf:`identity_ldap group_search_base_dn + ` configuration setting. + +.. envvar:: MINIO_IDENTITY_LDAP_TLS_SKIP_VERIFY + + *Optional* + + .. include:: /includes/common-minio-external-auth.rst + :start-after: start-minio-ad-ldap-tls-skip-verify + :end-before: end-minio-ad-ldap-tls-skip-verify + + This environment variable corresponds with the + :mc-conf:`identity_ldap tls_skip_verify + ` configuration setting. + +.. envvar:: MINIO_IDENTITY_LDAP_SERVER_INSECURE + + *Optional* + + .. include:: /includes/common-minio-external-auth.rst + :start-after: start-minio-ad-ldap-server-insecure + :end-before: end-minio-ad-ldap-server-insecure + + This environment variable corresponds with the + :mc-conf:`identity_ldap server_insecure + ` configuration setting. + +.. envvar:: MINIO_IDENTITY_LDAP_SERVER_STARTTLS + + *Optional* + + .. include:: /includes/common-minio-external-auth.rst + :start-after: start-minio-ad-ldap-server-starttls + :end-before: end-minio-ad-ldap-server-starttls + + This environment variable corresponds with the + :mc-conf:`identity_ldap server_starttls + ` configuration setting. + +.. envvar:: MINIO_IDENTITY_LDAP_COMMENT + + *Optional* + + .. include:: /includes/common-minio-external-auth.rst + :start-after: start-minio-ad-ldap-comment + :end-before: end-minio-ad-ldap-comment + + This environment variable corresponds with the + :mc-conf:`identity_ldap comment + ` configuration setting. + +.. _minio-server-envvar-external-identity-management-openid: + +OpenID Identity Management +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following section documents environment variables for enabling external +identity management using an OpenID Connect (OIDC)-compatible provider. See +:ref:`minio-external-identity-management-openid` for a tutorial on using these variables. + +.. envvar:: MINIO_IDENTITY_OPENID_CONFIG_URL + + *Required* + + .. include:: /includes/common-minio-external-auth.rst + :start-after: start-minio-openid-config-url + :end-before: end-minio-openid-config-url + + This environment variable corresponds with the + :mc-conf:`identity_openid config_url + ` setting. + +.. envvar:: MINIO_IDENTITY_OPENID_CLIENT_ID + + *Optional* + + .. include:: /includes/common-minio-external-auth.rst + :start-after: start-minio-openid-client-id + :end-before: end-minio-openid-client-id + + This environment variable corresponds with the + :mc-conf:`identity_openid client_id + ` setting. + +.. envvar:: MINIO_IDENTITY_OPENID_CLAIM_NAME + + *Optional* + + .. include:: /includes/common-minio-external-auth.rst + :start-after: start-minio-openid-claim-name + :end-before: end-minio-openid-claim-name + + This environment variable corresponds with the + :mc-conf:`identity_openid claim_name + ` setting. + +.. envvar:: MINIO_IDENTITY_OPENID_CLAIM_PREFIX + + *Optional* + + .. include:: /includes/common-minio-external-auth.rst + :start-after: start-minio-openid-claim-prefix + :end-before: end-minio-openid-claim-prefix + + This environment variable corresponds with the + :mc-conf:`identity_openid claim_prefix + ` setting. + +.. envvar:: MINIO_IDENTITY_OPENID_SCOPES + + *Optional* + + .. include:: /includes/common-minio-external-auth.rst + :start-after: start-minio-openid-scopes + :end-before: end-minio-openid-scopes + + This environment variable corresponds with the + :mc-conf:`identity_openid scopes + ` setting. + +.. envvar:: MINIO_IDENTITY_OPENID_COMMENT + + *Optional* + + .. include:: /includes/common-minio-external-auth.rst + :start-after: start-minio-openid-comment + :end-before: end-minio-openid-comment + + This environment variable corresponds with the + :mc-conf:`identity_openid comment + ` setting. diff --git a/source/replication/enable-server-side-one-way-bucket-replication.rst b/source/replication/enable-server-side-one-way-bucket-replication.rst index ffd7b09e..77760b44 100644 --- a/source/replication/enable-server-side-one-way-bucket-replication.rst +++ b/source/replication/enable-server-side-one-way-bucket-replication.rst @@ -302,7 +302,7 @@ The following examples use ``Alpha`` and ``Baker`` as placeholder :mc:`aliases appropriate aliases for the MinIO clusters on which you are configuring bucket replication. These examples assume that the specified aliases have the necessary permissions for creating policies and users on both clusters. See -:ref:`minio-users` and :ref:`minio-policy` for more complete documentation on +:ref:`minio-users` and :ref:`MinIO Policy Based Access Control ` for more complete documentation on MinIO users and policies respectively. A\) Create Replication Administrator diff --git a/source/replication/enable-server-side-two-way-bucket-replication.rst b/source/replication/enable-server-side-two-way-bucket-replication.rst index 67a97f26..35dcd8de 100644 --- a/source/replication/enable-server-side-two-way-bucket-replication.rst +++ b/source/replication/enable-server-side-two-way-bucket-replication.rst @@ -309,7 +309,7 @@ The following examples use ``Alpha`` and ``Baker`` as placeholder :mc:`aliases appropriate aliases for the MinIO clusters on which you are configuring bucket replication. These examples assume that the specified aliases have the necessary permissions for creating policies and users on both clusters. See -:ref:`minio-users` and :ref:`minio-policy` for more complete documentation on +:ref:`minio-users` and :ref:`MinIO Policy Based Access Control ` for more complete documentation on MinIO users and policies respectively. A\) Create Replication Administrators diff --git a/source/security/IAM/iam-groups.rst b/source/security/IAM/iam-groups.rst deleted file mode 100644 index ef910b7d..00000000 --- a/source/security/IAM/iam-groups.rst +++ /dev/null @@ -1,80 +0,0 @@ -.. _minio-groups: - -====== -Groups -====== - -.. 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. - -.. 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 - `. - -Create a Group --------------- - -Use the :mc-cmd:`mc admin group add` command to add a user to a group. -MinIO implicitly creates the group if it does not already exist. You cannot -create empty groups: - -Delete a Group --------------- - -Use the :mc-cmd:`mc admin group remove` command to remove a group: \ No newline at end of file diff --git a/source/security/IAM/iam-security-token-service.rst b/source/security/IAM/iam-security-token-service.rst deleted file mode 100644 index 88233421..00000000 --- a/source/security/IAM/iam-security-token-service.rst +++ /dev/null @@ -1,81 +0,0 @@ -.. _minio-sts: - -:orphan: - -====================== -Security Token Service -====================== - -.. default-domain:: minio - -.. contents:: Table of Contents - :local: - :depth: 2 - -.. important:: - - This page is under active development and isn't ready for prime-time. - If you've found this page, consider checking out our legacy documentation on - :legacy:`MinIO STS Quickstart Guide ` - for more information. - -Overview --------- - -The MinIO Security Token Service (STS) is an endpoint service that enables -clients to request temporary credentials for MinIO resources. Temporary -credentials work almost identically to default admin credentials, with some -differences: - -- Temporary credentials are short-term, as the name implies. They can be - configured to last for anywhere from a few minutes to several hours. After the - credentials expire, MinIO no longer recognizes them or allows any kind of - access from API requests made with them. - -- Temporary credentials do not need to be stored with the application but are - generated dynamically and provided to the application when requested. When (or - even before) the temporary credentials expire, the application can request new - credentials. - -Consider the following advantages of using temporary credentials: - -- Eliminates the need to embed long-term credentials with an application. - -- Eliminates the need to provide access to buckets and objects without having to - define static credentials. - -- Temporary credentials have a limited lifetime, there is no need to rotate them - or explicitly revoke them. Expired temporary credentials cannot be reused. - -Identity Federation -------------------- - -MinIO STS supports the following identity federation providers: - -.. list-table:: - :header-rows: 1 - :widths: 30 70 - - * - Provider - - Description - - * - OpenID Providers - - Applications can request a client credential grant from an - OpenID-compatible identity provider. Clients validate their identity - using a JWT access token supplied by the identity provider. - - See for more information on configuring OpenID-based identity - federation. - - * - OpenID WebIdentity - - Applications can request temporary credentials using any OpenID (OIDC) - compatible web identity provider. See for more information. - - * - AssumeRole - - Applications can request temporary credentials using a MinIO User - access and secret key. - - * - Active Directory / Lightweight Directory Access Protocol (AD/LDAP) - - Applications can request temporary credentials using an external - AD/LDAP service. - diff --git a/source/security/IAM/iam-users.rst b/source/security/IAM/iam-users.rst deleted file mode 100644 index c1c65c98..00000000 --- a/source/security/IAM/iam-users.rst +++ /dev/null @@ -1,167 +0,0 @@ -.. _minio-users: - -===== -Users -===== - -.. default-domain:: minio - -.. contents:: Table of Contents - :local: - :depth: 2 - -Overview --------- - -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 can have one or more assigned :ref:`policies ` that -explicitly list the actions and resources to which the user is allowed or denied -access. A user can also have membership in a :ref:`group `, where -the user inherits any policies assigned to the group. Policies support -*authorization* on the MinIO deployment, such that clients can only access a -resource or operation if the user's assigned and inherited policies explicitly -grant. MinIO by default *denies* access to any resource or operation not -explicitly allowed by a user's assigned or inherited policies. - -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: - -.. list-table:: - :header-rows: 1 - :widths: 20 40 40 - :width: 100% - - * - User - - Policy - - Operations - - * - ``Operations`` - - | :userpolicy:`readwrite` on ``finance`` bucket - | :userpolicy:`readonly` on ``audit`` bucket - - - | ``PUT`` and ``GET`` on ``finance`` bucket. - | ``PUT`` on ``audit`` bucket - - * - ``Auditing`` - - | :userpolicy:`readonly` on ``audit`` bucket - - ``GET`` on ``audit`` bucket - - * - ``Admin`` - - :policy-action:`admin:*` - - All :mc-cmd:`mc admin` commands. - -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. - -.. admonition:: ``Deny`` overrides ``Allow`` - :class: note - - MinIO follows the 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 - `. - -.. _minio-users-root: - -``root`` User -~~~~~~~~~~~~~ - -MinIO deployments have a ``root`` user with access to all actions and resources -on the deployment. 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. - -When specifying the ``root`` access key and secret key, consider using *long, -unique, and random* strings. 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. - -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. - -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` 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. diff --git a/source/security/IAM/identity-access-management.rst b/source/security/IAM/identity-access-management.rst deleted file mode 100644 index 0e6055b8..00000000 --- a/source/security/IAM/identity-access-management.rst +++ /dev/null @@ -1,102 +0,0 @@ -.. _minio-auth-authz-overview: - -============================== -Identity and Access Management -============================== - -.. default-domain:: minio - -.. contents:: Table of Contents - :local: - :depth: 2 - -Overview --------- - -*Authentication* is the process of verifying the identity of a connecting -client. MinIO authentication requires providing user credentials in the form of -an access key (username) and corresponding secret key (password). The MinIO -deployment only grants access *if*: - -- The access key corresponds to a user on the deployment, *and* -- The secret key corresponds to the specified access key. - -*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. - -- For more information on MinIO user management, see - :ref:`minio-users`. - -- For more information on MinIO group management, see - :ref:`minio-groups`. - -- For more information on MinIO policy creation, see - :ref:`minio-policy`. - -Users and Groups ----------------- - -MinIO requires that client's *authenticate* using an access key and secret key -that correspond to a :ref:`user `. A user can have membership in -one or more :ref:`groups `, where the user inherits any privileges -associated to each group. MinIO *authorizes* the client to access only those -resources and operations which the user's assigned or inherited :ref:`privileges -` explicitly allow. - -MinIO supports creating an arbitrary number of users and groups on the -deployment for supporting client authentication. - -- Use :mc-cmd:`mc admin user add` to create a new user. - -- Use :mc-cmd:`mc admin group add` to add users to a group. The command - implicitly creates the group if it does not exist. - -For complete documentation on creating MinIO users and groups, see -:ref:`minio-users` and :ref:`minio-groups`. - -MinIO *also* supports federating identity management to supported third-party -services through the :legacy:`Secure Token Service -`. Supported identity providers include Okta, -Facebook, Google, and Active Directory/LDAP. - -Policies --------- - -MinIO uses :ref:`Policy-Based Access Control ` (PBAC) to specify -the *authorized* resources and operations to which a :ref:`user ` -or :ref:`groups ` has access. MinIO PBAC uses AWS IAM-compatible -JSON syntax for defining policies. For example, MinIO can use IAM policies -designed for use with AWS S3 or S3-compatible services. - -MinIO provides a set of built-in policies that provide a baseline for -seperation of least privilege, such that a user has access to the minimum set -of privileges required to perform their assigned actions. MinIO also supports -customized policies, including those imported from AWS IAM or IAM-compatible -policy building tools. For more complete documentation on MinIO policies, see -:ref:`minio-policy`. - -To assign policies to users or groups, use the :mc-cmd:`mc admin policy set` -command from the :program:`mc` command line tool. - -Security Token Service ----------------------- - -The MinIO Security Token Service (STS) is an endpoint service that -enables clients to request temporary credentials for MinIO resources. - -See :legacy:`MinIO STS Quickstart Guide ` -for more information. - -.. toctree:: - :hidden: - :titlesonly: - - /security/IAM/iam-users - /security/IAM/iam-groups - /security/IAM/iam-policies \ No newline at end of file diff --git a/source/security/IAM/iam-policies.rst b/source/security/access-management/access-management-overview.rst similarity index 69% rename from source/security/IAM/iam-policies.rst rename to source/security/access-management/access-management-overview.rst index 7b891569..2a69c19e 100644 --- a/source/security/IAM/iam-policies.rst +++ b/source/security/access-management/access-management-overview.rst @@ -1,8 +1,8 @@ -.. _minio-policy: +.. _minio-access-management: -======== -Policies -======== +================= +Access Management +================= .. default-domain:: minio @@ -10,28 +10,85 @@ Policies :local: :depth: 2 +.. _minio-policy: + Overview -------- -A *policy* is a document that describes the resources and operations to which -a MinIO :ref:`user ` or the members of a :ref:`group -` have access. +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. -MinIO uses Policy-Based Access Control (PBAC) to define the *authorized* -resources and operations to which a :ref:`user ` or members of a -:ref:`group ` have access. +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 by default *denies* access to any -resource or operation not explicitly allowed by a user's assigned or inherited -policies. +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 PBAC uses AWS IAM-compatible JSON -syntax for defining policies. For example, MinIO can use IAM policies designed -for use with AWS S3 or S3-compatible services. +For MinIO deployments using an External IDP, policy assignment depends on the +choice of IDP: -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. +.. 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. + +.. 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 + `. .. _minio-policy-built-in: @@ -62,6 +119,54 @@ MinIO provides the following built-in policies for assigning to Use :mc-cmd:`mc admin policy set` to associate a policy to a user or group on a MinIO deployment. +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: + +.. list-table:: + :header-rows: 1 + :widths: 20 40 40 + :width: 100% + + * - User + - Policy + - Operations + + * - ``Operations`` + - | :userpolicy:`readwrite` on ``finance`` bucket + | :userpolicy:`readonly` on ``audit`` bucket + + - | ``PUT`` and ``GET`` on ``finance`` bucket. + | ``PUT`` on ``audit`` bucket + + * - ``Auditing`` + - | :userpolicy:`readonly` on ``audit`` bucket + - ``GET`` on ``audit`` bucket + + * - ``Admin`` + - :policy-action:`admin:*` + - All :mc-cmd:`mc admin` commands. + +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. + +.. admonition:: ``Deny`` overrides ``Allow`` + :class: note + + MinIO follows the 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 + `. + .. _minio-policy-document: Policy Document Structure @@ -658,28 +763,62 @@ MinIO supports the following conditions for use with defining policies for For complete information on any listed condition key, see the :iam-docs:`IAM Condition Element Documentation ` -Creating Custom Policies ------------------------- +.. _minio-groups: -Use the :mc-cmd:`mc admin policy add` command to add a policy to the MinIO -server. The policy *must* be a valid JSON document formatted according to -IAM policy specifications. For example: +MinIO Groups +------------ -.. code-block:: shell +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. - mc admin policy add myminio/ new_policy new_policy.json +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. -Use the :mc-cmd:`mc admin policy set` command to associate a policy to a -:ref:`user ` or :ref:`group `. +.. list-table:: + :header-rows: 1 + :widths: 20 40 40 + :width: 100% -.. code-block:: shell + * - Group + - Policy + - Members - mc admin policy set myminio/ new_policy user=user_name + * - ``Operations`` + - | :userpolicy:`readwrite` on ``finance`` bucket + | :userpolicy:`readonly` on ``audit`` bucket + + - ``john.doe``, ``jane.doe`` - mc admin policy set myminio/ new_policy group=group_name + * - ``Auditing`` + - | :userpolicy:`readonly` on ``audit`` bucket + - ``jen.doe``, ``joe.doe`` -.. note:: + * - ``Admin`` + - :policy-action:`admin:*` + - ``greg.doe``, ``jen.doe`` - ``myminio`` refers to the :mc-cmd:`alias ` of an S3-compatible - host configured for use with :program:`mc`. See :mc-cmd:`mc alias` for - more information on aliases. \ No newline at end of file +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 + `. diff --git a/source/security/ad-ldap-external-identity-management/AssumeRoleWithLDAPIdentity.rst b/source/security/ad-ldap-external-identity-management/AssumeRoleWithLDAPIdentity.rst new file mode 100644 index 00000000..0137a599 --- /dev/null +++ b/source/security/ad-ldap-external-identity-management/AssumeRoleWithLDAPIdentity.rst @@ -0,0 +1,154 @@ +.. _minio-sts-assumerolewithldapidentity: + +============================== +``AssumeRoleWithLDAPIDentity`` +============================== + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 2 + +The MinIO Security Token Service (STS) ``AssumeRoleWithLDAPIDentity`` API +endpoint generates temporary access credentials using Active Directory +or LDAP user credentials. This page documents the MinIO +server ``AssumeRoleWithLDAPIDentity`` endpoint. For instructions on +implementing STS using an S3-compatible SDK, defer to the documentation +for that SDK. + +The MinIO STS ``AssumeRoleWithLDAPIDentity`` API endpoint is modeled +after the +AWS :aws-docs:`AssumeRoleWithWebIdentity +` +endpoint and shares certain request/response elements. This page +documents the MinIO-specific syntax and links out to the AWS reference for +all shared elements. + +Request Endpoint +---------------- + +The ``AssumeRoleWithLDAPIDentity`` endpoint has the following form: + +.. code-block:: shell + + POST https://minio.example.net/Action=AssumeRoleWithLDAPIDentity[&ARGS] + +The following example uses all supported arguments. Replace the +``minio.example.net`` hostname with the appropriate URL for your MinIO +cluster: + +.. code-block:: shell + + POST https://minio.example.net/Action=AssumeRoleWithLDAPIDentity + &LDAPUsername=USERNAME + &LDAPPassword=PASSWORD + &Version=2011-06-15 + &Policy={} + +Request Query Parameters +~~~~~~~~~~~~~~~~~~~~~~~~ + +This endpoint supports the following query parameters: + +.. list-table:: + :header-rows: 1 + :widths: 20 20 60 + :width: 100% + + * - Parameter + - Type + - Description + + * - ``LDAPUsername`` + - string + - *Required* + + Specify the username of the AD/LDAP user as whom you want to + authenticate. + + * - ``LDAPPassword`` + - string + - *Required* + + Specify the password for the ``LDAPUsername``. + + * - ``Version`` + - string + - *Required* + + Specify ``2011-06-15``. + + + * - ``Policy`` + - string + - *Optional* + + Specify the URL-encoded JSON-formatted :ref:`policy ` to + use as an inline session policy. + + - The minimum string length is ``1``. + - The maximum string length is ``2048``. + + The resulting permissions for the temporary credentials are the + intersection between the :ref:`policy + ` matching the Distinguished + Name (DN) of the ``LDAPUsername`` and the specified inline policy. + Applications can only perform those operations for which they are + explicitly authorized. + + The inline policy can specify a subset of permissions allowed by the + policy specified in the DN policy. Applications can never assume + more privileges than those specified in the DN policy. + + Omit to use only the DN policy. + + See :ref:`minio-access-management` for more information on MinIO + authentication and authorization. + +Response Elements +----------------- + +The XML response for this API endpoint is similar to the AWS +:aws-docs:`AssumeRoleWithLDAPIDentity response +`. +Specifically, MinIO returns an ``AssumeRoleWithLDAPIDentityResult`` object, +where the ``AssumedRoleUser.Credentials`` object contains the temporary +credentials generated by MinIO: + +- ``AccessKeyId`` - The access key applications use for authentication. +- ``SecretKeyId`` - The secret key applications use for authentication. +- ``Expiration`` - The ISO-8601 date-time after which the credentials expire. +- ``SessionToken`` - The session token applications use for authentication. Some + SDKs may require this field when using temporary credentials. + +The following example is similar to the response returned by the MinIO STS +``AssumeRoleWithLDAPIDentity`` endpoint: + +.. code-block:: xml + + + + + + + + + + Y4RJU1RNFGK48LGO9I2S + sYLRKS1Z7hSjluf6gEbb9066hnx315wHTiACPAjg + 2019-08-08T20:26:12Z + eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhY2Nlc3NLZXkiOiJZNFJKVTFSTkZHSzQ4TEdPOUkyUyIsImF1ZCI6IlBvRWdYUDZ1Vk80NUlzRU5SbmdEWGo1QXU1WWEiLCJhenAiOiJQb0VnWFA2dVZPNDVJc0VOUm5nRFhqNUF1NVlhIiwiZXhwIjoxNTQxODExMDcxLCJpYXQiOjE1NDE4MDc0NzEsImlzcyI6Imh0dHBzOi8vbG9jYWxob3N0Ojk0NDMvb2F1dGgyL3Rva2VuIiwianRpIjoiYTBiMjc2MjktZWUxYS00M2JmLTg3MzktZjMzNzRhNGNkYmMwIn0.ewHqKVFTaP-j_kgZrcOEKroNUjk10GEp8bqQjxBbYVovV0nHO985VnRESFbcT6XMDDKHZiWqN2vi_ETX_u3Q-w + + + + + +Error Elements +-------------- + +The XML error response for this API endpoint is similar to the AWS +:aws-docs:`AssumeRoleWithLDAPIDentity response +`. + + 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 new file mode 100644 index 00000000..37431ccd --- /dev/null +++ b/source/security/ad-ldap-external-identity-management/configure-ad-ldap-external-identity-management.rst @@ -0,0 +1,211 @@ +.. _minio-authenticate-using-ad-ldap-generic: + +================================================================ +Configure MinIO for Authentication using Active Directory / LDAP +================================================================ + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 2 + +Overview +-------- + +MinIO supports using an Active Directory / LDAP Connect for external management of user +identities. The procedure on this page provides instructions for: + +- Configuring a MinIO cluster for an external AD/LDAP provider. +- Logging into the cluster using the MinIO Console and AD/LDAP credentials. +- Using the MinIO ``AssumeRoleWithLDAPIdentity`` Security Token Service (STS) + API to generate temporary credentials for use by applications. + +This procedure is generic for AD/LDAP services. Defer to the documentation for +the AD/LDAP provider of your choice for specific instructions or procedures on +configuration of user identities. + +Prerequisites +------------- + +Active Directory / LDAP Compatible IDentity Provider +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This procedure assumes an existing Active Directory or LDAP service. +Instructions on configuring AD/LDAP are out of scope for this procedure. + +MinIO requires a read-only service account with which it +:ref:`binds ` to perform +authenticated user and group queries. + +MinIO Cluster +~~~~~~~~~~~~~ + +This procedure assumes an existing MinIO cluster running the +:minio-git:`latest stable MinIO version `. +This procedure *may* work as expected for older versions of MinIO. + +Install and Configure ``mc`` with Access to the MinIO Cluster +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This procedure uses :mc:`mc` for performing operations on the +MinIO cluster. Install ``mc`` on a machine with network access to the cluster. +See the ``mc`` :ref:`Installation Quickstart ` for instructions on +downloading and installing ``mc``. + +This procedure assumes a configured :mc:`alias ` for the MinIO +cluster. + +.. _minio-external-identity-management-ad-ldap-configure: + +Procedure +--------- + +1) Set the Active Directory / LDAP Configuration Settings +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can configure the AD/LDAP provider using either +environment variables *or* server runtime configuration settings. Both +methods require starting/restarting the MinIO deployment to apply changes. The +following tabs provide a quick reference of all required and optional +environment variables and configuration settings respectively: + +.. tabs:: + + .. tab:: Environment Variables + + MinIO supports specifying the AD/LDAP provider + settings using :ref:`environment variables + `. The + :mc:`minio server` process applies the specified settings on its next + startup. For distributed deployments, specify these settings across all + nodes in the deployment using the *same* values consistently. + + The following example code sets *all* environment variables related to + configuring an AD/LDAP provider for external + identity management. The minimum *required* variable are: + + - :envvar:`MINIO_IDENTITY_LDAP_SERVER_ADDR` + - :envvar:`MINIO_IDENTITY_LDAP_LOOKUP_BIND_DN` + - :envvar:`MINIO_IDENTITY_LDAP_LOOKUP_BIND_PASSWORD` + + .. code-block:: shell + :class: copyable + + + For complete documentation on these variables, see + :ref:`minio-server-envvar-external-identity-management-ad-ldap` + + .. tab:: Configuration Settings + + MinIO supports specifying the AD/LDAP provider + settings using :mc-conf:`configuration settings `. The + :mc:`minio server` process applies the specified settings on its next + startup. For distributed deployments, the :mc-cmd:`mc admin config` + command applies the configuration to all nodes in the deployment. + + The following example code sets *all* configuration settings related to + configuring an AD/LDAP provider for external + identity management. The minimum *required* setting are: + + - :mc-conf:`identity_ldap server_addr ` + + - :mc-conf:`identity_ldap lookup_bind_dn ` + + - :mc-conf:`identity_ldap lookup_bind_password ` + + .. code-block:: shell + :class: copyable + + mc admin config set ALIAS/ identity_ldap \ + + For more complete documentation on these settings, see + :mc-conf:`identity_ldap`. + +2) Restart the MinIO Deployment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You must restart the MinIO deployment to apply the configuration changes. +Use the :mc-cmd:`mc admin service restart` command to restart the deployment. + +.. important:: + + MinIO restarts *all* :mc:`minio server` processes associated to the + deployment at the same time. Applications may experience a brief period of + downtime during the restart process. + + Consider scheduling the restart during a maintenance period to minimize + interruption of services. + +.. code-block:: shell + :class: copyable + + mc admin service restart ALIAS + +Replace ``ALIAS`` with the :mc:`alias ` of the deployment to +restart. + +3) Use the MinIO Console to Log In with AD/LDAP Credentials +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The MinIO Console supports the full workflow of authenticating to the +AD/LDAP provider, generating temporary credentials using +the MinIO :ref:`minio-sts-assumerolewithldapidentity` Security Token Service +(STS) endpoint, and logging the user into the MinIO deployment. + +Starting in RELEASE, the MinIO Console is embedded in the MinIO server. +You can access the Console by opening the root URL for the MinIO cluster. +For example, ``https://minio.example.net:9001``. + +From the Console, click :guilabel:`BUTTON` to begin the Active Directory / LDAP +authentication flow. + +Once logged in, you can perform any action for which the authenticated +user is :ref:`authorized +`. + +You can also create :ref:`service accounts ` for +supporting applications which must perform operations on MinIO. Service accounts +are long-lived credentials which inherit their privileges from the parent user. +The parent user can further restrict those privileges while creating the service +account. + +4) Generate S3-Compatible Temporary Credentials using AD/LDAP Credentials +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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. + +Applications can generate temporary access credentials as-needed using the +:ref:`minio-sts-assumerolewithldapidentity` Security Token Service (STS) API +endpoint and AD/LDAP user credentials. MinIO provides an example Go application +:minio-git:`ldap.go ` with an example of +managing this workflow. + +.. code-block:: shell + + POST https://minio.example.net/Action=AssumeRoleWithLDAPIDentity + &LDAPUsername=USERNAME + &LDAPPassword=PASSWORD + &Version=2011-06-15 + &Policy={} + +- Replace the ``LDAPUsername`` with the username of the AD/LDAP user. + +- Replace the ``LDAPPassword`` with the password of the AD/LDAP user. + +- Replace the ``Policy`` with an inline URL-encoded JSON + :ref:`policy ` that further restricts the permissions associated + to the temporary credentials. Omit to use the + :ref:`policy whose name matches ` + the Distinguished Name (DN) of the AD/LDAP user. + +The API response consists of an XML document containing the +access key, secret key, session token, and expiration date. Applications +can use the access key and secret key to access and perform operations on +MinIO. + +See the :ref:`minio-sts-assumerolewithldapidentity` for reference documentation. \ No newline at end of file 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 new file mode 100644 index 00000000..1cbd4cc2 --- /dev/null +++ b/source/security/ad-ldap-external-identity-management/external-authentication-with-ad-ldap-identity-provider.rst @@ -0,0 +1,252 @@ +.. _minio-external-identity-management-ad-ldap: + +==================================================== +Active Directory / LDAP External Identity Management +==================================================== + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 2 + +Overview +-------- + +MinIO supports using an Active Directory or LDAP (AD/LDAP) service for external +management of user identities. Configuring an external IDentity Provider (IDP) +enables Single-Sign On (SSO) workflows, where applications authenticate against +the external IDP before accessing MinIO. + +MinIO by default denies access to all actions or resources not explicitly +allowed by a user's assigned or inherited :ref:`policies `. Users +managed by an AD/LDAP provider must specify the necessary policies as part of +the user profile data. See :ref:`Access Control for AD/LDAP Managed Identities +` for more +information. + +See :ref:`minio-authenticate-using-ad-ldap-generic` for instructions on enabling +external identity management using an AD/LDAP service. + +.. admonition:: MinIO Supports At Most One Configured IDentity Provider + :class: important + + Configuring an external IDP disables the :ref:`MinIO internal IDP + ` and prevents the configuration of any other + external IDP. + + The external :abbr:`IDP (IDentity Provider)` must have *at least* one + configured user identity with the required :ref:`policy claims + `. If no such user + exists, the MinIO server is effectively inaccessible outside of using the + :ref:`root ` user. + +Authentication and Authorization Flow +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The login flow for an application using Active Directory / LDAP +credentials is as follows: + +1. Specify the AD/LDAP credentials to the MinIO Security Token Service (STS) + :ref:`minio-sts-assumerolewithldapidentity` API endpoint. + +2. MinIO verifies the provided credentials against the AD/LDAP server. + +3. MinIO checks for any :ref:`policy ` whose name matches the + user Distinguished Name (DN) and assigns that policy to the authenticated + user. + + If configured to perform group queries, MinIO also queries for a list of + AD/LDAP groups in which the user has membership. MinIO checks for any policy + whose name matches a returned group DN and assigns that + policy to the authenticated user. + +4. 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 whose name matches either the authenticated user DN + *or* a group DN. + +MinIO provides an example Go application +:minio-git:`ldap.go ` that handles the +full login flow. + +As an alternative to implementing this application flow, application owners can +log into the :minio-git:`MinIO Console ` using their external +user credentials and create :ref:`service accounts ` +for their applications. Service accounts are long-lived credentials which +inherit their privileges from the parent user. The parent user can further +restrict those privileges while creating the service account. + +Querying the Active Directory / LDAP Service +-------------------------------------------- + +MinIO queries the configured Active Directory / LDAP server to verify the +credentials specified by the application and optionally return a list of groups +in which the user has membership. MinIO supports two modes for performing +these queries: + +- :ref:`minio-external-identity-management-ad-ldap-lookup-bind` - Use a special + read-only account for querying the LDAP server. + +- :ref:`minio-external-identity-management-ad-ldap-username-bind` - Use the + credentials specified by the application to login to the LDAP server. + +MinIO recommends using Lookup-Bind mode as the preferred method for verifying +AD/LDAP credentials. Username-Bind mode is a legacy method retained +for backwards compatibility only. + +.. _minio-external-identity-management-ad-ldap-lookup-bind: + +Lookup-Bind Mode +~~~~~~~~~~~~~~~~ + +In Lookup-Bind mode, MinIO uses a read-only AD/LDAP account with the minimum +privileges required to authenticate to the AD/LDAP server and perform user and +group lookups. + +The following tabs provide a reference of the environment variables and +configuration settings required for enabling Lookup-Bind mode. + +.. tabs:: + + .. tab:: Environment Variable + + - :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` + + 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 + + - :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 ` + + See the :mc-conf:`identity_ldap` reference documentation for more + information on these settings. The + :ref:`minio-authenticate-using-openid-generic` tutorial includes complete + instructions on setting these variables. + +Lookup-Bind is incompatible and mutually exclusive with +:ref:`minio-external-identity-management-ad-ldap-username-bind`. + +.. _minio-external-identity-management-ad-ldap-username-bind: + +Username-Bind Mode +~~~~~~~~~~~~~~~~~~ + +In Username-Bind mode, MinIO uses the AD/LDAP credentials provided by the client +attempting authentication to login to the AD/LDAP server and perform and group +lookups. + +Username-Bind mode is preserved for compatibility only. MinIO recommends +using :ref:`minio-external-identity-management-ad-ldap-lookup-bind` wherever possible. + +The following tabs provide a reference of the environment variables and +configuration settings required for enabling Username-Bind mode. + +.. tabs:: + + .. tab:: Environment Variable + + - :envvar:`MINIO_IDENTITY_LDAP_USERNAME_FORMAT` + + See the :ref:`minio-server-envvar-external-identity-management-ad-ldap` + reference documentation for more information on this variable. + + .. tab:: Configuration Setting + + - :mc-conf:`identity_ldap username_format ` + + See the :mc-conf:`identity_ldap` reference documentation for more + information on this setting. + +Username-bind is incompatible and mutually exclusive with +:ref:`minio-external-identity-management-ad-ldap-lookup-bind`. + +.. _minio-external-identity-management-ad-ldap-access-control: + +Access Control for Externally Managed Identities +------------------------------------------------ + +MinIO uses :ref:`Policy Based Access Control (PBAC) ` +to define the actions and resources to which an authenticated user has access. +MinIO supports creating and managing :ref:`policies ` which an +externally managed user can claim. + +For identities managed by the external Active Directory / LDAP server, +MinIO attempts to match existing policies to the authenticated user's +Distinguished Name (DN). + +MinIO also supports querying for the user's AD/LDAP group membership. MinIO +attempts to match existing policies to the DN for each of the user's groups. See +:ref:`minio-external-identity-management-ad-ldap-access-control-group-lookup` +for more information. + +For example, consider the following user and group DNs: + +.. code-block:: shell + + cn=applicationUser,cn=users,dc=example,dc=com + cn=applicationGroup,cn=groups,dc=example,dc=com + +MinIO attaches the policies with names matching the *full* DN for the user and +group to the authenticated user. + +The authenticated users complete set of permissions consists of its +explicitly assigned and inherited policies. If the user DN and group DNs +do not match any policies on the MinIO deployment, MinIO denies authorization +for any and all operations issued by that user. + +MinIO provides :ref:`built-in policies ` for basic access +control. You can create new policies using the :mc:`mc admin policy` command. +You can create new groups using the :mc:`mc admin group` command and assign +policies to that group using :mc-cmd:`mc admin policy set`. + +.. _minio-external-identity-management-ad-ldap-access-control-group-lookup: + +Group Lookup +~~~~~~~~~~~~ + +MinIO supports querying the Active Directory / LDAP server for a list of +groups in which the authenticated user has membership. MinIO +attempts to match existing :ref:`policies ` to each group +DN and assigns each matching policy to the authenticated user. + +The following tabs provide a reference of the environment variables and +configuration settings required for enabling group lookups: + +.. tabs:: + + .. tab:: Environment Variable + + - :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. + + .. tab:: Configuration Setting + + + - :mc-conf:`identity_ldap group_search_base_dn ` + - :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. + + +.. toctree:: + :titlesonly: + + /security/ad-ldap-external-identity-management/configure-ad-ldap-external-identity-management.rst + /security/ad-ldap-external-identity-management/AssumeRoleWithLDAPIdentity.rst + diff --git a/source/security/encryption/server-side-encryption-sse-s3.rst b/source/security/encryption/server-side-encryption-sse-s3.rst index 64c08494..6fc43e1c 100644 --- a/source/security/encryption/server-side-encryption-sse-s3.rst +++ b/source/security/encryption/server-side-encryption-sse-s3.rst @@ -33,8 +33,6 @@ following KMS providers: - Thales CipherTrust (formerly Gemalto KeySecure) - Hashicorp KeyVault - - Requirements ------------ 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 new file mode 100644 index 00000000..d42a824a --- /dev/null +++ b/source/security/minio-identity-management/basic-authentication-with-minio-identity-provider.rst @@ -0,0 +1,220 @@ +.. _minio-internal-idp: +.. _minio-users: + +================================== +MinIO Internal Identity Management +================================== + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 2 + +Overview +-------- + +MinIO includes a built-in IDentity Provider (IDP) that provides core identity +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. + +Administrators use the :mc-cmd:`mc admin user` command to create and manage +MinIO users. The :minio-git:`MinIO Console ` provides a graphical +interface for creating users. + +MinIO also supports creating :ref:`service accounts +`. Service accounts are child identities of an +authenticated parent user and inherit their permissions from the parent. + +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. + +.. admonition:: External Identity Management + :class: dropdown, note + + MinIO supports 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-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. + +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: + +.. list-table:: + :header-rows: 1 + :widths: 20 40 40 + :width: 100% + + * - User + - Policy + - Operations + + * - ``Operations`` + - | :userpolicy:`readwrite` on ``finance`` bucket + | :userpolicy:`readonly` on ``audit`` bucket + + - | ``PUT`` and ``GET`` on ``finance`` bucket. + | ``PUT`` on ``audit`` bucket + + * - ``Auditing`` + - | :userpolicy:`readonly` on ``audit`` bucket + - ``GET`` on ``audit`` bucket + + * - ``Admin`` + - :policy-action:`admin:*` + - All :mc-cmd:`mc admin` commands. + +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. + +.. _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. + +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. + diff --git a/source/security/openid-external-identity-management/AssumeRoleWithWebIdentity.rst b/source/security/openid-external-identity-management/AssumeRoleWithWebIdentity.rst new file mode 100644 index 00000000..d308795c --- /dev/null +++ b/source/security/openid-external-identity-management/AssumeRoleWithWebIdentity.rst @@ -0,0 +1,165 @@ +.. _minio-sts-assumerolewithwebidentity: + +============================= +``AssumeRoleWithWebIdentity`` +============================= + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 2 + +The MinIO Security Token Service (STS) ``AssumeRoleWithWebIdentity`` API +endpoint generates temporary access credentials using a +JSON Web Token (JWT) returned from a +:ref:`configured OpenID IDentity Provider (IDP) +`. This page documents the MinIO +server ``AssumeRoleWithWebIdentity`` endpoint. For instructions on +implementing STS using an S3-compatible SDK, defer to the documentation +for that SDK. + +The MinIO STS ``AssumeRoleWithWebIdentity`` API endpoint is modeled +after the +AWS :aws-docs:`AssumeRoleWithWebIdentity +` +endpoint and shares certain request/response elements. This page +documents the MinIO-specific syntax and links out to the AWS reference for +all shared elements. + +Request Endpoint +---------------- + +The ``AssumeRoleWithWebIdentity`` endpoint has the following form: + +.. code-block:: shell + + POST https://minio.example.net/Action=AssumeRoleWithWebIdentity[&ARGS] + +The following example uses all supported arguments. Replace the +``minio.example.net`` hostname with the appropriate URL for your MinIO +cluster: + +.. code-block:: shell + + POST https://minio.example.net/Action=AssumeRoleWithWebIdentity + &WebIdentityToken=TOKEN + &Version=2011-06-15 + &DurationSeconds=86000 + &Policy={} + +Request Query Parameters +~~~~~~~~~~~~~~~~~~~~~~~~ + +This endpoint supports the following query parameters: + +.. list-table:: + :header-rows: 1 + :widths: 20 20 60 + :width: 100% + + * - Parameter + - Type + - Description + + * - ``WebIdentityToken`` + - string + - *Required* + + Specify the JSON Web Token (JWT) returned by the + :ref:`configured OpenID IDentity Provider + `. + + * - ``Version`` + - string + - *Required* + + Specify ``2011-06-15``. + + * - ``DurationSeconds`` + - integer + - *Optional* + + Specify the number of seconds after which the temporary credentials + expire. Defaults to ``3600``. + + - The minimum value is ``900`` or 15 minutes. + - The maximum value is ``604800`` or 7 days. + + If ``DurationSeconds`` is omitted, MinIO checks the JWT token for an + ``exp`` claim before using the default duration. See + `RFC 7519 4.1.4: Expiration Time Claim + `__ + for more information on JSON web token expiration. + + * - ``Policy`` + - string + - *Optional* + + Specify the URL-encoded JSON-formatted :ref:`policy ` to + use as an inline session policy. + + - The minimum string length is ``1``. + - The maximum string length is ``2048``. + + The resulting permissions for the temporary credentials are the + intersection between the policy specified as part of the :ref:`JWT claim + ` and the specified inline + policy. Applications can only perform those operations for which they + are explicitly authorized. + + The inline policy can specify a subset of permissions allowed by the + policy specified in the JWT claim. Applications can never assume + more privileges than those specified in the JWT claim policy. + + Omit to use only the JWT claim policy. + + See :ref:`minio-access-management` for more information on MinIO + authentication and authorization. + +Response Elements +----------------- + +The XML response for this API endpoint is similar to the AWS +:aws-docs:`AssumeRoleWithWebIdentity response +`. +Specifically, MinIO returns an ``AssumeRoleWithWebIdentityResult`` object, +where the ``AssumedRoleUser.Credentials`` object contains the temporary +credentials generated by MinIO: + +- ``AccessKeyId`` - The access key applications use for authentication. +- ``SecretKeyId`` - The secret key applications use for authentication. +- ``Expiration`` - The ISO-8601 date-time after which the credentials expire. +- ``SessionToken`` - The session token applications use for authentication. Some + SDKs may require this field when using temporary credentials. + +The following example is similar to the response returned by the MinIO STS +``AssumeRoleWithWebIdentity`` endpoint: + +.. code-block:: xml + + + + + + + + + + Y4RJU1RNFGK48LGO9I2S + sYLRKS1Z7hSjluf6gEbb9066hnx315wHTiACPAjg + 2019-08-08T20:26:12Z + eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhY2Nlc3NLZXkiOiJZNFJKVTFSTkZHSzQ4TEdPOUkyUyIsImF1ZCI6IlBvRWdYUDZ1Vk80NUlzRU5SbmdEWGo1QXU1WWEiLCJhenAiOiJQb0VnWFA2dVZPNDVJc0VOUm5nRFhqNUF1NVlhIiwiZXhwIjoxNTQxODExMDcxLCJpYXQiOjE1NDE4MDc0NzEsImlzcyI6Imh0dHBzOi8vbG9jYWxob3N0Ojk0NDMvb2F1dGgyL3Rva2VuIiwianRpIjoiYTBiMjc2MjktZWUxYS00M2JmLTg3MzktZjMzNzRhNGNkYmMwIn0.ewHqKVFTaP-j_kgZrcOEKroNUjk10GEp8bqQjxBbYVovV0nHO985VnRESFbcT6XMDDKHZiWqN2vi_ETX_u3Q-w + + + + + +Error Elements +-------------- + +The XML error response for this API endpoint is similar to the AWS +:aws-docs:`AssumeRoleWithWebIdentity response +`. + + 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 new file mode 100644 index 00000000..36df0a59 --- /dev/null +++ b/source/security/openid-external-identity-management/configure-openid-external-identity-management.rst @@ -0,0 +1,235 @@ +.. _minio-authenticate-using-openid-generic: + +=============================================== +Configure MinIO for Authentication using OpenID +=============================================== + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 2 + +Overview +-------- + +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. The procedure on this page provides instructions for: + +- Configuring a MinIO cluster for an external OIDC provider. +- Logging into the cluster using the MinIO Console and OIDC credentials. +- Using the MinIO ``AssumeRoleWithWebIdentity`` Security Token Service (STS) + API to generate temporary credentials for use by applications. + +This procedure is generic for OIDC compatible providers. Defer to +the documentation for the OIDC provider of your choice for specific instructions +or procedures on authentication and JWT retrieval. + +Prerequisites +------------- + +OpenID-Connect (OIDC) Compatible IDentity Provider +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This procedure assumes an existing OIDC provider such as Okta, +KeyCloak, Dex, Google, or Facebook. Instructions on configuring these services +are out of scope for this procedure. + +Ensure each user identity intended for use with MinIO has the appropriate +:ref:`claim ` configured such that +MinIO can associate a :ref:`policy ` to the authenticated user. +An OpenID user with no assigned policy has no permission to access any action +or resource on the MinIO cluster. + +MinIO Cluster +~~~~~~~~~~~~~ + +This procedure assumes an existing MinIO cluster running the +:minio-git:`latest stable MinIO version `. +This procedure *may* work as expected for older versions of MinIO. + +Install and Configure ``mc`` with Access to the MinIO Cluster +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This procedure uses :mc:`mc` for performing operations on the +MinIO cluster. Install ``mc`` on a machine with network access to the cluster. +See the ``mc`` :ref:`Installation Quickstart ` for instructions on +downloading and installing ``mc``. + +This procedure assumes a configured :mc:`alias ` for the MinIO +cluster. + +.. _minio-external-identity-management-openid-configure: + +Procedure +--------- + +1) Set the OpenID Configuration Settings +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can configure the :abbr:`OIDC (OpenID Connect)` provider using either +environment variables *or* server runtime configuration settings. Both +methods require starting/restarting the MinIO deployment to apply changes. The +following tabs provide a quick reference of all required and optional +environment variables and configuration settings respectively: + +.. tabs:: + + .. tab:: Environment Variables + + MinIO supports specifying the :abbr:`OIDC (OpenID Connect)` provider + settings using :ref:`environment variables + `. The + :mc:`minio server` process applies the specified settings on its next + startup. For distributed deployments, specify these settings across all + nodes in the deployment using the *same* values consistently. + + The following example code sets *all* environment variables related to + configuring an :abbr:`OIDC (OpenID Connect)` provider for external + identity management. The minimum *required* variable is + :envvar:`MINIO_IDENTITY_OPENID_CONFIG_URL`: + + .. 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="" + + Replace the ``MINIO_IDENTITY_OPENID_CONFIG_URL`` with the URL endpoint of + the :abbr:`OIDC (OpenID Connect)` provider discovery document. + + For complete documentation on these variables, see + :ref:`minio-server-envvar-external-identity-management-openid` + + .. tab:: Configuration Settings + + MinIO supports specifying the :abbr:`OIDC (OpenID Connect)` provider + settings using :mc-conf:`configuration settings `. The + :mc:`minio server` process applies the specified settings on its next + startup. For distributed deployments, the :mc-cmd:`mc admin config` + command applies the configuration to all nodes in the deployment. + + The following example code sets *all* configuration settings related to + configuring an :abbr:`OIDC (OpenID Connect)` provider for external + identity management. The minimum *required* setting is + :mc-conf:`identity_openid config_url `: + + .. code-block:: shell + :class: copyable + + mc admin config set ALIAS/ identity_openid \ + config_url="https://openid-provider.example.net/.well-known/openid-configuration" \ + client_id="" \ + claim_name="" \ + claim_prefix="" \ + scopes="" \ + comment="" + + Replace the ``config_url`` with the URL endpoint of the + :abbr:`OIDC (OpenID Connect)` provider discovery document. + + For more complete documentation on these settings, see + :mc-conf:`identity_openid`. + +2) Restart the MinIO Deployment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You must restart the MinIO deployment to apply the configuration changes. +Use the :mc-cmd:`mc admin service restart` command to restart the deployment. + +.. important:: + + MinIO restarts *all* :mc:`minio server` processes associated to the + deployment at the same time. Applications may experience a brief period of + downtime during the restart process. + + Consider scheduling the restart during a maintenance period to minimize + interruption of services. + +.. code-block:: shell + :class: copyable + + mc admin service restart ALIAS + +Replace ``ALIAS`` with the :mc:`alias ` of the deployment to +restart. + +3) Use the MinIO Console to Log In with OIDC Credentials +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The MinIO Console supports the full workflow of authenticating to the +:abbr:`OIDC (OpenID Connect)` provider, generating temporary credentials using +the MinIO :ref:`minio-sts-assumerolewithwebidentity` Security Token Service +(STS) endpoint, and logging the user into the MinIO deployment. + +Starting in RELEASE, the MinIO Console is embedded in the MinIO server. +You can access the Console by opening the root URL for the MinIO cluster. +For example, ``https://minio.example.net:9001``. + +From the Console, click :guilabel:`BUTTON` to begin the OpenID authentication +flow. + +Once logged in, you can perform any action for which the authenticated +user is :ref:`authorized +`. + +You can also create :ref:`service accounts ` for +supporting applications which must perform operations on MinIO. Service accounts +are long-lived credentials which inherit their privileges from the parent user. +The parent user can further restrict those privileges while creating the service +account. + +4) Generate S3-Compatible Temporary Credentials using OIDC Credentials +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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. + +Applications can generate temporary access credentials as-needed using the +:ref:`minio-sts-assumerolewithwebidentity` Security Token Service (STS) +API endpoint and the JSON Web Token (JWT) returned by the +:abbr:`OIDC (OpenID Connect)` provider. + +The application must provide a workflow for logging into the +:abbr:`OIDC (OpenID Connect)` provider and retrieving the +JSON Web Token (JWT) associated to the authentication session. Defer to the +provider documentation for obtaining and parsing the JWT token after successful +authentication. MinIO provides an example Go application +:minio-git:`web-identity.go ` with +an example of managing this workflow. + +Once the application retrieves the JWT token, use the +``AssumeRoleWithWebIdentity`` endpoint to generate the temporary credentials: + +.. code-block:: shell + :class: copyable + + POST https://minio.example.net/Action=AssumeRoleWithWebIdentity + &WebIdentityToken=TOKEN + &Version=2011-06-15 + &DurationSeconds=86400 + &Policy=Policy + +- Replace the ``TOKEN`` with the JWT token returned in the previous step. +- Replace the ``DurationSeconds`` with the duration in seconds until the + temporary credentials expire. The example above specifies a period of + ``86400`` seconds, or 24 hours. +- Replace the ``Policy`` with an inline URL-encoded JSON + :ref:`policy ` that further restricts the permissions associated + to the temporary credentials. Omit to use the policy associated to the + OpenID user :ref:`policy claim `. + +The API response consists of an XML document containing the +access key, secret key, session token, and expiration date. Applications +can use the access key and secret key to access and perform operations on +MinIO. + +SEe the :ref:`minio-sts-assumerolewithwebidentity` for reference documentation. \ No newline at end of file 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 new file mode 100644 index 00000000..05f2b068 --- /dev/null +++ b/source/security/openid-external-identity-management/external-authentication-with-openid-identity-provider.rst @@ -0,0 +1,139 @@ +.. _minio-external-identity-management-openid: + +=================================== +OpenID External Identity Management +=================================== + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 2 + +Overview +-------- + +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. Configuring an external :abbr:`IDP (IDentity Provider)` enables +Single-Sign On workflows, where applications authenticate against the external +:abbr:`IDP (IDentity Provider)` before accessing MinIO. + +MinIO by default denies access to all actions or resources not explicitly +allowed by a user's assigned or inherited :ref:`policies `. Users +managed by an OIDC provider must specify the necessary policies as part of the +user profile data. See :ref:`Access Control for OIDC Managed Identities +` for more +information. + +See :ref:`minio-authenticate-using-openid-generic` for instructions on enabling +external identity management using an :abbr:`OIDC (OpenID Connect)` compatible +service. + +.. admonition:: MinIO Supports At Most One Configured IDentity Provider + :class: important + + Configuring an external IDP disables the :ref:`MinIO internal IDP + ` and prevents the configuration of any other + external IDP. + + The external :abbr:`IDP (IDentity Provider)` must have *at least* one + configured user identity with the required :ref:`policy claims + `. If no such user + exists, the MinIO server is effectively inaccessible outside of using the + :ref:`root ` user. + +Authentication and Authorization Flow +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The login flow for an application using :abbr:`OIDC (OpenID Connect)` +credentials is as follows: + +1. Authenticate to the configured :abbr:`OIDC (OpenID Connect)` + provider and retrieve a + `JSON Web Token (JWT) `__. + +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. + + If the JWT is valid, MinIO checks for a :ref:`claim + ` specifying a list + of one or more :ref:`policies ` to assign to the + authenticated user. MinIO defaults to checking the ``policy`` claim. + +3. 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 JWT claim. + +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 ` that +handles the full login flow. + +As an alternative to implementing this application flow, application owners can +log into the :minio-git:`MinIO Console ` using their external +user credentials and create :ref:`service accounts ` +for their applications. Service accounts are long-lived credentials which +inherit their privileges from the parent user. The parent user can further +restrict those privileges while creating the service account. + +.. _minio-external-identity-management-openid-access-control: + +Access Control for Externally Managed Identities +------------------------------------------------ + +MinIO uses :ref:`Policy Based Access Control (PBAC) ` +to define the actions and resources to which an authenticated user has access. +MinIO supports creating and managing :ref:`policies ` which an +externally managed user can claim. + +For identities managed by the external OpenID Connect (OIDC) compatible +provider, MinIO uses a `JSON Web Token claim +`__ to identify the +:ref:`policy ` to assign to the authenticated user. + +MinIO by default looks for a ``policy`` claim and reads a list of one or more +policies to assign. MinIO attempts to match existing policies to those +specified in the JWT claim. If none of the specified policies exist on the MinIO +deployment, MinIO denies authorization for any and all operations issued +by that user. For example, consider a claim with the following key-value +assignment: + +.. code-block:: shell + + policy="readwrite_data,read_analytics,read_logs" + +The specified policy claim directs MinIO to attach the policies with names +matching ``readwrite_data``, ``read_analytics``, and ``read_logs`` to the +authenticated user. + +You can set a custom policy claim using the +:envvar:`MINIO_IDENTITY_OPENID_CLAIM_NAME` environment variable +*or* by using :mc-cmd:`mc admin config set` to set the +:mc-conf:`identity_openid claim_name ` setting. + +You can use a `JWT Debugging tool `__ to decode the returned +JWT token and validate that the user attributes include the required claims. See +`RFC 7519: JWT Claim +`__ for more +information on JWT claims. Defer to the documentation for your preferred OIDC +provider for instructions on configuring user claims. + +MinIO provides :ref:`built-in policies ` for basic access +control. You can create new policies using the :mc:`mc admin policy` command, or +by using the MinIO Console. MinIO does not support assigning :ref:`groups +` to an :abbr:`OIDC (OpenID Connect)` managed identity. Specify +any and all policies to attach to the user as part of its :abbr:`JWT (JWT)` +policy claim. + +.. toctree:: + :titlesonly: + :hidden: + + /security/openid-external-identity-management/configure-openid-external-identity-management + /security/openid-external-identity-management/AssumeRoleWithWebIdentity diff --git a/source/security/security-overview.rst b/source/security/security-overview.rst index a122f1f8..5140587c 100644 --- a/source/security/security-overview.rst +++ b/source/security/security-overview.rst @@ -1,22 +1,106 @@ -============== -MinIO Security -============== +======== +Security +======== .. default-domain:: minio -:doc:`/security/IAM/identity-access-management` - Identity and Access Management (IAM) governs secured access to a MinIO - deployment, where administrators have granular controls over the - resources and operations which a client can perform. +.. contents:: Table of Contents + :local: + :depth: 2 -:doc:`/security/encryption/encryption-key-management` - Encryption and Key Management (EKM) governs the encryption of objects - stored on MinIO, including on-disk encryption *and* over-the-wire (network) - encryption. +.. _minio-authentication-and-identity-management: + +Authentication and Identity 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 supports both internal and external identity management: + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + :width: 100% + + * - IDentity Provider (IDP) + - Description + + * - :ref:`MinIO Internal IDP ` + - Provides built-in identity management functionality. + + * - :ref:`OpenID ` + - Supports managing identities through an OpenID Connect (OIDC) compatible + service. + + * - :ref:`Active Directory / LDAP + ` + - 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*. + +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. + +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. + +For more complete documentation, see :ref:`minio-access-management`. + +Encryption +---------- + +MinIO supports end-to-end encryption of objects over-the-wire (network +encryption) and on read/write (at-rest). + +Network Encryption +~~~~~~~~~~~~~~~~~~ + +MinIO supports :ref:`Transport Layer Security (TLS) ` encryption of +incoming and outgoing traffic. + +TLS is the successor to Secure Socket Layer (SSL) encryption. SSL is fully +`deprecated `__ as of June 30th, 2018. +MinIO uses only supported (non-deprecated) TLS protocols (TLS 1.2 and later). + +See :ref:`minio-encryption-tls` for more complete documentation. + +Server-Side Object Encryption (SSE) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +MinIO supports :ref:`Server-Side Object Encryption (SSE) ` of +objects, where MinIO uses a secret key to encrypt and store objects on disk +(encryption at-rest). MinIO SSE requires :ref:`minio-encryption-tls`. +See :ref:`minio-sse` for more complete documentation. .. toctree:: :titlesonly: :hidden: - /security/IAM/identity-access-management - /security/encryption/encryption-key-management \ No newline at end of file + /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 +