Skip to main content

Get your Credentials for your account root user

Every call to the Astran Continuity Cloud API must be digitally signed following AWS SigV4 specifications. The whole signature process is managed by AWS CLI, you just have to provide it with a valid access key.

This page will guide you through the steps required to obtain temporary access keys for your account root user.

Temporary credentials​

To retrieve an access token you will need your email adress as well as the password you set when you were onboarded.

info

In this example we are using the email demo@astran.io and the password PASSWORD123

caution

The following commands only works for root accounts. If you are not using a root account you need to contact your company's IT administrator and they will guide you through the process of retrieving an access token.

# Replace with your email address
ASTRAN_USERNAME="demo@astran.io"
ASTRAN_IDP_URL="https://astran.cloud-iam.com/auth/realms/root-accounts/protocol/openid-connect/token"
ASTRAN_IDP_CLIENT_ID="root-client"
# Prompt the user for their root account's password
echo -n "Password: "
read -r -s ASTRAN_PASSWORD
curl -X POST --data-urlencode "client_id=$ASTRAN_IDP_CLIENT_ID" --data-urlencode "grant_type=password" --data-urlencode "username=$ASTRAN_USERNAME" --data-urlencode "password=$ASTRAN_PASSWORD" "$ASTRAN_IDP_URL"
unset ASTRAN_PASSWORD
danger

It's a bad practice to put a password directly in a shell command as they could be retrieve in your shell's history. We recommend instead either reading the password through the standard input or retrieve it using your password manager in the terminal.

This should give you a similar output:

{
  "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 and use it in the following command:

ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
JWT_DECODED=$(echo -n $ACCESS_TOKEN | cut -d'.' -f2 | base64 --decode)
echo $JWT_DECODED

This will give you an output similar to this:

{
  "exp": 1724308670,
  "iat": 1724308370,
  "jti": "b1594437-d4f4-4b5c-b228-8698ebb04910",
  "iss": "https://astran.cloud-iam.com/auth/realms/root-accounts",
  "aud": "root-client",
  "sub": "ce04d61d-afac-504f-a96b-ebbbced80013",
  "typ": "Bearer",
  "azp": "root-client",
  "session_state": "104b7eb9-c3ba-4384-9d19-931e7ecc2205",
  "acr": "1",
  "scope": "email",
  "sid": "104b7eb9-c3ba-4384-9d19-931e7ecc2205",
  "email_verified": true,
  "https://aws.amazon.com/tags": {
    "principal_tags": {
      "role": ["arn:demo:iam::ce04d61d-afac-504f-a96b-ebbbced80013:root"]
    }
  },
  "email": "demo@astran.io"
}

Copy the property "https://aws.amazon.com/tags"."principal_tags"."role" in this case arn:demo:iam::ce04d61d-afac-504f-a96b-ebbbced80013:root. This is the role ARN that we are going to assume.

We now have everything we need to retrieve our temporary credentials:

ARN="arn:demo:iam::ce04d61d-afac-504f-a96b-ebbbced80013:root"
aws --profile astran sts assume-role-with-web-identity --role-arn "$ARN" --role-session-name rootSession --web-identity-token "$ACCESS_TOKEN"

Which will give you an output similar to this:

{
  "Credentials": {
    "AccessKeyId": "ASIAEXAMPLE12344567890",
    "SecretAccessKey": "asdfkj234LKJfslkdn34slkfdu9FDjkj423cwjke",
    "SessionToken": "SOME_SESSION_TOKEN",
    "Expiration": "2024-08-22T08:32:56+00:00"
  },
  "SubjectFromWebIdentityToken": "ce04d61d-afac-504f-a96b-ebbbced80013",
  "AssumedRoleUser": {
    "AssumedRoleId": "root",
    "Arn": "arn:demo:iam::ce04d61d-afac-504f-a96b-ebbbced80013:root"
  },
  "Provider": "https://astran.cloud-iam.com/auth/realms/root-accounts/protocol/openid-connect/token",
  "Audience": "root-client",
  "SourceIdentity": "arn:demo:iam::ce04d61d-afac-504f-a96b-ebbbced80013:oidc-provider/astran.cloud-iam.com/auth/realms/root-accounts"
}
caution

The access token you retrieve is valid for 5 minutes. If you get the following error

An error occurred (ExpiredToken) when calling the AssumeRoleWithWebIdentity operation (reached max retries: 0): Token is expired

It means that you need to start over and retrieve the access token again

note

A temporary access key always starts with the prefix ASIA

note

By default the credentials returned by assume-role-with-web-identity are valid for an hour. You can extend the duration using the --duration-seconds parameter. It takes a duration in seconds up to 12 hours.

For more information use the aws sts assume-role-with-web-identity help command.

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 tutorial 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"
aws --endpoint-url https://demo.s3.astran.io s3 mb s3://tutorial

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

make_bucket: tutorial

Congratulations you've learned how to retrieve temporary credentials and use them to make API calls using the CLI !

note

You can't use the astran profile that you've configured previously with temporary credentials, because the CLI will attempt to retrieve credentials from the credentials file, which we haven't configured yet.

You could configure it like this:

Open the ~/.aws/credentials file and add the following:

[astran]
aws_access_key_id = ASIAEXAMPLE12344567890
aws_secret_access_key = asdfkj234LKJfslkdn34slkfdu9FDjkj423cwjke
aws_session_token = SOME_SESSION_TOKEN

You can then use the astran profile like this:

aws --profile astran s3 mb s3://tutorial2

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

make_bucket: tutorial2

Permanent credentials​

danger

We don't recommend using permanent credentials as they require regular access key rotation, you should use temporary credentials instead.

note

This part of the tutorial requires you to have temporary credentials currently set in your environment variables.

To create a permanent access key for your root account, you can use the following command:

aws --endpoint-url https://demo.iam.astran.io iam create-access-key

You should get an output similar to this:

{
  "AccessKey": {
    "UserName": "root",
    "AccessKeyId": "AKIAEXAMPLE1234567890",
    "Status": "Active",
    "SecretAccessKey": "SOME_SECRET_ACCESS_KEY",
    "CreateDate": "2024-08-22T08:13:50.652118+00:00"
  }
}
note

A permanent access key always starts with the prefix AKIA.

You can now configure your CLI with those permanent credentials like this:

Open the ~/.aws/credentials file and add the following:

[astran]
aws_access_key_id = AKIAEXAMPLE12344567890
aws_secret_access_key = SOME_SECRET_ACCESS_KEY

You can then use the astran profile like this:

aws --profile astran s3 mb s3://tutorial3

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

make_bucket: tutorial3