Skip to main content

Managing users

So far we have only used the role root to do API calls. root is a special role that has all permissions, it can use any endpoint. We're going to create new users to show you how you can restrict access to endpoints for them.

Creating a new user​

In this tutorial, we're going to create a user with the email bob@astran.io.

aws --profile astran iam create-user --user-name bob@astran.io

Which gives us the following output:

{
    "User": {
        "Path": "/",
        "UserName": "bob@astran.io",
        "UserId": "AIDAC654348CB5834CDE8B4A2011F31CD2CB",
        "Arn": "arn:astran:iam::ce09c61d-afac-404f-a96b-ebbbced80013:user/bob@astran.io",
        "CreateDate": "2025-03-27T08:43:40.813640+00:00"
    }
}

An email will also be send to bob@astran.io to verify the email and set the password for this user.

note

Even though the parameter is called UserName it has to be an email address. Astran uses email adresses as unique identifiers for users unlike AWS. In order to keep the ability to use the AWS SDK and CLI, we decided to keep the parameter as UserName.

Authenticating to Astran API's with a new user​

note

First make sure that you have verified your email and setup your password by clicking on the link that you have received in the email.

Now that we have created our bob@astran.io user, we can use it to authenticate ourself.

# Replace with the email address of the user you want to use
USERNAME="bob@astran.io"
# Replace with the name of the partition you are using
PARTITION="demo"
URL="https://astran.cloud-iam.com/auth/realms/${PARTITION}/protocol/openid-connect/token"
CLIENT_ID="s5"
# Prompt the user for their root account's password
read -rp "Password: " -s PASSWORD
curl -X POST --data-urlencode "client_id=$CLIENT_ID" \
    --data-urlencode "grant_type=password" \
    --data-urlencode "username=$USERNAME" \
    --data-urlencode "password=$PASSWORD" "$URL"

You should have an input similar to this:

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "expires_in": 300,
  "refresh_expires_in": 1800,
  "refresh_token": "YOUR_REFRESH_TOKEN",
  "token_type": "Bearer",
  "not-before-policy": 0,
  "session_state": "faeee2cb-423b-4f6b-a833-7b0eeda28db2",
  "scope": "email"
}

Copy the access token. We now have everything we need to retrieve our temporary credentials:

# Use the access token you've retrieved in the previous step
ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
USER_SESSION_NAME="bob-session-name"
# Replace with your partition
PARTITION="demo"
curl -X POST --data-urlencode "Version=2011-06-15" \
    --data-urlencode "Action=LoginWithWebIdentity" \
    --data-urlencode "WebIdentityToken=${ACCESS_TOKEN}" \
    --data-urlencode "UserSessionName=${USER_SESSION_NAME}" \
    "https://${PARTITION}.sts.astran.io"

Which will give you an output similar to this:

<LoginWithWebIdentityResponse>
    <LoginWithWebIdentityResult>
        <Credentials>
            <AccessKeyId>ASIA4FB16A86064449E6A02C1BB6EE4740CD</AccessKeyId>
            <SecretAccessKey>tSSQTo03wjC0Z5VXJAPNOu3HLPKweIWBOT82kVBx</SecretAccessKey>
            <SessionToken>SOME_SESSION_TOKEN</SessionToken>
            <Expiration>2025-03-27T10:27:32Z</Expiration>
        </Credentials>
        <SubjectFromWebIdentityToken>c654348c-b583-4cde-8b4a-2011f31cd2cb</SubjectFromWebIdentityToken>
        <Audience>s5</Audience>
        <User>
            <Id>c654348c-b583-4cde-8b4a-2011f31cd2cb</Id>
            <Arn>arn:demo:iam::ce09c61d-afac-404f-a96b-ebbbced80013:user/bob@astran.io</Arn>
        </User>
        <Provider>https://astran.cloud-iam.com/auth/realms/demo</Provider>
        <SourceIdentity>arn:demo:iam::astran:oidc-provider/astran.cloud-iam.com/auth/realms/demo</SourceIdentity>
    </LoginWithWebIdentityResult>
</LoginWithWebIdentityResponse>

We're going to copy the "Credentials"."AccessKeyId" "Credentials"."SecretAccessKey" and "Credentials"."SessionToken" properties to export them in environment variables used by the CLI. We'll then attempt to create a bucket test to test that everything is working as intended:

export AWS_ACCESS_KEY_ID="ASIAEXAMPLE12344567890"
export AWS_SECRET_ACCESS_KEY="asdfkj234LKJfslkdn34slkfdu9FDjkj423cwjke"
export AWS_SESSION_TOKEN="SOME_SESSION_TOKEN"
PARTITION="demo"
aws --endpoint-url https://${PARTITION}.s3.astran.io s3 mb s3://test

If you've done everything properly you should get the following error:

make_bucket failed: s3://test An error occurred (AccessDenied) when calling the CreateBucket operation: You don't have permission to access this resource

That's because a new user is not part of any groups and has no policies whatsoever attached to it and by default, you automatically get a Deny for an endpoint if there's no policy related to it. We'll see how we can create a group to attach a policy to it and add the user to that group in the next part of this tutorial.

Listing all users​

You can list all the roles available with the following command:

aws --profile astran iam list-users

Which should give you the following output:

{
    "Users": [
        {
            "Path": "/",
            "UserName": "bob@astran.io",
            "UserId": "AIDAC654348CB5834CDE8B4A2011F31CD2CB",
            "Arn": "arn:demo:iam::ce09c61d-afac-404f-a96b-ebbbced80013:user/bob@astran.io",
            "CreateDate": "2025-03-27T08:43:40.813640+00:00"
        }
    ]
}

Deleting a user​

To delete a user, you can run the following command:

# Replace `emailOfTheUser` with the name of the user you want to delete
aws --profile astran iam delete-user --user-name emailOfTheUser

Managing groups

In order to give our users permissions to use the API, we need to first create groups to add them to.

Creating a new group​

Let's create a marketing group.

aws --profile astran iam create-group --group-name marketing

Which should give you the following output:

{
    "Group": {
        "Path": "/",
        "GroupName": "marketing",
        "GroupId": "AGPAB81D210A1B2445929F039716332A7954",
        "Arn": "arn:demo:iam::ce09c61d-afac-404f-a96b-ebbbced80013:group/marketing",
        "CreateDate": "2025-03-27T09:40:47.582297+00:00"
    }
}

Adding a user to a group​

To add a user to a group, use the following command:

aws --profile astran iam add-user-to-group --user-name bob@astran.io --group-name marketing

If everything was successful, you should not get an output.

Listing the groups a user belongs to​

To list all the groups a user belongs to, run the following command:

aws --profile astran iam list-groups-for-user --user-name bob@astran.io

Which should give you the following output:

{
    "Groups": [
        {
            "Path": "/",
            "GroupName": "marketing",
            "GroupId": "AGPAB81D210A1B2445929F039716332A7954",
            "Arn": "arn:astran:iam::ce09c61d-afac-404f-a96b-ebbbced80013:group/marketing",
            "CreateDate": "2025-03-27T09:40:47.582297+00:00"
        }
    ]
}

Attach a policy to a group​

In order to give permissions to a user, you need to attach policies to groups they belong to.

Astran provides different builtin policies to help you navigate common use cases. Just for the sake of showing you how to attach a policy to a group, we're going to give full permissions access to the marketing group using the AstranAdmin builtin policy

To add the AstranAdmin policy to the marketing group, run the following command:

PARTITION="demo"
aws --profile astran iam attach-group-policy --group-name marketing --policy-arn arn:$Partition:iam::astran:policy/AstranAdmin

Now if you run again the create bucket from earlier:

PARTITION="demo"
aws --endpoint-url https://${PARTITION}.s3.astran.io s3 mb s3://test

You now get the following output:

make_bucket: test
note

When you authenticate with a user using the LoginWithWebIdentity action, your temporary credentials are valid for an hour by the default. If you get an error that says Invalid token: Token expired, please redo the authentication part.

Now your user bob@astran.io has all the permissions granted by the AstranAdmin builtin policy. Since this gives you full access to all endpoints, let's now remove that policy from the marketing group.

Detach a policy from a group​

To remove a policy from a group, run the following command:

PARTITION="demo"
aws --profile astran iam detach-group-policy --group-name marketing --policy-arn arn:$Partition:iam::astran:policy/AstranAdmin

If you try to create another bucket, it will now fail:

PARTITION="demo"
aws --endpoint-url https://${PARTITION}.s3.astran.io s3 mb s3://test-2

Output:

make_bucket failed: s3://test-2 An error occurred (AccessDenied) when calling the CreateBucket operation: You don't have permission to access this resource

In the next part of the tutorial, we will show you how to create a custom policy so that you can give specific permissions to your users.