From: Casey Bodley Date: Wed, 20 Dec 2023 03:11:05 +0000 (-0500) Subject: doc/radosgw: start on iam/account docs X-Git-Tag: testing/wip-pdonnell-testing-20240416.232051-debug~25^2~68 X-Git-Url: http://git.apps.os.sepia.ceph.com/?a=commitdiff_plain;h=019f1a83cbcf08b2ba3894ef6d64a14146ba6293;p=ceph-ci.git doc/radosgw: start on iam/account docs Signed-off-by: Casey Bodley --- diff --git a/doc/radosgw/account.rst b/doc/radosgw/account.rst new file mode 100644 index 00000000000..ff6dba96640 --- /dev/null +++ b/doc/radosgw/account.rst @@ -0,0 +1,187 @@ +=============== + User Accounts +=============== + +.. versionadded:: Squid + +The Ceph Object Gateway supports *user accounts* as an optional feature to +enable the self-service management of :ref:`Users `, +Groups and `Roles`_ similar to those in `AWS Identity and Access Management`_ +(IAM). + +.. _radosgw-account-root-user: + +Account Root User +================= + +Each account is managed by an *account root user*. Like normal users and roles, +accounts and account root users must be created by an administrator using +``radosgw-admin`` or the `Admin Ops API`_. + +The account root user has default permissions on all resources owned by +the account. The root user's credentials (access and secret keys) can be +used with the `Ceph Object Gateway IAM API`_ to create additional IAM users +and roles for use with the `Ceph Object Gateway S3 API`_, as well as to +manage their associated access keys and policies. + +Account owners are encouraged to use this account root user for management +only, and create users and roles with fine-grained permissions for specific +applications. + +.. warning:: While the account root user does not require IAM policy to + access resources within the account, it is possible to add policy that + denies their access explicitly. Use Deny statements with caution. + +Resource Ownership +================== + +When a normal (non-account) user creates buckets and uploads objects, those +resources are owned by the user. The associated S3 ACLs name that user as +both the owner and grantee, and those buckets are only visible to the owning +user in a ``s3:ListBuckets`` request. + +In contrast, when users or roles belong to an account, the resources they +create are instead owned by the account itself. The associated S3 ACLs name +the account id as the owner and grantee, and those buckets are visible to +``s3:ListBuckets`` requests sent by any user or role in that account. + +Because the resources are owned by the account rather than its users, all +usage statistics and quota enforcement apply to the account as a whole rather +than its individual users. + +Account IDs +=========== + +Account identifiers can be used in several places that otherwise accept +User IDs or tenant names, so Account IDs use a special format to avoid +ambiguity: the string ``RGW`` followed by 17 numeric digits like +``RGW33567154695143645``. An Account ID in that format is randomly generated +upon account creation if one is not specified. + +Account IDs are commonly found in the `Amazon Resource Names`_ (ARNs) of IAM +policy documents. For example, ``arn:aws:iam::RGW33567154695143645:user/A`` +refers to an IAM user named A in that account. The Ceph Object Gateway also +supports tenant names in that position. + +Accounts IDs can also be used in ACLs for a ``Grantee`` of type ``CanonicalUser``. +User IDs are also supported here. + +IAM Policy +========== + +While non-account users are allowed to create buckets and upload objects by +default, account users start with no permissions at all. + +Before an IAM user can perform API operations, some policy must be added to +allow it. The account root user can add identity policies to its users in +several ways. + +* Add policy directly to the user with the ``iam:PutUserPolicy`` and + ``iam:AttachUserPoliicy`` actions. + +* Create an IAM group and add group policy with the ``iam:PutGroupPolicy`` and + ``iam:AttachGroupPoliicy`` actions. Users added to that group with the + ``iam:AddUserToGroup`` action will inherit all of the group's policy. + +* Create an IAM role and add role policy with the ``iam:PutRolePolicy`` and + ``iam:AttachRolePoliicy`` actions. Users that assume this role with the + ``sts:AssumeRole`` and ``sts:AssumeRoleWithWebIdentity`` actions will inherit + all of the role's policy. + +These identity policies are evaluated according to the rules in +`Evaluating policies within a single account`_ and +`Cross-account policy evaluation logic`_. + +Principals +---------- + +The "Principal" ARNs in policy documents refer to users differently when they +belong to an account. + +Outside of an account, user principals are named by user id such as +``arn:aws:iam:::user/uid`` or ``arn:aws:iam::tenantname:user/uid``, where +``uid`` corresponds to the ``--uid`` argument from ``radosgw-admin``. + +Within an account, user principals instead use the user name, such as +``arn:aws:iam::RGW33567154695143645:user/name`` where ``name`` corresponds +to the ``--display-name`` argument from ``radosgw-admin``. Account users +continue to match the tenant form so that existing policy continues to work +when users are migrated into accounts. + +Tenant Isolation +================ + +Like users, accounts can optionally belong to a tenant for namespace isolation +of buckets. For example, one account named "acct" can exist under a tenant "a", +and a different account named "acct" can exist under tenant "b". Refer to +:ref:`Multitenancy ` for details. + +A tenanted account can only contain users with the same tenant name. + +Regardless of tenant, account IDs and email addresses must be globally unique. + +Account Management +================== + +Create an Account +----------------- + +To create an account:: + + radosgw-admin account create [--account-name={name}] [--account-id={id}] [--email={email}] + +Create an Account Root User +--------------------------- + +To create an account root user:: + + radosgw-admin user create --uid={userid} --display-name={name} --account-id={accountid} --account-root --gen-secret --gen-access-key + +Delete an Account +----------------- + +To delete an account:: + + radosgw-admin account rm --account-id={accountid} + +Account Stats/Quota +------------------- + +To view account stats:: + + radosgw-admin account stats --account-id={accountid} --sync-stats + +To enable an account quota:: + + radosgw-admin quota set --account-id={accountid} --max-size=10G + radosgw-admin quota enable --account-id={accountid} + +Migrate an existing User into an Account +---------------------------------------- + +An existing user can be adopted into an account with ``user modify``:: + + radosgw-admin user modify --uid={userid} --account-id={accountid} + +.. note:: Ownership of all of the user's buckets will be transferred to + the account. + +.. note:: Account membership is permanent. Once added, users cannot be + removed from their account. + +Because account users have no permissions by default, some identity policy must +be added to restore the user's original permissions. + +Alternatively, you may want to create a new account for each existing user. In +that case, you may want to add the ``--account-root`` option to make each user +the root user of their account. + + +.. _Roles: ../role/ +.. _AWS Identity and Access Management: https://aws.amazon.com/iam/ +.. _Ceph Object Gateway IAM API: ../iam/ +.. _Admin Ops API: ../adminops/ +.. _Ceph Object Gateway S3 API: ../s3/ +.. _Amazon Resource Names: https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html +.. _Evaluating policies within a single account: https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_evaluation-logic.html#policy-eval-basics +.. _Cross-account policy evaluation logic: https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_evaluation-logic-cross-account.html diff --git a/doc/radosgw/admin.rst b/doc/radosgw/admin.rst index 6e09bfefb2b..93ea283a206 100644 --- a/doc/radosgw/admin.rst +++ b/doc/radosgw/admin.rst @@ -5,13 +5,16 @@ After the Ceph Object Storage service is up and running, it can be administered with user management, access controls, quotas, and usage tracking. +.. _radosgw-user-management: + User Management =============== Ceph Object Storage user management refers only to users of the Ceph Object Storage service and not to the Ceph Object Gateway as a user of the Ceph Storage Cluster. Create a user, access key, and secret key to enable end users -to interact with Ceph Object Gateway services. +to interact with Ceph Object Gateway services. Optionally, the users can belong +to `Accounts`_ for ease of management. There are two types of user: @@ -22,12 +25,16 @@ There are two types of user: .. ditaa:: +---------+ - | User | + | Account | +----+----+ | - | +-----------+ - +-----+ Subuser | - +-----------+ + | +---------+ + +-----+ User | + +----+----+ + | + | +-----------+ + +-----+ Subuser | + +-----------+ Users and subusers can be created, modified, viewed, suspended and removed. you may add a Display names and an email addresses can be added to user @@ -892,3 +899,4 @@ example commands: .. _radosgw-admin: ../../man/8/radosgw-admin/ .. _Pool Configuration: ../../rados/configuration/pool-pg-config-ref/ .. _Ceph Object Gateway Config Reference: ../config-ref/ +.. _Accounts: ../account/ diff --git a/doc/radosgw/iam.rst b/doc/radosgw/iam.rst new file mode 100644 index 00000000000..230fd176dda --- /dev/null +++ b/doc/radosgw/iam.rst @@ -0,0 +1,157 @@ +============================= + Ceph Object Gateway IAM API +============================= + +.. versionadded:: Squid + +The Ceph Object Gateway supports a subset of the `Amazon IAM API`_ for +the RESTful management of account users, roles, and associated policies. + +This REST API is served by the same HTTP endpoint as the +`Ceph Object Gateway S3 API`_. + +Authorization +============= + +By default, only :ref:`Account Root Users ` are +authorized to use the IAM API, and can only see the resources under their own +account. The account root user can use policies to delegate these permissions +to other users or roles in the account. + +Feature Support +=============== + +The following tables describe the currently supported IAM actions. + +Users +----- + ++------------------------------+---------------------------------------------+ +| Action | Remarks | ++==============================+=============================================+ +| **CreateUser** | | ++------------------------------+---------------------------------------------+ +| **GetUser** | | ++------------------------------+---------------------------------------------+ +| **UpdateUser** | | ++------------------------------+---------------------------------------------+ +| **DeleteUser** | | ++------------------------------+---------------------------------------------+ +| **ListUsers** | | ++------------------------------+---------------------------------------------+ +| **CreateAccessKey** | | ++------------------------------+---------------------------------------------+ +| **UpdateAccessKey** | | ++------------------------------+---------------------------------------------+ +| **DeleteAccessKey** | | ++------------------------------+---------------------------------------------+ +| **ListAccessKeys** | | ++------------------------------+---------------------------------------------+ +| **PutUserPolicy** | | ++------------------------------+---------------------------------------------+ +| **GetUserPolicy** | | ++------------------------------+---------------------------------------------+ +| **DeleteUserPolicy** | | ++------------------------------+---------------------------------------------+ +| **ListUserPolicies** | | ++------------------------------+---------------------------------------------+ +| **AttachUserPolicies** | | ++------------------------------+---------------------------------------------+ +| **DetachUserPolicy** | | ++------------------------------+---------------------------------------------+ +| **ListAttachedUserPolicies** | | ++------------------------------+---------------------------------------------+ + +Groups +------ + ++-------------------------------+--------------------------------------------+ +| Action | Remarks | ++===============================+============================================+ +| **CreateGroup** | | ++-------------------------------+--------------------------------------------+ +| **GetGroup** | | ++-------------------------------+--------------------------------------------+ +| **UpdateGroup** | | ++-------------------------------+--------------------------------------------+ +| **DeleteGroup** | | ++-------------------------------+--------------------------------------------+ +| **ListGroups** | | ++-------------------------------+--------------------------------------------+ +| **AddUserToGroup** | | ++-------------------------------+--------------------------------------------+ +| **RemoveUserFromGroup** | | ++-------------------------------+--------------------------------------------+ +| **ListGroupsForUser** | | ++-------------------------------+--------------------------------------------+ +| **PutGroupPolicy** | | ++-------------------------------+--------------------------------------------+ +| **GetGroupPolicy** | | ++-------------------------------+--------------------------------------------+ +| **DeleteGroupPolicy** | | ++-------------------------------+--------------------------------------------+ +| **ListGroupPolicies** | | ++-------------------------------+--------------------------------------------+ +| **AttachGroupPolicies** | | ++-------------------------------+--------------------------------------------+ +| **DetachGroupPolicy** | | ++-------------------------------+--------------------------------------------+ +| **ListAttachedGroupPolicies** | | ++-------------------------------+--------------------------------------------+ + +Roles +----- + ++------------------------------+---------------------------------------------+ +| Action | Remarks | ++==============================+=============================================+ +| **CreateRole** | | ++------------------------------+---------------------------------------------+ +| **GetRole** | | ++------------------------------+---------------------------------------------+ +| **UpdateRole** | | ++------------------------------+---------------------------------------------+ +| **UpdateAssumeRolePolicy** | | ++------------------------------+---------------------------------------------+ +| **DeleteRole** | | ++------------------------------+---------------------------------------------+ +| **ListRoles** | | ++------------------------------+---------------------------------------------+ +| **TagRole** | | ++------------------------------+---------------------------------------------+ +| **UntagRole** | | ++------------------------------+---------------------------------------------+ +| **ListRoleTags** | | ++------------------------------+---------------------------------------------+ +| **PutRolePolicy** | | ++------------------------------+---------------------------------------------+ +| **GetRolePolicy** | | ++------------------------------+---------------------------------------------+ +| **DeleteRolePolicy** | | ++------------------------------+---------------------------------------------+ +| **ListRolePolicies** | | ++------------------------------+---------------------------------------------+ +| **AttachRolePolicies** | | ++------------------------------+---------------------------------------------+ +| **DetachRolePolicy** | | ++------------------------------+---------------------------------------------+ +| **ListAttachedRolePolicies** | | ++------------------------------+---------------------------------------------+ + +OpenIDConnectProvider +--------------------- + ++---------------------------------+------------------------------------------+ +| Action | Remarks | ++=================================+==========================================+ +| **CreateOpenIDConnectProvider** | | ++---------------------------------+------------------------------------------+ +| **GetOpenIDConnectProvider** | | ++---------------------------------+------------------------------------------+ +| **DeleteOpenIDConnectProvider** | | ++---------------------------------+------------------------------------------+ +| **ListOpenIDConnectProviders** | | ++---------------------------------+------------------------------------------+ + +.. _Amazon IAM API: https://docs.aws.amazon.com/IAM/latest/APIReference/welcome.html +.. _Ceph Object Gateway S3 API: ../s3/ diff --git a/doc/radosgw/index.rst b/doc/radosgw/index.rst index 5afd5b67617..da92692fa8b 100644 --- a/doc/radosgw/index.rst +++ b/doc/radosgw/index.rst @@ -49,7 +49,9 @@ Cluster with one API and then retrieve that data with the other API. Configuring Pools Config Reference Admin Guide + User Accounts S3 API + IAM API Data caching and CDN Swift API Admin Ops API