--- title: "Security Token Service (STS) and IAM Roles" slug: "security-token-service-sts-and-iam-roles" tags: ["5.4"] updated: 2026-10-28T01:54:03Z published: 2026-10-28T01:54:03Z canonical: "docs.vastdata.com/security-token-service-sts-and-iam-roles" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.vastdata.com/llms.txt > Use this file to discover all available pages before exploring further. # Security Token Service (STS) and IAM Roles ## Overview The VAST Cluster includes a Security Token Service (STS) server, which allows users or other principals to assume IAM roles and then obtain temporary access keys for S3 buckets on the VAST Cluster. The Security Token Service (STS), used with IAM roles, is used to control user access to S3 buckets in the cluster in a secure and scalable way. STS acts as a trusted intermediary that issues temporary security credentials after verifying a user or service's identity. These credentials are linked to IAM roles, which define a set of permissions that can be assumed by users dynamically. Users can access S3 buckets on the cluster using the temporary access keys that the STS server returns when they successfully assume an IAM role. If the user creates objects in the bucket, they are owned by the role (or the bucket owner, depending on configuration), not by the user that assumed the role. When the requesting user uses the temporary credentials to assume the specified IAM role, access checks for subsequent operations are based on the identity and bucket policies attached to the assumed IAM role. The VAST STS server accepts two methods for authenticating a request to assume an IAM role: using a permanent S3 access key pair, or using a JSON web token (JWT) obtained from an OIDC provider. > [!NOTE] > Note > > The ability to authenticate requests to assume IAM roles using an access key pair is introduced in VAST Cluster 5.4.3. ## Configuring IAM Roles and S3 Buckets on the VAST Cluster for Use with STS ### Configuring S3 Buckets for Use with STS and IAM Roles To configure buckets that can be accessed by users assuming IAM roles, create (or modify) views with the following settings: - *Protocol*: Must include *S3 Bucket*. Additional protocols may also be enabled on the view. - *S3 Bucket Name* must be set. - *Bucket Owner*. This can be the IAM role. Alternatively, the IAM role should have permissions to access the bucket, granted through an identity policy or bucket policy. > [!NOTE] > Note > > To configure an IAM role as the bucket owner, you need to explicitly set the bucket owner type to role vs user. In the VAST Web UI, this is done by selecting the **IAM Role** radio button above the **Bucket Owner** field. In the VAST CLI, set `--bucket-owner-type` to `ROLE`. - *View policy*. Set this to a view policy that has *S3 Native* security flavor. ## Creating IAM Roles using the VAST Web UI 1. Navigate to the **User Management** page in the VAST Web UI, and select the **IAM Roles** tab. 2. Click **Create New Role**. 3. In the **General** section, enter the following: | **Tenant** | Select the tenant that the role belongs to. A role can be associated with a single tenant. | | --- | --- | | **Name** | A unique name (within the tenant) for the role. | | **Description** | (Optional). A description of the role. | | **Max session duration** | > [!NOTE] > This field is introduced in VAST Cluster 5.4.3. (Optional). Limits the maximum session duration that can be granted to a requesting user. Maximum (default): 36 hours Minimum: 15 minutes | 4. In the **Attach Identity Policies** section, select identity policies that will be associated with the role, from the list. These policies are applied to users who assume the role, to determine their permissions and the resources they can access. Details for the selected policies are shown in JSON format in the **Identity Policies** pane, on the right. See [Managing Identity Policies](/docs-5-4/docs/managing-identity-policies) for details about creating identity policies. 5. In the **Trust Policy** section, configure a trust policy for the role. Trust policies define which users can assume the role, and which users are denied. See [Trust Policies for IAM Roles](/docs-5-4/docs/security-token-service-sts-and-iam-roles#trust-policies-for-iam-roles). A default policy is provided and displayed in the right pane. ```plaintext {  "Version": "2012-10-17",  "Statement": [    {      "Effect": "Allow",      "Principal": "*",      "Action": "sts:*"    }, ``` The default policy allows all principals to assume roles using all STS methods. This is not a secure policy, and therefore it is recommended that it be modified. To modify the policy, you can edit the JSON structure directly, in the right pane, upload a policy from a JSON file, or compose it using the UI, in the left pane. Follow these steps to add to the policy using the UI: 1. In the **Statement ID** field, enter a name for a statement that you want to add to the policy. 2. Select the **Effect** of the statement: **Allow** or **Deny**. When applied, the policy will either allow or deny the specified actions and principals. 3. From the **Action** dropdown, select one of the following: > [!NOTE] > Note > > If you want the statement to apply to all actions, you can enter * as a wildcard. However, this is supported by typing in the editor and not through the dropdown. - **AssumeRole**. To restrict the effect to the `sts:AssumeRole` method. - **AssumeRoleWithWebIdentity**. To restrict the effect to the `sts:AssumeRoleWithWebIdentity` method with one or more OIDC providers. 4. In the **Principal** field, enter the principals. These are the users affected by the trust policy. - If the action is *AssumeRole*, enter a user name or a comma-separated list of user names. For example: *user1, user2, user3@domain* - If the action is *AssumeRoleWithWebIdentity*, enter `oidc-provider/<issuer>` where `<issuer>` is obtained from the "iss" claim of the JWT. 5. Optionally, if the action is *AssumeRoleWithWebIdentity*, in the **Conditions** section add conditions for the statement. Conditions qualify when a policy statement applies to resources. Follow these steps to add conditions to the policy: 1. Click **Add Condition**. 2. Select a **Condition Key** from the list. This is the element that is tested by the condition. 3. Enter an **Issuer**. This is the element in the JWT token that is compared with the values (entered below), to determine if the condition is satisfied. 4. Select a **Qualifier** from the list. This indicates whether the condition applies to *any* or *all* values in a request. 5. Select an **Operator** from the list. This indicates how the Issuer and Values are compared. This is a string comparison, from these options: - **StringEquals**. The Issuer string matches one of the Values exactly. - **StringNotEquals**. The Issuer string does not exactly match any of the Values. - **StringEqualsIgnoreCase**. The Issuer string matches one of the Values, ignoring case. - **StringNotEqualIgnoreCase**. The Issuer string does not match any of the Values, ignoring case. 6. Enter a list of **Values**, separated by commas. These are compared with the **Issuer** string. For example, this condition checks the `'aud'` field in a JWT for specific users. ```plaintext "Condition": {    "StringEquals": {"login.microsoftonline.com//v2.0:aud": "0oalggs6d5D6exca65d7"} } ``` 7. Repeat these steps for additional conditions for the same statement. 6. Click **Add to Policy** to move the statement you built over to the policy. 7. Repeat as needed to add more statements. 6. Click **Create**. The IAM role is created and displayed in the **IAM Roles** tab. ## Managing IAM Roles using the VAST Web UI ### Modifying IAM Roles You can modify an IAM role. Changes in roles only affect principals who assume the role after the changes, not users who have already assumed the role. 1. In the **IAM Roles** tab, right-click on the role to be edited, and select **Edit**. 2. Make any changes to the role as necessary. You cannot change the name of the role. 3. Click **Update**. ### Revoking Access Keys for IAM Roles Temporary S3 access keys are generated for the role by the STS server. You can revoke the keys for all users who have assumed the IAM role, effectively denying them access to the resource. 1. In the **IAM Roles** tab, right-click on the role, and select **Revoke All Access Keys**. ### Deleting IAM Roles IAM roles can be deleted if they are not the owners of any S3 views. If they are owners of views, they must be removed as owners first before the role can be deleted (or the view can be deleted). Access keys associated with the role become invalid when the role is deleted. 1. In the **IAM Roles** tab, right-click on the role, and select **Delete**. ## Trust Policies for IAM Roles Trust policies for IAM Roles contain statements, which indicate who can assume the role. This is an example of a trust policy: ```plaintext {  "Version": "2012-10-17",  "Statement": [    {      "Effect": "Allow",      "Principal": "*",      "Action": "sts:*"    }, ``` A statement in a policy has these components: | Effect | Indicates if the statement allows or denies access to principals for specific actions. | | --- | --- | | Principal | Indicates who can assume the role, according to Action selected, as follows: - with AssumeRole: a comma-separated list of users, either external domain (Active Directory) or local (VAST Provider) - with AssumeRoleWithWebIdentity: an OIDC provider or list of providers. | | Action | The STS action, one of the following: - **STS:AssumeRole** - for local or domain users - **STS:AssumeRoleWithWebIdentity** - for external users, using an OIDC provider | | Condition | Conditions in which an IAM role can be assumed by the named principals. - **sub**: Subject - **aud**: Audience - **amr**: Authentication Methods Reference - **azp**: Authorized Party - **email**: Email - **oaud**: Original Audience Conditions are used only with the *STS:AssumeRoleWithWebIdentity* action. | ### Examples of Trust Policies This policy allows users *user1, user2,* and *user3*, and denies users *user2* and *user4*. Note *user2* is listed in both the Allow and Deny blocks; in this case the Deny overrides the Allow. ```plaintext trust_policy = {    "Version": "2012-10-17",    "Statement": [        {            "Effect": "Allow",            "Principal": {                "User": [user1, user2, user3]            },            "Action": "sts:AssumeRole"        },        {            "Effect": "Deny",            "Principal": {                "User": [user2, user4]            },            "Action": "sts:AssumeRole"        }    ] } ``` This example uses domain users: ```plaintext trust_policy = {    "Version": "2012-10-17",    "Statement": [        {            "Effect": "Allow",            "Principal": {"User": user1@domain_name"},            "Action": "sts:AssumeRole"        },        {            "Effect": "Deny",            "Principal": {"User": user2@domain_name"},            "Action": "sts:AssumeRole"        }    ] } ``` This example includes a condition: ```plaintext trust_policy = {    "Version": "2012-10-17",    "Statement": [        {            "Effect": "Allow",            "Principal": {                "Federated": "oidc-provider/keycloak.example.com/realms/my-realm"            },            "Action": "sts:AssumeRoleWithWebIdentity",            "Condition": {                "StringEquals": {                    "keycloak.example.com/realms/my-realm:sub": "iam_role_name"                }            }        }    ] } ``` ## Using STS Clients to Assume IAM Roles ### Request Syntax Requests to the VAST STS service to assume IAM roles can be made using an AWS STS client such as the AWS CLI, using the `aws sts assume-role` or `aws sts assume-role-with-web-identity` commands. #### Endpoint URL The endpoint can be any virtual IP configured on the cluster for protocol access. It must be accessed by HTTPS only. For example, for virtual IP 1.2.3.4: https://1.2.3.4 #### Required Parameters - `Action`. One of the following: - `AssumeRole`. In this case, the request must be authenticated with a v4 signature using a permanent access key ID and secret access key created on a cluster's VMS for a user on a provider connected to the cluster. This can be a VAST provider, LDAP or Active Directory. For information about how to generate an access key pair on VMS for a user, see [Managing S3 User Permissions](/docs-5-4/docs/managing-s3-user-permissions). - `AssumeRoleWithWebIdentity`, where the requesting user is authenticated using a JWT from an OIDC provider such as Okta, Entra ID, and Keycloak. - `Version`. Set this to `2011-06-15`. - `RoleArn`. Set this to `arn:vast:iam::<tenant>:role/<IAM role>`, in which: - `<tenant>` is the name of a tenant on the VAST Cluster. The tenant must match the permanent access pair being used to authenticate the request. This means that the user for which the access key pair is created belongs to a VAST provider that is connected to the same tenant that is specified here. - `<IAM role>` is the name of the IAM role requested to be assumed. This role must belong to the specified tenant. > [!NOTE] > From version 5.4.6, the 5-token format of the ARN is also supported (without the ​*iam*​​ service token): *arn:vast:::role/* - `RoleSessionName`. Provide a string value. ##### Optional Parameters - `WebIdentityToken`. This is required if *Action*=*AssumeRoleWithWebIdentity*. Use this parameter to supply a JSON web token (JWT). Your application needs to get the JWT from the OIDC provider after the provider authenticates the user. Must be provided as base64 encoded JSON. - `Policy`. Specifies an optional inline session policy. A session policy limits the total permissions granted by the bucket policy and the identity policy. The resulting permissions for the temporary access key are the intersection of the session policy and the bucket policy plus the intersection of the session policy and any identity policies attached to the IAM role. An inline session policy specifically restricts the permissions of the requested temporary access key. When an IAM role is assumed multiple times with different session policies, each temporary access key can have different permissions, based on the associated session policy. You can pass a session policy as an inline JSON object, with up to 2K characters. The format and structure of a session policy is as described [here](/docs-5-4/docs/identity-and-bucket-policy-reference) for identity policies. For example: ```plaintext {  "Version": "2012-10-17",  "Id": "f660efc4-d34b-4710-8f13-57cf12456037",  "Statement": [    {      "Sid": "ListAllowedPrefix",      "Action": [        "s3:ListBucket"      ],      "Effect": "Allow",      "Resource": "bucket1",      "Condition": {        "StringEquals": {          "s3:prefix": "allowed"        }      }    },    {      "Sid": "GetAllowedPath",      "Action": "s3:GetObject",      "Effect": "Allow",      "Resource": "bucket1/allowed*"    }  ] } ``` - `DurationSeconds`. Sets the requested validity duration for the temporary key, in seconds. Minimum: 900 (15 minutes). Maximum: 129,600 (36 hours) unless max session duration is set to a lower limit for the IAM role in VMS. If the requested duration is outside the valid range, the request fails. #### Request Output The output of the request includes a set of temporary credentials, including: - `AccessKeyId`. The temporary access key. - `SecretAccessKey`. The temporary secret key. - `SessionToken`. A unique session token for the temporary access key pair. - `Expiration`. The timestamp of the expiration of the temporary access key pair. The returned access keys can be used within the specified expiration period (or until revoked) to assume the IAM role and send requests to the S3 bucket. #### Example Requests The following example uses the AWS CLI to to make an *AssumeRoleWithWebIdentity* request. The request is to assume some IAM role *examplerole* to access some tenant *exampletenant*, using some virtual IP 1.2.3.4 configured for protocol access on the VAST Cluster. A session policy is passed inline. The policy limits the access key so that the caller can only list the bucket *my-secure-bucket* and read objects in that bucket, assuming that this is allowed by an identity or bucket policy associated with the assumed IAM role. The request is authenticated based on a JWT web token that has been obtained from an OIDC provider. ```plaintext aws sts assume-role-with-web-identity \    --role-arn arn:vast::exampletenant:role/examplerole \    --role-session-name "RestrictedSession" \    --web-identity-token "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" \    --endpoint-url https://1.2.3.4:443 \    --policy '{      "Version": "2012-10-17",      "Id": "f660efc4-d34b-4710-8f13-57cf12456037",      "Statement": [         {           "Sid": "ListAllowedPrefix",           "Action": [             "s3:ListBucket"           ],           "Effect": "Allow",           "Resource": "bucket1",           "Condition": {             "StringEquals": {               "s3:prefix": "allowed"             }           }         },         {           "Sid": "GetAllowedPath",           "Action": "s3:GetObject",           "Effect": "Allow",           "Resource": "bucket1/allowed*"         }       ]     }' ``` The following example uses the AWS CLI to make an *AssumeRole* request. The AWS client is first configured with an access key and secret key. This must be generated by VMS for the user. The access key pair authenticates the request. The user passes an optional session policy, this time referencing a file containing the session policy. The request attempts to access the default tenant on a cluster accessed by some protocol VIP 1.2.3.4 and to assume the IAM role *examplerole*. A temporary access key pair is requested for a 1 hour duration. ```plaintext >export AWS_ACCESS_KEY_ID=AKIDEXAMPLE123456789 >export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY >aws sts assume-role \    --role-arn arn:vast::default:role/examplerole \    --role-session-name "RestrictedSession" \    --endpoint-url https://1.2.3.4:443 \    --policy file:///home/vastdata/session-policy.json \    --duration-seconds 3600 \    --no-verify-ssl ``` ## Creating and Managing IAM Roles using the VAST CLI Use these VAST CLI commands to manage IAM roles: | Task | Command | | --- | --- | | Create an IAM role | [iamrole create](/docs-5-4/docs/en/iamrole-create) | | Modify an IAM role | [iamrole modify](/docs-5-4/docs/en/iamrole-modify) | | Delete an IAM role | [iamrole delete](/docs-5-4/docs/en/iamrole-delete) | | List IAM roles | [iamrole list](/docs-5-4/docs/en/iamrole-list) | | Show details for an IAM role | [iamrole show](/docs-5-4/docs/en/iamrole-show) | | Revoke access keys for an IAM role | [iamrole revoke_access_keys](/docs-5-4/docs/en/iamrole-revoke-access-keys) | | Get details for an access key for an IAM role | [iamrole get_credentials](/docs-5-4/docs/en/iamrole-get-credentials) |