ActiveScale IAM API
1.0 Introduction
The ActiveScale Identity and Access Management (IAM) API allows users to set fine-grained access permissions on AWS compatible services on ActiveScale (S3 and IAM). In addition, the users can also use the IAM API to control who can set those permissions.
The ActiveScale IAM API is compatible with the Amazon Web Services (AWS) IAM API, although not all features found on AWS are supported. The full AWS IAM API can be found here, this document details the difference in supported features as well as some basic examples to help you get started.
1.1 Configuring IAM Domains
At least one IAM domain must be configured before IAM calls can be made. Refer to Add an S3/IAM Domain on how to configure an IAM domain.
2.0 AWS IAM API Compatibility
2.1 Policy grammar specifics
| Actions | Notes |
|---|---|
| Version | Only version “2012-10-17” is supported by ActiveScale IAM. For more information on IAM version refer to the AWS documentation. |
| Statement.Principal |
Note: Only for bucket policies. Supported principal types:
|
| Statement.NotPrincipal | Refer to Statement.Principal. |
| Action |
|
| NotAction | Refer to Action. |
| Resource |
|
| NotResource | Refer to Resource. |
| Condition | Supported from ActiveScale 7.1 and above. |
2.2 Supported Wildcards
| ? | Match one character. For example “arn:aws:s3:::bucket?” matches “arn:aws:s3::bucket1” and “arn:aws:s3:buckets” but not “arn:aws:s3::bucket123”. |
| * | Match any number of characters. For example “arn:aws:s3:::bucket*” matches “arn:aws:s3::bucket1”, “arn:aws:s3:buckets” and “arn:aws:s3::bucket123”. |
2.3 Policy Variables
Supported from ActiveScale 7.1 and above.
2.4 Supported Actions
The following tables list the support actions supported by ActiveScale IAM and any difference with AWS IAM. For more in-depth information on the actions please refer to the AWS documentation.
2.4.1 Access Key
| Actions | Request Parameters | Response Elements |
|---|---|---|
| CreateAccessKey |
Supported request parameters:
|
Supported response elements:
Not supported response elements:
|
| ListAccessKeys |
Supported request parameters:
|
Supported response elements:
|
| UpdateAccessKey |
Supported request parameters:
|
Status Supported response elements:
|
2.4.2 Group
| Actions | Request Parameters | Response Elements |
|---|---|---|
| CreateGroup |
Supported request parameters:
|
Supported response elements:
|
| GetGroup |
Supported request parameters:
|
Supported response elements:
|
| ListGroups |
Supported request parameters:
|
Supported response elements:
|
| UpdateGroup |
Supported request parameters:
|
Supported response elements:
|
| DeleteGroup |
Supported request parameters:
|
Supported response elements:
|
| AddUserToGroup |
Supported request parameters:
|
Supported response elements:
|
| ListGroupsForUser |
Supported request parameters:
|
Supported response elements:
|
| RemoveUserFromGroup |
Supported request parameters:
|
Supported response elements:
|
2.4.3 Group Policy
| Actions | Request Parameters | Response Elements |
|---|---|---|
| PutGroupPolicy |
Supported request parameters:
|
Supported response elements:
|
| GetGroupPolicy |
Supported request parameters:
|
Supported response elements:
|
| ListGroupPolicies |
Supported request parameters:
|
Supported response elements:
|
| DeleteGroupPolicy |
Supported request parameters:
|
Supported response elements:
|
| AttachGroupPolicy |
Supported request parameters:
|
Supported response elements:
|
| ListAttachedGroupPolicies |
Supported request parameters:
|
Supported response elements:
|
| DetachGroupPolicy |
Supported request parameters:
|
Supported response elements:
|
2.4.4 Policy
| Actions | Request Parameters | Response Elements |
|---|---|---|
| CreatePolicy |
Supported request parameters:
Description Not supported request parameters:
|
Supported response elements:
Not supported response elements:
|
| GetPolicy |
Supported request parameters:
|
Supported response elements:
Not supported response elements:
|
| ListPolicies |
Supported request parameters:
|
Supported response elements:
Not supported response elements:
|
| DeletePolicy |
Supported request parameters:
|
Supported response elements:
|
2.4.5 Policy Version
| Actions | Request Parameters | Response Elements |
|---|---|---|
| CreatePolicyVersion |
Supported request parameters:
|
Supported response elements:
|
| GetPolicyVersion |
Supported request parameters:
|
Supported response elements:
|
| ListPolicyVersions |
Supported request parameters:
|
Supported response elements:
|
| DeletePolicyVersion |
Supported request parameters:
|
Supported response elements:
|
| SetDefaultPolicyVersion |
Supported request parameters:
|
Supported response elements:
|
2.4.6 User
| Actions | Request Parameters | Response Elements |
|---|---|---|
| CreateUser |
Supported request parameters:
Not supported requests parameters:
|
Supported response elements:
|
| GetUser |
Supported request parameters:
|
Supported response elements:
Not supported response elements:
|
| ListUsers |
Supported request parameters:
|
Supported response elements:
Not supported response elements:
|
| UpdateUser |
Supported request parameters:
|
Supported response elements:
|
| DeleteUser |
Supported request parameters:
|
Supported response elements:
|
2.4.7 User Policy
| Actions | Request Parameters | Response Elements |
|---|---|---|
| PutUserPolicy |
Supported request parameters:
|
Supported response elements:
|
| GetUserPolicy |
Supported request parameters:
|
Supported response elements
|
| ListUserPolicies |
Supported request parameters:
|
Supported response elements:
|
| DeleteUserPolicy |
Supported request parameters:
|
PolicyName Supported response elements:
|
| AttachUserPolicy |
Supported request parameters:
|
PolicyArn Supported response elements:
|
| ListAttachedUserPolicies |
Supported request parameters:
|
Supported response elements:
|
| DetachUserPolicy |
Supported request parameters:
|
Supported response elements:
|
2.5 Supported Condition Keys
2.5.1 AWS Content Keys
| Condition Key | Description |
|---|---|
|
aws:CurrentTime |
Current time in ISO8601 format. |
|
aws:EpochTime |
The date in epoch or Unix time. |
|
aws:PrincipalAccount |
The account id to which the principal belongs. |
|
aws:PrincipalArn |
The ARN of the principal. |
|
aws:PrincipalType |
Indicates whether the principal is an account or user ("Account", "User", "Anonymous"). |
|
aws:SecureTransport |
Boolean value that represents whether the request was sent using SSL. |
|
aws:SourceIp |
The requester's IP address. |
|
aws:UserAgent |
Information about the requester's client application. |
|
aws:userid |
(if "Account"), unique user id (if "User") or not set (if "Anonymous"). |
|
aws:username |
The friendly name of the current user (only set for principal type "User"). |
2.5.2 IAM Condition Keys
| Condition Key | Description |
|---|---|
|
iam:PolicyARN |
ARN of a managed policy in requests that involve a managed policy. |
2.5.3 S3 Condition Keys
| Condition Key | Description |
|---|---|
|
s3:LocationConstraint |
The region. |
|
s3:ResourceAccount |
The owner account id of the resource (bucket). |
|
s3:TlsVersion |
The TLS version used by the client. |
|
s3:VersionId |
The object version id. |
|
s3:authType |
The authentication method ("REST-HEADER", "REST-QUERY-STRING", "POST"). |
|
s3:delimiter |
The delimiter parameter of the request. |
|
s3:max-keys |
The max-keys parameter of the request. |
|
s3:object-lock-legal-hold |
The object legal hold status. |
|
s3:object-lock-mode |
The object retention mode ("COMPLIANCE", "GOVERNANCE"). |
|
s3:object-lock-remaining-retention-days |
The remaining object retention days. |
|
s3:object-lock-retain-until-date |
The object retain until date. |
|
s3:prefix |
The prefix parameter of the request. |
|
s3:signatureAge |
The age (in ms) of the request signature. |
|
s3:signatureversion |
The signature version ("AWS" for v2, "AWS4-HMAC-SHA256" for v4). |
|
s3:x-amz-acl |
The canned ACL from the request x-amz-acl header. |
|
s3:x-amz-content-sha256 |
Set to "UNSIGNED-PAYLOAD" if the payload isn't signed. |
|
s3:x-amz-copy-source |
The copy source (bucket, prefix, object) for a copy request. |
|
s3:x-amz-grant-full-control |
The request x-amz-grant-full-control header. |
|
s3:x-amz-grant-read |
The request x-amz-grant-read header. |
|
s3:x-amz-grant-read-acp |
The request x-amz-grant-read-acp header. |
|
s3:x-amz-grant-write |
The request x-amz-grant-write header. |
|
s3:x-amz-grant-write-acp |
The request x-amz-grant-write-acp header. |
|
s3:x-amz-metadata-directive |
The request x-amz-metadata-directive header. |
|
s3:x-amz-server-side-encryption |
The request x-amz-server-side-encryption header. |
|
s3:x-amz-storage-class |
The request x-amz-storage-class header. |
|
s3:x-amz-website-redirect-location |
The request x-amz-website-redirect-location header. |
2.6 IAM Limits
| Resource | Max Value |
|---|---|
| Managed policy size: | 6144 bytes (whitespace ignored) |
| User policy size: | 2048 bytes (whitespace ignored) |
| Attached policies per user: | 20 |
| Group policy size: | 5120 bytes (whitespace ignored) |
| Attached policies per group: | 10 |
| Number of access keys per IAM user: | 2 |
| Total number of accounts: | 10000 |
| Total number of users per account: | 5000 |
| Total number of groups per account: | 500 |
| Number of groups a user can be attached to: | 10 |
| Number of users per group: | 5000 |
| Number of managed policies per account: | 5000 |
| Number of policy versions: | 5 |
2.7 ACL Permissions Mapped to Policy Permissions
The following table shows how each ACL permission maps to the corresponding access policy permissions. As you can see, access policy allows more permissions than an ACL does. You use ACLs primarily to grant basic read/write permissions, similar to file system permissions, while policy permissions provide a lot more fine grained control over permissions.
| ACL Permission | Corresponding access policy permissions when the ACL permission is granted on a bucket | Corresponding access policy permissions when the ACL permission is granted on an object |
|---|---|---|
READ (Read Objects) |
|
|
WRITE (Write Objects) |
Bucket owner can create, overwrite, and delete any object in the bucket, and object owner has
In addition, when the grantee is the bucket owner, granting |
Not applicable |
READ_ACP (Read Bucket Permissions) |
|
|
WRITE_ACP (Write Bucket Permissions) |
|
|
FULL_CONTROL
|
Equivalent to granting READ, WRITE, READ_ACP, and WRITE_ACP ACL permissions. Accordingly, this ACL permission maps to a combination of corresponding access policy permissions. |
Equivalent to granting READ, READ_ACP, and WRITE_ACP ACL permissions. Accordingly, this ACL permission maps to a combination of corresponding access policy permissions |
3.0 Basic Examples
3.1 Best Practices
It is not recommended to perform day-to-day operations as the account root user. Instead, create a user with the minimum required permissions for day-to-day operations. For example, you could create an administrative user who can be used to set permissions for other users, but who cannot perform any S3 calls. Keep in mind that permissions can be set on a subset of resources by using the appropriate wildcards.
You cannot limit the permissions of the account's root user, who has all permissions by default. Quantum advises to only use the root user's credentials for initially setting up and carrying over permissions to an administrative user (group), and then removing or disabling the root user's access keys. Malicious use of (leaked) access keys can then always be rapidly stopped by a DenyAll policy for the User owning the access keys.
In emergency cases, access keys may also be disabled or deleted through the GUI by the system administrator, and new access keys can be created for the account's root user.
3.2 Sample Policy Documents
3.2.1 Administrative User /Group
The following policy gives a user or a group the permission to perform all IAM operations on all IAM resources. IAM actions all start with the “iam” prefix, and in combination with the “*” wildcard all IAM operations are specified.
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "allowAllIam",
"Effect": "Allow",
"Action": "iam:*",
"Resource": "*"
}
]
}
3.2.2 S3 PUT and S3 GET on a Subset of Resources
The following policy only allows PUT object and GET object on all objects with the prefix “engineering/” in the bucket “my-corporation”.
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "restrictedPutGet",
"Effect": "Allow",
"Action": ["s3:PutObject", "s3:GetObject"],
"Resource": "arn:aws:s3:::my-corporation/engineering/*"
}
]
}
3.2.3 Allowing all S3 actions Except Delete Actions
The following policy allows all S3 operations on the bucket “main-bucket” and its objects, except for those S3 operations that start with “Delete”.
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "allowAllS3ObjectActionsExceptDelete",
"Effect": "Allow",
"NotAction ": "s3:Delete*",
"Resource": "arn:aws:s3:::main-bucket/*"
},
{
"Sid": "allowAllS3BucketActionsExceptDelete",
"Effect": "Allow",
"NotAction": "s3:Delete*",
"Resource": "arn:aws:s3:::main-bucket"
}
]
}
3.2.4 Allow an S3 action to one user from group using conditions
The following group policy allows access for “exam-results” only to users “alice” and “bob” while denying access to other users from the same group
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowAliceAndBob",
"Effect": "Allow",
"Action": "*",
"Resource": [
"arn:aws:s3:::exam-results"
],
"Condition": {
"StringEquals": {
"aws:username": ["alice", “bob”]
}
}
}
]
}
3.2.5 Allow an S3 action using policy variables
The following group policy allows access to all users but only for objects which have their username as a prefix:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "*",
"Resource": [
"arn:aws:s3:::exam-results/${aws:username}/*"
]
}
]
}
3.2.6 Bucket Policy Denying Access to Specific Users
The following bucket policy applied to the bucket “exam-results” denies access to all users belonging to account “123456789012” in the “students” path.
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "noStudents",
"Effect": "Deny",
"Principal": {
"AWS": "arn:aws:iam::123456789012:students/*"
},
"Action": "*",
"Resource": ["arn:aws:s3:::exam-results, "arn:aws:s3:::exam-results/*"]
}
]
}
3.3 Example Using AWS CLI
The following code snippet shows the various users and groups interact with policies using AWS CLI. For more information on AWS CLI refer to the AWS documentation.
# Create a user called "demo-user"
~ $ aws --profile demo iam create-user --user-name demo-user
{
"User": {
"Path": "/",
"UserName": "demo-user",
"UserId": "AIDACCX78G1TZHCH0ATQ1",
"Arn": "arn:aws:iam::652303226922:user/demo-user",
"CreateDate": "2024-03-04T09:03:07+00:00"
}
}
# Add a new inline policy document to "demo-user"
# User policy is a local json file similar to the "Sample policy document" examples
~ $ aws --profile demo iam put-user-policy --user-name demo-user --policy-name my-policy --policy-document file://my-policy.json
# List and get the new inline policy
~ $ aws --profile demo iam list-user-policies --user-name demo-user
{
"PolicyNames": [
"my-policy"
]
}
~ $ aws --profile demo iam get-user-policy --user-name demo-user --policy-name my-policy
{
"UserName": "demo-user",
"PolicyName": "my-policy",
"PolicyDocument": {
"Version": "2012-10-17",
"Statement": [
{
"Sid": "allowAllIam",
"Effect": "Allow",
"Action": "iam:*",
"Resource": "*"
}
]
}
}
# Create a group of users, users of a group automatically have the permissions of the group
# on top of any permissions they already have (for example via in-line policies)
~ $ aws --profile demo iam create-group --group-name my-users
{
"Group": {
"Path": "/",
"GroupName": "my-users",
"GroupId": "AGPAYOKKRE1I380Y6UW6E",
"Arn": "arn:aws:iam::652303226922:group/my-users",
"CreateDate": "2024-03-04T09:24:35+00:00"
}
}
# Add our user to this group and list all users for this group
~ $ aws --profile demo iam add-user-to-group --user-name demo-user --group-name my-users
~ $ aws --profile demo iam get-group --group-name my-users
{
"Users": [
{
"Path": "/",
"UserName": "demo-user",
"UserId": "AIDA3FFSDMOUD3GJPUOE1",
"Arn": "arn:aws:iam::652303226922:user/demo-user",
"CreateDate": "2024-03-04T09:13:24+00:00"
}
],
"Group": {
"Path": "/",
"GroupName": "my-users",
"GroupId": "AGPAYOKKRE1I380Y6UW6E",
"Arn": "arn:aws:iam::652303226922:group/my-users",
"CreateDate": "2024-03-04T09:24:35+00:00"
}
}
# Groups can also have inline policies
~ $ aws --profile demo iam put-group-policy --group-name my-users --policy-name group-policy --policy-document file://group-policy.json
# When the same policy needs to applied to many different users or groups, we can create managed policies which can be re-used
~ $ aws --profile demo iam create-policy --policy-name reusable-policy --policy-document file://my-policy.json
{
"Policy": {
"PolicyName": "reusable-policy",
"PolicyId": "ANPA932LSXO1VC1W7XVZH",
"Arn": "arn:aws:iam::652303226922:policy/reusable-policy",
"Path": "/",
"DefaultVersionId": "v1",
"AttachmentCount": 0,
"IsAttachable": true,
"CreateDate": "2024-03-04T09:31:15+00:00",
"UpdateDate": "2024-03-04T09:31:15+00:00"
}
}
# This policy can now be attached to users and groups, the attached policy will be added on-top of any existing permissions
# When the policy is updated all attached users and groups will have their permissions updated as well
# In this example we only attach the policy to the group
~ $ aws --profile demo iam attach-group-policy --group-name my-user s --policy-arn "arn:aws:iam::652303226922:policy/reusable-policy"
~ $ aws --profile demo iam list-attached-group-policies --group-name my-users
{
"AttachedPolicies": [
{
"PolicyName": "reusable-policy",
"PolicyArn": "arn:aws:iam::652303226922:policy/reusable-policy"
}
]
}
