Guides: access & security

How to create IAM users and groups

Give every client its own scoped credential — here, a CI pipeline (ci-uploader) that can write firmware builds and nothing else.

1. Enable bootstrap SigV4

IAM users require authentication to be on. If the proxy still runs open, set the bootstrap credential pair and restart:

# validate
access:
  access_key_id: acme-bootstrap-key
  secret_access_key: a-long-random-secret-of-40-plus-characters

Or via env vars: DGP_ACCESS_KEY_ID + DGP_SECRET_ACCESS_KEY. For the guided zero-to-secured walkthrough, see the Secure your proxy tutorial.

2. Create the user

Go to Settings → Access → Users → + Add user.

IAM users panel

  1. Name: ci-uploader.
  2. Leave Access key ID and Secret access key blank to auto-generate them.
  3. Add permissions (next step) or pick a group.
  4. Save. The secret is shown once, on the "Created" toast — copy it now. If it's lost, rotate the keys (step 4).

If you script it instead, POST /_/api/admin/users needs name; access_key_id and secret_access_key are auto-generated when omitted, enabled defaults to true, and permissions defaults to empty. Group membership is a separate call: POST /_/api/admin/groups/:id/members. All admin routes require a session cookie from POST /_/api/admin/login — see the admin API reference.

3. Write a permission

Each permission is an ABAC rule: effect, actions, resources, optional conditions. The shapes you'll write most often:

Write-only CI — ci-uploader may upload firmware builds and list its bucket, nothing else:

[
  { "effect": "Allow", "actions": ["write"], "resources": ["releases/firmware/*"] },
  { "effect": "Allow", "actions": ["list"],  "resources": ["releases"] }
]

Read-only prefix — download access to one folder:

{ "effect": "Allow", "actions": ["read", "list"], "resources": ["downloads/public/*"] }

Full access to one bucket — note the two rules: bucket-level operations match the bare bucket name, object operations match bucket/*:

[
  { "effect": "Allow", "actions": ["*"], "resources": ["db-archive"] },
  { "effect": "Allow", "actions": ["*"], "resources": ["db-archive/*"] }
]

Deny is absolute: if any Deny rule matches — direct or group-inherited — the request fails regardless of Allows. For the full grammar (action-to-S3-operation mapping, glob rules, ${iam:username} identity templates) and the canned starting-point templates in Settings → Access → Users → Apply template, see the IAM permissions reference.

4. Rotate keys without downtime

POST /_/api/admin/users/:id/rotate-keys swaps the credential atomically — the old key stops working the moment the call returns. If a brief 403 window on the client is acceptable, rotate and redeploy.

To rotate with zero downtime, overlap two credentials:

  1. Clone the user: per-user row menu → Clone, or POST /_/api/admin/users/:id/clone. The clone gets fresh keys and a copy of the permissions.
  2. Roll the new credentials out to every client.
  3. Delete the original user once nothing signs with it (check the audit log at /_/admin/diagnostics/audit).

If you only need to suspend a user, untick Enabled instead of deleting — the row, groups, and permissions survive.

5. Put shared policy in a group

Don't copy the same rules onto ten users. Acme's Engineering group carries read access to releases and downloads:

  1. Settings → Access → Groups → + Add group, name it Engineering.
  2. Add permissions on the group (same JSON schema as user permissions):
[
  { "effect": "Allow", "actions": ["read", "list"], "resources": ["releases", "releases/*"] },
  { "effect": "Allow", "actions": ["read", "list"], "resources": ["downloads", "downloads/*"] }
]
  1. Add members: Settings → Access → Users → edit dana → Groups → tick Engineering.

Members get the group's rules in addition to their direct rules; a Deny from either source wins. If you use SSO, mapping rules can add people to Engineering automatically on login — see How to set up OAuth/OIDC single sign-on.

6. Switch an AWS client over

No client-side code changes — only the endpoint and the credentials:

export AWS_ACCESS_KEY_ID=ci-uploader-key
export AWS_SECRET_ACCESS_KEY=ci-uploader-secret
export AWS_ENDPOINT_URL=https://s3.acme.example

aws s3 cp firmware-v2.4.0.bin s3://releases/firmware/firmware-v2.4.0.bin

Or as a profile in ~/.aws/credentials + ~/.aws/config:

# ~/.aws/credentials
[acme-proxy]
aws_access_key_id = ci-uploader-key
aws_secret_access_key = ci-uploader-secret

# ~/.aws/config
[profile acme-proxy]
endpoint_url = https://s3.acme.example
region = us-east-1

boto3, Terraform, rclone, and the rest of the SigV4 ecosystem work the same way — endpoint override plus proxy credentials. See client configuration.

7. Presigned URLs

aws s3 presign works out of the box; URLs expire after at most 7 days and carry the signing user's permissions — Deny rules apply to presigned requests too.

Verify

Test the allow and the deny — a policy that's never seen a 403 isn't verified:

# Allowed: write inside the granted prefix
aws --profile acme-proxy s3 cp build.bin s3://releases/firmware/build.bin
# upload: ./build.bin to s3://releases/firmware/build.bin

# Denied: read outside the grant
aws --profile acme-proxy s3 cp s3://db-archive/nightly/dump.sql.gz .
# fatal error: An error occurred (AccessDenied)

Every denial lands in the audit log (Settings → Diagnostics → Audit) with user, action, bucket, and path.