Subusers and scoped credentials

Intermediate⏱ ~16 minradosgw-admin

What you'll learn

Create subusers with appropriate access levels
Distinguish subusers from separate users
Choose between subusers and bucket policies
Apply subusers in a Swift deployment

Prerequisites

None — start here.

Verified against Ceph Tentacle 20.2.x · Ceph Squid 19.2.x (supported previous) · cephadm matches the verified Ceph release · podman 4.x · csi-rbd and csi-cephfs current · RBD / CephFS / RGW current (matches Ceph release) · Linux kernel 5.15+ (5.10 minimum) · Ubuntu 24.04 LTS (Ceph host baseline) · Debian 12 (Bookworm) (Ceph host baseline) · Rocky Linux / RHEL / AlmaLinux 9.x (Ceph host baseline) · Proxmox VE 9.x (cross-course integration) · Kubernetes 1.31+ (cross-course integration) · 2026-08-18

Why this matters in production

Subusers give an application a restricted credential without a separate identity, which is useful for Swift and for coarse read-only access. For anything finer, bucket policies are the better tool — and knowing which applies avoids building a permission model on the wrong mechanism.

Creating

radosgw-admin subuser create --uid=analytics \
    --subuser=analytics:reader --access=read

radosgw-admin subuser create --uid=analytics \
    --subuser=analytics:writer --access=readwrite

radosgw-admin user info --uid=analytics | jq '.subusers'

Access level	Permits
`read`	GET, HEAD, LIST
`write`	PUT, DELETE
`readwrite`	both
`full`	both plus bucket operations

Keys

# Swift credential
radosgw-admin key create --subuser=analytics:reader --key-type=swift --gen-secret

# S3 credential on a subuser
radosgw-admin key create --subuser=analytics:reader --key-type=s3 \
    --gen-access-key --gen-secret

Swift credentials attach to subusers by design; S3 credentials can attach to either the user or a subuser.

Scope

A subuser’s access applies across everything the parent user owns. A read subuser can read all of the parent’s buckets, not a selected one.

That is the key limitation: subusers give a coarse access level over the parent’s entire scope, not per-bucket permissions.

Subuser versus separate user versus bucket policy

Need	Mechanism
Read-only credential for a Swift client	subuser
Read-only credential over all a user’s buckets	subuser
Access to one specific bucket	bucket policy
Different permissions per bucket	bucket policy
Complete separation with its own quota	separate user
Cross-account access	bucket policy

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": {"AWS": ["arn:aws:iam:::user/reporting"]},
    "Action": ["s3:GetObject", "s3:ListBucket"],
    "Resource": ["arn:aws:s3:::reports", "arn:aws:s3:::reports/*"]
  }]
}

A bucket policy expresses per-bucket, per-action, per-principal rules — everything subusers cannot.

Removal

radosgw-admin subuser rm --uid=analytics --subuser=analytics:reader
radosgw-admin subuser rm --uid=analytics --subuser=analytics:reader --purge-keys

Quiz

Knowledge check · 4 questions

Q1. A requirement is for an application to read one specific bucket owned by another user. What mechanism fits?

A bucket policy granting the application's principal read access to that bucket A read subuser under the bucket owner, since a subuser's access level is scoped per bucket A separate user created with a copy of the owner's access key, so that both can read it An RGW capability of buckets=read on the application's user, granting read on that bucket
Q2. A read-only subuser can be restricted to a single bucket owned by its parent user.

True False
Q3. Design credentials for a reporting integration.

A reporting tool needs read access to two of a team's twelve buckets. The team proposes creating a read subuser and giving the tool its credentials.
Q4. Why do Swift credentials attach to subusers rather than to the user directly?

Passing score: 75%. Answers are checked in this browser.

Production discipline

Reach for bucket policies whenever a requirement names a specific bucket, action, or principal; subusers apply one coarse level across the parent’s whole scope and a model built on them fails at the first exception. Give integrations their own user identity so their access is auditable separately from a human owner’s.

Cross-course references

Kubernetes: RBAC RoleBindings scoped to specific resources are the analogue of bucket policies
Linux: group membership versus per-file ACLs is the same coarse-versus-precise choice