19

Amazon IAM API

Chris Lu edited this page 2026-05-19 17:58:53 -07:00

Table of Contents

• Amazon IAM API
• Embedded IAM (Default)
• Starting S3 with Embedded IAM
• Accessing the Embedded IAM API
• Standalone IAM (Deprecated)
• Supported IAM Actions
• Self-Service Operations
• Authentication
• Setting Up Admin Credentials
• Using the IAM API
• Examples
• Create a User and Access Key
• Caller-Supplied AccessKeyId and SecretAccessKey (Extension)
• Attach a Policy to User
• List Users and Access Keys
• Managed Policies
• Self-Service: User Managing Their Own Keys
• User and Access Key Status Management
• Disable a User
• Deactivate an Access Key
• Check Access Key Status
• Group Management
• Key Behaviors
• Examples
• Configuration Storage
• Related Documentation

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Amazon IAM API

SeaweedFS provides AWS IAM API compatibility for managing users, access keys, and policies.

Embedded IAM (Default)

Starting with SeaweedFS 3.x, the IAM API is embedded in the S3 server by default. This means:

• IAM API is available on the same port as S3 (default: 8333)
• No need to run a separate IAM server
• Simplified deployment - single process handles both S3 and IAM

Starting S3 with Embedded IAM

# IAM is enabled by default
weed s3 -filer=localhost:8888

# Or with weed server
weed server -s3

# To explicitly disable embedded IAM
weed s3 -iam=false -filer=localhost:8888

Accessing the Embedded IAM API

The IAM API is available at the root path (/) of the S3 server using POST requests with an Action parameter:

# IAM endpoint is the same as S3 endpoint
export AWS_ENDPOINT=http://localhost:8333

---

Standalone IAM (Deprecated)

Note

: The standalone weed iam command is deprecated. Please use the embedded IAM in the S3 server instead.

For backwards compatibility, you can still run a separate IAM server:

weed iam -filer=localhost:8888 -port=8111

---

Supported IAM Actions

Action	Description	Self-Service
CreateUser	Create a new IAM user	Admin only
DeleteUser	Delete an IAM user	Admin only
GetUser	Get user details	Yes (own user)
UpdateUser	Update user properties	Admin only
ListUsers	List all users	Admin only
SetUserStatus	Enable or disable a user	Admin only
CreateAccessKey	Create access key for user (supports optional caller-supplied AccessKeyId/SecretAccessKey, see below)	Yes (own keys)
DeleteAccessKey	Delete access key	Yes (own keys)
UpdateAccessKey	Change access key status (Active/Inactive)	Yes (own keys)
ListAccessKeys	List access keys for user	Yes (own keys)
PutUserPolicy	Attach inline policy to user	Admin only
GetUserPolicy	Get user's inline policy	Admin only
DeleteUserPolicy	Remove user's inline policy	Admin only
ListUserPolicies	List inline policy names for user	Admin only
CreatePolicy	Create and store a managed policy	Admin only
DeletePolicy	Delete a managed policy	Admin only
ListPolicies	List managed policies	Admin only
GetPolicy	Get managed policy metadata	Admin only
AttachUserPolicy	Attach managed policy to user	Admin only
DetachUserPolicy	Remove managed policy from user	Admin only
ListAttachedUserPolicies	List managed policies for user	Admin only
CreateGroup	Create an IAM group	Admin only
DeleteGroup	Delete an IAM group (must have no members or policies)	Admin only
GetGroup	Get group details and members	Admin only
ListGroups	List all groups	Admin only
AddUserToGroup	Add a user to a group	Admin only
RemoveUserFromGroup	Remove a user from a group	Admin only
AttachGroupPolicy	Attach managed policy to group	Admin only
DetachGroupPolicy	Remove managed policy from group	Admin only
ListAttachedGroupPolicies	List managed policies for group	Admin only
PutGroupPolicy	Attach inline policy to group	Admin only
GetGroupPolicy	Get group's inline policy	Admin only
DeleteGroupPolicy	Remove inline policy from group	Admin only
ListGroupPolicies	List inline policy names for group	Admin only
ListGroupsForUser	List groups a user belongs to	Admin only
UpdateGroup	Rename or enable/disable a group (SeaweedFS extension)	Admin only
TagUser	Attach key/value tags to a user (max 50 tags, key 1-128, value 0-256)	Admin only
UntagUser	Remove tags from a user	Admin only
ListUserTags	List tags attached to a user	Admin only
GetPolicyVersion	Read a specific managed-policy version	Admin only
ListPolicyVersions	List versions of a managed policy	Admin only
CreateServiceAccount	Create a service-account credential	Admin only
DeleteServiceAccount	Delete a service-account credential	Admin only
GetServiceAccount	Get service-account details	Admin only
ListServiceAccounts	List service-account credentials	Admin only
UpdateServiceAccount	Update a service-account credential	Admin only

Self-Service Operations

Users can manage their own access keys without admin privileges:

• Create, delete, and list their own access keys
• View their own user information

Operations on other users require Admin action permission.

---

Authentication

Setting Up Admin Credentials

Before using the IAM API, create an admin user with the Admin action:

echo 's3.configure -access_key admin_key -secret_key admin_secret -user admin -actions Admin -apply' | weed shell

Using the IAM API

Set environment variables for AWS CLI:

export AWS_ACCESS_KEY_ID=admin_key
export AWS_SECRET_ACCESS_KEY=admin_secret
export AWS_ENDPOINT=http://localhost:8333  # S3/IAM endpoint

---

Examples

Create a User and Access Key

# Create user
aws --endpoint $AWS_ENDPOINT iam create-user --user-name alice

# Create access key for user
aws --endpoint $AWS_ENDPOINT iam create-access-key --user-name alice

Caller-Supplied AccessKeyId and SecretAccessKey (Extension)

SeaweedFS extends CreateAccessKey with two optional form parameters that are not part of the AWS IAM API: AccessKeyId and SecretAccessKey. When both are supplied, they are used verbatim instead of being randomly generated. This is useful when applications need stable, pre-known credentials — for example, when provisioning S3 secrets from an external source into a Kubernetes deployment.

Rules:

• Both parameters must be supplied together. Supplying only one is rejected with InvalidInput.
• AccessKeyId: 4–128 ASCII alphanumeric characters (A-Z, a-z, 0-9). The restriction prevents characters that would break AWS SigV4 canonicalization (e.g. /, =, ,).
• SecretAccessKey: 8–128 characters.
• AccessKeyId must be unique across all identities and service accounts; a collision returns EntityAlreadyExists.
• Omit both to get the AWS-standard random-generation behavior.

The AWS CLI does not expose these parameters, so callers must POST directly to the IAM endpoint. For example, using the standalone IAM API:

# The standalone IAM API listens on port 8111 by default.
IAM_ENDPOINT=http://localhost:8111

curl -X POST "$IAM_ENDPOINT" \
  --data-urlencode "Action=CreateAccessKey" \
  --data-urlencode "UserName=alice" \
  --data-urlencode "AccessKeyId=my-app-key" \
  --data-urlencode "SecretAccessKey=my-app-secret-value" \
  --aws-sigv4 "aws:amz:us-east-1:iam" \
  --user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY"

The embedded IAM in the S3 server accepts the same parameters on its IAM endpoint. SecretAccessKey is redacted from server logs regardless of log verbosity. The response format is identical to the AWS CreateAccessKey response.

Attach a Policy to User

# Create policy document
cat > policy.json << 'EOF'
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:Get*", "s3:List*"],
      "Resource": ["arn:aws:s3:::my-bucket/*"]
    }
  ]
}
EOF

# Attach policy to user
aws --endpoint $AWS_ENDPOINT iam put-user-policy \
  --user-name alice \
  --policy-name ReadOnlyPolicy \
  --policy-document file://policy.json

List Users and Access Keys

# List all users
aws --endpoint $AWS_ENDPOINT iam list-users

# List access keys for a user
aws --endpoint $AWS_ENDPOINT iam list-access-keys --user-name alice

Managed Policies

Managed policies are standalone policies that can be attached to multiple users.

# Attach a managed policy to user
aws --endpoint $AWS_ENDPOINT iam attach-user-policy \
  --user-name alice \
  --policy-arn arn:aws:iam:::policy/ReadOnlyPolicy

# List attached managed policies for a user
aws --endpoint $AWS_ENDPOINT iam list-attached-user-policies --user-name alice

# Detach a managed policy
aws --endpoint $AWS_ENDPOINT iam detach-user-policy \
  --user-name alice \
  --policy-arn arn:aws:iam:::policy/ReadOnlyPolicy

# Create a managed policy
aws --endpoint $AWS_ENDPOINT iam create-policy \
  --policy-name MyManagedPolicy \
  --policy-document file://policy.json

# List all managed policies
aws --endpoint $AWS_ENDPOINT iam list-policies

# Get managed policy metadata
aws --endpoint $AWS_ENDPOINT iam get-policy \
  --policy-arn arn:aws:iam:::policy/MyManagedPolicy

# Delete a managed policy (must be detached from all users first)
aws --endpoint $AWS_ENDPOINT iam delete-policy \
  --policy-arn arn:aws:iam:::policy/MyManagedPolicy

Self-Service: User Managing Their Own Keys

A non-admin user can manage their own access keys:

# Set credentials for the user
export AWS_ACCESS_KEY_ID=alice_access_key
export AWS_SECRET_ACCESS_KEY=alice_secret_key

# User can create additional access keys for themselves
aws --endpoint $AWS_ENDPOINT iam create-access-key
# (no --user-name needed, defaults to authenticated user)

# List own access keys
aws --endpoint $AWS_ENDPOINT iam list-access-keys

# Deactivate an access key (key rotation)
aws --endpoint $AWS_ENDPOINT iam update-access-key --access-key-id AKIAEXAMPLE --status Inactive

---

User and Access Key Status Management

SeaweedFS supports enabling/disabling users and access keys without deleting them. This is useful for:

• Temporary suspension: Disable user access during investigation
• Key rotation: Deactivate old keys before deletion
• Offboarding: Disable rather than delete for audit purposes
• Emergency response: Quickly disable compromised credentials

Disable a User

# Disable a user (all their access keys will stop working)
aws --endpoint $AWS_ENDPOINT iam set-user-status --user-name alice --status Inactive

# Re-enable the user
aws --endpoint $AWS_ENDPOINT iam set-user-status --user-name alice --status Active

Deactivate an Access Key

# Deactivate an access key
aws --endpoint $AWS_ENDPOINT iam update-access-key \
  --user-name alice \
  --access-key-id AKIAEXAMPLE \
  --status Inactive

# Reactivate the access key
aws --endpoint $AWS_ENDPOINT iam update-access-key \
  --user-name alice \
  --access-key-id AKIAEXAMPLE \
  --status Active

Check Access Key Status

# List access keys shows their status
aws --endpoint $AWS_ENDPOINT iam list-access-keys --user-name alice

Output:

{
    "AccessKeyMetadata": [
        {
            "UserName": "alice",
            "AccessKeyId": "X8R439UM7OSQJX28I9QTP",
            "Status": "Active"
        },
        {
            "UserName": "alice", 
            "AccessKeyId": "Y9S540VN8PTRKZ39J0URP",
            "Status": "Inactive"
        }
    ]
}

---

Group Management

IAM groups allow you to organize users and apply policies at the group level. Policies attached to a group apply to all members of that group.

Key Behaviors

• Authorization: Group policies are evaluated alongside user policies during S3 request authorization
• Disabled groups: A group can be disabled, which suspends its policies for all members without removing membership
• User deletion: Deleting a user automatically removes them from all groups
• Policy deletion: A policy cannot be deleted if it is attached to any group (must detach first)
• Group deletion: A group must have no members and no attached policies before it can be deleted

Examples

# Create a group
aws --endpoint $AWS_ENDPOINT iam create-group --group-name developers

# Add user to group
aws --endpoint $AWS_ENDPOINT iam add-user-to-group --group-name developers --user-name alice

# Attach a managed policy to the group
aws --endpoint $AWS_ENDPOINT iam attach-group-policy \
  --group-name developers \
  --policy-arn arn:aws:iam:::policy/ReadOnlyPolicy

# List groups
aws --endpoint $AWS_ENDPOINT iam list-groups

# List group members
aws --endpoint $AWS_ENDPOINT iam get-group --group-name developers

# List policies attached to a group
aws --endpoint $AWS_ENDPOINT iam list-attached-group-policies --group-name developers

# List groups a user belongs to
aws --endpoint $AWS_ENDPOINT iam list-groups-for-user --user-name alice

# Remove user from group
aws --endpoint $AWS_ENDPOINT iam remove-user-from-group --group-name developers --user-name alice

# Detach policy from group
aws --endpoint $AWS_ENDPOINT iam detach-group-policy \
  --group-name developers \
  --policy-arn arn:aws:iam:::policy/ReadOnlyPolicy

# Delete group (must have no members or policies)
aws --endpoint $AWS_ENDPOINT iam delete-group --group-name developers

---

Configuration Storage

IAM configurations are stored on the filer at /etc/iam/identity.json. Changes are automatically propagated to all S3 servers subscribed to filer metadata events.

You can view the current configuration:

echo 's3.configure' | weed shell

---

Related Documentation

• AWS IAM CLI - AWS CLI examples for IAM operations
• S3 Credentials - Managing S3 access credentials
• S3 Configuration - S3 server configuration options
• Amazon S3 API - S3 API compatibility

Introduction

• Quick Start with weed mini
• Simplest S3 Bucket and User Setup
• Components
• Getting Started
• Production Setup
• A typical step‐by‐step example
• Benchmarks
• FAQ
• Applications

API

• Master Server API
• Volume Server API
• Filer Server API
• Client Libraries
• SeaweedFS Java Client

Configuration

• Replication
• Store file with a Time To Live
• Failover Master Server
• Erasure coding for warm storage
• EC Bitrot Detection
• Server Startup via Systemd
• Environment Variables

Filer

• Filer Setup
• Directories and Files
• File Operations Quick Reference
• Data Structure for Large Files
• Filer Data Encryption
• Filer Commands and Operations
• Filer JWT Use
• TUS Resumable Uploads

Filer Stores

• Filer Cassandra Setup
• Filer Redis Setup
• Super Large Directories
• Path-Specific Filer Store
• Choosing a Filer Store
• Customize Filer Store

Management

• Admin UI
• Admin UI OIDC
• Worker
• Plugin Worker Scheduling

Advanced Filer Configurations

• Migrate to Filer Store
• Add New Filer Store
• Filer Store Replication
• Filer Active Active cross cluster continuous synchronization
• Filer as a Key-Large-Value Store
• Path Specific Configuration
• Filer Change Data Capture
• Filer Operation Serialization

FUSE Mount

• FIO benchmark
• fstab and systemd mount
• POSIX Compliance
• Distributed POSIX Locks
• P2P reading in weed mount

WebDAV

SFTP Server

Cloud Drive

• Cloud Drive Benefits
• Cloud Drive Architecture
• Configure Remote Storage
• Mount Remote Storage
• Cache Remote Storage
• Cloud Drive Quick Setup
• Gateway to Remote Object Storage

AWS S3 API

• Amazon S3 API
• Supported APIs vs Minio
• S3 Lifecycle
• S3 Lifecycle vs Volume TTL
• S3 Conditional Operations
• S3 CORS
• S3 Object Lock and Retention
• S3 Object Versioning
• S3 API Benchmark
• S3 API FAQ
• S3 Bucket Quota
• S3 Rate Limiting
• S3 API Audit log
• S3 Nginx Proxy
• Docker Compose for S3

S3 Table Bucket

• S3 Table Bucket
• S3 Table Bucket Commands
• S3 Tables Security
• SeaweedFS Iceberg Catalog
• Iceberg Table Maintenance

Iceberg Integrations

• Spark Iceberg Integration
• Trino Iceberg Integration
• Dremio Iceberg Integration
• DuckDB Iceberg Integration
• Doris Iceberg Integration
• RisingWave Iceberg Integration
• Lakekeeper Iceberg Integration

S3 Authentication & IAM

• S3 Configuration - Start Here
• S3 Credentials (-s3.config)
• OIDC Integration (-s3.iam.config)
• Kubernetes ServiceAccount Authentication (IRSA-style)
• S3 Policy Variables
• S3 Policy Conditions
• S3 Bucket Policies
• Amazon IAM API
• AWS IAM CLI
• weed shell - Shell IAM Commands

Server-Side Encryption

• Server-Side Encryption
• Server-Side Encryption SSE-KMS
• Server-Side Encryption SSE-C

S3 Client Tools

• AWS CLI with SeaweedFS
• s3cmd with SeaweedFS
• rclone with SeaweedFS
• restic with SeaweedFS
• nodejs with Seaweed S3

Machine Learning

• TensorFlow with SeaweedFS
• Distributing AI Model Files for Multi-GPU Loading

HDFS

• Hadoop Compatible File System
• run Spark on SeaweedFS
• run HBase on SeaweedFS
• run Presto on SeaweedFS
• Hadoop Benchmark
• HDFS via S3 connector

Replication and Backup

• Async Replication to another Filer [Deprecated]
• Async Backup
• Async Filer Metadata Backup
• Async Replication to Cloud [Deprecated]
• Kubernetes Backups and Recovery with K8up

Metadata Change Events

• Filer Metadata Events
• Filer Notification Webhook

Messaging

• Structured Data Lake with SMQ and SQL
• Seaweed Message Queue
• SQL Queries on Message Queue
• SQL Quick Reference
• PostgreSQL-compatible Server weed db
• Pub-Sub to SMQ to SQL
• Kafka to Kafka Gateway to SMQ to SQL

Use Cases

• Use Cases
• Actual Users

Operations

• System Metrics
• weed shell
• Data Backup
• Deployment to Kubernetes and Minikube
• Deployment with seaweed-up
  • Cluster Plan Workflow
  • Cluster Plan Inventory Reference
  • Cluster Plan Day 2 Operations

Rust Volume Server

• Rust Volume Server

Advanced

• Large File Handling
• Optimization
• Optimization for Many Small Buckets
• Volume Management
• Tiered Storage
• Cloud Tier
• Cloud Monitoring
• Load Command Line Options from a file
• SRV Service Discovery
• Volume Files Structure

Security

• Security Overview
• Security Configuration
• Cryptography and FIPS Compliance
• Run Blob Storage on Public Internet

Misc Use Case Examples

• UrBackup with SeaweedFS
• Docker Image Registry with SeaweedFS
• SeaweedFS in Docker Swarm
• Words from SeaweedFS Users
• Independent Benchmarks
• Hardware