AWS Tools for Windows PowerShell
Command Reference

AWS services or capabilities described in AWS Documentation may vary by region/location. Click Getting Started with Amazon AWS to see specific differences applicable to the China (Beijing) Region.

Synopsis

Invokes the AssumeRoleWithWebIdentity operation against AWS Security Token Service.

Syntax

Use-STSWebIdentityRole
-RoleArn <String>
-RoleSessionName <String>
-WebIdentityToken <String>
-ProviderId <String>
-Policy <String>
-Duration <Nullable<Int32>>
-Region <String>

Description

Returns a set of temporary security credentials for users who have been authenticated in a mobile or web application with a web identity provider, such as Login with Amazon, Facebook, or Google. AssumeRoleWithWebIdentity is an API call that does not require the use of AWS security credentials. Therefore, you can distribute an application (for example, on mobile devices) that requests temporary security credentials without including long-term AWS credentials in the application or by deploying server-based proxy services that use long-term AWS credentials. For more information, see Creating a Mobile Application with Third-Party Sign-In in AWS Security Token Service . The temporary security credentials consist of an access key ID, a secret access key, and a security token. Applications can use these temporary security credentials to sign calls to AWS service APIs. The credentials are valid for the duration that you specified when calling AssumeRoleWithWebIdentity , which can be from 900 seconds (15 minutes) to 3600 seconds (1 hour). By default, the temporary security credentials are valid for 1 hour. The temporary security credentials that are returned from the AssumeRoleWithWebIdentity response have the permissions that are associated with the access policy of the role being assumed and any policies that are associated with the AWS resource being accessed. You can further restrict the permissions of the temporary security credentials by passing a policy in the request. The resulting permissions are an intersection of both policies. The role's access policy and the policy that you passed are evaluated when calls to AWS service APIs are made using the temporary security credentials. Before your application can call AssumeRoleWithWebIdentity , you must have an identity token from an identity provider and create a role that the application can assume. Typically, to get an identity token, you need to register your application with the identity provider and get a unique application ID from that provider. Also, when you create the role that the application assumes, you must specify the registered identity provider as a principal (establish trust with the identity provider). For more information, see Creating Temporary Security Credentials for Mobile Apps Using Third-Party Identity Providers.

Parameters

-Duration <Nullable<Int32>>
The duration, in seconds, of the role session. The value can range from 900 seconds (15 minutes) to 3600 seconds (1 hour). By default, the value is set to 3600 seconds. Constraints:Range900 - 129600
Required?False
Position?Named
Accept pipeline input?False
-Policy <String>
A supplemental policy that is associated with the temporary security credentials from the AssumeRoleWithWebIdentity call. The resulting permissions of the temporary security credentials are an intersection of this policy and the access policy that is associated with the role. Use this policy to further restrict the permissions of the temporary security credentials. Constraints:Length1 - 2048Pattern[\u0009\u000A\u000D\u0020-\u00FF]+
Required?False
Position?5
Accept pipeline input?False
-ProviderId <String>
Specify this value only for OAuth access tokens. Do not specify this value for OpenID Connect id tokens, such as accounts.google.com. This is the fully-qualified host component of the domain name of the identity provider. Do not include URL schemes and port numbers. Currently, www.amazon.com and graph.facebook.com are supported. Constraints:Length4 - 2048
Required?False
Position?4
Accept pipeline input?False
-Region <String>
The region to use. STS has a single endpoint irrespective of region, though STS in GovCloud and China (Beijing) has its own endpoint.
Required?False
Position?Named
Accept pipeline input?False
-RoleArn <String>
The Amazon Resource Name (ARN) of the role that the caller is assuming. Constraints:Length20 - 2048
Required?False
Position?1
Accept pipeline input?True (ByValue, )
-RoleSessionName <String>
An identifier for the assumed role session. Typically, you pass the name or identifier that is associated with the user who is using your application. That way, the temporary security credentials that your application will use are associated with that user. This session name is included as part of the ARN and assumed role ID in the AssumedRoleUser response element. Constraints:Length2 - 32Pattern[\w+=,.@-]*
Required?False
Position?2
Accept pipeline input?False
-WebIdentityToken <String>
The OAuth 2.0 access token or OpenID Connect id token that is provided by the identity provider. Your application must get this token by authenticating the user who is using your application with a web identity provider before the application makes an AssumeRoleWithWebIdentity call. Constraints:Length4 - 2048
Required?False
Position?3
Accept pipeline input?False

Inputs

You can pipe a String object to this cmdlet for the RoleArn parameter.

Outputs

This cmdlet returns an Amazon.SecurityToken.Model.AssumeRoleWithWebIdentityResult instance. The service response (type Amazon.SecurityToken.Model.AssumeRoleWithWebIdentityResponse) is added to the cmdlet entry in the $AWSHistory stack.

Examples

Example 1

PS C:\>Use-STSWebIdentityRole -DurationInSeconds 3600 -ProviderId "www.amazon.com" -RoleSessionName "app1" -RoleArn "arn:aws:iam::123456789012:role/FederatedWebIdentityRole" -WebIdentityToken "Atza...DVI0r1"
Returns a temporary set of credentials, valid for one hour, for a user who has been authenticated with the Login with Amazon identity provider. The credentials assume the access policy associated with the role identified by the role ARN. Optionally, you can pass a JSON policy to the -Policy parameter that further refine the access permissions (you cannot grant more permissions than are available in the permissions associated with the role). The value supplied to the -WebIdentityToken is the unique user identifier that was returned by the identity provider.

Supported Version

AWS Tools for PowerShell: 2.x.y.z