# Temporary security credentials in IAM Temporary security credentials You can use the AWS Security Token Service (AWS STS) to create and provide trusted users with temporary security credentials that can control access to your AWS resources. Temporary security credentials work almost identically to long-term access key credentials, with the following differences: + Temporary security credentials are *short-term*, as the name implies. They can be configured to last for anywhere from a few minutes to several hours. After the credentials expire, AWS no longer recognizes them or allows any kind of access from API requests made with them. + Temporary security credentials are not stored with the user but are generated dynamically and provided to the user when requested. When (or even before) the temporary security credentials expire, the user can request new credentials, as long as the user requesting them still has permissions to do so. As a result, temporary credentials have the following advantages over long-term credentials: + You do not have to distribute or embed long-term AWS security credentials with an application. + You can provide access to your AWS resources to users without having to define an AWS identity for them. Temporary credentials are the basis for [roles](id_roles.md) and [identity federation](id_roles_providers.md). + The temporary security credentials have a limited lifetime, so you do not have to update them or explicitly revoke them when they're no longer needed. After temporary security credentials expire, they cannot be reused. You can specify how long the credentials are valid, up to a maximum limit. ## AWS STS and AWS regions Temporary security credentials are generated by AWS STS. By default, AWS STS is a global service with a single endpoint at `https://sts.amazonaws.com`. However, you can also choose to make AWS STS API calls to endpoints in any other supported Region. This can reduce latency (server lag) by sending the requests to servers in a Region that is geographically closer to you. No matter which Region your credentials come from, they work globally. For more information, see [Manage AWS STS in an AWS Region](id_credentials_temp_enable-regions.md). ## Common scenarios for temporary credentials Temporary credentials are useful in scenarios that involve identity federation, delegation, cross-account access, and IAM roles. ### Identity federation You can manage your user identities in an external system outside of AWS and grant users who sign in from those systems access to perform AWS tasks and access your AWS resources. IAM supports two types of identity federation. In both cases, the identities are stored outside of AWS. The distinction is where the external system resides—in your data center or an external third party on the web. To compare features of temporary security credentials for identity federation, see [Compare AWS STS credentials](id_credentials_sts-comparison.md). For more information about external identity providers, see [Identity providers and federation into AWS](id_roles_providers.md). + **OpenID Connect (OIDC) federation** – You can let users sign in using a well-known third-party identity provider such as Login with Amazon, Facebook, Google, or any OIDC 2.0 compatible provider for your mobile or web application, you don't need to create custom sign-in code or manage your own user identities. Using OIDC federation helps you keep your AWS account secure, because you don't have to distribute long-term security credentials, such as IAM user access keys, with your application. For more information, see [OIDC federation](id_roles_providers_oidc.md). AWS STS OIDC federation supports Login with Amazon, Facebook, Google, and any OpenID Connect (OIDC)-compatible identity provider. **Note** For mobile applications, we recommend that you use Amazon Cognito. You can use this service with AWS SDKs for mobile development to create unique identities for users and authenticate them for secure access to your AWS resources. Amazon Cognito supports the same identity providers as AWS STS, and also supports unauthenticated (guest) access and lets you migrate user data when a user signs in. Amazon Cognito also provides API operations for synchronizing user data so that it is preserved as users move between devices. For more information, see [Authentication with Amplify](https://docs.amplify.aws/lib/auth/getting-started/q/platform/js/#authentication-with-amplify) in the *Amplify Documentation*. + **SAML federation** – You can authenticate users in your organization's network, and then provide those users access to AWS without creating new AWS identities for them and requiring them to sign in with different sign-in credentials. This is known as the *single sign-on* approach to temporary access. AWS STS supports open standards like Security Assertion Markup Language (SAML) 2.0, with which you can use Microsoft AD FS to leverage your Microsoft Active Directory. You can also use SAML 2.0 to manage your own solution for federating user identities. For more information, see [SAML 2.0 federation](id_roles_providers_saml.md). + **Custom federation broker** – You can use your organization's authentication system to grant access to AWS resources. For an example scenario, see [Enable custom identity broker access to the AWS console](id_roles_providers_enable-console-custom-url.md). + **Federation using SAML 2.0** – You can use your organization's authentication system and SAML to grant access to AWS resources. For more information and an example scenario, see [SAML 2.0 federation](id_roles_providers_saml.md). ### Roles for cross-account access Many organizations maintain more than one AWS account. Using roles and cross-account access, you can define user identities in one account, and use those identities to access AWS resources in other accounts that belong to your organization. This is known as the *delegation* approach to temporary access. For more information about creating cross-account roles, see [Create a role to give permissions to an IAM user](id_roles_create_for-user.md). To learn whether principals in accounts outside of your zone of trust (trusted organization or account) have access to assume your roles, see [What is IAM Access Analyzer?](https://docs.aws.amazon.com/IAM/latest/UserGuide/what-is-access-analyzer.html). ### Roles for Amazon EC2 If you run applications on Amazon EC2 instances and those applications need access to AWS resources, you can provide temporary security credentials to your instances when you launch them. These temporary security credentials are available to all applications that run on the instance, so you don't need to store any long-term credentials on the instance. For more information, see [Use an IAM role to grant permissions to applications running on Amazon EC2 instances](id_roles_use_switch-role-ec2.md). To learn more about IAM Amazon EC2 role credentials, see [IAM roles for Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html) in the *Amazon Elastic Compute Cloud User Guide*. ### Other AWS services You can use temporary security credentials to access most AWS services. For a list of the services that accept temporary security credentials, see [AWS services that work with IAM](reference_aws-services-that-work-with-iam.md). ## Sample applications that use temporary credentials You can use AWS Security Token Service (AWS STS) to create and provide trusted users with temporary security credentials that can control access to your AWS resources. For more information about AWS STS, see [Temporary security credentials in IAM](#id_credentials_temp). To see how you can use AWS STS to manage temporary security credentials, you can download the following sample applications that implement complete example scenarios: + [Enabling Federation to AWS Using Windows Active Directory, ADFS, and SAML 2.0](https://aws.amazon.com/blogs/security/enabling-federation-to-aws-using-windows-active-directory-adfs-and-saml-2-0/). Demonstrates how to delgate access using enterprise federation to AWS using Windows Active Directory (AD), Active Directory Federation Services (ADFS) 2.0, and SAML (Security Assertion Markup Language) 2.0. + [Enable custom identity broker access to the AWS console](id_roles_providers_enable-console-custom-url.md). Demonstrates how to create a custom federation proxy that enables single sign-on (SSO) so that existing Active Directory users can sign in to the AWS Management Console. + [How to Use Shibboleth for Single Sign-On to the AWS Management Console.](https://aws.amazon.com/blogs/security/how-to-use-shibboleth-for-single-sign-on-to-the-aws-management-console/). Shows how to use [Shibboleth](http://shibboleth.net/) and [SAML](id_roles_providers_saml.md) to provide users with single sign-on (SSO) access to the AWS Management Console. ### Samples for OIDC federation The following sample applications illustrate how to use OIDCfederation with providers like Login with Amazon, Amazon Cognito, Facebook, or Google. You can trade authentication from these providers for temporary AWS security credentials to access AWS services. + [Amazon Cognito Tutorials](https://docs.aws.amazon.com/cognito/latest/developerguide/tutorials.html) – We recommend that you use Amazon Cognito with the AWS SDKs for mobile development. Amazon Cognito is the simplest way to manage identity for mobile apps, and it provides additional features like synchronization and cross-device identity. For more information about Amazon Cognito, see [Authentication with Amplify](https://docs.amplify.aws/lib/auth/getting-started/q/platform/js/#authentication-with-amplify) in the *Amplify Documentation*. ## Additional resources for temporary security credentials Additional resources for temporary credentials The following scenarios and applications can guide you in using temporary security credentials: + [How to integrate AWS STS SourceIdentity with your identity provider](https://aws.amazon.com/blogs/security/how-to-integrate-aws-sts-sourceidentity-with-your-identity-provider/). This post shows you how to set up the AWS STS `SourceIdentity` attribute when using Okta, Ping, or OneLogin as your IdP. + [OIDC federation](id_roles_providers_oidc.md). This section discusses how to configure IAM roles when you use OIDC federation and the `AssumeRoleWithWebIdentity` API. + [Secure API access with MFA](id_credentials_mfa_configure-api-require.md). This topic explains how to use roles to require multi-factor authentication (MFA) to protect sensitive API actions in your account. For more information on policies and permissions in AWS see the following topics: + [Access management for AWS resources](access.md) + [Policy evaluation logic](reference_policies_evaluation-logic.md). + [Managing Access Permissions to Your Amazon S3 Resources](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-access-control.html) in *Amazon Simple Storage Service User Guide*. + To learn whether principals in accounts outside of your zone of trust (trusted organization or account) have access to assume your roles, see [What is IAM Access Analyzer?](https://docs.aws.amazon.com/IAM/latest/UserGuide/what-is-access-analyzer.html). # Compare AWS STS credentials The following table compares features of the API operations in AWS STS that return temporary security credentials. To learn about the different methods you can use to request temporary security credentials by assuming a role, see [Methods to assume a role](id_roles_manage-assume.md). To learn about the different AWS STS API operations that allow you to pass session tags, see [Pass session tags in AWS STS](id_session-tags.md). **Note** You can send AWS STS API calls either to a global endpoint or to one of the Regional endpoints. If you choose an endpoint closer to you, you can reduce latency and improve the performance of your API calls. You also can choose to direct your calls to an alternative Regional endpoint if you can no longer communicate with the original endpoint. If you are using one of the various AWS SDKs, then use that SDK method to specify a Region before you make the API call. If you manually construct HTTP API requests, then you must direct the request to the correct endpoint yourself. For more information, see the [AWS STS section of *Regions and Endpoints*](https://docs.aws.amazon.com/general/latest/gr/rande.html#sts_region) and [Manage AWS STS in an AWS Region](id_credentials_temp_enable-regions.md). | **AWS STS API** | **Who can call** | **Credential lifetime (min \$1 max \$1 default)** | **MFA support**¹ | **Session policy support**² | **Restrictions on resulting temporary credentials** | | --- | --- | --- | --- | --- | --- | | [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) | IAM user or IAM role with existing temporary security credentials | 15 m \$1 Maximum session duration setting³ \$1 1 hr | Yes | Yes | Cannot call `GetFederationToken` or `GetSessionToken`. | | [AssumeRoleWithSAML](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) | Any user; caller must pass a SAML authentication response that indicates authentication from a known identity provider | 15 m \$1 Maximum session duration setting³ \$1 1 hr | No | Yes | Cannot call `GetFederationToken` or `GetSessionToken`. | | [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html) | Any user; caller must pass an OIDC compliant JWT token that indicates authentication from a known identity provider | 15 m \$1 Maximum session duration setting³ \$1 1 hr | No | Yes | Cannot call `GetFederationToken` or `GetSessionToken`. | | [GetFederationToken](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetFederationToken.html) | IAM user or AWS account root user | IAM user: 15 m \$1 36 hr \$1 12 hr Root user: 15 m \$1 1 hr \$1 1 hr | No | Yes | Cannot call IAM operations using the AWS CLI or AWS API. This limitation does not apply to console sessions. Cannot call AWS STS operations except `GetCallerIdentity`.⁴ SSO to console is allowed.⁵ | | [GetSessionToken](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetSessionToken.html) | IAM user or AWS account root user | IAM user: 15 m \$1 36 hr \$1 12 hr Root user: 15 m \$1 1 hr \$1 1 hr | Yes | No | Cannot call IAM API operations unless MFA information is included with the request. Cannot call AWS STS API operations except `AssumeRole` or `GetCallerIdentity`. SSO to console is not allowed.⁶ | ¹ **MFA support**. You can include information about a multi-factor authentication (MFA) device when you call the AssumeRole and GetSessionToken API operations. This ensures that the temporary security credentials that result from the API call can be used only by users who are authenticated with an MFA device. For more information, see [Secure API access with MFA](id_credentials_mfa_configure-api-require.md). ² **Session policy support**. Session policies are policies that you pass as a parameter when you programmatically create a temporary session for a role or AWS STS federated user session. This policy limits the permissions from the role or user's identity-based policy that are assigned to the session. The resulting session's permissions are the intersection of the entity's identity-based policies and the session policies. Session policies cannot be used to grant more permissions than those allowed by the identity-based policy of the role that is being assumed. For more information about role session permissions, see [Session policies](access_policies.md#policies_session). ³ **Maximum session duration setting**. Use the `DurationSeconds` parameter to specify the duration of your role session from 900 seconds (15 minutes) up to the maximum session duration setting for the role. To learn how to view the maximum value for your role, see [Update the maximum session duration for a role](id_roles_update-role-settings.md#id_roles_update-session-duration). ⁴ **GetCallerIdentity**. No permissions are required to perform this operation. If an administrator adds a policy to your IAM user or role that explicitly denies access to the `sts:GetCallerIdentity` action, you can still perform this operation. Permissions are not required because the same information is returned when an IAM user or role is denied access. To view an example response, see [I am not authorized to perform: iam:DeleteVirtualMFADevice](troubleshoot.md#troubleshoot_general_access-denied-delete-mfa). ⁵ **Single sign-on (SSO) to the console**. To support SSO, AWS lets you call a federation endpoint (`https://signin.aws.amazon.com/federation`) and pass temporary security credentials. The endpoint returns a token that you can use to construct a URL that signs a user directly into the console without requiring a password. For more information, see [Enabling SAML 2.0 federated principals to access the AWS Management Console](id_roles_providers_enable-console-saml.md) and [ How to Enable Cross-Account Access to the AWS Management Console](https://aws.amazon.com/blogs/security/how-to-enable-cross-account-access-to-the-aws-management-console) in the AWS Security Blog. ⁶ After you retrieve your temporary credentials, you can't access the AWS Management Console by passing the credentials to the federation single sign-on endpoint. For more information, see [Enable custom identity broker access to the AWS console](id_roles_providers_enable-console-custom-url.md). # Service bearer tokens Some AWS services require that you have permission to get an AWS STS service bearer token before you can access their resources programmatically. These services support a protocol that requires you to use a bearer token instead of using a traditional [AWS Signature Version 4 for API requests](reference_sigv.md). When you perform AWS CLI or AWS API operations that require bearer tokens, the AWS service requests a bearer token on your behalf. The service provides you with the token, which you can then use to perform subsequent operations in that service. AWS STS service bearer tokens include information from your original principal authentication that might affect your permissions. This information can include principal tags, session tags, and session policies. The token's access key ID begins with the `ABIA` prefix. This helps you to identify operations that were performed using service bearer tokens in your CloudTrail logs. **Important** The bearer token can be used only for calls to the service that generates it and in the Region where it was generated. You can't use the bearer token to perform operations in other services or Regions. An example of a service that supports bearer tokens is AWS CodeArtifact. Before you can interact with AWS CodeArtifact using a package manager such as NPM, Maven, or PIP, you must call the `aws codeartifact get-authorization-token` operation. This operation returns a bearer token that you can use to perform AWS CodeArtifact operations. Alternatively, you can use the `aws codeartifact login` command that completes the same operation and then configures your client automatically. If you perform an action in an AWS service that generates a bearer token for you, you must have the following permissions in your IAM policy: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AllowServiceBearerToken", "Effect": "Allow", "Action": "sts:GetServiceBearerToken", "Resource": "*" } ] } ``` ------ For a service bearer token example, see [ Using identity-based policies for AWS CodeArtifact](https://docs.aws.amazon.com/codeartifact/latest/ug/auth-and-access-control-iam-identity-based-access-control.html) in the *AWS CodeArtifact* user guide. # Request temporary security credentials To request temporary security credentials, you can use AWS Security Token Service (AWS STS) operations in the AWS API. These include operations to create and provide trusted users with temporary security credentials that can control access to your AWS resources. For more information about AWS STS, see [Temporary security credentials in IAM](id_credentials_temp.md). To learn about the different methods that you can use to request temporary security credentials by assuming a role, see [Methods to assume a role](id_roles_manage-assume.md). To call the API operations, you can use one of the [AWS SDKs](http://aws.amazon.com/tools/). The SDKs are available for a variety of programming languages and environments, including Java, .NET, Python, Ruby, Android, and iOS. The SDKs take care of tasks such as cryptographically signing your requests, retrying requests if necessary, and handling error responses. You can also use the AWS STS Query API, which is described in the [AWS Security Token Service API Reference](https://docs.aws.amazon.com/STS/latest/APIReference/). Finally, two command line tools support the AWS STS commands: the [AWS Command Line Interface](https://aws.amazon.com/documentation/cli), and the [AWS Tools for Windows PowerShell](https://aws.amazon.com/documentation/powershell). The AWS STS API operations create a new session with temporary security credentials that include an access key pair and a session token. The access key pair consists of an access key ID and a secret key. Users (or an application that the user runs) can use these credentials to access your resources. You can create a role session and pass session policies and session tags programmatically using AWS STS API operations. The resulting session permissions are the intersection of the role's identity-based policies and the session policies. For more information about session policies, see [Session policies](access_policies.md#policies_session). For more information about session tags, see [Pass session tags in AWS STS](id_session-tags.md). **Note** The size of the session token that AWS STS API operations return is not fixed. We strongly recommend that you make no assumptions about the maximum size. The typical token size is less than 4096 bytes, but that can vary. ## Using AWS STS with AWS Regions You can send AWS STS API calls either to a global endpoint or to one of the Regional endpoints. If you choose an endpoint closer to you, you can reduce latency and improve the performance of your API calls. You also can choose to direct your calls to an alternative Regional endpoint if you can no longer communicate with the original endpoint. If you are using one of the various AWS SDKs, then use that SDK method to specify a Region before you make the API call. If you manually construct HTTP API requests, then you must direct the request to the correct endpoint yourself. For more information, see the [AWS STS section of *Regions and Endpoints*](https://docs.aws.amazon.com/general/latest/gr/rande.html#sts_region) and [Manage AWS STS in an AWS Region](id_credentials_temp_enable-regions.md). The following are the API operations that you can use to acquire temporary credentials for use in your AWS environment and applications. ## Requesting credentials for cross-account delegation and federation through a custom identity broker Requesting credentials with AssumeRole The [https://docs.aws.amazon.com//STS/latest/APIReference/API_AssumeRole.html](https://docs.aws.amazon.com//STS/latest/APIReference/API_AssumeRole.html) API operation is useful for allowing existing IAM users to access AWS resources that they don't already have access to. For example, the user might need access to resources in another AWS account. It is also useful as a means to temporarily gain privileged access—for example, to provide multi-factor authentication (MFA). You must call this API using active credentials. To learn who can call this operation, see [Compare AWS STS credentials](id_credentials_sts-comparison.md). For more information, see [Create a role to give permissions to an IAM user](id_roles_create_for-user.md) and [Secure API access with MFA](id_credentials_mfa_configure-api-require.md). **To request temporary security credentials for cross-account delegation and federation through a custom identity broker** 1. Authenticate with your AWS security credentials. This call must be made using valid AWS security credentials. 1. Call the operation [https://docs.aws.amazon.com//STS/latest/APIReference/API_AssumeRole.html](https://docs.aws.amazon.com//STS/latest/APIReference/API_AssumeRole.html). The following example shows a sample request and response using `AssumeRole`. This example request assumes the `demo` role for the specified duration with the included [session policy](access_policies.md#policies_session), [session tags](id_session-tags.md), [external ID](id_roles_common-scenarios_third-party.md), and [source identity](id_credentials_temp_control-access_monitor.md). The resulting session is named `John-session`. **Example request** ``` https://sts.amazonaws.com/ ?Version=2011-06-15 &Action=AssumeRole &RoleSessionName=John-session &RoleArn=arn:aws::iam::123456789012:role/demo &Policy=%7B%22Version%22%3A%222012-10-17 %22%2C%22Statement%22%3A%5B%7B%22Sid%22%3A%20%22Stmt1%22%2C%22Effect%22%3A%20%22Allow%22%2C%22Action%22%3A%20%22s3%3A*%22%2C%22Resource%22%3A%20%22*%22%7D%5D%7D &DurationSeconds=1800 &Tags.member.1.Key=Project &Tags.member.1.Value=Pegasus &Tags.member.2.Key=Cost-Center &Tags.member.2.Value=12345 &ExternalId=123ABC &SourceIdentity=DevUser123 &AUTHPARAMS ``` The policy value shown in the preceding example is the URL-encoded version of the following policy: ------ #### [ JSON ] **** ``` {"Version":"2012-10-17", "Statement":[{"Sid":"Stmt1","Effect":"Allow","Action":"s3:*","Resource":"*"}]} ``` ------ The `AUTHPARAMS` parameter in the example is a placeholder for your *signature*. A signature is the authentication information that you must include with AWS HTTP API requests. We recommend using the [AWS SDKs](https://aws.amazon.com/tools/) to create API requests, and one benefit of doing so is that the SDKs handle request signing for you. If you must create and sign API requests manually, see [Signing AWS Requests By Using Signature Version 4](https://docs.aws.amazon.com/general/latest/gr/sigv4_signing.html) in the *Amazon Web Services General Reference* to learn how to sign a request. In addition to the temporary security credentials, the response includes the Amazon Resource Name (ARN) for the federated user and the expiration time of the credentials. **Example response** ``` DevUser123 AQoDYXdzEPT//////////wEXAMPLEtc764bNrC9SAPBSM22wDOk4x4HIZ8j4FZTwdQW LWsKWHGBuFqwAeMicRXmxfpSPfIeoIYRqTflfKD8YUuwthAx7mSEI/qkPpKPi/kMcGd QrmGdeehM4IC1NtBmUpp2wUE8phUZampKsburEDy0KPkyQDYwT7WZ0wq5VSXDvp75YU 9HFvlRd8Tx6q6fE8YQcHNVXAkiY9q6d+xo0rKwT38xVqr7ZD0u0iPPkUL64lIZbqBAz +scqKmlzm8FDrypNC9Yjc8fPOLn9FX9KSYvKTr4rvx3iSIlTJabIQwj2ICCR/oLxBA== wJalrXUtnFEMI/K7MDENG/bPxRfiCYzEXAMPLEKEY 2019-07-15T23:28:33.359Z AKIAIOSFODNN7EXAMPLE arn:aws:sts::123456789012:assumed-role/demo/John ARO123EXAMPLE123:John 8 c6104cbe-af31-11e0-8154-cbc7ccf896c7 ``` **Note** An AWS conversion compresses the passed session policies and session tags into a packed binary format that has a separate limit. Your request can fail for this limit even if your plaintext meets the other requirements. The `PackedPolicySize` response element indicates by percentage how close the policies and tags for your request are to the upper size limit. ## Requesting credentials through an OIDC provider Requesting credentials with AssumeRoleWithWebIdentity The [https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html) API operation returns a set of temporary AWS security credentials in exchange for a JSON Web Token (JWT). This includes public identity providers, such as Login with Amazon, Facebook, Google, and providers that issue JWTs that are compatible with OpenID Connect (OIDC) discovery, such as GitHub actions or Azure Devops. For more information, see [OIDC federation](id_roles_providers_oidc.md). **Note** `AssumeRoleWithWebIdentity` requests are not signed with, and do not require AWS credentials. **Requesting credentials through an OIDC provider** 1. Call the operation [https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html). When you call `AssumeRoleWithWebIdentity`, AWS validates the token presented by verifying the digital signature using public keys made available through your IdP's JSON web keyset (JWKS). If the token is valid, and all conditions set forth in the IAM role trust policy are met, AWS returns the following information to you: + A set of temporary security credentials. These consist of an access key ID, a secret access key, and a session token. + The role ID and the ARN of the assumed role. + A `SubjectFromWebIdentityToken` value that contains the unique user ID. 1. Your application may then use the temporary security credentials that were returned in the response to make AWS API calls. This is the same process as making an AWS API call with long-term security credentials. The difference is that you must include the session token, which lets AWS verify that the temporary security credentials are valid. Your application should cache the credentials returned by AWS STS and refresh them as needed. If your application is built using an AWS SDK, the SDK has credential providers that can handle calling `AssumeRoleWithWebIdentity` and refreshing AWS credentials before they expire. For more information, see [AWS SDKs and Tools standardized credential providers](https://docs.aws.amazon.com/sdkref/latest/guide/standardized-credentials.html) in the *AWS SDKs and Tools Reference Guide*. ## Requesting credentials through a SAML 2.0 identity provider Requesting credentials with AssumeRoleWithSAML The [https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) API operation returns a set of temporary security credentials for SAML federated principals who are authenticated by your organization's existing identity system. The users must also use [SAML](https://www.oasis-open.org/standards#samlv2.0) 2.0 (Security Assertion Markup Language) to pass authentication and authorization information to AWS. This API operation is useful in organizations that have integrated their identity systems (such as Windows Active Directory or OpenLDAP) with software that can produce SAML assertions. Such an integration provides information about user identity and permissions (such as Active Directory Federation Services or Shibboleth). For more information, see [SAML 2.0 federation](id_roles_providers_saml.md). 1. Call the operation [https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html). This is an unsigned call, meaning you do not need to authenticate AWS security credentials prior to making the request. **Note** A call to `AssumeRoleWithSAML` is not signed (encrypted). Therefore, you should only include optional session policies if the request is transmitted through a trusted intermediary. In this case, someone could alter the policy to remove the restrictions. 1. When you call `AssumeRoleWithSAML`, AWS verifies the authenticity of the SAML assertion. Assuming that the identity provider validates the assertion, AWS returns the following information to you: + A set of temporary security credentials. These consist of an access key ID, a secret access key, and a session token. + The role ID and the ARN of the assumed role. + An `Audience` value that contains the value of the `Recipient` attribute of the `SubjectConfirmationData` element of the SAML assertion. + An `Issuer` value that contains the value of the `Issuer` element of the SAML assertion. + A `NameQualifier` element that contains a hash value built from the `Issuer` value, the AWS account ID, and the friendly name of the SAML provider. When combined with the `Subject` element, they can uniquely identify the SAML federated principal. + A `Subject` element that contains the value of the `NameID` element in the `Subject` element of the SAML assertion. + A `SubjectType` element that indicates the format of the `Subject` element. The value can be `persistent`, `transient`, or the full `Format` URI from the `Subject` and `NameID` elements used in your SAML assertion. For information about the `NameID` element's `Format` attribute, see [Configure SAML assertions for the authentication response](id_roles_providers_create_saml_assertions.md). 1. Use the temporary security credentials returned in the response to make AWS API calls. This is the same process as making an AWS API call with long-term security credentials. The difference is that you must include the session token, which lets AWS verify that the temporary security credentials are valid. Your app should cache the credentials. By default the credentials expire after an hour. If you are not using the [AmazonSTSCredentialsProvider](https://aws.amazon.com/blogs/mobile/using-the-amazoncredentialsprovider-protocol-in-the-aws-sdk-for-ios) action in the AWS SDK, it's up to you and your app to call `AssumeRoleWithSAML` again. Call this operation to get a new set of temporary security credentials before the old ones expire. ## Requesting credentials through a custom identity broker Requesting credentials with GetFederationToken The [https://docs.aws.amazon.com/STS/latest/APIReference/API_GetFederationToken.html](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetFederationToken.html) API operation returns a set of temporary security credentials for AWS STS federated user principals. This API differs from `AssumeRole` in that the default expiration period is substantially longer (12 hours instead of one hour). Additionally, you can use the `DurationSeconds` parameter to specify a duration for the temporary security credentials to remain valid. The resulting credentials are valid for the specified duration, between 900 seconds (15 minutes) to 129,600 seconds (36 hours). The longer expiration period can help reduce the number of calls to AWS because you do not need to get new credentials as often. 1. Authenticate with the AWS security credentials of your specific IAM user. This call must be made using valid AWS security credentials. 1. Call the operation [https://docs.aws.amazon.com/STS/latest/APIReference/API_GetFederationToken.html](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetFederationToken.html). The `GetFederationToken` call returns temporary security credentials that consist of the session token, access key, secret key, and expiration. You can use `GetFederationToken` if you want to manage permissions inside your organization (for example, using the proxy application to assign permissions). The following example shows a sample request and response that uses `GetFederationToken`. This example request federates the calling user for the specified duration with the [session policy](access_policies.md#policies_session) ARN and [session tags](id_session-tags.md). The resulting session is named `Jane-session`. **Example request** ``` https://sts.amazonaws.com/ ?Version=2011-06-15 &Action=GetFederationToken &Name=Jane-session &PolicyArns.member.1.arn==arn%3Aaws%3Aiam%3A%3A123456789012%3Apolicy%2FRole1policy &DurationSeconds=1800 &Tags.member.1.Key=Project &Tags.member.1.Value=Pegasus &Tags.member.2.Key=Cost-Center &Tags.member.2.Value=12345 &AUTHPARAMS ``` The policy ARN shown in the preceding example includes the following URL-encoded ARN: `arn:aws:iam::123456789012:policy/Role1policy` Also, note that the `&AUTHPARAMS` parameter in the example is meant as a placeholder for the authentication information. This is the *signature*, which you must include with AWS HTTP API requests. We recommend using the [AWS SDKs](https://aws.amazon.com/tools/) to create API requests, and one benefit of doing so is that the SDKs handle request signing for you. If you must create and sign API requests manually, go to [Signing AWS Requests By Using Signature Version 4](https://docs.aws.amazon.com/general/latest/gr/sigv4_signing.html) in the *Amazon Web Services General Reference* to learn how to sign a request. In addition to the temporary security credentials, the response includes the Amazon Resource Name (ARN) for the federated user and the expiration time of the credentials. **Example response** ``` AQoDYXdzEPT//////////wEXAMPLEtc764bNrC9SAPBSM22wDOk4x4HIZ8j4FZTwdQW LWsKWHGBuFqwAeMicRXmxfpSPfIeoIYRqTflfKD8YUuwthAx7mSEI/qkPpKPi/kMcGd QrmGdeehM4IC1NtBmUpp2wUE8phUZampKsburEDy0KPkyQDYwT7WZ0wq5VSXDvp75YU 9HFvlRd8Tx6q6fE8YQcHNVXAkiY9q6d+xo0rKwT38xVqr7ZD0u0iPPkUL64lIZbqBAz +scqKmlzm8FDrypNC9Yjc8fPOLn9FX9KSYvKTr4rvx3iSIlTJabIQwj2ICCEXAMPLE== wJalrXUtnFEMI/K7MDENG/bPxRfiCYzEXAMPLEKEY 2019-04-15T23:28:33.359Z AKIAIOSFODNN7EXAMPLE; arn:aws:sts::123456789012:federated-user/Jean 123456789012:Jean 4 c6104cbe-af31-11e0-8154-cbc7ccf896c7 ``` **Note** An AWS conversion compresses the passed session policies and session tags into a packed binary format that has a separate limit. Your request can fail for this limit even if your plaintext meets the other requirements. The `PackedPolicySize` response element indicates by percentage how close the policies and tags for your request are to the upper size limit. AWS recommends that you grant permissions at the resource level (for example, you attach a resource-based policy to an Amazon S3 bucket), you can omit the `Policy` parameter. However, if you do not include a policy for the AWS STS federated user principal, the temporary security credentials will not grant any permissions. In this case, you *must* use resource policies to grant the federated user access to your AWS resources. For example, assume your AWS account number is 111122223333, and you have an Amazon S3 bucket that you want to allow Susan to access. Susan's temporary security credentials don't include a policy for the bucket. In that case, you would need to ensure that the bucket has a policy with an ARN that matches Susan's ARN, such as `arn:aws:sts::111122223333:federated-user/Susan`. ## Requesting credentials for users in untrusted environments Requesting credentials with GetSessionToken The [https://docs.aws.amazon.com/STS/latest/APIReference/API_GetSessionToken.html](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetSessionToken.html) API operation returns a set of temporary security credentials to an existing IAM user. This is useful for providing enhanced security, such as allowing AWS requests only when MFA is enabled for the IAM user. Because the credentials are temporary, they provide enhanced security when you have an IAM user who accesses your resources through a less secure environment. Examples of less secure environments include a mobile device or web browser. 1. Authenticate with the AWS security credentials of your specific IAM user. This call must be made using valid AWS security credentials. 1. Call the operation [https://docs.aws.amazon.com/STS/latest/APIReference/API_GetSessionToken.html](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetSessionToken.html). 1. `GetSessionToken` returns temporary security credentials consisting of a session token, an access key ID, and a secret access key. By default, temporary security credentials for an IAM user are valid for a maximum of 12 hours. But you can request a duration as short as 15 minutes or as long as 36 hours using the `DurationSeconds` parameter. For security reasons, a token for an AWS account root user is restricted to a duration of one hour. The following example shows a sample request and response using `GetSessionToken`. The response also includes the expiration time of the temporary security credentials. **Example request** ``` https://sts.amazonaws.com/ ?Version=2011-06-15 &Action=GetSessionToken &DurationSeconds=1800 &AUTHPARAMS ``` The `AUTHPARAMS` parameter in the example is a placeholder for your *signature*. A signature is the authentication information that you must include with AWS HTTP API requests. We recommend using the [AWS SDKs](https://aws.amazon.com/tools/) to create API requests, and one benefit of doing so is that the SDKs handle request signing for you. If you must create and sign API requests manually, go to [Signing AWS Requests By Using Signature Version 4](https://docs.aws.amazon.com/general/latest/gr/sigv4_signing.html) in the *Amazon Web Services General Reference* to learn how to sign a request. **Example response** ``` AQoEXAMPLEH4aoAH0gNCAPyJxz4BlCFFxWNE1OPTgk5TthT+FvwqnKwRcOIfrRh3c/L To6UDdyJwOOvEVPvLXCrrrUtdnniCEXAMPLE/IvU1dYUg2RVAJBanLiHb4IgRmpRV3z rkuWJOgQs8IZZaIv2BXIa2R4OlgkBN9bkUDNCJiBeb/AXlzBBko7b15fjrBs2+cTQtp Z3CYWFXG8C5zqx37wnOE49mRl/+OtkIKGO7fAE wJalrXUtnFEMI/K7MDENG/bPxRfiCYzEXAMPLEKEY 2011-07-11T19:55:29.611Z AKIAIOSFODNN7EXAMPLE 58c5dbae-abef-11e0-8cfe-09039844ac7d ``` Optionally, the `GetSessionToken` request can include `SerialNumber` and `TokenCode` values for AWS multi-factor authentication (MFA) verification. If the provided values are valid, AWS STS provides temporary security credentials that include the state of MFA authentication. The temporary security credentials can then be used to access the MFA-protected API operations or AWS websites for as long as the MFA authentication is valid. The following example shows a `GetSessionToken` request that includes an MFA verification code and device serial number. ``` https://sts.amazonaws.com/ ?Version=2011-06-15 &Action=GetSessionToken &DurationSeconds=7200 &SerialNumber=YourMFADeviceSerialNumber &TokenCode=123456 &AUTHPARAMS ``` **Note** The call to AWS STS can be to the global endpoint or to any of the Regional endpoints that you activate your AWS account. For more information, see the [AWS STS section of *Regions and Endpoints*](https://docs.aws.amazon.com/general/latest/gr/rande.html#sts_region). The `AUTHPARAMS` parameter in the example is a placeholder for your *signature*. A signature is the authentication information that you must include with AWS HTTP API requests. We recommend using the [AWS SDKs](https://aws.amazon.com/tools/) to create API requests, and one benefit of doing so is that the SDKs handle request signing for you. If you must create and sign API requests manually, see [Signing AWS Requests By Using Signature Version 4](https://docs.aws.amazon.com/general/latest/gr/sigv4_signing.html) in the *Amazon Web Services General Reference* to learn how to sign a request. # Use temporary credentials with AWS resources You can use temporary security credentials to make programmatic requests for AWS resources using the AWS CLI or AWS API (using the [AWS SDKs](https://aws.amazon.com/tools/)). The temporary credentials provide the same permissions as long-term security credentials, such as IAM user credentials. However, there are a few differences: + When you make a call using temporary security credentials, the call must include a session token, which is returned along with those temporary credentials. AWS uses the session token to validate the temporary security credentials. + Temporary credentials expire after a specified interval. After temporary credentials expire, any calls that you make with those credentials will fail, so you must generate a new set of temporary credentials. Temporary credentials cannot be extended or refreshed beyond the original specified interval. + When you use temporary credentials to make a request, your principal might include a set of tags. These tags come from session tags and tags that are attached to the role that you assume. For more information about session tags, see [Pass session tags in AWS STS](id_session-tags.md). If you are using the [AWS SDKs](https://aws.amazon.com/tools), the [AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/) (AWS CLI), or the [Tools for Windows PowerShell](https://aws.amazon.com/powershell), the way to get and use temporary security credentials differs with the context. If you are running code, AWS CLI, or Tools for Windows PowerShell commands inside an EC2 instance, you can take advantage of roles for Amazon EC2. Otherwise, you can call an [AWS STS API](https://docs.aws.amazon.com/STS/latest/APIReference/) to get the temporary credentials, and then use them explicitly to make calls to AWS services. **Note** You can use AWS Security Token Service (AWS STS) to create and provide trusted users with temporary security credentials that can control access to your AWS resources. For more information about AWS STS, see [Temporary security credentials in IAM](id_credentials_temp.md). AWS STS is a global service that has a default endpoint at `https://sts.amazonaws.com`. This endpoint is in the US East (N. Virginia) Region, although credentials that you get from this and other endpoints are valid globally. These credentials work with services and resources in any Region. You can also choose to make AWS STS API calls to endpoints in any of the supported Regions. This can reduce latency by making the requests from servers in a Region that is geographically closer to you. No matter which Region your credentials come from, they work globally. For more information, see [Manage AWS STS in an AWS Region](id_credentials_temp_enable-regions.md). **Contents** + [ ## Using temporary credentials in Amazon EC2 instances ](#using-temp-creds-sdk-ec2-instances) + [ ## Using temporary security credentials with the AWS SDKs ](#using-temp-creds-sdk) + [ ## Using temporary security credentials with the AWS CLI ](#using-temp-creds-sdk-cli) + [ ## Using temporary security credentials with API operations ](#RequestWithSTS) + [ ## More information ](#using-temp-creds-more-info) ## Using temporary credentials in Amazon EC2 instances If you want to run AWS CLI commands or code inside an EC2 instance, the recommended way to get credentials is to use [roles for Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html). You create an IAM role that specifies the permissions that you want to grant to applications that run on the EC2 instances. When you launch the instance, you associate the role with the instance. Applications, AWS CLI, and Tools for Windows PowerShell commands that run on the instance can then get automatic temporary security credentials from the instance metadata. You do not have to explicitly get the temporary security credentials. The AWS SDKs, AWS CLI, and Tools for Windows PowerShell automatically get the credentials from the EC2 Instance Metadata Service (IMDS) and use them. The temporary credentials have the permissions that you define for the role that is associated with the instance. For more information and for examples, see the following: + [Using IAM Roles to Grant Access to AWS Resources on Amazon Elastic Compute Cloud](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/java-dg-roles.html) — AWS SDK for Java + [Granting Access Using an IAM Role](https://docs.aws.amazon.com/sdk-for-net/latest/developer-guide/net-dg-hosm.html) — AWS SDK for .NET + [Creating a Role](https://docs.aws.amazon.com/sdk-for-ruby/latest/developer-guide/iam-example-create-role.html) — AWS SDK for Ruby ## Using temporary security credentials with the AWS SDKs To use temporary security credentials in code, you programmatically call an AWS STS API like `AssumeRole` and extract the resulting credentials and session token. You then use those values as credentials for subsequent calls to AWS. The following example shows pseudocode for how to use temporary security credentials if you're using an AWS SDK: ``` assumeRoleResult = AssumeRole(role-arn); tempCredentials = new SessionAWSCredentials( assumeRoleResult.AccessKeyId, assumeRoleResult.SecretAccessKey, assumeRoleResult.SessionToken); s3Request = CreateAmazonS3Client(tempCredentials); ``` For an example written in Python (using the [AWS SDK for Python (Boto)](https://aws.amazon.com/sdk-for-python/)), see [Switch to an IAM role (AWS API)](id_roles_use_switch-role-api.md). This example shows how to call `AssumeRole` to get temporary security credentials and then use those credentials to make a call to Amazon S3. For details about how to call `AssumeRole`, `GetFederationToken`, and other API operations, see the [AWS Security Token Service API Reference](https://docs.aws.amazon.com/STS/latest/APIReference/). For information on getting the temporary security credentials and session token from the result, see the documentation for the SDK that you're working with. You can find the documentation for all the AWS SDKs on the main [AWS documentation page](http://aws.amazon.com/documentation), in the **SDKs and Toolkits** section. You must make sure that you get a new set of credentials before the old ones expire. In some SDKs, you can use a provider that manages the process of refreshing credentials for you; check the documentation for the SDK you're using. ## Using temporary security credentials with the AWS CLI You can use temporary security credentials with the AWS CLI. This can be useful for testing policies. Using the [AWS CLI](https://docs.aws.amazon.com/cli/latest/reference/), you can call an [AWS STS API](https://docs.aws.amazon.com/STS/latest/APIReference/) like `AssumeRole` or `GetFederationToken` and then capture the resulting output. The following example shows a call to `AssumeRole` that sends the output to a file. In the example, the `profile` parameter is assumed to be a profile in the AWS CLI configuration file. It is also assumed to reference credentials for an IAM user who has permissions to assume the role. ``` aws sts assume-role --role-arn arn:aws:iam::123456789012:role/role-name --role-session-name "RoleSession1" --profile IAM-user-name > assume-role-output.txt ``` When the command is finished, you can extract the access key ID, secret access key, and session token from wherever you've routed it. You can do this either manually or by using a script. You can then assign these values to environment variables. When you run AWS CLI commands, the AWS CLI looks for credentials in a specific order—first in environment variables and then in the configuration file. Therefore, after you've put the temporary credentials into environment variables, the AWS CLI uses those credentials by default. (If you specify a `profile` parameter in the command, the AWS CLI skips the environment variables. Instead, the AWS CLI looks in the configuration file, which lets you override the credentials in the environment variables if you need to.) The following example shows how you might set the environment variables for temporary security credentials and then call an AWS CLI command. Because no `profile` parameter is included in the AWS CLI command, the AWS CLI looks for credentials first in environment variables and therefore uses the temporary credentials. **Linux** ``` $ export AWS_ACCESS_KEY_ID=ASIAIOSFODNN7EXAMPLE $ export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY $ export AWS_SESSION_TOKEN=AQoDYXdzEJr... $ aws ec2 describe-instances --region us-west-1 ``` **Windows** ``` C:\> SET AWS_ACCESS_KEY_ID=ASIAIOSFODNN7EXAMPLE C:\> SET AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY C:\> SET AWS_SESSION_TOKEN=AQoDYXdzEJr... C:\> aws ec2 describe-instances --region us-west-1 ``` ## Using temporary security credentials with API operations If you're making direct HTTPS API requests to AWS, you can sign those requests with the temporary security credentials that you get from the AWS Security Token Service (AWS STS). To do this, you use the access key ID and secret access key that you receive from AWS STS. You use the access key ID and secret access key the same way you would use long-term credentials to sign a request. You also add to your API request the session token that you receive from AWS STS. You add the session token to an HTTP header or to a query string parameter named `X-Amz-Security-Token`. You add the session token to the HTTP header *or* the query string parameter, but not both. For more information about signing HTTPS API requests, see [Signing AWS API Requests](https://docs.aws.amazon.com/general/latest/gr/signing_aws_api_requests.html) in the *AWS General Reference*. ## More information For more information about using AWS STS with other AWS services, see the following links: + **Amazon S3**. See [Making requests using IAM user temporary credentials](https://docs.aws.amazon.com/AmazonS3/latest/userguide/AuthUsingTempSessionToken.html) or [Making requests using federated user temporary credentials](https://docs.aws.amazon.com/AmazonS3/latest/userguide/AuthUsingTempFederationToken.html) in the *Amazon Simple Storage Service User Guide*. + **Amazon SNS**. See [Using identity-based policies with Amazon SNS](https://docs.aws.amazon.com/sns/latest/dg/UsingIAMwithSNS.html#UsingTemporarySecurityCredentials_SNS) in the *Amazon Simple Notification Service Developer Guide*. + **Amazon SQS**. See [Identity and access management in Amazon SQS](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/UsingIAM.html#UsingTemporarySecurityCredentials_SQS) in the *Amazon Simple Queue Service Developer Guide*. + **Amazon SimpleDB**. See [Using Temporary Security Credentials](https://docs.aws.amazon.com/AmazonSimpleDB/latest/DeveloperGuide/index.html?UsingTemporarySecurityCredentials_SDB.html) in the *Amazon SimpleDB Developer Guide*. # Permissions for temporary security credentials You can use AWS Security Token Service (AWS STS) to create and provide trusted users with temporary security credentials that can control access to your AWS resources. For more information about AWS STS, see [Temporary security credentials in IAM](id_credentials_temp.md). After AWS STS issues temporary security credentials, they are valid through the expiration period and cannot be revoked. However, the permissions assigned to temporary security credentials are evaluated each time a request is made that uses the credentials, so you can achieve the effect of revoking the credentials by changing their access rights after they have been issued. The following topics assume you have a working knowledge of AWS permissions and policies. For more information on these topics, see [Access management for AWS resources](access.md). **Topics** + [ # Permissions for AssumeRole, AssumeRoleWithSAML, and AssumeRoleWithWebIdentity ](id_credentials_temp_control-access_assumerole.md) + [ # Monitor and control actions taken with assumed roles ](id_credentials_temp_control-access_monitor.md) + [ # Permissions for GetFederationToken ](id_credentials_temp_control-access_getfederationtoken.md) + [ # Permissions for GetSessionToken ](id_credentials_temp_control-access_getsessiontoken.md) + [ # Disabling permissions for temporary security credentials ](id_credentials_temp_control-access_disable-perms.md) + [ # Granting permissions to create temporary security credentials ](id_credentials_temp_control-access_enable-create.md) + [ # Granting permissions to use identity-enhanced console sessions ](id_credentials_temp_control-access_sts-setcontext.md) # Permissions for AssumeRole, AssumeRoleWithSAML, and AssumeRoleWithWebIdentity Permissions for AssumeRole API operations The permissions policy of the role that is being assumed determines the permissions for the temporary security credentials that are returned by `AssumeRole`, `AssumeRoleWithSAML`, and `AssumeRoleWithWebIdentity`. You define these permissions when you create or update the role. Optionally, you can pass inline or managed [session policies](access_policies.md#policies_session) as parameters of the `AssumeRole`, `AssumeRoleWithSAML`, or `AssumeRoleWithWebIdentity` API operations. Session policies limit the permissions for the role's temporary credential session. The resulting session's permissions are the intersection of the role's identity-based policy and the session policies. You can use the role's temporary credentials in subsequent AWS API calls to access resources in the account that owns the role. You cannot use session policies to grant more permissions than those allowed by the identity-based policy of the role that is being assumed. To learn more about how AWS determines the effective permissions of a role, see [Policy evaluation logic](reference_policies_evaluation-logic.md). ![\[PermissionsWhenPassingRoles_Diagram\]](http://docs.aws.amazon.com/IAM/latest/UserGuide/images/role_passed_policy_permissions.png) The policies that are attached to the credentials that made the original call to `AssumeRole` are not evaluated by AWS when making the "allow" or "deny" authorization decision. The user temporarily gives up its original permissions in favor of the permissions assigned by the assumed role. In the case of the `AssumeRoleWithSAML` and `AssumeRoleWithWebIdentity` API operations, there are no policies to evaluate because the caller of the API is not an AWS identity. ## Example: Assigning permissions using AssumeRole You can use the `AssumeRole` API operation with different kinds of policies. Here are a few examples. ### Role permissions policy In this example, you call the `AssumeRole` API operation without specifying the session policy in the optional `Policy` parameter. The permissions assigned to the temporary credentials are determined by the permissions policy of the role being assumed. The following example permissions policy grants the role permission to list all objects that are contained in an S3 bucket named `productionapp`. It also allows the role to get, put, and delete objects within that bucket. **Example role permissions policy** **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "s3:ListBucket", "Resource": "arn:aws:s3:::productionapp" }, { "Effect": "Allow", "Action": [ "s3:GetObject", "s3:PutObject", "s3:DeleteObject" ], "Resource": "arn:aws:s3:::productionapp/*" } ] } ``` ### Session policy passed as a parameter Imagine that you want to allow a user to assume the same role as in the previous example. But in this case you want the role session to have permission only to get and put objects in the `productionapp` S3 bucket. You do not want to allow them to delete objects. One way to accomplish this is to create a new role and specify the desired permissions in that role's permissions policy. Another way to accomplish this is to call the `AssumeRole` API and include session policies in the optional `Policy` parameter as part of the API operation. The resulting session's permissions are the intersection of the role's identity-based policies and the session policies. Session policies cannot be used to grant more permissions than those allowed by the identity-based policy of the role that is being assumed. For more information about role session permissions, see [Session policies](access_policies.md#policies_session). After you retrieve the new session's temporary credentials, you can pass them to the user that you want to have those permissions. For example, imagine that the following policy is passed as a parameter of the API call. The person using the session has permissions to perform only these actions: + List all objects in the `productionapp` bucket. + Get and put objects in the `productionapp` bucket. In the following session policy, the `s3:DeleteObject` permission is filtered out and the assumed session is not granted the `s3:DeleteObject` permission. The policy sets the maximum permissions for the role session so that it overrides any existing permissions policies on the role. **Example session policy passed with `AssumeRole` API call** **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "s3:ListBucket", "Resource": "arn:aws:s3:::productionapp" }, { "Effect": "Allow", "Action": [ "s3:GetObject", "s3:PutObject" ], "Resource": "arn:aws:s3:::productionapp/*" } ] } ``` ### Resource-based policy Some AWS resources support resource-based policies, and these policies provide another mechanism to define permissions that affect temporary security credentials. Only a few resources, like Amazon S3 buckets, Amazon SNS topics, and Amazon SQS queues support resource-based policies. The following example expands on the previous examples, using an S3 bucket named `productionapp`. The following policy is attached to the bucket. When you attach the following resource-based policy to the `productionapp` bucket, *all* users are denied permission to delete objects from the bucket. (See the `Principal` element in the policy.) This includes all assumed role users, even though the role permissions policy grants the `DeleteObject` permission. An explicit `Deny` statement always takes precedence over an `Allow` statement. **Example bucket policy** **** ``` { "Version":"2012-10-17", "Statement": { "Principal": {"AWS": "*"}, "Effect": "Deny", "Action": "s3:DeleteObject", "Resource": "arn:aws:s3:::productionapp/*" } } ``` For more information about how multiple policy types are combined and evaluated by AWS, see [Policy evaluation logic](reference_policies_evaluation-logic.md). # Monitor and control actions taken with assumed roles Monitor and control actions taken with assumed roles An [IAM role](id_roles.md) is an object in IAM that is assigned [permissions](access_policies.md). When you [assume that role](id_roles_manage-assume.md) using an IAM identity or an identity from outside of AWS, you receive a session with the permissions that are assigned to the role. When you perform actions in AWS, the information about your session can be logged to AWS CloudTrail for your account administrator to monitor. Administrators can configure roles to require identities to pass a custom string that identifies the person or application that is performing actions in AWS. This identity information is stored as the *source identity* in AWS CloudTrail. When the administrator reviews activity in CloudTrail, they can view the source identity information to determine who or what performed actions with assumed role sessions. After a source identity is set, it is present in requests for any AWS action taken during the role session. The value that is set persists when a role is used to assume another role through the AWS CLI or AWS API, known as [role chaining](id_roles.md#iam-term-role-chaining). The value that is set cannot be changed during the role session. Administrators can configure granular permissions based on the presence or value of the source identity to further control AWS actions that are taken with shared roles. You can decide whether the source identity attribute can be used, whether it is required, and what value can be used. The way that you use source identity differs from role session name and session tags in an important way. The source identity value can't be changed after it is set, and it persists for any additional actions that are taken with the role session. Here's how you can use session tags and role session name: + **Session tags** – You can pass session tags when you assume a role or federate a user. Session tags are present when a role is assumed. You can define policies that use tag condition keys to grant permissions to your principals based on their tags. Then you can use CloudTrail to view the requests made to assume roles or federate users. To learn more about session tags, see [Pass session tags in AWS STS](id_session-tags.md). + **Role session name** – You can use the `sts:RoleSessionName` condition key in a role trust policy to require that your users provide a specific session name when they assume a role. Role session name can be used to differentiate role sessions when a role is used by different principals. To learn more about role session name, see [sts:RoleSessionName](reference_policies_iam-condition-keys.md#ck_rolesessionname). We recommend that you use source identity when you want to control the identity that assumes a role. Source identity is also useful for mining CloudTrail logs to determine who used the role to perform actions. **Topics** + [ ## Setting up to use source identity ](#id_credentials_temp_control-access_monitor-setup) + [ ## Things to know about source identity ](#id_credentials_temp_control-access_monitor-know) + [ ## Permissions required to set source identity ](#id_credentials_temp_control-access_monitor-perms) + [ ## Specifying a source identity when assuming a role ](#id_credentials_temp_control-access_monitor-specify-sourceid) + [ ## Using source identity with AssumeRole ](#id_credentials_temp_control-access_monitor-assume-role) + [ ## Using source identity with AssumeRoleWithSAML ](#id_credentials_temp_control-access_monitor-assume-role-saml) + [ ## Using source identity with AssumeRoleWithWebIdentity ](#id_credentials_temp_control-access_monitor-assume-role-web-id) + [ ## Control access using source identity information ](#id_credentials_temp_control-access_monitor-control-access) + [ ## Viewing source identity in CloudTrail ](#id_credentials_temp_control-access_monitor-ct) ## Setting up to use source identity Setting up The way that you set up to use source identity depends on the method used when your roles are assumed. For example, your IAM users might assume roles directly using the `AssumeRole` operation. If you have enterprise identities, also known as workforce identities, they might access your AWS resources using `AssumeRoleWithSAML`. If end users access your mobile or web applications, they might do so using `AssumeRoleWithWebIdentity`. The following is a high-level workflow overview to help you understand how you can set up to utilize source identity information in your existing environment. 1. **Configure test users and roles** – Using a preproduction environment, configure test users and roles and configure their policies to allow setting a source identity. If you use an identity provider (IdP) for your federated identities, configure your IdP to pass a user attribute of your choice for source identity in the assertion or token. 1. **Assume the role** – Test assuming roles and passing a source identity with the users and roles that you set up for testing. 1. **Review CloudTrail** – Review the source identity information for your test roles in your CloudTrail logs. 1. **Train your users** – After you've tested in your preproduction environment, ensure that your users know how to pass in the source identity information, if necessary. Set a deadline for when you will require your users to provide a source identity in your production environment. 1. **Configure production policies** – Configure your policies for your production environment, and then add them to your production users and roles. 1. **Monitor activity** – Monitor your production role activity using CloudTrail logs. ## Things to know about source identity Things to know Keep the following in mind when working with source identity. + Trust policies for all roles connected to an identity provider (IdP) must have the `sts:SetSourceIdentity` permission. For roles that don't have this permission in the role trust policy, the `AssumeRole*` operation will fail. If you don't want to update the role trust policy for each role, you can use a separate IdP instance for passing source identity. Then add the `sts:SetSourceIdentity` permission to only the roles that are connected to the separate IdP. + When an identity sets a source identity, the `sts:SourceIdentity` key is present in the request. For subsequent actions taken during the role session, the `aws:SourceIdentity` key is present in the request. AWS doesn’t control the value of the source identity in either the `sts:SourceIdentity` or `aws:SourceIdentity` keys. If you choose to require a source identity, you must choose an attribute that you want your users or IdP to provide. For security purposes, you must ensure that you can control how those values are provided. + The value of source identity must be between 2 and 64 characters long, can contain only alphanumeric characters, underscores, and the following characters: **. , \$1 = @ -** (hyphen). You cannot use a value that begins with the text **aws:**. This prefix is reserved for AWS internal use. + The source identity information is not captured by CloudTrail when an AWS service or service-linked role carries out an action on behalf of a federated or workforce identity. **Important** You cannot switch to a role in the AWS Management Console that requires a source identity to be set when the role is assumed. To assume such a role, you can use the AWS CLI or AWS API to call the `AssumeRole` operation and specify the source identity parameter. ## Permissions required to set source identity Permissions required to set source identity In addition to the action that matches the API operation, you must have the following permissions-only action in your policy: ``` sts:SetSourceIdentity ``` + To specify a source identity, principals (IAM users and roles) must have permissions to `sts:SetSourceIdentity`. As the administrator, you can configure this in the role trust policy and in the principal’s permissions policy. + When you assume a role with another role, called [role chaining](id_roles.md#iam-term-role-chaining), permissions for `sts:SetSourceIdentity` are required in both the permissions policy of the principal who is assuming the role and in the role trust policy of the target role. Otherwise, the assume role operation will fail. + When using source identity, the role trust policies for all roles connected to an IdP must have the `sts:SetSourceIdentity` permission. The `AssumeRole*` operation will fail for any role connected to an IdP without this permission. If you don't want to update the role trust policy for each role, you can use a separate IdP instance for passing source identity and add the `sts:SetSourceIdentity` permission to only the roles that are connected to the separate IdP. + To set a source identity across account boundaries, you must include the `sts:SetSourceIdentity` permission in two places. It must be in the permissions policy of the principal in the originating account and in the role trust policy of the role in the target account. You might need to do this, for example, when a role is used to assume a role in another account with [role chaining](id_roles.md#iam-term-role-chaining). As the account administrator, imagine that you want to allow the IAM user `DevUser` in your account to assume the `Developer_Role` in the same account. But you want to allow this action only if the user has set the source identity to their IAM user name. You can attach the following policy to the IAM user. **Example identity-based policy attached to DevUser** **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AssumeRole", "Effect": "Allow", "Action": "sts:AssumeRole", "Resource": "arn:aws:iam::123456789012:role/Developer_Role" }, { "Sid": "SetAwsUserNameAsSourceIdentity", "Effect": "Allow", "Action": "sts:SetSourceIdentity", "Resource": "arn:aws:iam::123456789012:role/Developer_Role", "Condition": { "StringLike": { "sts:SourceIdentity": "${aws:username}" } } } ] } ``` To enforce the acceptable source identity values, you can configure the following role trust policy. The policy gives the IAM user `DevUser` permissions to assume the role and set a source identity. The `sts:SourceIdentity` condition key defines the acceptable source identity value. **Example role trust policy for source identity** ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AllowDevUserAssumeRole", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::123456789012:user/DevUser" }, "Action": [ "sts:AssumeRole", "sts:SetSourceIdentity" ], "Condition": { "StringEquals": { "sts:SourceIdentity": "DevUser" } } } ] } ``` ------ Using the credentials for the IAM user `DevUser`, the user attempts to assume the `DeveloperRole` using the following AWS CLI request. **Example AssumeRole CLI request** ``` aws sts assume-role \ --role-arn arn:aws:iam::123456789012:role/Developer_Role \ --role-session-name Dev-project \ --source-identity DevUser \ ``` When AWS evaluates the request, the request context contains the `sts:SourceIdentity` of `DevUser`. ## Specifying a source identity when assuming a role You can specify a source identity when you use one of the AWS STS `AssumeRole*` API operations to get temporary security credentials for a role. The API operation that you use differs depending on your use case. For example, if you use IAM roles to give IAM users access to AWS resources that they don’t normally have access to, you might use the `AssumeRole` operation. If you use enterprise identity federation to manage your workforce users, you might use the `AssumeRoleWithSAML` operation. If you use OIDC federation to allow end users to access your mobile or web applications, you might use the `AssumeRoleWithWebIdentity` operation. The following sections explain how to use source identity with each operation. To learn more about common scenarios for temporary credentials, see [Common scenarios for temporary credentials](id_credentials_temp.md#sts-introduction). ## Using source identity with AssumeRole AssumeRole The `AssumeRole` operation returns a set of temporary credentials that you can use to access AWS resources. You can use IAM user or role credentials to call `AssumeRole`. To pass source identity while assuming a role, use the `-–source-identity` AWS CLI option or the `SourceIdentity` AWS API parameter. The following example shows how to specify the source identity using the AWS CLI. **Example AssumeRole CLI request** ``` aws sts assume-role \ --role-arn arn:aws:iam::123456789012:role/developer \ --role-session-name Audit \ --source-identity Admin \ ``` ## Using source identity with AssumeRoleWithSAML AssumeRoleWithSAML The principal calling the `AssumeRoleWithSAML` operation is authenticated using SAML-based federation. This operation returns a set of temporary credentials that you can use to access AWS resources. For more information about using SAML-based federation for AWS Management Console access, see [Enabling SAML 2.0 federated principals to access the AWS Management Console](id_roles_providers_enable-console-saml.md). For details about AWS CLI or AWS API access, see [SAML 2.0 federation](id_roles_providers_saml.md). For a tutorial of setting up SAML federation for your Active Directory users, see [AWS Federated Authentication with Active Directory Federation Services (ADFS)](https://aws.amazon.com/blogs/security/aws-federated-authentication-with-active-directory-federation-services-ad-fs/) in the AWS Security Blog. As an administrator, you can allow members of your company directory to federate into AWS using the AWS STS `AssumeRoleWithSAML` operation. To do this, you must complete the following tasks: 1. [Configure a SAML provider in your organization](id_roles_providers_saml_3rd-party.md). 1. [Create a SAML provider in IAM](id_roles_providers_create_saml.md). 1. [Configure a role and its permissions in AWS for your SAML federated principals](id_roles_create_for-idp_saml.md). 1. [Finish configuring the SAML IdP and create assertions for the SAML authentication response](id_roles_providers_create_saml_assertions.md). To set a SAML attribute for source identity, include the `Attribute` element with the `Name` attribute set to `https://aws.amazon.com/SAML/Attributes/SourceIdentity`. Use the `AttributeValue` element to specify the value of the source identity. For example, assume that you want to pass the following identity attribute as the source identity. `SourceIdentity:DiegoRamirez` To pass this attribute, include the following element in your SAML assertion. **Example snippet of a SAML assertion** ``` DiegoRamirez ``` ## Using source identity with AssumeRoleWithWebIdentity AssumeRoleWithWebIdentity The principal calling the `AssumeRoleWithWebIdentity` operation is authenticated using OpenID Connect (OIDC)-compliant federation. This operation returns a set of temporary credentials that you can use to access AWS resources. For more information about using OIDC federation for AWS Management Console access, see [OIDC federation](id_roles_providers_oidc.md). To pass source identity from OpenID Connect (OIDC), you must include the source identity in the JSON Web Token (JWT). Include source identity in the `[https://aws.amazon.com/](https://aws.amazon.com/)source_identity` namespace in the token when you submit the `AssumeRoleWithWebIdentity` request. To learn more about OIDC tokens and claims, see [Using Tokens with User Pools](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html) in the *Amazon Cognito Developer Guide*. For example, the following decoded JWT is a token that is used to call `AssumeRoleWithWebIdentity` with the `Admin` source identity. **Example decoded JSON Web Token** ``` { "sub": "john", "aud": "ac_oic_client", "jti": "ZYUCeRMQVtqHypVPWAN3VB", "iss": "https://xyz.com", "iat": 1566583294, "exp": 1566583354, "auth_time": 1566583292, "https://aws.amazon.com/source_identity":"Admin" } ``` ## Control access using source identity information Control access using source identity When a source identity is initially set, the [sts:SourceIdentity](reference_policies_iam-condition-keys.md#ck_sourceidentity) key is present in the request. After a source identity is set, the [aws:SourceIdentity](reference_policies_condition-keys.md#condition-keys-sourceidentity) key is present in all subsequent requests made during the role session. As the administrator, you can write policies that grant conditional authorization to perform AWS actions based on the existence or value of the source identity attribute. Imagine that you want to require your developers to set a source identity to assume a critical role that has permission to write to a production critical AWS resource. Also imagine that you grant AWS access to your workforce identities using `AssumeRoleWithSAML`. You only want senior developers Saanvi and Diego to have access to the role, so you create the following trust policy for the role. **Example role trust policy for source identity (SAML)** ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "SAMLProviderAssumeRoleWithSAML", "Effect": "Allow", "Principal": { "Federated": "arn:aws:iam::111122223333:saml-provider/name-of-identity-provider" }, "Action": [ "sts:AssumeRoleWithSAML" ], "Condition": { "StringEquals": { "SAML:aud": "https://signin.aws.amazon.com/saml" } } }, { "Sid": "SetSourceIdentitySrEngs", "Effect": "Allow", "Principal": { "Federated": "arn:aws:iam::111122223333:saml-provider/name-of-identity-provider" }, "Action": [ "sts:SetSourceIdentity" ], "Condition": { "StringLike": { "sts:SourceIdentity": [ "Saanvi", "Diego" ] } } } ] } ``` ------ The trust policy contains a condition for `sts:SourceIdentity` that requires a source identity of Saanvi or Diego to assume the critical role. Alternatively, if you use an OIDC provider for federation and users are authenticated with `AssumeRoleWithWebIdentity`, your role trust policy might look as follows. **Example role trust policy for source identity (OIDC provider)** ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Federated": "arn:aws:iam::111122223333:oidc-provider/server.example.com" }, "Action": [ "sts:AssumeRoleWithWebIdentity", "sts:SetSourceIdentity" ], "Condition": { "StringEquals": { "server.example.com:aud": "oidc-audience-id" }, "StringLike": { "sts:SourceIdentity": [ "Saanvi", "Diego" ] } } } ] } ``` ------ ### Role chaining and cross-account requirements Imagine that you want to allow users who have assumed `CriticalRole` to assume a `CriticalRole_2` in another account. The role session credentials that were obtained to assume `CriticalRole` are used to [role chain](id_roles.md#iam-term-role-chaining) to a second role, `CriticalRole_2`, in a different account. The role is being assumed across an account boundary. Therefore, the `sts:SetSourceIdentity` permission must be granted in both the permissions policy on `CriticalRole` and in the role trust policy on `CriticalRole_2`. **Example permissions policy on CriticalRole** ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AssumeRoleAndSetSourceIdentity", "Effect": "Allow", "Action": [ "sts:AssumeRole", "sts:SetSourceIdentity" ], "Resource": "arn:aws:iam::222222222222:role/CriticalRole_2" } ] } ``` ------ To secure setting source identity across the account boundary, the following role trust policy trusts only the role principal for `CriticalRole` to set the source identity. **Example role trust policy on CriticalRole\$12** ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111111111111:role/CriticalRole" }, "Action": [ "sts:AssumeRole", "sts:SetSourceIdentity" ], "Condition": { "StringLike": { "aws:SourceIdentity": ["Saanvi","Diego"] } } } ] } ``` ------ The user makes the following call using role session credentials obtained from assuming CriticalRole. The source identity was set during the assumption of CriticalRole, so it does not need to be explicitly set again. If the user attempts to set a source identity that is different from the value set when `CriticalRole` was assumed, the assume role request will be denied. **Example AssumeRole CLI request** ``` aws sts assume-role \ --role-arn arn:aws:iam::222222222222:role/CriticalRole_2 \ --role-session-name Audit \ ``` When the calling principal assumes the role, the source identity in the request persists from the first assumed role session. Therefore, both the `aws:SourceIdentity` and `sts:SourceIdentity` keys are present in the request context. ## Viewing source identity in CloudTrail Viewing source identity in AWS CloudTrail You can use CloudTrail to view the requests made to assume roles or federate users. You can also view the role or user requests to take actions in AWS. The CloudTrail log file includes information about the source identity set for the assumed-role or federated user session. For more information, see [Logging IAM and AWS STS API calls with AWS CloudTrail](cloudtrail-integration.md) For example, assume that a user makes an AWS STS `AssumeRole` request, and sets a source identity. You can find the `sourceIdentity` information in the `requestParameters` key in your CloudTrail log. **Example requestParameters section in an AWS CloudTrail log** ``` "eventVersion": "1.05", "userIdentity": { "type": "AWSAccount", "principalId": "AIDAJ45Q7YFFAREXAMPLE", "accountId": "111122223333" }, "eventTime": "2020-04-02T18:20:53Z", "eventSource": "sts.amazonaws.com", "eventName": "AssumeRole", "awsRegion": "us-east-1", "sourceIPAddress": "203.0.113.64", "userAgent": "aws-cli/1.16.96 Python/3.6.0 Windows/10 botocore/1.12.86", "requestParameters": { "roleArn": "arn:aws:iam::123456789012:role/DevRole", "roleSessionName": "Dev1", "sourceIdentity": "source-identity-value-set" } ``` If the user uses the assumed role session to perform an action, the source identity information is present in the `userIdentity` key in the CloudTrail log. **Example userIdentity key in an AWS CloudTrail log** ``` { "eventVersion": "1.08", "userIdentity": { "type": "AssumedRole", "principalId": "AROAJ45Q7YFFAREXAMPLE:Dev1", "arn": "arn:aws:sts::123456789012:assumed-role/DevRole/Dev1", "accountId": "123456789012", "accessKeyId": "ASIAIOSFODNN7EXAMPLE", "sessionContext": { "sessionIssuer": { "type": "Role", "principalId": "AROAJ45Q7YFFAREXAMPLE", "arn": "arn:aws:iam::123456789012:role/DevRole", "accountId": "123456789012", "userName": "DevRole" }, "webIdFederationData": {}, "attributes": { "mfaAuthenticated": "false", "creationDate": "2021-02-21T23:46:28Z" }, "sourceIdentity": "source-identity-value-present" } } } ``` To see example AWS STS API events in CloudTrail logs, see [Example IAM API events in CloudTrail log](cloudtrail-integration.md#cloudtrail-integration_examples-iam-api). For more details about the information contained in CloudTrail log files, see [CloudTrail Event Reference](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/eventreference.html) in the *AWS CloudTrail User Guide*. # Permissions for GetFederationToken The `GetFederationToken` operation is called by an IAM user and returns temporary credentials for that user. This operation *federates* the user. The permissions assigned to an AWS STS federated user session are defined in one of two places: + The session policies passed as a parameter of the `GetFederationToken` API call. (This is most common.) + A resource-based policy that explicitly names the AWS STS federated user session in the `Principal` element of the policy. (This is less common.) Session policies are advanced policies that you pass as parameters when you programmatically create a temporary session. When you create an AWS STS federated user session and pass session policies, the resulting session's permissions are the intersection of the user's identity-based policy and the session policies. You cannot use the session policy to grant more permissions than those allowed by the identity-based policy of the user that is being federated. In most cases if you do not pass a policy with the `GetFederationToken` API call, the resulting temporary security credentials have no permissions. However, a resource-based policy can provide additional permissions for the session. You can access a resource with a resource-based policy that specifies your session as the allowed principal. The following figures show a visual representation of how the policies interact to determine permissions for the temporary security credentials returned by a call to `GetFederationToken`. ![\[IAM userThe following illustrations show check marks to indicate that session permissions are the intersection of the user's identity-based policy and the session policies. Session permissions can also be the intersection of the user's identity-based policy and resource-based policies.\]](http://docs.aws.amazon.com/IAM/latest/UserGuide/images/getfederationtoken-permissions.diagram.png) ## Example: Assigning permissions using GetFederationToken You can use the `GetFederationToken` API action with different kinds of policies. Here are a few examples. ### Policy attached to the IAM user In this example, you have a browser-based client application that relies on two backend web services. One backend service is your own authentication server that uses your own identity system to authenticate the client application. The other backend service is an AWS service that provides some of the client application's functionality. The client application is authenticated by your server, and your server creates or retrieves the appropriate permissions policy. Your server then calls the `GetFederationToken` API to obtain temporary security credentials, and returns those credentials to the client application. The client application can then make requests directly to the AWS service with the temporary security credentials. This architecture allows the client application to make AWS requests without embedding long-term AWS credentials. Your authentication server calls the `GetFederationToken` API with the long-term security credentials of an IAM user named `token-app`. But the long-term IAM user credentials remain on your server and are never distributed to the client. The following example policy is attached to the `token-app` IAM user and defines the broadest set of permissions that your AWS STS federated users (clients) will need. Note that the `sts:GetFederationToken` permission is required for your authentication service to obtain temporary security credentials for the AWS STS federated users. **Example policy attached to IAM user `token-app` that calls `GetFederationToken`** **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "sts:GetFederationToken", "Resource": "*" }, { "Effect": "Allow", "Action": "dynamodb:ListTables", "Resource": "*" }, { "Effect": "Allow", "Action": "sqs:ReceiveMessage", "Resource": "*" }, { "Effect": "Allow", "Action": "s3:ListBucket", "Resource": "*" }, { "Effect": "Allow", "Action": "sns:ListSubscriptions", "Resource": "*" } ] } ``` The preceding policy grants several permissions to the IAM user. However, this policy alone doesn't grant any permissions to the AWS STS federated user. If this IAM user calls `GetFederationToken` and does not pass a policy as a parameter of the API call, the resulting AWS STS federated user has no effective permissions. ### Session policy passed as parameter The most common way to ensure that the AWS STS federated user is assigned appropriate permission is to pass session policies in the `GetFederationToken` API call. Expanding on the previous example, imagine that `GetFederationToken` is called with the credentials of the IAM user `token-app`. Then imagine that the following session policy is passed as a parameter of the API call. The resulting AWS STS federated user has permission to list the contents of the Amazon S3 bucket named `productionapp`. The user can't perform the Amazon S3 `GetObject`, `PutObject`, and `DeleteObject` actions on items in the `productionapp` bucket. The federated user is assigned these permissions because the permissions are the intersection of the IAM user policies and the session policies that you pass. The AWS STS federated user could not perform actions in Amazon SNS, Amazon SQS, Amazon DynamoDB, or in any S3 bucket except `productionapp`. These actions are denied even though those permissions are granted to the IAM user that is associated with the `GetFederationToken` call. **Example session policy passed as parameter of `GetFederationToken` API call** **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": ["s3:ListBucket"], "Resource": ["arn:aws:s3:::productionapp"] }, { "Effect": "Allow", "Action": [ "s3:GetObject", "s3:PutObject", "s3:DeleteObject" ], "Resource": ["arn:aws:s3:::productionapp/*"] } ] } ``` ### Resource-based policies Some AWS resources support resource-based policies, and these policies provide another mechanism to grant permissions directly to an AWS STS federated user. Only some AWS services support resource-based policies. For example, Amazon S3 has buckets, Amazon SNS has topics, and Amazon SQS has queues that you can attach policies to. For a list of all services that support resource-based policies, see [AWS services that work with IAM](reference_aws-services-that-work-with-iam.md) and review the "Resource-based policies" column of the tables. You can use resource-based policies to assign permissions directly to an AWS STS federated user. Do this by specifying the Amazon Resource Name (ARN) of the AWS STS federated user in the `Principal` element of the resource-based policy. The following example illustrates this and expands on the previous examples, using an S3 bucket named `productionapp`. The following resource-based policy is attached to the bucket. This bucket policy allows an AWS STS federated user named Carol to access the bucket. When the example policy described earlier is attached to the `token-app` IAM user, the AWS STS federated user named Carol has permission to perform the `s3:GetObject`, `s3:PutObject`, and `s3:DeleteObject` actions on the bucket named `productionapp`. This is true even when no session policy is passed as a parameter of the `GetFederationToken` API call. That's because in this case the AWS STS federated user named Carol has been explicitly granted permissions by the following resource-based policy. Remember, an AWS STS federated user is granted permissions only when those permissions are explicitly granted to both the IAM user ***and*** the AWS STS federated user. They can also be granted (within the account) by a resource-based policy that explicitly names the AWS STS federated user in the `Principal` element of the policy, as in the following example. **Example bucket policy that allows access to federated user** **** ``` { "Version":"2012-10-17", "Statement": { "Principal": { "AWS": "arn:aws:sts::111122223333:federated-user/Carol" }, "Effect": "Allow", "Action": [ "s3:GetObject", "s3:PutObject", "s3:DeleteObject" ], "Resource": [ "arn:aws:s3:::productionapp/*" ] } } ``` For more information about how policies are evaluated see [Policy evaluation logic](reference_policies_evaluation-logic.md). # Permissions for GetSessionToken The primary occasion for calling the `GetSessionToken` API operation or the `get-session-token` CLI command is when a user must be authenticated with multi-factor authentication (MFA). It is possible to write a policy that allows certain actions only when those actions are requested by a user who has been authenticated with MFA. In order to successfully pass the MFA authorization check, a user must first call `GetSessionToken` and include the optional `SerialNumber` and `TokenCode` parameters. If the user is successfully authenticated with an MFA device, the credentials returned by the `GetSessionToken` API operation include the MFA context. This context indicates that the user is authenticated with MFA and is authorized for API operations that require MFA authentication. ## Permissions required for GetSessionToken No permissions are required for a user to get a session token. The purpose of the `GetSessionToken` operation is to authenticate the user using MFA. You cannot use policies to control authentication operations. To grant permissions to perform most AWS operations, you add the action with the same name to a policy. For example, to create a user, you must use the `CreateUser` API operation, the `create-user` CLI command, or the AWS Management Console. To perform these operations, you must have a policy that allows you to access the `CreateUser` action. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "iam:CreateUser", "Resource": "*" } ] } ``` ------ You can include the `GetSessionToken` action in your policies, but it has no effect on a user's ability to perform the `GetSessionToken` operation. ## Permissions granted by GetSessionToken If `GetSessionToken` is called with the credentials of an IAM user, the temporary security credentials have the same permissions as the IAM user. Similarly, if `GetSessionToken` is called with AWS account root user credentials, the temporary security credentials have root user permissions. **Note** We recommend that you do not call `GetSessionToken` with root user credentials. Instead, follow our [best practices](best-practices-use-cases.md) and create IAM users with the permissions they need. Then use these IAM users for everyday interaction with AWS. The temporary credentials that you get when you call `GetSessionToken` have the following capabilities and limitations: + You can use the credentials to access the AWS Management Console by passing the credentials to the federation single sign-on endpoint at `https://signin.aws.amazon.com/federation`. For more information, see [Enable custom identity broker access to the AWS console](id_roles_providers_enable-console-custom-url.md). + You **cannot** use the credentials to call IAM or AWS STS API operations. You **can** use them to call API operations for other AWS services. Compare this API operation and its limitations and capability with the other API operations that create temporary security credentials at [Compare AWS STS credentials](id_credentials_sts-comparison.md) For more information about MFA-protected API access using `GetSessionToken`, see [Secure API access with MFA](id_credentials_mfa_configure-api-require.md). # Disabling permissions for temporary security credentials Disabling permissions Temporary security credentials are valid until they expire. These credentials are valid for the specified duration, from 900 seconds (15 minutes) up to a maximum of 129,600 seconds (36 hours). The default session duration is 43,200 seconds (12 hours). You can revoke these credentials, but you must also change permissions for the IAM user or role to stop the use of compromised credentials for malicious account activity. Permissions assigned to temporary security credentials are evaluated each time they are used to make an AWS request. Once you remove all permissions from the credentials, AWS requests that use them fail. It might take a few minutes for policy updates to take effect. For IAM role sessions, you can revoke the role’s temporary security credentials to force all users assuming the role to reauthenticate and request new credentials. For more information, see [Revoke the role’s temporary security credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_revoke-sessions.html). You cannot change the permissions for an AWS account root user. Likewise, you cannot change the permissions for the temporary security credentials that were created by calling `GetFederationToken` or `GetSessionToken` while signed in as the root user. For this reason, we recommend that you do not call `GetFederationToken` or `GetSessionToken` as a root user. For procedures on how to change the permissions for an IAM user, see [Change permissions for an IAM user](id_users_change-permissions.md). For procedures on how to change the permissions for an IAM role, see [Update permissions for a role](id_roles_update-role-permissions.md). **Important** You can't edit roles in IAM that were created from IAM Identity Center permission sets. You must revoke the active permission set session for a user in IAM Identity Center. For more information, see [Revoke active IAM role sessions created by permission sets](https://docs.aws.amazon.com/singlesignon/latest/userguide/useraccess.html#revoke-user-permissions) in the *IAM Identity Center User Guide*. **Topics** + [ ## Deny access to all IAM role sessions associated with a role ](#deny-access-to-all-sessions) + [ ## Deny access to a specific IAM role session ](#deny-access-to-specific-session) + [ ## Deny access to temporary security credentials sessions with condition context keys ](#deny-access-to-specific-session-condition-key) + [ ## Deny access to a specific principal with resource-based policies ](#deny-access-with-resource-based) ## Deny access to all IAM role sessions associated with a role This procedure denies permissions to **all** IAM role sessions associated with a role. Use this approach when you are concerned about suspicious access by: + Principals from another account using cross-account access + External user identities with permissions to access AWS resources in your account + Users who have been authenticated in a mobile or web application with an OIDC provider To change or remove the permissions assigned to the temporary security credentials obtained by calling `AssumeRole`, `AssumeRoleWithSAML`, or `AssumeRoleWithWebIdentity`, `GetFederationToken`, or `GetSessionToken`, you can edit or delete the identity-based policy that defines the permissions for the role. **Important** If there's a resource-based policy that allows the principal access, you must also add an explicit deny for that resource. See [Deny access to a specific principal with resource-based policies](#deny-access-with-resource-based) for details. **To deny access to **all** IAM role sessions associated with a role** 1. Sign in to the AWS Management Console and open the IAM console. 1. In the navigation pane, choose **Roles**.. 1. Choose the name of the role to edit. You can use the search box to filter the list. 1. Choose the **Permissions** tab. 1. Select the relevant policy to edit. Before you edit a customer managed policy, review the **Entities attached** tab to avoid disrupting access to other identities that may have the same policy attached. 1. Choose the **JSON** tab and update the policy to deny all resources and actions. **Note** These permissions are the same as those in the AWS managed policy [AWSDenyAll](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSDenyAll.html). You can attach this AWS managed policy to any IAM user or role you want to deny all access to. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "DenyAll", "Effect": "Deny", "Action": [ "*" ], "Resource": "*" } ] } ``` ------ 1. On the **Review** page, review the policy **Summary** and then choose **Save changes** to save your work. When you update the policy, the changes affect the permissions of all temporary security credentials associated with the role, including credentials that were issued before you changed the role's permissions policy. After you update the policy, you can [revoke the role’s temporary security credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_revoke-sessions.html) to immediately revoke all permissions to the role's issued credentials. ## Deny access to a specific IAM role session When you update IAM roles with a deny-all policy or delete the role entirely, all users that have access to the role are disrupted. You can deny access without impacting the permissions of all other sessions associated with the role. The `Principal` can be denied permissions using [condition context keys](#deny-access-to-specific-session-condition-key) or [resource-based policies](#deny-access-with-resource-based). **Tip** You can find the ARNs of federated users using AWS CloudTrail logs. For more information, see [How to Easily Identify Your Federated Users by Using AWS CloudTrail](https://aws.amazon.com/blogs/security/how-to-easily-identify-your-federated-users-by-using-aws-cloudtrail/). ## Deny access to temporary security credentials sessions with condition context keys You can use condition context keys in identity-based policies in situations where you want to deny access to specific temporary security credential sessions without affecting the permissions of the IAM user or role that created the credentials. For IAM roles, after you update the policy, you can also [revoke the role’s temporary security credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_revoke-sessions.html) sessions to immediately revoke all issued credentials. For more information about condition context keys, see [AWS global condition context keys](reference_policies_condition-keys.md). ### aws:PrincipalArn You can use condition context key [aws:PrincipalArn](reference_policies_condition-keys.md#condition-keys-principalarn) in an identity-based policy to deny access to a specific principal by their Amazon Resource Name (ARN). You do this by specifying the ARN of the IAM user, role, or AWS STS federated user session the temporary security credentials are associated with in the Condition element of a policy. **To deny access to a specific principal by their ARN** 1. In the IAM console navigation pane, choose **Users** or **Roles**. 1. Choose the name of the IAM user or role to edit. You can use the search box to filter the list. 1. Choose the **Permissions** tab. 1. Select the relevant policy to edit. Before you edit a customer managed policy, review the **Entities attached** tab to avoid disrupting access to other identities that may have the same policy attached. 1. Choose the **JSON** tab and add a deny statement for the principal ARN as shown in the following example. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Deny", "Action": "*", "Resource": "*", "Condition": { "ArnEquals": { "aws:PrincipalArn": [ "arn:aws:iam::222222222222:role/ROLENAME", "arn:aws:iam::222222222222:user/USERNAME", "arn:aws:iam::222222222222:federated-user/USERNAME" ] } } } ] } ``` ------ 1. On the **Review** page, review the policy **Summary** and then choose **Save changes** to save your work. ### aws:SourceIdentity You can use condition context key [aws:SourceIdentity](reference_policies_condition-keys.md#condition-keys-sourceidentity) in an identity-based policy to deny access to a specific source identity associated with an IAM role session. This applies as long as the role session was issued by setting the `SourceIdentity` request parameter when the principal assumed a role using any AWS STS `assume-role`\$1 CLI commands, or AWS STS `AssumeRole`\$1 API operations. You do this by specifying the source identity that the temporary security credentials are associated with in the `Condition` element of a policy. Unlike context key [sts:RoleSessionName](reference_policies_iam-condition-keys.md#ck_rolesessionname), after the source identity is set, the value cannot be changed. The `aws:SourceIdentity` key is present in the request context for all actions taken by the role. The source identity persists into subsequent role sessions when you use the session credentials to assume another role. Assuming one role from another is called [role chaining](id_roles.md#iam-term-role-chaining). The following policy shows an example of how you can deny access to temporary security credential sessions using condition context key `aws:SourceIdentity`. If you specify the source identity associated with a role session, it will deny role sessions with the named source identity without affecting the permissions of the role that created the credentials. For this example, the source identity set by the principal when the role session was issued is `nikki_wolf@example.com`. Any request made by a role session with the source identity `nikki_wolf@example.com` will be denied because the source identity is included in the policy condition and the policy Effect is set to `Deny`. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Deny", "Action": "*", "Resource": "*", "Condition": { "StringLike": { "aws:SourceIdentity": [ "nikki_wolf@example.com", "" ] } } } ] } ``` ------ ### aws:userid You can use condition context key [aws:userid](reference_policies_condition-keys.md#condition-keys-userid) in an identity-based policy to deny access to all or specific temporary security credential sessions associated with the IAM user or role. You do this by specifying the unique identifier (ID) of the IAM user, role, or AWS STS federated user session the temporary security credentials are associated with in the `Condition` element of a policy. The following policy shows an example of how you can deny access to temporary security credential sessions using condition context key `aws:userid`. + `AIDAXUSER1` represents the unique ID for an IAM user. Specifying the unique ID of an IAM user as a value for context key `aws:userid` will deny access to the IAM user. This includes any temporary security credential sessions that were created by calling the `GetSessionToken` API. + `AROAXROLE1:*` represents the unique ID for all sessions associated with the IAM role. Specifying the unique ID of an IAM role and a wildcard (\$1) character in the caller-specified-role-session-name portion as a value for context key `aws:userid` will deny all sessions associated with the role. + `AROAXROLE2:` represents the unique ID for an assumed-role session. In the caller-specified-role-session-name portion of the assumed-role unique ID you can specify a role session name or a wildcard character if the StringLike condition operator is used. If you specify the role session name, it will deny the named role session without affecting the permissions of the role that created the credentials. If you specify a wildcard character for the role session name, it will deny all sessions associated with the role. **Note** The caller-specified role session name, which is part of the unique identifier for an assumed-role session, can change during role chaining. Role chaining occurs when one role assumes another role. The role session name is set using the `RoleSessionName` request parameter when the principal assumes a role using the AWS STS `AssumeRole` API operation. + `account-id:` represents the unique ID for an AWS STS federated user session. An IAM user creates this session by calling the `GetFederationToken` API. Specifying the unique ID for an AWS STS federated user session denies the named federated session without affecting the permissions of the IAM user that created the credentials. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Deny", "Action": "*", "Resource": "*", "Condition": { "StringLike": { "aws:userId": [ "AIDAXUSER1", "AROAXROLE1:*", "AROAXROLE2:", "123456789012:" ] } } } ] } ``` ------ For specific examples of principal key values, see [Principal key values](reference_policies_variables.md#principaltable). For information about IAM unique identifiers and how to get them, see [Unique identifiers](reference_identifiers.md#identifiers-unique-ids). ## Deny access to a specific principal with resource-based policies To restrict access to a specific principal with a resource-based policy, you can use condition context keys [aws:PrincipalArn](reference_policies_condition-keys.md#condition-keys-principalarn) or [aws:SourceIdentity](reference_policies_condition-keys.md#condition-keys-sourceidentity) in the `Condition` element. A resource-based policy is a permission policy attached to a resource and controls who can access the resource and what actions they can perform on it. When you use the `aws:PrincipalARN` context key, specify the ARN of the IAM user, role, or AWS STS federated user session associated with the temporary security credentials in the Condition element of a policy. The following example policy demonstrates how to use the `aws:PrincipalARN` context key in a resource-based policy: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": { "Principal": "*", "Effect": "Deny", "Action": "s3:*", "Resource": "arn:aws:s3:::amzn-s3-demo-bucket", "Condition": { "ArnEquals": { "aws:PrincipalArn": [ "arn:aws:iam::222222222222:role/ROLENAME", "arn:aws:iam::222222222222:user/USERNAME", "arn:aws:sts::222222222222:federated-user/USERNAME" ] } } } } ``` ------ When you use the `aws:SourceIdentity` context key, specify the source identity value associated with the role's temporary security credentials in the `Condition` element of a policy. This applies as long as the role session was issued by setting the `SourceIdentity` request parameter when the principal assumed a role using any AWS STS `assume-role`\$1 CLI commands, or AWS STS `AssumeRole`\$1 API operations. The following example demonstrates how to use the `aws:SourceIdentity` context key in a resource-based policy: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": { "Principal": "*", "Effect": "Deny", "Action": "s3:*", "Resource": "arn:aws:s3:::amzn-s3-demo-bucket", "Condition": { "StringLike": { "aws:SourceIdentity": [ "nikki_wolf@example.com", "" ] } } } } ``` ------ If you only update the identity-based policy for a principal, they can still perform actions allowed in the resource-based policy, except when those actions are explicitly denied in the identity-based policy. **To deny access to a specific principal in a resource-based policy** 1. Refer to [AWS services that work with IAM](reference_aws-services-that-work-with-iam.md) to see if the service supports resource-based policies. 1. Sign in to the AWS Management Console and open the console for the service. Each service has a different location in the console for attaching policies. 1. Edit the resource-based policy. Add a deny policy statement to specify the identifying information of the credential: 1. In the `Principal` element, enter wildcard (\$1). The principal will be restricted in the `Condition` element. 1. In the `Effect` element, enter “Deny.” 1. In `Action`, enter the service namespace and the name of the action to deny. To deny all actions, use the wildcard (\$1) character. For example: `"s3:*"`. 1. In the `Resource` element, enter the ARN of the target resource. For example: `"arn:aws:s3:::amzn-s3-demo-bucket"`. 1. In the `Condition` element, specify either the `aws:PrincipalARN` or `aws:SourceIdentity` context key. If you use the `aws:PrincipalARN` context key, enter the ARN of the principal to deny access for. If you use the `aws:SourceIdentity` context key, enter the source identity value set in the role session to deny access for. 1. Save your work. # Granting permissions to create temporary security credentials Granting permissions to create credentials By default, IAM users do not have permission to create temporary security credentials for AWS STS federated user sessions and roles. You must use a policy to provide your users with these permissions. Although you can grant permissions directly to a user, we strongly recommend that you grant permissions to a group. This makes management of the permissions much easier. When someone no longer needs to perform the tasks associated with the permissions, you simply remove them from the group. If someone else needs to perform that task, add them to the group to grant the permissions. To grant an IAM group permission to create temporary security credentials for AWS STS federated user sessions or roles, you attach a policy that grants one or both of the following privileges: + For OIDC and SAML federated principals to access an IAM role, grant access to AWS STS `AssumeRole`. + For AWS STS federated users that don't need a role, grant access to AWS STS `GetFederationToken`. For more information about the differences between the `AssumeRole` and `GetFederationToken` API operations, see [Request temporary security credentials](id_credentials_temp_request.md). IAM users can also call [https://docs.aws.amazon.com/STS/latest/APIReference/API_GetSessionToken.html](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetSessionToken.html) to create temporary security credentials. No permissions are required for a user to call `GetSessionToken`. The purpose of this operation is to authenticate the user using MFA. You cannot use policies to control authentication. This means that you cannot prevent IAM users from calling `GetSessionToken` to create temporary credentials. **Example policy that grants permission to assume a role** The following example policy grants permission to call `AssumeRole` for the `UpdateApp` role in AWS account `123123123123`. When `AssumeRole` is used, the user (or application) that creates the security credentials on behalf of a federated user cannot delegate any permissions that are not already specified in the role permission policy. **** ``` { "Version":"2012-10-17", "Statement": [{ "Effect": "Allow", "Action": "sts:AssumeRole", "Resource": "arn:aws:iam::123123123123:role/UpdateAPP" }] } ``` **Example policy that grants permission to create temporary security credentials for a federated user** The following example policy grants permission to access `GetFederationToken`. **** ``` { "Version":"2012-10-17", "Statement": [{ "Effect": "Allow", "Action": "sts:GetFederationToken", "Resource": "*" }] } ``` **Important** When you give IAM users permission to create temporary security credentials for AWS STS federated users with `GetFederationToken`, be aware that this permits those users to delegate their own permissions. For more information about delegating permissions across IAM users and AWS accounts, see [Examples of policies for delegating access](id_roles_create_policy-examples.md). For more information about controlling permissions in temporary security credentials, see [Permissions for temporary security credentials](id_credentials_temp_control-access.md). **Example policy that grants a user limited permission to create temporary security credentials for federated users** When you let an IAM user call `GetFederationToken`, it is a best practice to restrict the permissions that the IAM user can delegate. For example, the following policy shows how to let an IAM user create temporary security credentials only for AWS STS federated users whose names start with *Manager*. **** ``` { "Version":"2012-10-17", "Statement": [{ "Effect": "Allow", "Action": "sts:GetFederationToken", "Resource": ["arn:aws:sts::123456789012:federated-user/Manager*"] }] } ``` # Granting permissions to use identity-enhanced console sessions Granting permissions to use identity-enhanced console sessions Identity-enhanced console sessions enables AWS IAM Identity Center user and session IDs to be included in users' AWS console sessions when they sign in. For example, Amazon Q Developer Pro uses identity-enhanced console sessions to personalize the service experience. For more information about identity-enhanced console sessions, see [Enabling identity-enhanced console sessions](https://docs.aws.amazon.com/singlesignon/latest/userguide/identity-enhanced-sessions.html) in the *AWS IAM Identity Center User Guide*. For information about Amazon Q Developer setup, see [Setting up Amazon Q Developer](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/setting-up.html) in the *Amazon Q Developer User Guide*. For identity-enhanced console sessions to be available to a user, you must use an identity-based policy to grant the IAM principal the `sts:SetContext` permission for the resource that represents their own console session. **Important** By default, users do not have permission to set context for their identity-enhanced console sessions. To allow this, you must grant the IAM principal the `sts:SetContext` permission in an identity-based policy as shown in the policy example below. The following example identity-based policy grants the `sts:SetContext` permission to an IAM principal, allowing the principal to set identity-enhanced console session context for their own AWS console sessions. The policy resource, `arn:aws:sts::account-id:self`, represents the caller’s AWS session. The `account-id` ARN segment can be replaced with a wildcard character `*` in cases where the same permission policy is deployed across multiple accounts, such as when this policy is deployed using IAM Identity Center permission sets. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "sts:SetContext", "Resource": "arn:aws:sts::111122223333:self" } ] } ``` ------ # Manage AWS STS in an AWS Region A Regional endpoint is the URL of the entry point within a particular region for an AWS web service. AWS recommends using Regional AWS Security Token Service (AWS STS) endpoints instead of the global endpoint to reduce latency, build in redundancy, and increase session token validity. Although the global (legacy) AWS STS endpoint `https://sts.amazonaws.com` is highly available, it’s hosted in a single AWS Region, US East (N. Virginia), and like other endpoints, it doesn’t provide automatic failover to endpoints in other Regions. + **Reduce latency** – By making your AWS STS calls to an endpoint that is geographically closer to your services and applications, you can access AWS STS services with lower latency and better response times. + **Build in redundancy** – You can limit the effects of a failure within a workload to a limited number of components with a predictable scope of impact containment. Using regional AWS STS endpoints lets you align the scope of your components with the scope of your session tokens. For more information about this reliability pillar, see [Use fault isolation to protect your workload](https://docs.aws.amazon.com/wellarchitected/latest/reliability-pillar/use-fault-isolation-to-protect-your-workload.html) in the *AWS Well-Architected Framework*. + **Increase session token validity** – Session tokens from Regional AWS STS endpoints are valid in all AWS Regions. Session tokens from the global STS endpoint are valid only in AWS Regions that are enabled by default. If you intend to enable a new Region for your account, you can use session tokens from Regional AWS STS endpoints. If you choose to use the global endpoint, you must change the Region compatibility of AWS STS session tokens for the global endpoint. Doing so ensures that tokens are valid in all AWS Regions. For a list of AWS STS Regions and their endpoints, see [AWS STS Regions and endpoints](id_credentials_temp_region-endpoints.md). **Note** AWS has made changes to the AWS Security Token Service (AWS STS) global endpoint (`https://sts.amazonaws.com`) in Regions [enabled by default](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-regions.html) to enhance its resiliency and performance. AWS STS requests to the global endpoint are automatically served in the same AWS Region as your workloads. These changes will not be deployed to opt-in Regions. We recommend that you use the appropriate AWS STS regional endpoints. For more information, see [AWS STS global endpoint changes](id_credentials_temp_region-endpoints.md#reference_sts_global_endpoint_changes). **Topics** + [ ## Activating and deactivating AWS STS in an AWS Region ](#sts-regions-activate-deactivate) + [ ## Writing code to use AWS STS Regions ](#id_credentials_temp_enable-regions_writing_code) + [ ## Managing global endpoint session tokens ](#sts-regions-manage-tokens) ## Activating and deactivating AWS STS in an AWS Region When you activate AWS STS endpoints for a Region, AWS STS can issue temporary credentials to users and roles in your account that make an AWS STS request. Those credentials can then be used in any Region that is enabled by default or is manually enabled. For Regions that are enabled by default, you must activate the Regional AWS STS endpoint in the account where the temporary credentials are generated. It does not matter whether a user is signed into the same account or a different account when they make the request. When requesting temporary credentials for a role in another AWS account using a Region that is manually enabled, the target account (the account containing the role) must enable that Region for AWS STS operations. This ensures that the temporary security credentials can be generated correctly. For example, imagine a user in account A wants to send an `sts:AssumeRole` API request to the [AWS STS Regional endpoint](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_region-endpoints.html) `https://sts.ap-southeast-3.amazonaws.com`. The request is for temporary credentials for the role named `Developer` in account B. Because the request is to create credentials for an entity in account B, account B must have the `ap-southeast-3` Region enabled. Users from account A (or any other account) can call the `ap-southeast-3` AWS STS endpoint to request credentials for account B whether or not the Region is activated in their accounts. To learn more, see [Enable or disable AWS Regions in your account](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-regions.html). **Note** Active Regions are available to everyone that uses temporary credentials in that account. To control which IAM users or roles can access the Region, use the `aws:RequestedRegion` condition key in your permissions policies. **To activate or deactivate AWS STS in a Region that is enabled by default (console)** 1. Sign in as a root user or a user with permissions to perform IAM administration tasks. 1. Open the [IAM console](https://console.aws.amazon.com/iam/home?#home) and in the navigation pane choose [https://console.aws.amazon.com/iam/home?#account_settings](https://console.aws.amazon.com/iam/home?#account_settings). 1. In the **Security Token Service (STS)** section **Endpoints**, find the Region that you want to configure, and then choose **Active** or **Inactive** in the **STS status** column. 1. In the dialog box that opens, choose **Activate** or **Deactivate**. For Regions that must be enabled, we activate AWS STS automatically when you enable the Region. After you enable a Region, AWS STS is always active for the Region and you cannot deactivate it. To learn about enabling Regions that are disabled by default, see [ Specifying which AWS Regions your account can use](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-regions.html) in the *AWS Account Management Reference Guide*. ## Writing code to use AWS STS Regions After you activate a Region, you can direct AWS STS API calls to that Region. The following Java code snippet demonstrates how to configure an `AWSSecurityTokenService` object to make requests to the Europe (Milan) (eu-south-1) Region. ``` EndpointConfiguration regionEndpointConfig = new EndpointConfiguration("https://sts.eu-south-1.amazonaws.com", "eu-south-1"); AWSSecurityTokenService stsRegionalClient = AWSSecurityTokenServiceClientBuilder.standard() .withCredentials(credentials) .withEndpointConfiguration(regionEndpointConfig) .build(); ``` AWS STS recommends that you make calls to a Regional endpoint. To learn how to manually enable a Region, see [Specify which AWS Regions your account can use](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-regions.html) in the *AWS Account Management Reference Guide*. In the example, the first line instantiates an `EndpointConfiguration` object called `regionEndpointConfig`, passing the URL of the endpoint and the AWS Region as the parameters. To learn how to set AWS STS regional endpoints using an environment variable for AWS SDKs, see [AWS STS Regionalized endpoints](https://docs.aws.amazon.com/sdkref/latest/guide/feature-sts-regionalized-endpoints.html) in the *AWS SDKs and Tools Reference Guide*. For all other language and programming environment combinations, refer to the [documentation for the relevant SDK](https://aws.amazon.com/tools/). ## Managing global endpoint session tokens Most AWS Regions are enabled for operations in all AWS services by default. Those Regions are automatically activated for use with AWS STS. Some Regions, such as Asia Pacific (Hong Kong), must be manually enabled. To learn more about enabling and disabling AWS Regions, see [Specify which AWS Regions your account can use](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-regions.html) in the *AWS Account Management Reference Guide*. When you enable these AWS Regions, they are automatically activated for use with AWS STS. You cannot activate the AWS STS endpoint for a Region that is disabled. Session tokens that are valid in all AWS Regions include more characters than tokens that are valid in Regions that are enabled by default. Changing this setting might affect existing systems where you temporarily store tokens. You can change this setting using the AWS Management Console, AWS CLI, or AWS API. **To change the Region compatibility of session tokens for the global endpoint (console)** 1. Sign in as a root user or a user with permissions to perform IAM administration tasks. To change the compatibility of session tokens, you must have a policy that allows the `iam:SetSecurityTokenServicePreferences` action. 1. Open the [IAM console](https://console.aws.amazon.com/iam/home?#home). In the navigation pane, choose **Account settings**. 1. Under **Security Token Service (STS)** section **Session Tokens from the STS endpoints**. The **Global endpoint** indicates `Valid only in AWS Regions enabled by default`. Choose **Change**. 1. In the **Change region compatibility** dialog box, select **All AWS Regions**. Then choose **Save changes**. **Note** Session tokens that are valid in all AWS Region include more characters than tokens that are valid in Regions that are enabled by default. Changing this setting might affect existing systems where you temporarily store tokens. **To change the Region compatibility of session tokens for the global endpoint (AWS CLI)** Set the session token version. Version 1 tokens are valid only in AWS Regions that are available by default. These tokens do not work in manually enabled Regions, such as Asia Pacific (Hong Kong). Version 2 tokens are valid in all Regions. However, version 2 tokens include more characters and might affect systems where you temporarily store tokens. + [https://docs.aws.amazon.com/cli/latest/reference/iam/set-security-token-service-preferences.html](https://docs.aws.amazon.com/cli/latest/reference/iam/set-security-token-service-preferences.html) **To change the Region compatibility of session tokens for the global endpoint (AWS API)** Set the session token version. Version 1 tokens are valid only in AWS Regions that are available by default. These tokens do not work in manually enabled Regions, such as Asia Pacific (Hong Kong). Version 2 tokens are valid in all Regions. However, version 2 tokens include more characters and might affect systems where you temporarily store tokens. + [https://docs.aws.amazon.com/IAM/latest/APIReference/API_SetSecurityTokenServicePreferences.html](https://docs.aws.amazon.com/IAM/latest/APIReference/API_SetSecurityTokenServicePreferences.html) # AWS STS Regions and endpoints **Note** AWS has made changes to the AWS Security Token Service (AWS STS) global endpoint (`https://sts.amazonaws.com`) in Regions [enabled by default](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-regions.html) to enhance its resiliency and performance. AWS STS requests to the global endpoint are automatically served in the same AWS Region as your workloads. These changes will not be deployed to opt-in Regions. We recommend that you use the appropriate AWS STS regional endpoints. For more information, see [AWS STS global endpoint changes](#reference_sts_global_endpoint_changes). The following table lists the Regions and their endpoints. It indicates which ones are activated by default and which ones you can activate or deactivate. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_region-endpoints.html) ¹You must [enable the Region](https://docs.aws.amazon.com/general/latest/gr/rande-manage.html) to use it. This automatically activates AWS STS. You cannot manually activate or deactivate AWS STS in these Regions. ²To use AWS in China, you need an account and credentials specific to AWS in China. ## AWS STS global endpoint changes AWS has made changes to the AWS Security Token Service (AWS STS) global endpoint (`https://sts.amazonaws.com`) in Regions [enabled by default](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-regions.html) to enhance its resiliency and performance. Previously, all requests to the AWS STS global endpoint were served by a single AWS Region, US East (N. Virginia). Now in Regions [enabled by default](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-regions.html), requests to the AWS STS global endpoint are automatically served in the same Region where the request originates, rather than the US East (N. Virginia) Region. These changes will not be deployed to opt-in Regions. With this change, AWS STS will process your request based on the originating Region and DNS resolver used. Requests to the AWS STS global endpoint are served in the same Region as your AWS deployed workload if the DNS request for the AWS STS global endpoint is handled by the Amazon DNS server in Regions that are enabled by default. Requests to the AWS STS global endpoint will continue to be served in US East (N. Virginia) Region if your request originated from opt-in Regions or if your request was resolved using a DNS resolver other than the Amazon DNS server. For more information about Amazon DNS, see [ Amazon DNS server](https://docs.aws.amazon.com/vpc/latest/userguide/AmazonDNS-concepts.html#AmazonDNS) in the *Amazon Virtual Private Cloud User Guide*. The following table shows how requests to the AWS STS global endpoint are routed based on your DNS provider. | DNS Resolver | Requests to the AWS STS global endpoint routed to the local AWS Region? | | --- | --- | | Amazon DNS resolver in a Amazon VPC in an Region enabled by default | Yes | | Amazon DNS resolver in a Amazon VPC in an opt-in Region | No, the request will be routed to the US East (N. Virginia) Region | | DNS resolver provided by your ISP, a public DNS provider, or any other DNS provider | No, the request will be routed to the US East (N. Virginia) Region | To ensure minimal disruption to your existing processes, AWS has implemented the following measures: + AWS CloudTrail logs for requests made to the AWS STS global endpoint are sent to the US East (N. Virginia) Region. CloudTrail logs for requests served by AWS STS Regional endpoints will continue to be logged to their respective Region in CloudTrail. + CloudTrail logs for operations performed by the AWS STS global endpoint and Regional endpoints have additional fields `endpointType` and `awsServingRegion` to indicate which endpoint and Region served the request. For CloudTrail log examples, see [Example AWS STS API event using the global endpoint in CloudTrail log file](cloudtrail-integration.md#stscloudtrailexample-assumerole-sts-global-endpoint). + Requests made to the AWS STS global endpoint have a value of `us-east-1` for the `aws:RequestedRegion` condition key, regardless of which Region served the request. + Requests handled by the AWS STS global endpoint do not share a requests per second quota with Regional AWS STS endpoints. If you have workloads in an opt-in Region and are still using the AWS STS global endpoint, we recommend migrating to AWS STS regional endpoints for improved resiliency and performance. For more information about configuring regional AWS STS endpoints, see [AWS STS Regional endpoints](https://docs.aws.amazon.com/sdkref/latest/guide/feature-sts-regionalized-endpoints.html) in the *AWS SDKs and Tools Reference Guide*. ## AWS CloudTrail and Regional endpoints Calls to regional and global endpoints are logged in the `tlsDetails` field in AWS CloudTrail. Calls to regional endpoints, such as `us-east-2.amazonaws.com`, are logged in CloudTrail to their appropriate region. Calls to the global endpoint, `sts.amazonaws.com`, are logged as calls to a global service. Events for global AWS STS endpoints are logged to us-east-1. **Note** `tlsDetails` can only be viewed for services that support this field. See [Services that support TLS details in CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-supported-tls-details.html) in the *AWS CloudTrail User Guide* For more information, see [Logging IAM and AWS STS API calls with AWS CloudTrail](cloudtrail-integration.md). # Enable custom identity broker access to the AWS console Enable custom identity broker console access You can write and run code to create a URL that lets users who sign in to your organization's network securely access the AWS Management Console. The URL includes a sign-in token that you get from AWS and that authenticates the user to AWS. The resulting console session might include a distinct `AccessKeyId` due to federation. To trace the access key usage for federation sign-in through related CloudTrail events, see [Logging IAM and AWS STS API calls with AWS CloudTrail](cloudtrail-integration.md) and [AWS Management Console sign-in events](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-aws-console-sign-in-events.html). **Note** If your organization uses an identity provider (IdP) that is compatible with SAML, you can set up access to the console without writing code. This works with providers like Microsoft's Active Directory Federation Services or open-source Shibboleth. For details, see [Enabling SAML 2.0 federated principals to access the AWS Management Console](id_roles_providers_enable-console-saml.md). To enable your organization's users to access the AWS Management Console, you can create a custom *identity broker* that performs the following steps: 1. Verify that the user is authenticated by your local identity system. 1. Call the AWS Security Token Service (AWS STS) [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) (recommended) or [GetFederationToken](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetFederationToken.html) API operations to obtain temporary security credentials for the user. To learn about the different methods that you can use to assume a role, see [Methods to assume a role](id_roles_manage-assume.md). To learn how to pass optional session tags when you obtain your security credentials, see [Pass session tags in AWS STS](id_session-tags.md). + If you use one of the `AssumeRole*` API operations to get the temporary security credentials for a role, you can include the `DurationSeconds` parameter in your call. This parameter specifies the duration of your role session, from 900 seconds (15 minutes) up to the maximum session duration setting for the role. When you use `DurationSeconds` in an `AssumeRole*` operation, you must call it as an IAM user with long-term credentials. Otherwise, the call to the federation endpoint in step 3 fails. To learn how to view or change the maximum value for a role, see [Update the maximum session duration for a role](id_roles_update-role-settings.md#id_roles_update-session-duration). + If you use the `GetFederationToken` API operation to get the credentials, you can include the `DurationSeconds` parameter in your call. This parameter specifies the duration of your role session. The value can range from 900 seconds (15 minutes) to 129,600 seconds (36 hours). You can make this API call only by using the long-term AWS security credentials of an IAM user. You can also make these calls using AWS account root user credentials, but we do not recommend it. If you make this call as the root user, the default session lasts for one hour. Or you can specify a session from 900 seconds (15 minutes) up to 3,600 seconds (one hour). 1. Call the AWS federation endpoint and supply the temporary security credentials to request a sign-in token. 1. Construct a URL for the console that includes the token: + If you use one of the `AssumeRole*` API operations in your URL, you can include the `SessionDuration` HTTP parameter. This parameter specifies the duration of the console session, from 900 seconds (15 minutes) to 43200 seconds (12 hours). + If you use the `GetFederationToken` API operation in your URL, you can include the `DurationSeconds` parameter. This parameter specifies the duration of the federated console session. The value can range from 900 seconds (15 minutes) to 129,600 seconds (36 hours). **Note** Your `SessionDuration` cannot be greater than or equal to the maximum session duration setting for the role you're assuming. For example, you're set the maximum session duration for the role you want to assume to 5 hours. Your `SessionDuration` parameter can be 16524 seconds or 4 hours and 59 seconds. Do not use the `SessionDuration` HTTP parameter when you get temporary credentials with `GetFederationToken`. The operation will fail. Using the credentials for one role to assume a different role is called [*role chaining*](id_roles.md#iam-term-role-chaining). When you use role chaining, your new credentials are limited to a maximum duration of one hour. When you use roles to [grant permissions to applications that run on EC2 instances](id_roles_use_switch-role-ec2.md), those applications are not subject to this limitation. Do not use the `SessionDuration` HTTP parameter when you get temporary credentials through role chaining. The operation will fail. 1. Give the URL to the user or invoke the URL on the user's behalf. The URL that the federation endpoint provides is valid for 15 minutes after it is created. This differs from the duration (in seconds) of the temporary security credential session that is associated with the URL. Those credentials are valid for the duration you specified when you created them, starting from the time they were created. **Important** The URL grants access to your AWS resources through the AWS Management Console if you have enabled permissions in the associated temporary security credentials. For this reason, you should treat the URL as a secret. We recommend returning the URL through a secure redirect, for example, by using a 302 HTTP response status code over an SSL connection. For more information about the 302 HTTP response status code, go to [RFC 2616, section 10.3.3](https://datatracker.ietf.org/doc/html/rfc2616#section-10.3.3). To complete these tasks, you can use the [HTTPS Query API for AWS Identity and Access Management (IAM)](https://docs.aws.amazon.com/IAM/latest/APIReference/) and the [AWS Security Token Service (AWS STS)](https://docs.aws.amazon.com/STS/latest/APIReference/). Or, you can use programming languages, such as Java, Ruby, or C\$1, along with the appropriate [AWS SDK](https://aws.amazon.com/tools/). Each of these methods is described in the following topics. **Topics** + [ ## Example code using IAM query API operations ](#STSConsoleLink_manual) + [ ## Example code using Python ](#STSConsoleLink_programPython) + [ ## Example code using Java ](#STSConsoleLink_programJava) + [ ## Example showing how to construct the URL (Ruby) ](#STSConsoleLink_programRuby) ## Example code using IAM query API operations You can construct a URL that gives roles and federated principals direct access to the AWS Management Console. This task uses the IAM and AWS STS HTTPS Query API. For more information about making query requests, see [Making Query Requests](https://docs.aws.amazon.com/IAM/latest/UserGuide/IAM_UsingQueryAPI.html). **Note** The following procedure contains examples of text strings. To enhance readability, line breaks have been added to some of the longer examples. When you create these strings for your own use, you should omit any line breaks. **To give roles and federated principals access to your resources from the AWS Management Console** 1. Authenticate the user in your identity and authorization system. 1. Obtain temporary security credentials for the user. The temporary credentials consist of an access key ID, a secret access key, and a session token. For more information about creating temporary credentials, see [Temporary security credentials in IAM](id_credentials_temp.md). To get temporary credentials, you call either the AWS STS [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) API (recommended) or the [GetFederationToken](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetFederationToken.html) API. For more information about the differences between these API operations, see [Understanding the API Options for Securely Delegating Access to Your AWS Account](https://aws.amazon.com/blogs/security/understanding-the-api-options-for-securely-delegating-access-to-your-aws-account) in the AWS Security Blog. **Important** When you use the [GetFederationToken](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetFederationToken.html) API to create temporary security credentials, you must specify the permissions that the credentials grant to the user who assumes the role. For any of the API operations that begin with `AssumeRole*`, you use an IAM role to assign permissions. For the other API operations, the mechanism varies with the API. For more details, see [Permissions for temporary security credentials](id_credentials_temp_control-access.md). Additionally, if you use the `AssumeRole*` API operations, you must call them as an IAM user with long-term credentials. Otherwise, the call to the federation endpoint in step 3 fails. 1. After you obtain the temporary security credentials, build them into a JSON session string to exchange them for a sign-in token. The following example shows how to encode the credentials. You replace the placeholder text with the appropriate values from the credentials that you receive in the previous step. ``` {"sessionId":"*** temporary access key ID ***", "sessionKey":"*** temporary secret access key ***", "sessionToken":"*** session token ***"} ``` 1. [URL encode](https://en.wikipedia.org/wiki/Percent-encoding) the session string from the previous step. Because the information that you are encoding is sensitive, we recommend that you avoid using a web service for this encoding. Instead, use a locally installed function or feature in your development toolkit to securely encode this information. You can use the `urllib.quote_plus` function in Python, the `URLEncoder.encode` function in Java, or the `CGI.escape` function in Ruby. See the examples later in this topic. 1. **Note** AWS supports POST requests here. Send your request to the AWS federation endpoint: `https://region-code.signin.aws.amazon.com/federation` For a list of possible *region-code* values, see the **Region** column in [AWS Sign-In endpoints](https://docs.aws.amazon.com/general/latest/gr/signin-service.html). You can optionally use the default AWS Sign-In federation endpoint: `https://signin.aws.amazon.com/federation` The request must include the `Action` and `Session` parameters, and (optionally) if you used an [https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) API operation, a `SessionDuration` HTTP parameter as shown in the following example. ``` Action = getSigninToken SessionDuration = time in seconds Session = *** the URL encoded JSON string created in steps 3 & 4 *** ``` **Note** The following instructions in this step only work using GET requests. The `SessionDuration` HTTP parameter specifies the duration of the console session. This is separate from the duration of the temporary credentials that you specify using the `DurationSeconds` parameter. You can specify a `SessionDuration` maximum value of 43,200 (12 hours). If the `SessionDuration` parameter is missing, then the session defaults to the duration of the credentials that you retrieved from AWS STS in step 2 (which defaults to one hour). See the [documentation for the `AssumeRole` API](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) for details about how to specify a duration using the `DurationSeconds` parameter. The ability to create a console session that is longer than one hour is intrinsic to the `getSigninToken` operation of the federation endpoint. **Note** Your `SessionDuration` cannot be greater than or equal to the maximum session duration setting for the role you're assuming. For example, you're set the maximum session duration for the role you want to assume to 5 hours. Your `SessionDuration` parameter can be 16524 seconds or 4 hours and 59 seconds. Do not use the `SessionDuration` HTTP parameter when you get temporary credentials with `GetFederationToken`. The operation will fail. Using the credentials for one role to assume a different role is called [*role chaining*](id_roles.md#iam-term-role-chaining). When you use role chaining, your new credentials are limited to a maximum duration of one hour. When you use roles to [grant permissions to applications that run on EC2 instances](id_roles_use_switch-role-ec2.md), those applications are not subject to this limitation. Do not use the `SessionDuration` HTTP parameter when you get temporary credentials through role chaining. The operation will fail. When you enable console sessions with an extended duration, you increase the risk of credential exposure. To help you mitigate this risk, you can immediately disable the active console sessions for any role by choosing **Revoke Sessions** on the **Role Summary** IAM console page. For more information, see [Revoke IAM role temporary security credentials](id_roles_use_revoke-sessions.md). The following is an example of what your request might look like. The lines are wrapped here for readability, but you should submit it as a one-line string. ``` https://signin.aws.amazon.com/federation ?Action=getSigninToken &SessionDuration=1800 &Session=%7B%22sessionId%22%3A+%22ASIAJUMHIZPTOKTBMK5A%22%2C+%22sessionKey%22 %3A+%22LSD7LWI%2FL%2FN%2BgYpan5QFz0XUpc8s7HYjRsgcsrsm%22%2C+%22sessionToken%2 2%3A+%22FQoDYXdzEBQaDLbj3VWv2u50NN%2F3yyLSASwYtWhPnGPMNmzZFfZsL0Qd3vtYHw5A5dW AjOsrkdPkghomIe3mJip5%2F0djDBbo7SmO%2FENDEiCdpsQKodTpleKA8xQq0CwFg6a69xdEBQT8 FipATnLbKoyS4b%2FebhnsTUjZZQWp0wXXqFF7gSm%2FMe2tXe0jzsdP0O12obez9lijPSdF1k2b5 PfGhiuyAR9aD5%2BubM0pY86fKex1qsytjvyTbZ9nXe6DvxVDcnCOhOGETJ7XFkSFdH0v%2FYR25C UAhJ3nXIkIbG7Ucv9cOEpCf%2Fg23ijRgILIBQ%3D%3D%22%7D ``` The response from the federation endpoint is a JSON document with a `SigninToken` value. It will look similar to the following example. ``` {"SigninToken":"*** the SigninToken string ***"} ``` 1. **Note** AWS supports POST requests here. Finally, create the URL that your users can use to access the AWS Management Console. The URL is the same federation URL endpoint that you used in [Step 5](#STSConsoleLink_manual_step5), plus the following parameters: ``` ?Action = login &Issuer = *** the form-urlencoded URL for your internal sign-in page *** &Destination = *** the form-urlencoded URL to the desired AWS console page *** &SigninToken = *** the value of SigninToken received in the previous step *** ``` **Note** The following instructions in this step only work using GET API. The following example shows what the final URL might look like. The URL is valid for 15 minutes from the time it is created. The temporary security credentials and console session embedded within the URL are valid for the duration you specify in the `SessionDuration` HTTP parameter when you initially request them. ``` https://signin.aws.amazon.com/federation ?Action=login &Issuer=https%3A%2F%2Fexample.com &Destination=https%3A%2F%2Fconsole.aws.amazon.com%2F &SigninToken=VCQgs5qZZt3Q6fn8Tr5EXAMPLEmLnwB7JjUc-SHwnUUWabcRdnWsi4DBn-dvC CZ85wrD0nmldUcZEXAMPLE-vXYH4Q__mleuF_W2BE5HYexbe9y4Of-kje53SsjNNecATfjIzpW1 WibbnH6YcYRiBoffZBGExbEXAMPLE5aiKX4THWjQKC6gg6alHu6JFrnOJoK3dtP6I9a6hi6yPgm iOkPZMmNGmhsvVxetKzr8mx3pxhHbMEXAMPLETv1pij0rok3IyCR2YVcIjqwfWv32HU2Xlj471u 3fU6uOfUComeKiqTGX974xzJOZbdmX_t_lLrhEXAMPLEDDIisSnyHGw2xaZZqudm4mo2uTDk9Pv 9l5K0ZCqIgEXAMPLEcA6tgLPykEWGUyH6BdSC6166n4M4JkXIQgac7_7821YqixsNxZ6rsrpzwf nQoS14O7R0eJCCJ684EXAMPLEZRdBNnuLbUYpz2Iw3vIN0tQgOujwnwydPscM9F7foaEK3jwMkg Apeb1-6L_OB12MZhuFxx55555EXAMPLEhyETEd4ZulKPdXHkgl6T9ZkIlHz2Uy1RUTUhhUxNtSQ nWc5xkbBoEcXqpoSIeK7yhje9Vzhd61AEXAMPLElbWeouACEMG6-Vd3dAgFYd6i5FYoyFrZLWvm 0LSG7RyYKeYN5VIzUk3YWQpyjP0RiT5KUrsUi-NEXAMPLExMOMdoODBEgKQsk-iu2ozh6r8bxwC RNhujg ``` ## Example code using Python The following examples show how to use Python to programmatically construct a URL that gives users direct access to the AWS Management Console. There are two examples: + Federate via GET requests to AWS + Federate via POST requests to AWS Both examples use the the [AWS SDK for Python (Boto3)](https://aws.amazon.com/tools/) and [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) API to obtain temporary security credentials. Do not include `SessionDuration` if your `AssumeRoleSession` credentials are from role chaining. If you include `SessionDuration`, the operation will fail. ### Use GET Requests ``` import urllib, json, sys import requests # 'pip install requests' import boto3 # AWS SDK for Python (Boto3) 'pip install boto3' # Step 1: Authenticate user in your own identity system. # Step 2: Using the access keys for an IAM user in your AWS account, # call "AssumeRole" to get temporary access keys for the role or federated principal # Note: Calls to AWS STS AssumeRole must be signed using the access key ID # and secret access key of an IAM user or using existing temporary credentials. # The credentials can be in Amazon EC2 instance metadata, in environment variables, # or in a configuration file, and will be discovered automatically by the # client('sts') function. For more information, see the Python SDK docs: # http://boto3.readthedocs.io/en/latest/reference/services/sts.html # http://boto3.readthedocs.io/en/latest/reference/services/sts.html#STS.Client.assume_role sts_connection = boto3.client('sts') assumed_role_object = sts_connection.assume_role( RoleArn="arn:aws:iam::account-id:role/ROLE-NAME", RoleSessionName="AssumeRoleSession", ) # Step 3: Format resulting temporary credentials into JSON url_credentials = {} url_credentials['sessionId'] = assumed_role_object.get('Credentials').get('AccessKeyId') url_credentials['sessionKey'] = assumed_role_object.get('Credentials').get('SecretAccessKey') url_credentials['sessionToken'] = assumed_role_object.get('Credentials').get('SessionToken') json_string_with_temp_credentials = json.dumps(url_credentials) # Step 4. Make request to AWS federation endpoint to get sign-in token. Construct the parameter string with # the sign-in action request, a 12-hour session duration, and the JSON document with temporary credentials # as parameters. request_parameters = "?Action=getSigninToken" request_parameters += "&SessionDuration=43200" if sys.version_info[0] < 3: def quote_plus_function(s): return urllib.quote_plus(s) else: def quote_plus_function(s): return urllib.parse.quote_plus(s) request_parameters += "&Session=" + quote_plus_function(json_string_with_temp_credentials) request_url = "https://signin.aws.amazon.com/federation" + request_parameters r = requests.get(request_url) # Returns a JSON document with a single element named SigninToken. signin_token = json.loads(r.text) # Step 5: Create URL where users can use the sign-in token to sign in to # the console. This URL must be used within 15 minutes after the # sign-in token was issued. request_parameters = "?Action=login" request_parameters += "&Issuer=Example.org" request_parameters += "&Destination=" + quote_plus_function("https://console.aws.amazon.com/") request_parameters += "&SigninToken=" + signin_token["SigninToken"] request_url = "https://signin.aws.amazon.com/federation" + request_parameters # Send final URL to stdout print (request_url) ``` ### Use POST Requests ``` import urllib, json, sys import requests # 'pip install requests' import boto3 # AWS SDK for Python (Boto3) 'pip install boto3' import os from selenium import webdriver # 'pip install selenium', 'brew install chromedriver' # Step 1: Authenticate user in your own identity system. # Step 2: Using the access keys for an IAM user in your AAWS account, # call "AssumeRole" to get temporary access keys for the role or federated principal # Note: Calls to AWS STS AssumeRole must be signed using the access key ID # and secret access key of an IAM user or using existing temporary credentials. # The credentials can be in Amazon EC2 instance metadata, in environment variables, # or in a configuration file, and will be discovered automatically by the # client('sts') function. For more information, see the Python SDK docs: # http://boto3.readthedocs.io/en/latest/reference/services/sts.html # http://boto3.readthedocs.io/en/latest/reference/services/sts.html#STS.Client.assume_role if sys.version_info[0] < 3: def quote_plus_function(s): return urllib.quote_plus(s) else: def quote_plus_function(s): return urllib.parse.quote_plus(s) sts_connection = boto3.client('sts') assumed_role_object = sts_connection.assume_role( RoleArn="arn:aws:iam::account-id:role/ROLE-NAME", RoleSessionName="AssumeRoleDemoSession", ) # Step 3: Format resulting temporary credentials into JSON url_credentials = {} url_credentials['sessionId'] = assumed_role_object.get('Credentials').get('AccessKeyId') url_credentials['sessionKey'] = assumed_role_object.get('Credentials').get('SecretAccessKey') url_credentials['sessionToken'] = assumed_role_object.get('Credentials').get('SessionToken') json_string_with_temp_credentials = json.dumps(url_credentials) # Step 4. Make request to AWS federation endpoint to get sign-in token. Construct the parameter string with # the sign-in action request, a 12-hour session duration, and the JSON document with temporary credentials # as parameters. request_parameters = {} request_parameters['Action'] = 'getSigninToken' request_parameters['SessionDuration'] = '43200' request_parameters['Session'] = json_string_with_temp_credentials request_url = "https://signin.aws.amazon.com/federation" r = requests.post( request_url, data=request_parameters) # Returns a JSON document with a single element named SigninToken. signin_token = json.loads(r.text) # Step 5: Create a POST request where users can use the sign-in token to sign in to # the console. The POST request must be made within 15 minutes after the # sign-in token was issued. request_parameters = {} request_parameters['Action'] = 'login' request_parameters['Issuer']='Example.org' request_parameters['Destination'] = 'https://console.aws.amazon.com/' request_parameters['SigninToken'] =signin_token['SigninToken'] jsrequest = ''' var form = document.createElement('form'); form.method = 'POST'; form.action = '{request_url}'; request_parameters = {request_parameters} for (var param in request_parameters) {{ if (request_parameters.hasOwnProperty(param)) {{ const hiddenField = document.createElement('input'); hiddenField.type = 'hidden'; hiddenField.name = param; hiddenField.value = request_parameters[param]; form.appendChild(hiddenField); }} }} document.body.appendChild(form); form.submit(); '''.format(request_url=request_url, request_parameters=request_parameters) driver = webdriver.Chrome() driver.execute_script(jsrequest) input("Press Enter to close the browser window...") ``` ## Example code using Java The following example shows how to use Java to programmatically construct a URL that gives users direct access to the AWS Management Console. The following code snippet uses the [AWS SDK for Java](http://aws.amazon.com/documentation/sdkforjava/). ``` import java.net.URLEncoder; import java.net.URL; import java.net.URLConnection; import java.io.BufferedReader; import java.io.InputStreamReader; // Available at http://www.json.org/java/index.html import org.json.JSONObject; import com.amazonaws.auth.AWSCredentials; import com.amazonaws.auth.BasicAWSCredentials; import com.amazonaws.services.securitytoken.AWSSecurityTokenServiceClient; import com.amazonaws.services.securitytoken.model.Credentials; import com.amazonaws.services.securitytoken.model.GetFederationTokenRequest; import com.amazonaws.services.securitytoken.model.GetFederationTokenResult; /* Calls to AWS STS API operations must be signed using the access key ID and secret access key of an IAM user or using existing temporary credentials. The credentials should not be embedded in code. For this example, the code looks for the credentials in a standard configuration file. */ AWSCredentials credentials = new PropertiesCredentials( AwsConsoleApp.class.getResourceAsStream("AwsCredentials.properties")); AWSSecurityTokenServiceClient stsClient = new AWSSecurityTokenServiceClient(credentials); GetFederationTokenRequest getFederationTokenRequest = new GetFederationTokenRequest(); getFederationTokenRequest.setDurationSeconds(1800); getFederationTokenRequest.setName("UserName"); // A sample policy for accessing Amazon Simple Notification Service (Amazon SNS) in the console. String policy = "{\"Version\":\"2012-10-17\", \"Statement\":[{\"Action\":\"sns:*\"," + "\"Effect\":\"Allow\",\"Resource\":\"*\"}]}"; getFederationTokenRequest.setPolicy(policy); GetFederationTokenResult federationTokenResult = stsClient.getFederationToken(getFederationTokenRequest); Credentials federatedCredentials = federationTokenResult.getCredentials(); // The issuer parameter specifies your internal sign-in // page, for example https://mysignin.internal.mycompany.com/. // The console parameter specifies the URL to the destination console of the // AWS Management Console. This example goes to Amazon SNS. // The signin parameter is the URL to send the request to. String issuerURL = "https://mysignin.internal.mycompany.com/"; String consoleURL = "https://console.aws.amazon.com/sns"; String signInURL = "https://signin.aws.amazon.com/federation"; // Create the sign-in token using temporary credentials, // including the access key ID, secret access key, and session token. String sessionJson = String.format( "{\"%1$s\":\"%2$s\",\"%3$s\":\"%4$s\",\"%5$s\":\"%6$s\"}", "sessionId", federatedCredentials.getAccessKeyId(), "sessionKey", federatedCredentials.getSecretAccessKey(), "sessionToken", federatedCredentials.getSessionToken()); // Construct the sign-in request with the request sign-in token action, a // 12-hour console session duration, and the JSON document with temporary // credentials as parameters. String getSigninTokenURL = signInURL + "?Action=getSigninToken" + "&DurationSeconds=43200" + "&SessionType=json&Session=" + URLEncoder.encode(sessionJson,"UTF-8"); URL url = new URL(getSigninTokenURL); // Send the request to the AWS federation endpoint to get the sign-in token URLConnection conn = url.openConnection (); BufferedReader bufferReader = new BufferedReader(new InputStreamReader(conn.getInputStream())); String returnContent = bufferReader.readLine(); String signinToken = new JSONObject(returnContent).getString("SigninToken"); String signinTokenParameter = "&SigninToken=" + URLEncoder.encode(signinToken,"UTF-8"); // The issuer parameter is optional, but recommended. Use it to direct users // to your sign-in page when their session expires. String issuerParameter = "&Issuer=" + URLEncoder.encode(issuerURL, "UTF-8"); // Finally, present the completed URL for the AWS console session to the user String destinationParameter = "&Destination=" + URLEncoder.encode(consoleURL,"UTF-8"); String loginURL = signInURL + "?Action=login" + signinTokenParameter + issuerParameter + destinationParameter; ``` ## Example showing how to construct the URL (Ruby) The following example shows how to use Ruby to programmatically construct a URL that gives users direct access to the AWS Management Console. This code snippet uses the [AWS SDK for Ruby](http://aws.amazon.com/documentation/sdkforruby/). ``` require 'rubygems' require 'json' require 'open-uri' require 'cgi' require 'aws-sdk' # Create a new STS instance # # Note: Calls to AWS STS API operations must be signed using an access key ID # and secret access key. The credentials can be in EC2 instance metadata # or in environment variables and will be automatically discovered by # the default credentials provider in the AWS Ruby SDK. sts = Aws::STS::Client.new() # The following call creates a temporary session that returns # temporary security credentials and a session token. # The policy grants permissions to work # in the AWS SNS console. session = sts.get_federation_token({ duration_seconds: 1800, name: "UserName", policy: "{\"Version\":\"2012-10-17\", \"Statement\":{\"Effect\":\"Allow\",\"Action\":\"sns:*\",\"Resource\":\"*\"}}", }) # The issuer value is the URL where users are directed (such as # to your internal sign-in page) when their session expires. # # The console value specifies the URL to the destination console. # This example goes to the Amazon SNS console. # # The sign-in value is the URL of the AWS STS federation endpoint. issuer_url = "https://mysignin.internal.mycompany.com/" console_url = "https://console.aws.amazon.com/sns" signin_url = "https://signin.aws.amazon.com/federation" # Create a block of JSON that contains the temporary credentials # (including the access key ID, secret access key, and session token). session_json = { :sessionId => session.credentials[:access_key_id], :sessionKey => session.credentials[:secret_access_key], :sessionToken => session.credentials[:session_token] }.to_json # Call the federation endpoint, passing the parameters # created earlier and the session information as a JSON block. # The request returns a sign-in token that's valid for 15 minutes. # Signing in to the console with the token creates a session # that is valid for 12 hours. get_signin_token_url = signin_url + "?Action=getSigninToken" + "&SessionType=json&Session=" + CGI.escape(session_json) returned_content = URI.parse(get_signin_token_url).read # Extract the sign-in token from the information returned # by the federation endpoint. signin_token = JSON.parse(returned_content)['SigninToken'] signin_token_param = "&SigninToken=" + CGI.escape(signin_token) # Create the URL to give to the user, which includes the # sign-in token and the URL of the console to open. # The "issuer" parameter is optional but recommended. issuer_param = "&Issuer=" + CGI.escape(issuer_url) destination_param = "&Destination=" + CGI.escape(console_url) login_url = signin_url + "?Action=login" + signin_token_param + issuer_param + destination_param ```