Security Token Service (STS) and IAM Roles

  • Updated on Apr 23, 2026
  • Published on Jan 27, 2026
  • 11 minute(s) read
Prev Next

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 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

The ability to authenticate requests to assume IAM roles using an access key pair is introduced in VAST Cluster 5.4.3.

The VMS protocol auditing feature enables you to save audit logs for all actions performed using the STS protocol.

Client Side Requests 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. e.g. 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.

      The AssumeRole action type is supported from VAST Cluster 5.4.3.

    • 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::<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.

  • 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 for identity policies.

    For example:

    {
  "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.

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.

>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

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

    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 for the role.

    Description

    (Optional). A description of the role.

    Max session duration

    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, from the list, that will be associated with the role. 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 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.

    A default policy is provided and displayed in the right pane.

    {
  "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 should be modified.

    To modify the policy, you can edit it directly, or upload a policy from a .json file, using the GUI controls or a combination of the above.

    In general, when editing or preparing policies to upload:

    • Use the Effect element to specify if each statement should deny or allow access to the specified principal(s) and action(s).

    • Use the Action element to specify which action(s) the effect applies to.

      • "Action": "sts:*" specifies all actions.

      • "Action": "sts:AssumeRole" specifies the AssumeRole action.

      • "Action": "sts:AssumeRoleWithWebIdentity" specifies the AssumeRoleWithWebIdentity action.

    • Use the Principal element to limit who can assume the role:

      To specify an OIDC provider principle (applicable only when using sts:AssumeRoleWithWebIdentity), use this format:

      "Principal": {"Federated": "oidc-provider/<issuer>"}

      Note

      oidc-provider/ is hard-coded, and <issuer> is obtained from the "iss" attribute of the JWT.

      For example:

      "Principal": {"Federated": "oidc-provider/login.microsoftonline.com/<tenant>/v2.0";}

      When using the sts:AssumeRole action, you can specify individual users with this format:

      "Principal": {"User": "<username>"}

      For example, for a user on the VAST provider named userx,

      "Principal": {"User": "userx"}

      For an Active Directory user name userx on domain2:

      "Principal": {"User": "userx@domain2"}

    To add to the policy using the GUI controls:

    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:

      • 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.

      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.

    4. In the Principal field, enter the principal value:

      • If the action is AssumeRole, enter a user name or a comma separated list of user names.

      • If the action is AssumeRoleWithWebIdentity, enter oidc-provider/<issuer> where <issuer> is obtained from the "iss" attribute of the JWT.

    5. If the action is AssumeRoleWithWebIdentity, optionally, 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.

        Select a Qualifier from the list. This indicates whether the condition applies to any or for all values in a request.

        Note

        This field applies only to some condition keys.

      1. Select an Operator.

      2. Enter a list of Values, separated by commas.

        For example, this condition checks the 'aud'field in a JWT for specific users.

        "Condition": {
    "StringEquals": {"login.microsoftonline.com/<tenant>/v2.0:aud": "0oalggs6d5D6exca65d7"}
}

      3. Repeat above 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.

Managing IAM Roles using the VAST CLI

Use these VAST CLI commands to manage IAM roles:

Task

Command

Create an IAM role

iamrole create

Modify an IAM role

iamrole modify

Delete an IAM role

iamrole delete

List IAM roles

iamrole list

Show details for an IAM role

iamrole show

Revoke access keys for an IAM role

iamrole revoke_access_keys

Get details for an access key for an IAM role

iamrole get_credentials

Related articles
  • Security Token Service (STS) and IAM Roles
    VAST Cluster > Version 5.4 > VAST Cluster 5.4 Tenant Administrator's Guide > Managing Users > Identity Management
  • Creating Identity Policies
    VAST Cluster > Version 5.0 > VAST Cluster 5.0 Administrator's Guide > Managing Access Protocols > S3 Object Storage Protocol > Managing S3 Access > Managing Identity Policies (v4.6)
  • Creating Identity Policies
    VAST Cluster > Version 5.4 > VAST Cluster 5.4 Administrator's Guide > Managing Users > Identity Management > Managing Identity Policies