mirror of
https://github.com/minio/docs.git
synced 2025-06-04 08:42:23 +03:00
Restructure Security Docs
Further refinement Andreas fixups
This commit is contained in:
ravindk89
Ravind Kumar
parent
179722e56a
commit
941eab5e4d
@ -116,6 +116,10 @@ body div.left li.toctree-l2 {
|
||||
margin: 10px 0 10px 0;
|
||||
}
|
||||
|
||||
body div.left li.toctree-l3 {
|
||||
margin: 10px 0 10px 0;
|
||||
}
|
||||
|
||||
body div.left div.searchformwrapper {
|
||||
margin-top: 25px;
|
||||
}
|
||||
|
||||
@ -70,13 +70,13 @@ The example command breaks down as follows:
|
||||
:width: 100%
|
||||
|
||||
* - :envvar:`MINIO_ACCESS_KEY`
|
||||
- The access key for the :ref:`root <minio-auth-authz-root>` user.
|
||||
- The access key for the :ref:`root <minio-users-root>` user.
|
||||
|
||||
Replace this value with a unique, random, and long string.
|
||||
|
||||
* - :envvar:`MINIO_SECRET_KEY`
|
||||
- The corresponding secret key to use for the
|
||||
:ref:`root <minio-auth-authz-root>` user.
|
||||
:ref:`root <minio-users-root>` user.
|
||||
|
||||
Replace this value with a unique, random, and long string.
|
||||
|
||||
@ -189,13 +189,13 @@ The example command breaks down as follows:
|
||||
:width: 100%
|
||||
|
||||
* - :envvar:`MINIO_ACCESS_KEY`
|
||||
- The access key for the :ref:`root <minio-auth-authz-root>` user.
|
||||
- The access key for the :ref:`root <minio-users-root>` user.
|
||||
|
||||
Replace this value with a unique, random, and long string.
|
||||
|
||||
* - :envvar:`MINIO_SECRET_KEY`
|
||||
- The corresponding secret key to use for the
|
||||
:ref:`root <minio-auth-authz-root>` user.
|
||||
:ref:`root <minio-users-root>` user.
|
||||
|
||||
Replace this value with a unique, random, and long string.
|
||||
|
||||
@ -267,7 +267,7 @@ version of the ``minio`` server process:
|
||||
The command uses the following options:
|
||||
|
||||
- ``-e MINIO_ACCESS_KEY`` and ``-e MINIO_SECRET_KEY`` for configuring the
|
||||
:ref:`root <minio-auth-authz-root>` user credentials.
|
||||
:ref:`root <minio-users-root>` user credentials.
|
||||
|
||||
- ``-v /mnt/disk<int>:/disk<int>`` for configuring each disk the ``minio``
|
||||
server uses.
|
||||
@ -295,7 +295,7 @@ bleeding-edge version of the ``minio`` server process:
|
||||
The command uses the following options:
|
||||
|
||||
- ``MINIO_ACCESS_KEY`` and ``MINIO_SECRET_KEY`` for configuring the
|
||||
:ref:`root <minio-auth-authz-root>` user credentials.
|
||||
:ref:`root <minio-users-root>` user credentials.
|
||||
|
||||
- ``-v /mnt/disk<int>:/disk<int>`` for configuring each disk the ``minio``
|
||||
server uses.
|
||||
|
||||
@ -22,7 +22,7 @@ Users deploying onto a Kubernetes cluster should start with our
|
||||
/minio-features/overview
|
||||
/bare-metal/minio-baremetal-overview
|
||||
/kubernetes/minio-kubernetes-overview
|
||||
/security/minio-security
|
||||
/security/security-overview
|
||||
/minio-cli/minio-mc
|
||||
/minio-cli/minio-mc-admin
|
||||
/minio-server/minio-server
|
||||
|
||||
@ -19,9 +19,9 @@ The :mc-cmd:`mc admin group` command manages groups on a MinIO deployment.
|
||||
|
||||
.. end-mc-admin-groups-desc
|
||||
|
||||
A :ref:`group <minio-auth-authz-groups>` is a collection of :ref:`users
|
||||
<minio-auth-authz-users>`. Each group can have one or more assigned
|
||||
:ref:`policies <minio-auth-authz-pbac-policies>` that explicitly list the
|
||||
A :ref:`group <minio-groups>` 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.
|
||||
Groups provide a simplified method for managing shared permissions among users
|
||||
with common access patterns and workloads.
|
||||
@ -40,7 +40,7 @@ MinIO uses Policy-Based Access Control (PBAC) to support *authorization* of
|
||||
users who have successfully *authenticated* to the deployment. Each policy
|
||||
includes rules that dictate the allowed or denied actions/resources on the
|
||||
deployment. You can assign one or more :ref:`policies
|
||||
<minio-auth-authz-pbac-policies>` to a group. Users with membership in the
|
||||
<minio-policy>` to a group. Users with membership in the
|
||||
group inherit the group's assigned policies. A user's total set of permissions
|
||||
includes their explicitly assigned policies *and* any policies inherited
|
||||
via group membership.
|
||||
@ -49,8 +49,8 @@ Newly created groups have *no* policies by default. To configure a group's
|
||||
assigned policies, use the :mc-cmd:`mc admin policy set` command.
|
||||
|
||||
For more information on MinIO users and groups, see
|
||||
:ref:`minio-auth-authz-users` and :ref:`minio-auth-authz-groups`. For
|
||||
more information on MinIO policies, see :ref:`minio-auth-authz-pbac-policies`.
|
||||
:ref:`minio-users` and :ref:`minio-groups`. For
|
||||
more information on MinIO policies, see :ref:`minio-policy`.
|
||||
|
||||
.. admonition:: ``Deny`` overrides ``Allow``
|
||||
:class: note
|
||||
@ -84,25 +84,16 @@ Quick Reference
|
||||
|
||||
:mc-cmd:`mc admin group enable TARGET GROUPNAME <mc admin group enable>`
|
||||
Enables a group on the MinIO deployment. Users can only inherit
|
||||
:ref:`policies <minio-auth-authz-pbac-policies>` assigned to an enabled group.
|
||||
:ref:`policies <minio-policy>` assigned to an enabled group.
|
||||
|
||||
:mc-cmd:`mc admin group disable TARGET GROUPNAME <mc admin group disable>`
|
||||
Disables a group on the MinIO deployment. Users cannot inherit :ref:`policies
|
||||
<minio-auth-authz-pbac-policies>` assigned to a disabled group.
|
||||
<minio-policy>` assigned to a disabled group.
|
||||
|
||||
Syntax
|
||||
------
|
||||
|
||||
:mc-cmd:`mc admin group` has the following syntax:
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
mc admin group [SUBCOMMAND] [ARGUMENTS]
|
||||
|
||||
:mc-cmd:`mc admin group` supports the following subcommands:
|
||||
|
||||
.. mc-cmd:: mc admin group add
|
||||
.. mc-cmd:: add
|
||||
:fullpath:
|
||||
|
||||
Adds an existing user to the group. The command creates the group if it
|
||||
@ -134,12 +125,12 @@ Syntax
|
||||
deployment. Use :mc-cmd:`mc admin user list` to review the available
|
||||
users on the deployment.
|
||||
|
||||
.. mc-cmd:: mc admin group info
|
||||
.. mc-cmd:: info
|
||||
:fullpath:
|
||||
|
||||
Returns details for the group on the target deployment, such as all
|
||||
:ref:`users <minio-auth-authz-users>` with membership in the group and the
|
||||
assigned :ref:`policies <minio-auth-authz-pbac-policies>`. The command has
|
||||
:ref:`users <minio-users>` with membership in the group and the
|
||||
assigned :ref:`policies <minio-policy>`. The command has
|
||||
the following syntax:
|
||||
|
||||
.. code-block:: shell
|
||||
@ -158,7 +149,7 @@ Syntax
|
||||
|
||||
The name of the group.
|
||||
|
||||
.. mc-cmd:: mc admin group list
|
||||
.. mc-cmd:: list
|
||||
:fullpath:
|
||||
|
||||
List all groups on the target MinIO deployment. The command has the
|
||||
@ -176,12 +167,12 @@ Syntax
|
||||
The :mc-cmd:`alias <mc alias>` of a configured MinIO deployment from
|
||||
which to retrieve groups.
|
||||
|
||||
.. mc-cmd:: mc admin group remove
|
||||
.. mc-cmd:: remove
|
||||
:fullpath:
|
||||
|
||||
Removes a group on the target MinIO deployment. Removing a group does *not*
|
||||
remove any users with membership in the group. Use :mc-cmd:`mc admin user
|
||||
remove` to remove users from a group.
|
||||
remove any users with membership in the group. Use
|
||||
:mc-cmd:`mc admin user remove` to remove users from a group.
|
||||
|
||||
The command has the following syntax:
|
||||
|
||||
@ -205,7 +196,7 @@ Syntax
|
||||
:fullpath:
|
||||
|
||||
Enables the group on the target MinIO deployment. Users can only inherit
|
||||
:ref:`policies <minio-auth-authz-pbac-policies>` from an enabled group.
|
||||
:ref:`policies <minio-policy>` from an enabled group.
|
||||
Groups are enabled on creation by default. The command has the following
|
||||
syntax:
|
||||
|
||||
@ -229,7 +220,7 @@ Syntax
|
||||
:fullpath:
|
||||
|
||||
Disables the group on the target MinIO deployment. Users cannot inherit
|
||||
:ref:`policies <minio-auth-authz-pbac-policies>` from a disabled group. The
|
||||
:ref:`policies <minio-policy>` from a disabled group. The
|
||||
command has the following syntax:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
@ -23,52 +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
|
||||
:doc:`/security/minio-authentication-authorization`.
|
||||
|
||||
Quick Reference
|
||||
---------------
|
||||
|
||||
:mc-cmd:`mc admin policy add TARGET POLICYNAME POLICYFILE <mc admin policy add>`
|
||||
Creates a new policy on the target MinIO deployment.
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
mc admin policy add play myNewPolicy /path/to/policy.json
|
||||
|
||||
:mc-cmd:`mc admin policy list TARGET <mc admin policy list>`
|
||||
Lists the available policies on the target MinIO deployment.
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
mc admin policy list play
|
||||
|
||||
:mc-cmd:`mc admin policy info TARGET POLICYNAME <mc admin policy info>`
|
||||
Returns the policy in JSON format from the target MinIO deployment.
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
mc admin policy info play myNewPolicy
|
||||
|
||||
:mc-cmd:`mc admin policy set TARGET POLICYNAME user=|group= <mc admin policy set>`
|
||||
Associates a policy to a user or group on the target MinIO deployment.
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
mc admin policy set play myNewPolicy user=myMinioUser
|
||||
|
||||
mc admin policy set play myNewGroupPolicy group=myMinioGroup
|
||||
|
||||
:mc-cmd:`mc admin policy remove TARGET POLICYNAME <mc admin policy remove>`
|
||||
Removes a policy from the target MinIO deployment.
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
mc admin policy remove play myNewPolicy
|
||||
:ref:`minio-auth-authz-overview`.
|
||||
|
||||
Examples
|
||||
--------
|
||||
@ -320,7 +275,7 @@ Syntax
|
||||
as a comma-separated list.
|
||||
|
||||
MinIO deployments include the following :ref:`built-in policies
|
||||
<minio-auth-authz-pbac-built-in>` policies by default:
|
||||
<minio-policy-built-in>` policies by default:
|
||||
|
||||
- :userpolicy:`readonly`
|
||||
- :userpolicy:`readwrite`
|
||||
|
||||
@ -36,7 +36,7 @@ MinIO uses Policy-Based Access Control (PBAC) to support *authorization* of
|
||||
users who have successfully *authenticated* to the deployment. Each policy
|
||||
includes rules that dictate the allowed or denied actions/resources on the
|
||||
deployment. You can assign one or more :ref:`policies
|
||||
<minio-auth-authz-pbac-policies>` to a User. Users *also* inherit the policies
|
||||
<minio-policy>` to a User. Users *also* inherit the policies
|
||||
of any groups of which they are members. A user's total set of permissions
|
||||
includes their explicitly assigned policies *and* any policies inherited via
|
||||
group membership.
|
||||
@ -55,8 +55,8 @@ Each user's total set of permissions consists of their explicitly assigned
|
||||
permission *and* the inherited permissions from each of their assigned groups.
|
||||
|
||||
For more information on MinIO users and groups, see
|
||||
:ref:`minio-auth-authz-users` and :ref:`minio-auth-authz-groups`. For
|
||||
more information on MinIO policies, see :ref:`minio-auth-authz-pbac-policies`.
|
||||
:ref:`minio-users` and :ref:`minio-groups`. For
|
||||
more information on MinIO policies, see :ref:`minio-policy`.
|
||||
|
||||
.. admonition:: ``Deny`` overrides ``Allow``
|
||||
:class: note
|
||||
|
||||
@ -114,7 +114,7 @@ unsuccessful, check each of the following:
|
||||
S3 service. The user must have permission to perform actions on the
|
||||
service.
|
||||
|
||||
For MinIO deployments, see :doc:`/security/minio-authentication-authorization`
|
||||
For MinIO deployments, see :ref:`minio-auth-authz-overview`
|
||||
for more information on user access permissions. For other S3-compatible
|
||||
services, defer to the documentation for that service.
|
||||
|
||||
|
||||
@ -20,7 +20,7 @@ bucket Server-Side Encryption (SSE) mode. MinIO automatically encrypts
|
||||
objects using the specified SSE mode.
|
||||
|
||||
For more information on configuring SSE, see
|
||||
:doc:`/security/minio-security-server-side-encryption`.
|
||||
:ref:`minio-sse`
|
||||
|
||||
.. end-mc-encrypt-desc
|
||||
|
||||
|
||||
@ -262,7 +262,7 @@ Root Credentials
|
||||
|
||||
.. envvar:: MINIO_ACCESS_KEY
|
||||
|
||||
The access key for the :ref:`root <minio-auth-authz-root>` user.
|
||||
The access key for the :ref:`root <minio-users-root>` user.
|
||||
|
||||
.. warning::
|
||||
|
||||
@ -275,7 +275,7 @@ Root Credentials
|
||||
|
||||
.. envvar:: MINIO_SECRET_KEY
|
||||
|
||||
The secret key for the :ref:`root <minio-auth-authz-root>` user.
|
||||
The secret key for the :ref:`root <minio-users-root>` user.
|
||||
|
||||
.. warning::
|
||||
|
||||
@ -288,7 +288,7 @@ Root Credentials
|
||||
|
||||
.. envvar:: MINIO_ACCESS_KEY_OLD
|
||||
|
||||
Used for rotating the :ref:`root <minio-auth-authz-root>` user access
|
||||
Used for rotating the :ref:`root <minio-users-root>` user access
|
||||
key.
|
||||
|
||||
Restart the :mc:`minio server` process with *all* of the following
|
||||
@ -306,7 +306,7 @@ Root Credentials
|
||||
|
||||
.. envvar:: MINIO_SECRET_KEY_OLD
|
||||
|
||||
Used for rotating the :ref:`root <minio-auth-authz-root>` user secret
|
||||
Used for rotating the :ref:`root <minio-users-root>` user secret
|
||||
key.
|
||||
|
||||
Restart the :mc:`minio server` process with *all* of the following
|
||||
|
||||
80
source/security/IAM/iam-groups.rst
Normal file
80
source/security/IAM/iam-groups.rst
Normal file
@ -0,0 +1,80 @@
|
||||
.. _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:
|
||||
@ -1,8 +1,8 @@
|
||||
.. _minio-auth-authz-overview:
|
||||
.. _minio-policy:
|
||||
|
||||
================================
|
||||
Authentication and Authorization
|
||||
================================
|
||||
========
|
||||
Policies
|
||||
========
|
||||
|
||||
.. default-domain:: minio
|
||||
|
||||
@ -13,205 +13,33 @@ Authentication and Authorization
|
||||
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*:
|
||||
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.
|
||||
|
||||
- The access key corresponds to a user on the deployment, *and*
|
||||
- The secret key corresponds to the specified access key.
|
||||
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.
|
||||
|
||||
*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
|
||||
:iam-docs:`IAM actions and conditions
|
||||
<reference_policies_actions-resources-contextkeys.html>` when creating policies.
|
||||
By default, MinIO *denies* access to actions or resources not explicitly
|
||||
referenced in a user's assigned or inherited policies.
|
||||
MinIO by default *denies* access to any
|
||||
resource or operation not explicitly allowed by a user's assigned or inherited
|
||||
policies.
|
||||
|
||||
- For more information on MinIO user management, see
|
||||
:ref:`minio-auth-authz-users`.
|
||||
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 more information on MinIO group management, see
|
||||
:ref:`minio-auth-authz-groups`.
|
||||
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 information on MinIO policy creation, see
|
||||
:ref:`minio-auth-authz-pbac-policies`.
|
||||
|
||||
.. _minio-auth-authz-users:
|
||||
|
||||
Users
|
||||
-----
|
||||
|
||||
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-auth-authz-pbac-policies>` that explicitly list the actions and resources
|
||||
to which the user is allowed or denied access. Policies support *authorization*
|
||||
of operations on the MinIO deployment, such that clients can only perform
|
||||
an operation if the user's assigned policies allow access to both the operation
|
||||
*action* and the target *resources*.
|
||||
|
||||
For example, consider the following table of users. Each user is assigned
|
||||
a :ref:`built-in policy <minio-auth-authz-pbac-built-in>` or
|
||||
a supported :ref:`action <minio-auth-authz-pbac-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.
|
||||
|
||||
Users also inherit permissions from their assigned :ref:`groups
|
||||
<minio-auth-authz-groups>`. A user's total set of permissions consists of their
|
||||
explicitly assigned permissions *and* the inherited permissions from each of
|
||||
their assigned groups.
|
||||
|
||||
.. 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-auth-authz-root:
|
||||
|
||||
``root`` User
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
By default, MinIO deployments provide ``root`` user with access to all actions
|
||||
and resources on the deployment. The ``root`` user credentials are set when
|
||||
starting the ``minio`` server. 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.
|
||||
|
||||
.. _minio-auth-authz-groups:
|
||||
|
||||
Groups
|
||||
------
|
||||
|
||||
A *group* is a collection of :ref:`users <minio-auth-authz-users>`. Each group
|
||||
can have one or more assigned :ref:`policies <minio-auth-authz-pbac-policies>`
|
||||
that explicitly list the actions and resources to which group members are
|
||||
allowed or denied access.
|
||||
|
||||
For example, consider the following groups. Each group is assigned a
|
||||
:ref:`built-in policy <minio-auth-authz-pbac-built-in>` or supported
|
||||
:ref:`policy action <minio-auth-authz-pbac-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.
|
||||
|
||||
.. 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>`.
|
||||
|
||||
.. _minio-auth-authz-pbac-policies:
|
||||
|
||||
Policies
|
||||
--------
|
||||
|
||||
MinIO uses Policy-Based Access Control (PBAC) for supporting *authorization* of
|
||||
users who have successfully *authenticated* to the deployment. Each policy
|
||||
describes one or more rules that outline the permissions of a user or group of
|
||||
users. MinIO PBAC follows the guidelines and standards set by AWS Identity and
|
||||
Access Management (IAM). MinIO supports a subset of :iam-docs:`IAM actions and
|
||||
conditions <reference_policies_actions-resources-contextkeys.html>` when
|
||||
creating policies. By default, MinIO *denies* access to actions or resources not
|
||||
explicitly referenced in a user's assigned or inherited policies.
|
||||
|
||||
This section focuses on MinIO's implementation and extensions of IAM policies
|
||||
and access management. A complete description of IAM or IAM policies is out
|
||||
of scope of this documentation. Consider deferring to the
|
||||
:iam-docs:`IAM documentation <>` for more complete documentation on the
|
||||
IAM service.
|
||||
|
||||
.. _minio-auth-authz-pbac-built-in:
|
||||
.. _minio-policy-built-in:
|
||||
|
||||
Built-In Policies
|
||||
~~~~~~~~~~~~~~~~~
|
||||
-----------------
|
||||
|
||||
MinIO provides the following built-in policies for assigning to users
|
||||
and groups:
|
||||
MinIO provides the following built-in policies for assigning to
|
||||
:ref:`users <minio-users>` or :ref:`groups <minio-groups>`:
|
||||
|
||||
.. userpolicy:: readonly
|
||||
|
||||
@ -231,15 +59,18 @@ and groups:
|
||||
Grants write-only permissions for all buckets and objects on the MinIO
|
||||
server.
|
||||
|
||||
.. _minio-auth-authz-pbac-document:
|
||||
Use :mc-cmd:`mc admin policy set` to associate a policy to a
|
||||
user or group on a MinIO deployment.
|
||||
|
||||
.. _minio-policy-document:
|
||||
|
||||
Policy Document Structure
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
-------------------------
|
||||
|
||||
MinIO policy documents use the same schema as
|
||||
:aws-docs:`AWS IAM Policy <IAM/latest/UserGuide/access.html>` documents.
|
||||
|
||||
The following sample document provides a general schema for creating custom
|
||||
The following sample document provides a template for creating custom
|
||||
policies for use with a MinIO deployment. For more complete documentation on IAM
|
||||
policy elements, see the :aws-docs:`IAM JSON Policy Elements Reference
|
||||
<IAM/latest/UserGuide/reference_policies_elements.html>`.
|
||||
@ -266,7 +97,7 @@ policy elements, see the :aws-docs:`IAM JSON Policy Elements Reference
|
||||
}
|
||||
|
||||
- For the ``Statement.Action`` array, specify one or more
|
||||
:ref:`supported S3 actions <minio-auth-authz-pbac-actions>`. MinIO deployments
|
||||
:ref:`supported S3 actions <minio-policy-actions>`. MinIO deployments
|
||||
supports a subset of AWS S3 actions.
|
||||
|
||||
- For the ``Statement.Resource`` key, you can replace the ``*`` with
|
||||
@ -274,13 +105,13 @@ policy elements, see the :aws-docs:`IAM JSON Policy Elements Reference
|
||||
Using ``*`` applies the statement to all resources on the MinIO deployment.
|
||||
|
||||
- For the ``Statement.Condition`` key, you can specify one or more
|
||||
:ref:`supported Conditions <minio-auth-authz-pbac-conditions>`. MinIO
|
||||
:ref:`supported Conditions <minio-policy-conditions>`. MinIO
|
||||
deployments supports a subset of AWS S3 conditions.
|
||||
|
||||
.. _minio-auth-authz-pbac-actions:
|
||||
.. _minio-policy-actions:
|
||||
|
||||
Supported Policy Actions
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Supported S3 Policy Actions
|
||||
---------------------------
|
||||
|
||||
MinIO policy documents support a subset of IAM
|
||||
:iam-docs:`S3 Action keys <list_amazons3.html#amazons3-actions-as-permissions>`.
|
||||
@ -558,7 +389,7 @@ The following table lists the MinIO-supported policy action keys.
|
||||
<API_GetObjectVersionForReplication.html>` IAM action.
|
||||
|
||||
|
||||
.. _minio-auth-authz-pbac-mc-admin-actions:
|
||||
.. _minio-policy-mc-admin-actions:
|
||||
|
||||
``mc admin`` Policy Action Keys
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
@ -716,10 +547,10 @@ services:
|
||||
|
||||
Allows getting bucket targets
|
||||
|
||||
.. _minio-auth-authz-pbac-conditions:
|
||||
.. _minio-policy-conditions:
|
||||
|
||||
Supported Policy Condition Keys
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Supported S3 Policy Condition Keys
|
||||
----------------------------------
|
||||
|
||||
MinIO policy documents support IAM
|
||||
:iam-docs:`conditional statements <reference_policies_elements_condition.html>`.
|
||||
@ -732,7 +563,7 @@ information on any listed condition key, see the
|
||||
<reference_policies_elements_condition.html>`
|
||||
|
||||
MinIO supports the following condition keys for all supported
|
||||
:ref:`actions <minio-auth-authz-pbac-actions>`:
|
||||
:ref:`actions <minio-policy-actions>`:
|
||||
|
||||
- ``aws:Referer``
|
||||
- ``aws:SourceIp``
|
||||
@ -802,10 +633,10 @@ actions:
|
||||
- ``s3:versionid``
|
||||
|
||||
``mc admin`` Policy Condition Keys
|
||||
``````````````````````````````````
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
MinIO supports the following conditions for use with defining policies for
|
||||
:mc-cmd:`mc admin` :ref:`actions <minio-auth-authz-pbac-mc-admin-actions>`.
|
||||
:mc-cmd:`mc admin` :ref:`actions <minio-policy-mc-admin-actions>`.
|
||||
|
||||
- ``aws:Referer``
|
||||
- ``aws:SourceIp``
|
||||
@ -818,19 +649,18 @@ For complete information on any listed condition key, see the :iam-docs:`IAM
|
||||
Condition Element Documentation <reference_policies_elements_condition.html>`
|
||||
|
||||
Creating Custom Policies
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
------------------------
|
||||
|
||||
Use the ``mc admin policy`` command to add a policy to the MinIO
|
||||
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:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
mc config host add myminio http://myminio1.example.net:9000 <access_key> <secret_key>
|
||||
|
||||
mc admin policy add myminio/ new_policy new_policy.json
|
||||
|
||||
To add this policy to a user or group, use the ``mc admin policy set`` command:
|
||||
Use the :mc-cmd:`mc admin policy set` command to associate a policy to a
|
||||
:ref:`user <minio-users>` or :ref:`group <minio-groups>`.
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
@ -838,3 +668,8 @@ To add this policy to a user or group, use the ``mc admin policy set`` command:
|
||||
|
||||
mc admin policy set myminio/ new_policy group=group_name
|
||||
|
||||
.. note::
|
||||
|
||||
``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.
|
||||
11
source/security/IAM/iam-providers.rst
Normal file
11
source/security/IAM/iam-providers.rst
Normal file
@ -0,0 +1,11 @@
|
||||
=========
|
||||
Providers
|
||||
=========
|
||||
|
||||
.. default-domain:: minio
|
||||
|
||||
.. contents:: Table of Contents
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
Stub - might duplicate STS page?
|
||||
@ -1,14 +1,14 @@
|
||||
.. _minio-sts-overview:
|
||||
.. _minio-sts:
|
||||
|
||||
============================
|
||||
MinIO Security Token Service
|
||||
============================
|
||||
======================
|
||||
Security Token Service
|
||||
======================
|
||||
|
||||
.. default-domain:: minio
|
||||
|
||||
.. contents:: Table of Contents
|
||||
:local:
|
||||
:depth: 1
|
||||
:depth: 2
|
||||
|
||||
Overview
|
||||
--------
|
||||
138
source/security/IAM/iam-users.rst
Normal file
138
source/security/IAM/iam-users.rst
Normal file
@ -0,0 +1,138 @@
|
||||
.. _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 envrionment variables:
|
||||
|
||||
- :envvar:`MINIO_ACCESS_KEY`
|
||||
- :envvar:`MINIO_SECRET_KEY`
|
||||
|
||||
To rotate the ``root`` user credentials, set the following environment
|
||||
variables and restart the :mc:`minio` server:
|
||||
|
||||
- :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.
|
||||
|
||||
After the :mc:`minio` server starts successfully, you can unset the
|
||||
:envvar:`MINIO_ACCESS_KEY_OLD` and :envvar:`MINIO_SECRET_KEY_OLD`.
|
||||
|
||||
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.
|
||||
|
||||
Create a User
|
||||
-------------
|
||||
|
||||
Use the :mc-cmd:`mc admin user add` command to create a new user on the
|
||||
MinIO deployment:
|
||||
|
||||
Delete a User
|
||||
-------------
|
||||
|
||||
Use the :mc-cmd:`mc admin user remove` command to remove a user on a
|
||||
MinIO deployment:
|
||||
|
||||
Authenticate as a User
|
||||
----------------------
|
||||
|
||||
ToDo: Examples of authenticating to a MinIO deployment with a created user.
|
||||
|
||||
Should have examples with `mc` and each of the SDKs.
|
||||
96
source/security/IAM/identity-access-management.rst
Normal file
96
source/security/IAM/identity-access-management.rst
Normal file
@ -0,0 +1,96 @@
|
||||
.. _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
|
||||
:iam-docs:`IAM actions and conditions
|
||||
<reference_policies_actions-resources-contextkeys.html>` 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 :ref:`Secure Token Service <minio-sts>`. Supported
|
||||
identity providers include Okta, Facebook, Google, and Active Directory/LDAP.
|
||||
For more complete documentation on MinIO STS configuration, see
|
||||
:ref:`minio-sts`.
|
||||
|
||||
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.
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
:titlesonly:
|
||||
|
||||
/security/IAM/iam-users
|
||||
/security/IAM/iam-groups
|
||||
/security/IAM/iam-policies
|
||||
/security/IAM/iam-providers
|
||||
/security/IAM/iam-security-token-service
|
||||
49
source/security/encryption/encryption-key-management.rst
Normal file
49
source/security/encryption/encryption-key-management.rst
Normal file
@ -0,0 +1,49 @@
|
||||
=============================
|
||||
Encryption and Key Management
|
||||
=============================
|
||||
|
||||
.. default-domain:: minio
|
||||
|
||||
.. contents:: Table of Contents
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
MinIO supports key security features around object-level and network-level
|
||||
encryption:
|
||||
|
||||
Server-Side Object Encryption
|
||||
-----------------------------
|
||||
|
||||
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.
|
||||
Only clients with access to the correct secret key can decrypt and read the
|
||||
object.
|
||||
|
||||
<Diagram to follow>
|
||||
|
||||
See :ref:`Server-Side Object Encryption (SSE) <minio-sse>` for more complete
|
||||
instructions on configuring MinIO for object encryption.
|
||||
|
||||
Transport Layer Security (TLS)
|
||||
------------------------------
|
||||
|
||||
MinIO supports :ref:`Transport Layer Security (TLS) <minio-TLS>` encryption of
|
||||
incoming and outgoing traffic.
|
||||
|
||||
<Diagram to Follow>
|
||||
|
||||
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:`Transport Layer Security (TLS) <minio-TLS>`
|
||||
for more complete instructions on configuring MinIO for TLS.
|
||||
|
||||
.. toctree::
|
||||
:titlesonly:
|
||||
:hidden:
|
||||
|
||||
/security/encryption/server-side-encryption
|
||||
/security/encryption/transport-layer-security
|
||||
/security/encryption/minio-kes
|
||||
/security/encryption/sse-s3-thales
|
||||
84
source/security/encryption/minio-kes.rst
Normal file
84
source/security/encryption/minio-kes.rst
Normal file
@ -0,0 +1,84 @@
|
||||
.. _minio-kes:
|
||||
|
||||
============================
|
||||
MinIO Key Encryption Service
|
||||
============================
|
||||
|
||||
.. default-domain:: minio
|
||||
|
||||
.. contents:: Table of Contents
|
||||
:local:
|
||||
:depth: 2
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
The MinIO Key Encryption Service (KES) is a stateless and distributed
|
||||
key-management system for high-performance applications. KES provides
|
||||
a bridge between applications running in bare-metal or orchestrated
|
||||
environments to centralised KMS solutions.
|
||||
|
||||
<DIAGRAM>
|
||||
|
||||
KES is designed for simplicity, scalability, and security. It requires
|
||||
minimal configuration to enable full functionality and requires only
|
||||
basic familiarity with cryptography or key-management concepts.
|
||||
|
||||
MinIO servers require KES for performing Server-Side Encryption (SSE) of objects
|
||||
using Key Management Services (KMS).
|
||||
|
||||
KES Server Process
|
||||
------------------
|
||||
|
||||
.. mc:: kes server
|
||||
|
||||
:mc:`kes server` command starts the KES server. The :mc:`kes server` process
|
||||
handles requests for creating and retrieving cryptography keys from a supported
|
||||
Key Management System (KMS).
|
||||
|
||||
The command has the following syntax:
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
kes server --cert CERTIFICATE --key PRIVATEKEY --root ROOT_IDENTITY [OPTIONAL_FLAGS]
|
||||
|
||||
:mc:`kes server` supports the following arguments:
|
||||
|
||||
.. mc-cmd:: cert
|
||||
:option:
|
||||
|
||||
The location of the public certificate ``.crt`` to use for
|
||||
enabling :abbr:`TLS (Transport Layer Encryption)`.
|
||||
|
||||
.. mc-cmd:: config
|
||||
:option:
|
||||
|
||||
The path to the KES configuration file. See :ref:`minio-kes-config` for
|
||||
more information on the configuration file format and contents.
|
||||
|
||||
.. mc-cmd:: key
|
||||
:option:
|
||||
|
||||
The location of the private key ``.key`` to use for enabling
|
||||
:abbr:`TLS (Transport Layer Encryption`).
|
||||
|
||||
.. mc-cmd:: root
|
||||
:option:
|
||||
|
||||
ToDo: Description
|
||||
|
||||
.. mc-cmd:: port
|
||||
:option:
|
||||
|
||||
The port on which the :mc:`kes server` listens.
|
||||
|
||||
Defaults to ``7373``.
|
||||
|
||||
.. _minio-kes-config:
|
||||
|
||||
KES Configuration File
|
||||
----------------------
|
||||
|
||||
ToDo: Import https://github.com/minio/kes/wiki/Configuration , need to
|
||||
include instructions on how to set the config file (directory, cli option etc.)
|
||||
@ -1,3 +1,5 @@
|
||||
.. _minio-sse:
|
||||
|
||||
=============================
|
||||
Server-Side Object Encryption
|
||||
=============================
|
||||
@ -24,8 +26,8 @@ SSE-C
|
||||
|
||||
SSE-S3
|
||||
The server uses a secret key managed by a Key Management System (KMS)
|
||||
to perform encryption and decryption. SSE-S3 requires a compatible KMS
|
||||
provider accessible by the MinIO server.
|
||||
to perform encryption and decryption. SSE-S3 requires using
|
||||
:ref:`MinIO KES <minio-kes>` and a supported KMS.
|
||||
|
||||
Encryption Process Overview
|
||||
---------------------------
|
||||
@ -56,11 +58,9 @@ object:
|
||||
object. MinIO encrypts the OEK using the KEK and stores the encrypted
|
||||
OEK as metadata with the object.
|
||||
|
||||
SSE Encryption Types
|
||||
--------------------
|
||||
|
||||
SSE with Client Provided Keys (SSE-C)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
SSE using S3-Client Keys (SSE-C)
|
||||
--------------------------------
|
||||
|
||||
SSE-C allows S3 clients to specify an Encryption Key (EK) for encrypting or
|
||||
decrypting an object stored on the MinIO server. The S3 client sends the secret
|
||||
@ -77,7 +77,7 @@ compromise of that EK *also* results in the loss or compromise of all data
|
||||
encrypted with that EK.
|
||||
|
||||
Key Rotation
|
||||
````````````
|
||||
~~~~~~~~~~~~
|
||||
|
||||
S3 clients can rotate the client EK of an existing object using an S3 ``COPY``
|
||||
operation. The ``COPY`` source and destination *must* be the same, while the
|
||||
@ -93,8 +93,8 @@ object:
|
||||
|
||||
Such a special COPY request is also known as S3 SSE-C key rotation.
|
||||
|
||||
SSE with KMS Provided Keys (SSE-S3)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
SSE using a Key Management Service (SSE-S3)
|
||||
-------------------------------------------
|
||||
|
||||
SSE-S3 allows S3 clinets to encrypt or decrypt an object at the MinIO server
|
||||
using an external Key Management Service (KMS). The MinIO server requires
|
||||
@ -108,14 +108,19 @@ the KMS provide the following services:
|
||||
along with an encrypted data key. The KMS uses the master key to decrypt
|
||||
the data key and return the plain data key.
|
||||
|
||||
The MinIO server requests a new data key from the KMS for each uploaded
|
||||
object and uses that data key as the Encryption Key (EK). MinIO stores
|
||||
the encrypted EK and the master key ID as part of the object metadata.
|
||||
While the MinIO server never stores the plain EK to disk, the EK resides
|
||||
in system RAM during the encryption or decryption process.
|
||||
Enabling SSE-S3 requires deploying one or more
|
||||
:ref:`MinIO Key Encryption Servers (KES) <minio-kes>` and configuring the
|
||||
:mc:`minio` server for access to KES. The KES handles processing
|
||||
cryptographic key requests to the KMS service.
|
||||
|
||||
With SSE-S3, the MinIO server requests a new data key for each uploaded object
|
||||
and uses that data key as the Encryption Key (EK). MinIO stores the encrypted EK
|
||||
and the master key ID as part of the object metadata. While the MinIO server
|
||||
never stores the plain EK to disk, the EK resides in system RAM during the
|
||||
encryption or decryption process.
|
||||
|
||||
Key Rotation
|
||||
````````````
|
||||
~~~~~~~~~~~~
|
||||
|
||||
The MinIO server supports key rotation for SSE-S3 encrypted objects. The MinIO
|
||||
server decrypts the Object Encryption Key (OEK) using the current encrypted data
|
||||
@ -130,7 +135,7 @@ Only the root MinIO user can perform an SSE-S3 key rotation using the Admin-API
|
||||
the ``mc`` client. Refer to the ``mc admin guide`` <todo>
|
||||
|
||||
Secure Erasure and Locking
|
||||
``````````````````````````
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The MinIO server requires an available KMS to en/decrypt SSE-S3 encrypted
|
||||
objects. Therefore it is possible to erase or lock some or all encrypted
|
||||
57
source/security/encryption/sse-s3-thales.rst
Normal file
57
source/security/encryption/sse-s3-thales.rst
Normal file
@ -0,0 +1,57 @@
|
||||
==============================================
|
||||
Server-Side Encryption with Thales CipherTrust
|
||||
==============================================
|
||||
|
||||
.. default-domain:: minio
|
||||
|
||||
.. contents:: Table of Contents
|
||||
:local:
|
||||
:depth: 2
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
Paragraph summarizing SSE-S3 and Thales CipherTrust as a KMS.
|
||||
|
||||
Note that Gemalto KeySecure is now Thales CipherTrust.
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
Thales CipherTrust Deployment
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
High-Level description of CipherTrust requirements:
|
||||
|
||||
- What access will the user need?
|
||||
- What versions do we support?
|
||||
|
||||
MinIO Key Encryption Service
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
High-level description of KES requirements:
|
||||
|
||||
- A host for deploying at least one KES server
|
||||
- For Kubernetes, at least one node with enough resources to run the server
|
||||
|
||||
MinIO Server
|
||||
~~~~~~~~~~~~
|
||||
|
||||
High-level description of MinIO server requirements:
|
||||
|
||||
- ?
|
||||
|
||||
Procedure
|
||||
---------
|
||||
|
||||
1) Configure CipherTrust Manager for MinIO Access
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Substeps:
|
||||
|
||||
1. Foo
|
||||
|
||||
2. Bar
|
||||
|
||||
2) Configure KES...
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
@ -1,47 +0,0 @@
|
||||
==============
|
||||
MinIO Security
|
||||
==============
|
||||
|
||||
.. default-domain:: minio
|
||||
|
||||
MinIO provides support for the following security features:
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
:widths: 30 70
|
||||
|
||||
* - Feature
|
||||
- Description
|
||||
|
||||
* - Server-Side Object Encryption
|
||||
- Encrypt objects using a secret key provided by the S3 client
|
||||
or a supported Key Management System (KMS). Only clients with access
|
||||
to the secret key can decrypt the object.
|
||||
|
||||
* - Transport Layer Security (TLS) Encryption
|
||||
- Enable TLS encryption of all network traffic. Several MinIO
|
||||
security features, such as Server-Side Object Encryption, require
|
||||
TLS encryption to ensure end-to-end security of data.
|
||||
|
||||
* - Policy Based Access Control (RBAC)
|
||||
- MinIO uses :aws-docs:`IAM-compatible policy documents
|
||||
<IAM/latest/UserGuide/access_policies>` for controlling user privileges.
|
||||
You can also assign privileges to a group, where all members of the
|
||||
group inherit the group privileges. MinIO provides built-in
|
||||
policies for the most common access patterns.
|
||||
|
||||
* - Security Token Service (STS)
|
||||
- MinIO Security Token Service (STS) is an endpoint service that allows
|
||||
clients to request temporary credentials for accessing MinIO resources.
|
||||
MinIO STS supports multiple forms of identity federation, including
|
||||
OpenID identity providers and Active Directory/LDAP services.
|
||||
|
||||
|
||||
.. toctree::
|
||||
:titlesonly:
|
||||
:hidden:
|
||||
|
||||
/security/minio-authentication-authorization
|
||||
/security/minio-security-TLS-encryption
|
||||
/security/minio-security-server-side-encryption
|
||||
/security/minio-security-security-token-service
|
||||
22
source/security/security-overview.rst
Normal file
22
source/security/security-overview.rst
Normal file
@ -0,0 +1,22 @@
|
||||
==============
|
||||
MinIO 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.
|
||||
|
||||
: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.
|
||||
|
||||
.. toctree::
|
||||
:titlesonly:
|
||||
:hidden:
|
||||
|
||||
/security/IAM/identity-access-management
|
||||
/security/encryption/encryption-key-management
|
||||
@ -258,7 +258,7 @@ class MinioObject(ObjectDescription):
|
||||
|
||||
#: If ``allow_nesting`` is ``True``, the object prefixes will be accumulated
|
||||
#: based on directive nesting
|
||||
allow_nesting = False
|
||||
allow_nesting = True
|
||||
|
||||
option_spec = {
|
||||
'noindex': directives.flag,
|
||||
@ -273,73 +273,24 @@ class MinioObject(ObjectDescription):
|
||||
directives.
|
||||
"""
|
||||
sig = sig.strip()
|
||||
if '(' in sig and sig[-1:] == ')':
|
||||
member, arglist = sig.split('(', 1)
|
||||
member = member.strip()
|
||||
arglist = arglist[:-1].strip()
|
||||
elif ',' in sig:
|
||||
# Bit ugly. For subcommands w/ aliases
|
||||
member, alias = sig.split(',', 1)
|
||||
member = member.strip()
|
||||
alias = alias.strip()
|
||||
else:
|
||||
member = sig
|
||||
arglist = None
|
||||
alias = None
|
||||
|
||||
member = sig
|
||||
# If construct is nested, prefix the current prefix
|
||||
prefix = self.env.ref_context.get('minio:object', None)
|
||||
mod_name = self.env.ref_context.get('minio:command')
|
||||
name = member
|
||||
try:
|
||||
member_prefix, member_name = member.rsplit('.', 1)
|
||||
except ValueError:
|
||||
member_name = name
|
||||
member_prefix = ''
|
||||
finally:
|
||||
name = member_name
|
||||
if prefix and member_prefix:
|
||||
prefix = '.'.join([prefix, member_prefix])
|
||||
elif prefix is None and member_prefix:
|
||||
prefix = member_prefix
|
||||
fullname = name
|
||||
if prefix and self.allow_nesting==False:
|
||||
fullname = '.'.join([prefix, name])
|
||||
elif prefix and self.allow_nesting==True:
|
||||
fullname = ' '.join([prefix, name])
|
||||
|
||||
signode['module'] = mod_name
|
||||
fullname = member
|
||||
|
||||
if prefix:
|
||||
fullname = '.'.join([prefix, member])
|
||||
|
||||
signode['object'] = prefix
|
||||
signode['fullname'] = fullname
|
||||
|
||||
if self.display_prefix:
|
||||
signode += addnodes.desc_annotation(self.display_prefix,
|
||||
self.display_prefix)
|
||||
if prefix:
|
||||
signode += addnodes.desc_addname(prefix + '.', prefix + '.')
|
||||
|
||||
# In our current usage, we only nest for command/subcommand. So we
|
||||
# need to split some of the logic here from nesting of YAML or JSON
|
||||
# So if allow_nesting is true, we should use " " instead of "." for
|
||||
# the prefix description.
|
||||
# We also have an exit for the 'subcommand' type so that we don't end
|
||||
# up building long name strings for subcommands
|
||||
# Finally for subcommands w/ aliases, need to append the alias name
|
||||
signode += addnodes.desc_name(member, member)
|
||||
|
||||
|
||||
if prefix and self.allow_nesting == False:
|
||||
signode += addnodes.desc_addname(prefix + '.', prefix + '.')
|
||||
elif prefix and self.allow_nesting == True and self.objtype != 'subcommand':
|
||||
signode += addnodes.desc_addname(prefix + ' ', prefix + ' ')
|
||||
signode += addnodes.desc_addname(alias + ' ', alias + ' ')
|
||||
elif mod_name:
|
||||
signode += addnodes.desc_addname(mod_name + '.', mod_name + '.')
|
||||
if (alias != None):
|
||||
signode += addnodes.desc_name(name + ", " + alias, name + ", " + alias)
|
||||
else:
|
||||
signode += addnodes.desc_name(name, name)
|
||||
if self.has_arguments:
|
||||
if not arglist:
|
||||
signode += addnodes.desc_parameterlist()
|
||||
else:
|
||||
_pseudo_parse_arglist(signode, arglist)
|
||||
return fullname, prefix
|
||||
|
||||
def add_target_and_index(self, name_obj: Tuple[str, str], sig: str,
|
||||
@ -533,7 +484,7 @@ class MinIODomain(Domain):
|
||||
'mc-cmd': ObjType(_('mc-cmd'), 'mc-cmd'),
|
||||
'mc-cmd-option': ObjType(_('mc-cmd-option'), 'mc-cmd-option'),
|
||||
'policy-action': ObjType(_('policy-action'), 'policy-action'),
|
||||
'envvar': ObjType(_('envvar'), 'envvar')
|
||||
'envvar': ObjType(_('envvar'), 'envvar')
|
||||
}
|
||||
directives = {
|
||||
'data': MinioObject,
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user