minio/docs
1
0
Fork 0
mirror of https://github.com/minio/docs.git synced 2025-07-30 07:03:26 +03:00
Code Activity

Migrate STS docs to next-gen, restructure/revise

Browse Source
This commit is contained in:
ravindk89
2021-06-11 12:59:15 -04:00
committed by Harshavardhana
parent 00c5863642
commit 92e6fc898a
25 changed files with 2416 additions and 488 deletions
Download Patch File Download Diff File Expand all files Collapse all files

237
source/includes/common-minio-external-auth.rst Normal file
View File

@ -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
<https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig>`__.
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 <https://datatracker.ietf.org/doc/html/rfc7519#section-4>`__
MinIO uses to identify the :ref:`policies <minio-policy>` 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 <https://datatracker.ietf.org/doc/html/rfc7519#section-4>`__
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 <https://datatracker.ietf.org/doc/html/rfc6749#section-3.3>`__.
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 ``<int><unit>``.
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
<minio-external-identity-management-ad-ldap-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
<minio-external-identity-management-ad-ldap-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 <minio-external-identity-management-ad-ldap-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 <https://ldapwiki.com/wiki/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

2
source/includes/common-minio-tiering.rst
View File

@ -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 <minio-policy>` for more
complete documentation on MinIO users and policies respectively.
.. end-create-transition-user-desc

2
source/reference/minio-cli/minio-mc-admin/mc-admin-group.rst
View File

@ -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 <minio-policy>`.
.. admonition:: ``Deny`` overrides ``Allow``
:class: note

2
source/reference/minio-cli/minio-mc-admin/mc-admin-policy.rst
View File

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

2
source/reference/minio-cli/minio-mc-admin/mc-admin-user.rst
View File

@ -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 <minio-policy>`.
.. admonition:: ``Deny`` overrides ``Allow``
:class: note

277
source/reference/minio-cli/minio-mc-admin/mc-admin.config.rst
View File

@ -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
<minio-external-identity-management-ad-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 <minio-external-identity-management-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.

2
source/reference/minio-cli/minio-mc.rst
View File

@ -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.

2
source/reference/minio-cli/minio-mc/mc-alias.rst
View File

@ -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 <security.html>`.

247
source/reference/minio-server/minio-server.rst
View File

@ -2126,3 +2126,250 @@ endpoints as ``PRIMARY`` and ``SECONDARY`` respectively:
This environment variable corresponds with the
:mc-conf:`notify_webhook comment <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
<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
<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
<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
<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
<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
<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
<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
<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
<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
<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
<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
<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
<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
<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
<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
<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
<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
<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
<identity_openid.comment>` setting.

2
source/replication/enable-server-side-one-way-bucket-replication.rst
View File

@ -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 <minio-policy>` for more complete documentation on
MinIO users and policies respectively.
A\) Create Replication Administrator

2
source/replication/enable-server-side-two-way-bucket-replication.rst
View File

@ -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 <minio-policy>` for more complete documentation on
MinIO users and policies respectively.
A\) Create Replication Administrators

80
source/security/IAM/iam-groups.rst
View File

@ -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 <minio-users>`. Each group
can have one or more assigned :ref:`policies <minio-policy>`
that explicitly list the actions and resources to which group members are
allowed or denied access.
For example, consider the following groups. Each group is assigned a
:ref:`built-in policy <minio-policy-built-in>` or supported
:ref:`policy action <minio-policy-actions>`. Each group also has one or
more assigned users. Each user's total set of permissions consists of their
explicitly assigned permission *and* the inherited permissions from each of
their assigned groups. MinIO by default *denies* access to any resource or
operation not explicitly allowed by a user's assigned or inherited policies.
.. list-table::
:header-rows: 1
:widths: 20 40 40
:width: 100%
* - Group
- Policy
- Members
* - ``Operations``
- | :userpolicy:`readwrite` on ``finance`` bucket
| :userpolicy:`readonly` on ``audit`` bucket
- ``john.doe``, ``jane.doe``
* - ``Auditing``
- | :userpolicy:`readonly` on ``audit`` bucket
- ``jen.doe``, ``joe.doe``
* - ``Admin``
- :policy-action:`admin:*`
- ``greg.doe``, ``jen.doe``
Groups provide a simplified method for managing shared permissions among
users with common access patterns and workloads. Client's *cannot* authenticate
to a MinIO deployment using a group as an identity.
.. admonition:: ``Deny`` overrides ``Allow``
:class: note
MinIO follows the IAM standard where a ``Deny`` rule overrides ``Allow`` rule
on the same action or resource. For example, if a user has an explicitly
assigned policy with an ``Allow`` rule for an action/resource while one of
its groups has an assigned policy with a ``Deny`` rule for that
action/resource, MinIO would apply only the ``Deny`` rule.
For more information on IAM policy evaluation logic, see the IAM
documentation on
:iam-docs:`Determining Whether a Request is Allowed or Denied Within an Account
<reference_policies_evaluation-logic.html#policy-eval-denyallow>`.
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:

81
source/security/IAM/iam-security-token-service.rst
View File

@ -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 <minio-sts-quickstart-guide.html>`
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 <doc> 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 <doc> 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.

167
source/security/IAM/iam-users.rst
View File

@ -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 <minio-policy>` 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 <minio-groups>`, 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 <minio-policy-built-in>` or
a supported :ref:`action <minio-policy-actions>`. The table
describes a subset of operations a client could perform if authenticated
as that user:
.. list-table::
:header-rows: 1
: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
<reference_policies_evaluation-logic.html#policy-eval-denyallow>`.
.. _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 <mc admin user add TARGET>` with the
:mc-cmd:`alias <mc alias>` of the MinIO deployment.
- Replace :mc-cmd:`ACCESSKEY <mc admin user add ACCESSKEY>` with the
access key for the user. MinIO allows retrieving the access key after
user creation through the :mc-cmd:`mc admin user info` command.
- Replace :mc-cmd:`SECRETKEY <mc admin user add SECRETKEY>` with the
secret key for the user. MinIO *does not* provide any method for retrieving
the secret key once set.
Specify a unique, random, and long string for both the ``ACCESSKEY`` and
``SECRETKEY``. Your organization may have specific internal or regulatory
requirements around generating values for use with access or secret keys.
After creating the user, use :mc-cmd:`mc admin policy set` to associate
a :ref:`minio-policy` to the new user. You can also use
:mc-cmd:`mc admin group add` to add the user to a :ref:`minio-groups`.
Delete a User
-------------
Use the :mc-cmd:`mc admin user remove` command to remove a user on a
MinIO deployment:
.. code-block:: shell
:class: copyable
mc admin user remove ALIAS USERNAME
- Replace :mc-cmd:`ALIAS <mc admin user remove TARGET>` with the
:mc-cmd:`alias <mc alias>` of the MinIO deployment.
- Replace :mc-cmd:`USERNAME <mc admin user remove USERNAME>` with the name of
the user to remove.

102
source/security/IAM/identity-access-management.rst
View File

@ -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 <minio-policy-actions>` and
:ref:`conditions <minio-policy-conditions>` when creating policies.
By default, MinIO *denies* access to actions or resources not explicitly
referenced in a user's assigned or inherited policies.
- 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 <minio-users>`. A user can have membership in
one or more :ref:`groups <minio-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
<minio-policy>` 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
<minio-sts-quickstart-guide.html>`. Supported identity providers include Okta,
Facebook, Google, and Active Directory/LDAP.
Policies
--------
MinIO uses :ref:`Policy-Based Access Control <minio-policy>` (PBAC) to specify
the *authorized* resources and operations to which a :ref:`user <minio-users>`
or :ref:`groups <minio-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 <minio-sts-quickstart-guide.html>`
for more information.
.. toctree::
:hidden:
:titlesonly:
/security/IAM/iam-users
/security/IAM/iam-groups
/security/IAM/iam-policies

209
source/security/IAM/iam-policies.rst → source/security/access-management/access-management-overview.rst
View File

@ -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 <minio-users>` or the members of a :ref:`group
<minio-groups>` 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 <minio-policy-actions>` and :ref:`conditions
<minio-policy-conditions>` that outline the permissions of a
:ref:`user <minio-users>` or :ref:`group <minio-groups>` of
users. By default, MinIO *denies* access to actions or resources not explicitly
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 <minio-users>` or members of a
:ref:`group <minio-groups>` 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-authentication-and-identity-management>`.
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 <minio-internal-idp>`
require explicitly associating a user to a policy or policies using the
:mc-cmd:`mc admin policy set` command. A user can also inherit the policies
attached to the :ref:`groups <minio-groups>` in which they have membership.
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-external-identity-management-openid>`
- MinIO checks for a JSON Web Token (JWT) claim (``policy`` by default)
containing the name of the policy or policies to attach to the
authenticated user. If the policies do not exist, the user cannot
perform any action on the MinIO deployment.
MinIO does not support assigning OIDC user identities to
:ref:`groups <minio-groups>`. The IDP administrator must instead
assign all necessary policies to the user's policy claim.
See :ref:`Access Control for Externally Managed Identities
<minio-external-identity-management-openid-access-control>` for
more information.
* - :ref:`Active Directory / LDAP (AD/LDAP)
<minio-external-identity-management-ad-ldap>`
- MinIO checks for a policy whose name matches the Distinguished Name (DN)
of the authenticated AD/LDAP user.
MinIO also supports querying for the authenticated AD/LDAP user's
group memberships. MinIO assigns any policy whose name matches the
DN for each returned group.
If no policies match either the user DN *or* any of the user's group DNs,
the user cannot perform any action on the MinIO deployment.
See :ref:`Access Control for Externally Managed Identities
<minio-external-identity-management-ad-ldap-access-control>` for more
information.
MinIO PBAC is built for compatibility with AWS IAM policy syntax, structure, and
behavior. The MinIO documentation makes a best-effort to cover IAM-specific
behavior and functionality. Consider deferring to the :iam-docs:`IAM
documentation <>` for more complete documentation on IAM, IAM policies, or IAM
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
<reference_policies_evaluation-logic.html#policy-eval-denyallow>`.
.. _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 <minio-policy-built-in>` or
a supported :ref:`action <minio-policy-actions>`. The table
describes a subset of operations a client could perform if authenticated
as that user:
.. list-table::
:header-rows: 1
: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
<reference_policies_evaluation-logic.html#policy-eval-denyallow>`.
.. _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 <reference_policies_elements_condition.html>`
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 <minio-users>`. Each group
can have one or more assigned :ref:`policies <minio-policy>`
that explicitly list the actions and resources to which group members are
allowed or denied access.
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 <minio-policy-built-in>` or supported
:ref:`policy action <minio-policy-actions>`. Each group also has one or
more assigned users. Each user's total set of permissions consists of their
explicitly assigned permission *and* the inherited permissions from each of
their assigned groups. MinIO by default *denies* access to any resource or
operation not explicitly allowed by a user's assigned or inherited policies.
Use the :mc-cmd:`mc admin policy set` command to associate a policy to a
:ref:`user <minio-users>` or :ref:`group <minio-groups>`.
.. 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 <mc alias>` of an S3-compatible
host configured for use with :program:`mc`. See :mc-cmd:`mc alias` for
more information on aliases.
Groups provide a simplified method for managing shared permissions among
users with common access patterns and workloads. Client's *cannot* authenticate
to a MinIO deployment using a group as an identity. Use the
:mc-cmd:`mc admin group` command to create and manage groups on MinIO.
.. admonition:: ``Deny`` overrides ``Allow``
:class: note
MinIO follows the IAM standard where a ``Deny`` rule overrides ``Allow`` rule
on the same action or resource. For example, if a user has an explicitly
assigned policy with an ``Allow`` rule for an action/resource while one of
its groups has an assigned policy with a ``Deny`` rule for that
action/resource, MinIO would apply only the ``Deny`` rule.
For more information on IAM policy evaluation logic, see the IAM
documentation on
:iam-docs:`Determining Whether a Request is Allowed or Denied Within an Account
<reference_policies_evaluation-logic.html#policy-eval-denyallow>`.

154
source/security/ad-ldap-external-identity-management/AssumeRoleWithLDAPIdentity.rst Normal file
View File

@ -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
<STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html>`
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 <minio-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
<minio-external-identity-management-ad-ldap-access-control>` 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
<STS/latest/APIReference/API_AssumeRoleWithLDAPIDentity.html#API_AssumeRoleWithLDAPIDentity_ResponseElements>`.
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
<?xml version="1.0" encoding="UTF-8"?>
<AssumeRoleWithLDAPIDentityResponse xmlns="https://sts.amazonaws.com/doc/2011-06-15/">
<AssumeRoleWithLDAPIDentityResult>
<AssumedRoleUser>
<Arn/>
<AssumeRoleId/>
</AssumedRoleUser>
<Credentials>
<AccessKeyId>Y4RJU1RNFGK48LGO9I2S</AccessKeyId>
<SecretAccessKey>sYLRKS1Z7hSjluf6gEbb9066hnx315wHTiACPAjg</SecretAccessKey>
<Expiration>2019-08-08T20:26:12Z</Expiration>
<SessionToken>eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhY2Nlc3NLZXkiOiJZNFJKVTFSTkZHSzQ4TEdPOUkyUyIsImF1ZCI6IlBvRWdYUDZ1Vk80NUlzRU5SbmdEWGo1QXU1WWEiLCJhenAiOiJQb0VnWFA2dVZPNDVJc0VOUm5nRFhqNUF1NVlhIiwiZXhwIjoxNTQxODExMDcxLCJpYXQiOjE1NDE4MDc0NzEsImlzcyI6Imh0dHBzOi8vbG9jYWxob3N0Ojk0NDMvb2F1dGgyL3Rva2VuIiwianRpIjoiYTBiMjc2MjktZWUxYS00M2JmLTg3MzktZjMzNzRhNGNkYmMwIn0.ewHqKVFTaP-j_kgZrcOEKroNUjk10GEp8bqQjxBbYVovV0nHO985VnRESFbcT6XMDDKHZiWqN2vi_ETX_u3Q-w</SessionToken>
</Credentials>
</AssumeRoleWithLDAPIDentityResult>
<ResponseMetadata/>
</AssumeRoleWithLDAPIDentityResponse>
Error Elements
--------------
The XML error response for this API endpoint is similar to the AWS
:aws-docs:`AssumeRoleWithLDAPIDentity response
<STS/latest/APIReference/API_AssumeRoleWithLDAPIDentity.html#API_AssumeRoleWithLDAPIDentity_Errors>`.

211
source/security/ad-ldap-external-identity-management/configure-ad-ldap-external-identity-management.rst Normal file
View File

@ -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 <minio-external-identity-management-ad-ldap-lookup-bind>` to perform
authenticated user and group queries.
MinIO Cluster
~~~~~~~~~~~~~
This procedure assumes an existing MinIO cluster running the
:minio-git:`latest stable MinIO version <minio/releases/latest>`.
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 <mc-install>` for instructions on
downloading and installing ``mc``.
This procedure assumes a configured :mc:`alias <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
<minio-server-envvar-external-identity-management-ad-ldap>`. 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 <identity_ldap>`. 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 <identity_ldap.server_addr>`
- :mc-conf:`identity_ldap lookup_bind_dn <identity_ldap.lookup_bind_dn>`
- :mc-conf:`identity_ldap lookup_bind_password <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 <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
<minio-external-identity-management-ad-ldap-access-control>`.
You can also create :ref:`service accounts <minio-idp-service-account>` 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 <sig-v4-authenticating-requests.html>` with support for the deprecated
Signature Version 2 protocol. Specifically, clients must present a valid access
key and secret key to access any S3 or MinIO administrative API, such as
``PUT``, ``GET``, and ``DELETE`` operations.
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 <minio/blob/master/docs/sts/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 <minio-policy>` that further restricts the permissions associated
to the temporary credentials. Omit to use the
:ref:`policy whose name matches <minio-external-identity-management-ad-ldap-access-control>`
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.

252
source/security/ad-ldap-external-identity-management/external-authentication-with-ad-ldap-identity-provider.rst Normal file
View File

@ -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 <minio-policy>`. 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
<minio-external-identity-management-ad-ldap-access-control>` 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
<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
<minio-external-identity-management-ad-ldap-access-control>`. If no such user
exists, the MinIO server is effectively inaccessible outside of using the
:ref:`root <minio-users-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 <minio-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 <minio/blob/master/docs/sts/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 <console>` using their external
user credentials and create :ref:`service accounts <minio-idp-service-account>`
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 <identity_ldap.lookup_bind_dn>`
- :mc-conf:`identity_ldap lookup_bind_password <identity_ldap.lookup_bind_password>`
- :mc-conf:`identity_ldap user_dn_search_base_dn <identity_ldap.user_dn_search_base_dn>`
- :mc-conf:`identity_ldap user_dn_search_filter <identity_ldap.user_dn_search_filter>`
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 <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) <minio-access-management>`
to define the actions and resources to which an authenticated user has access.
MinIO supports creating and managing :ref:`policies <minio-policy>` 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 <minio-policy-built-in>` 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 <minio-policy>` 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 <identity_ldap.group_search_base_dn>`
- :mc-conf:`identity_ldap group_search_filter <identity_ldap.group_search_filter>`
See the :mc-conf:`identity_ldap` reference documentation for more
information on these settings. The :ref:`` tutorial includes
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

2
source/security/encryption/server-side-encryption-sse-s3.rst
View File

@ -33,8 +33,6 @@ following KMS providers:
- Thales CipherTrust (formerly Gemalto KeySecure)
- Hashicorp KeyVault
Requirements
------------

220
source/security/minio-identity-management/basic-authentication-with-minio-identity-provider.rst Normal file
View File

@ -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 <console>` provides a graphical
interface for creating users.
MinIO also supports creating :ref:`service accounts
<minio-idp-service-account>`. 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 <minio-policy>`. You
must either explicitly assign a :ref:`policy <minio-policy>` describing the
user's authorized actions and resources *or* assign the user to :ref:`groups
<minio-groups>` which have associated policies. See
:ref:`minio-access-management` for more information.
.. 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-idp-service-account>`.
.. _minio-users-root:
MinIO ``root`` User
~~~~~~~~~~~~~~~~~~~
MinIO deployments have a ``root`` user with access to all actions and resources
on the deployment, regardless of the configured :ref:`identity manager
<minio-authentication-and-identity-management>`. When a :mc:`minio` server first
starts, it sets the ``root`` user credentials by checking the value of the
following environment variables:
- :envvar:`MINIO_ROOT_USER`
- :envvar:`MINIO_ROOT_PASSWORD`
Rotating the root user credentials requires updating either or both variables
for all MinIO servers in the deployment. Specify *long, unique, and random*
strings for root credentials. Exercise all possible precautions in storing the
access key and secret key, such that only known and trusted individuals who
*require* superuser access to the deployment can retrieve the ``root``
credentials.
- MinIO *strongly discourages* using the ``root`` user for regular client access
regardless of the environment (development, staging, or production).
- MinIO *strongly recommends* creating users such that each client has access to
the minimal set of actions and resources required to perform their assigned
workloads.
If these variables are unset, :mc:`minio` defaults to ``minioadmin`` and
``minioadmin`` as the access key and secret key respectively. MinIO *strongly
discourages* use of the default credentials regardless of deployment
environment.
.. admonition:: Deprecation of Legacy Root User Environment Variables
:class: dropdown, important
MinIO :minio-release:`RELEASE.2021-04-22T15-44-28Z` and later deprecates the
following variables used for setting or updating root user
credentials:
- :envvar:`MINIO_ACCESS_KEY` to the new access key.
- :envvar:`MINIO_SECRET_KEY` to the new secret key.
- :envvar:`MINIO_ACCESS_KEY_OLD` to the old access key.
- :envvar:`MINIO_SECRET_KEY_OLD` to the old secret key.
Access Control
--------------
A user by default has no associated :ref:`privileges <minio-access-management>`.
You must either explicitly assign a :ref:`policy <minio-policy>` describing
the user's authorized actions and resources *or* assign the user to
:ref:`groups <minio-groups>` which have associated policies. A user with
no explicitly assigned or inherited policies cannot perform any S3 or
MinIO administrative API operations.
For example, consider the following table of users. Each user is assigned
a :ref:`built-in policy <minio-policy-built-in>` or
a supported :ref:`action <minio-policy-actions>`. The table
describes a subset of operations a client could perform if authenticated
as that user:
.. list-table::
:header-rows: 1
: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 <minio-policy>` attached to it's parent user *or* those
groups in which the parent user has membership. Service accounts also support
an optional inline policy which further restricts access to a subset of
actions and resources available to the parent user.
A MinIO user can generate any number of service accounts. This allows
application owners to generate arbitrary service accounts for their applications
without requiring action from the MinIO administrators. Since the generated
service accounts have the same or fewer permissions as the parents,
administrators can focus on managing the top-level parent users without
micro-managing generated service accounts.
Service accounts are only available through the :minio-git:`MinIO Console
<console>`. After logging into the Console, click :guilabel:`Account`
from the left navigation to view all service accounts associated to the
authenticated user. Click :guilabel:`Create Service Account` to create
new service accounts.
User Management
---------------
Create a User
~~~~~~~~~~~~~
Use the :mc-cmd:`mc admin user add` command to create a new user on the
MinIO deployment:
.. code-block:: shell
:class: copyable
mc admin user add ALIAS ACCESSKEY SECRETKEY
- Replace :mc-cmd:`ALIAS <mc admin user add TARGET>` with the
:mc-cmd:`alias <mc alias>` of the MinIO deployment.
- Replace :mc-cmd:`ACCESSKEY <mc admin user add ACCESSKEY>` with the
access key for the user. MinIO allows retrieving the access key after
user creation through the :mc-cmd:`mc admin user info` command.
- Replace :mc-cmd:`SECRETKEY <mc admin user add SECRETKEY>` with the
secret key for the user. MinIO *does not* provide any method for retrieving
the secret key once set.
Specify a unique, random, and long string for both the ``ACCESSKEY`` and
``SECRETKEY``. Your organization may have specific internal or regulatory
requirements around generating values for use with access or secret keys.
After creating the user, use :mc-cmd:`mc admin policy set` to associate
a :ref:`MinIO Policy Based Access Control <minio-policy>` to the new user. You can also use
:mc-cmd:`mc admin group add` to add the user to a :ref:`minio-groups`.
Delete a User
~~~~~~~~~~~~~
Use the :mc-cmd:`mc admin user remove` command to remove a user on a
MinIO deployment:
.. code-block:: shell
:class: copyable
mc admin user remove ALIAS USERNAME
- Replace :mc-cmd:`ALIAS <mc admin user remove TARGET>` with the
:mc-cmd:`alias <mc alias>` of the MinIO deployment.
- Replace :mc-cmd:`USERNAME <mc admin user remove USERNAME>` with the name of
the user to remove.

165
source/security/openid-external-identity-management/AssumeRoleWithWebIdentity.rst Normal file
View File

@ -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)
<minio-external-identity-management-openid-configure>`. 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
<STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html>`
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
<minio-external-identity-management-openid-configure>`.
* - ``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
<https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4>`__
for more information on JSON web token expiration.
* - ``Policy``
- string
- *Optional*
Specify the URL-encoded JSON-formatted :ref:`policy <minio-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
<minio-external-identity-management-openid-access-control>` 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
<STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html#API_AssumeRoleWithWebIdentity_ResponseElements>`.
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
<?xml version="1.0" encoding="UTF-8"?>
<AssumeRoleWithWebIdentityResponse xmlns="https://sts.amazonaws.com/doc/2011-06-15/">
<AssumeRoleWithWebIdentityResult>
<AssumedRoleUser>
<Arn/>
<AssumeRoleId/>
</AssumedRoleUser>
<Credentials>
<AccessKeyId>Y4RJU1RNFGK48LGO9I2S</AccessKeyId>
<SecretAccessKey>sYLRKS1Z7hSjluf6gEbb9066hnx315wHTiACPAjg</SecretAccessKey>
<Expiration>2019-08-08T20:26:12Z</Expiration>
<SessionToken>eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhY2Nlc3NLZXkiOiJZNFJKVTFSTkZHSzQ4TEdPOUkyUyIsImF1ZCI6IlBvRWdYUDZ1Vk80NUlzRU5SbmdEWGo1QXU1WWEiLCJhenAiOiJQb0VnWFA2dVZPNDVJc0VOUm5nRFhqNUF1NVlhIiwiZXhwIjoxNTQxODExMDcxLCJpYXQiOjE1NDE4MDc0NzEsImlzcyI6Imh0dHBzOi8vbG9jYWxob3N0Ojk0NDMvb2F1dGgyL3Rva2VuIiwianRpIjoiYTBiMjc2MjktZWUxYS00M2JmLTg3MzktZjMzNzRhNGNkYmMwIn0.ewHqKVFTaP-j_kgZrcOEKroNUjk10GEp8bqQjxBbYVovV0nHO985VnRESFbcT6XMDDKHZiWqN2vi_ETX_u3Q-w</SessionToken>
</Credentials>
</AssumeRoleWithWebIdentityResult>
<ResponseMetadata/>
</AssumeRoleWithWebIdentityResponse>
Error Elements
--------------
The XML error response for this API endpoint is similar to the AWS
:aws-docs:`AssumeRoleWithWebIdentity response
<STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html#API_AssumeRoleWithWebIdentity_Errors>`.

235
source/security/openid-external-identity-management/configure-openid-external-identity-management.rst Normal file
View File

@ -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 <minio-external-identity-management-openid-access-control>` configured such that
MinIO can associate a :ref:`policy <minio-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 <minio/releases/latest>`.
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 <mc-install>` for instructions on
downloading and installing ``mc``.
This procedure assumes a configured :mc:`alias <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
<minio-server-envvar-external-identity-management-openid>`. 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="<string>"
set MINIO_IDENTITY_OPENID_CLAIM_NAME="<string>"
set MINIO_IDENTITY_OPENID_CLAIM_PREFIX="<string>"
set MINIO_IDENTITY_OPENID_SCOPES="<string>"
set MINIO_IDENTITY_OPENID_COMMENT="<string>"
Replace the ``MINIO_IDENTITY_OPENID_CONFIG_URL`` with the URL endpoint of
the :abbr:`OIDC (OpenID Connect)` provider discovery document.
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 <identity_openid>`. 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 <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="<string>" \
claim_name="<string>" \
claim_prefix="<string>" \
scopes="<string>" \
comment="<string>"
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 <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
<minio-external-identity-management-openid-access-control>`.
You can also create :ref:`service accounts <minio-idp-service-account>` 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 <sig-v4-authenticating-requests.html>` with support for the deprecated
Signature Version 2 protocol. Specifically, clients must present a valid access
key and secret key to access any S3 or MinIO administrative API, such as
``PUT``, ``GET``, and ``DELETE`` operations.
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 <minio/blob/master/docs/sts/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 <minio-policy>` that further restricts the permissions associated
to the temporary credentials. Omit to use the policy associated to the
OpenID user :ref:`policy claim <minio-external-identity-management-openid-access-control>`.
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.

139
source/security/openid-external-identity-management/external-authentication-with-openid-identity-provider.rst Normal file
View File

@ -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 <minio-policy>`. 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
<minio-external-identity-management-openid-access-control>` 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
<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
<minio-external-identity-management-openid-access-control>`. If no such user
exists, the MinIO server is effectively inaccessible outside of using the
:ref:`root <minio-users-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) <https://jwt.io/introduction>`__.
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
<minio-external-identity-management-openid-access-control>` specifying a list
of one or more :ref:`policies <minio-policy>` 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 <minio/blob/master/docs/sts/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 <console>` using their external
user credentials and create :ref:`service accounts <minio-idp-service-account>`
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) <minio-access-management>`
to define the actions and resources to which an authenticated user has access.
MinIO supports creating and managing :ref:`policies <minio-policy>` 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
<https://datatracker.ietf.org/doc/html/rfc7519#section-4>`__ to identify the
:ref:`policy <minio-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 <identity_openid.claim_name>` setting.
You can use a `JWT Debugging tool <https://jwt.io/>`__ to decode the returned
JWT token and validate that the user attributes include the required claims. See
`RFC 7519: JWT Claim
<https://datatracker.ietf.org/doc/html/rfc7519#section-4>`__ 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 <minio-policy-built-in>` 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
<minio-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

110
source/security/security-overview.rst
View File

@ -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 <sig-v4-authenticating-requests.html>`
with support for the deprecated Signature Version 2 protocol. Specifically,
clients must present a valid access key and secret key to access any
S3 or MinIO administrative API, such as ``PUT``, ``GET``, and
``DELETE`` operations.
MinIO 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 <minio-internal-idp>`
- Provides built-in identity management functionality.
* - :ref:`OpenID <minio-external-identity-management-openid>`
- Supports managing identities through an OpenID Connect (OIDC) compatible
service.
* - :ref:`Active Directory / LDAP
<minio-external-identity-management-ad-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
<minio-authentication-and-identity-management>` its identity for all S3 API
operations, such as ``PUT``, ``GET``, and ``DELETE``. Once a client successfully
authenticates, MinIO allows that client to perform only those operations for
which they are explicitly *authorized*.
MinIO uses Policy-Based Access Control (PBAC) to define the authorized actions
and resources to which an authenticated user has access. Each policy describes
one or more :ref:`actions <minio-policy-actions>` and :ref:`conditions
<minio-policy-conditions>` that outline the permissions of a
:ref:`user <minio-users>` or :ref:`group <minio-groups>` 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) <minio-TLS>` encryption of
incoming and outgoing traffic.
TLS is the successor to Secure Socket Layer (SSL) encryption. SSL is fully
`deprecated <https://tools.ietf.org/html/rfc7568>`__ 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) <minio-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
/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