1// Code generated by smithy-go-codegen DO NOT EDIT.
2
3package sts
4
5import (
6 "context"
7 "fmt"
8 awsmiddleware "github.com/aws/aws-sdk-go-v2/aws/middleware"
9 "github.com/aws/aws-sdk-go-v2/service/sts/types"
10 "github.com/aws/smithy-go/middleware"
11 smithyhttp "github.com/aws/smithy-go/transport/http"
12)
13
14// Returns a set of temporary security credentials for users who have been
15// authenticated in a mobile or web application with a web identity provider.
16// Example providers include the OAuth 2.0 providers Login with Amazon and
17// Facebook, or any OpenID Connect-compatible identity provider such as Google or [Amazon Cognito federated identities].
18//
19// For mobile applications, we recommend that you use Amazon Cognito. You can use
20// Amazon Cognito with the [Amazon Web Services SDK for iOS Developer Guide]and the [Amazon Web Services SDK for Android Developer Guide] to uniquely identify a user. You can also
21// supply the user with a consistent identity throughout the lifetime of an
22// application.
23//
24// To learn more about Amazon Cognito, see [Amazon Cognito identity pools] in Amazon Cognito Developer Guide.
25//
26// Calling AssumeRoleWithWebIdentity does not require the use of Amazon Web
27// Services security credentials. Therefore, you can distribute an application (for
28// example, on mobile devices) that requests temporary security credentials without
29// including long-term Amazon Web Services credentials in the application. You also
30// don't need to deploy server-based proxy services that use long-term Amazon Web
31// Services credentials. Instead, the identity of the caller is validated by using
32// a token from the web identity provider. For a comparison of
33// AssumeRoleWithWebIdentity with the other API operations that produce temporary
34// credentials, see [Requesting Temporary Security Credentials]and [Comparing the Amazon Web Services STS API operations] in the IAM User Guide.
35//
36// The temporary security credentials returned by this API consist of an access
37// key ID, a secret access key, and a security token. Applications can use these
38// temporary security credentials to sign calls to Amazon Web Services service API
39// operations.
40//
41// # Session Duration
42//
43// By default, the temporary security credentials created by
44// AssumeRoleWithWebIdentity last for one hour. However, you can use the optional
45// DurationSeconds parameter to specify the duration of your session. You can
46// provide a value from 900 seconds (15 minutes) up to the maximum session duration
47// setting for the role. This setting can have a value from 1 hour to 12 hours. To
48// learn how to view the maximum value for your role, see [View the Maximum Session Duration Setting for a Role]in the IAM User Guide.
49// The maximum session duration limit applies when you use the AssumeRole* API
50// operations or the assume-role* CLI commands. However the limit does not apply
51// when you use those operations to create a console URL. For more information, see
52// [Using IAM Roles]in the IAM User Guide.
53//
54// # Permissions
55//
56// The temporary security credentials created by AssumeRoleWithWebIdentity can be
57// used to make API calls to any Amazon Web Services service with the following
58// exception: you cannot call the STS GetFederationToken or GetSessionToken API
59// operations.
60//
61// (Optional) You can pass inline or managed [session policies] to this operation. You can pass a
62// single JSON policy document to use as an inline session policy. You can also
63// specify up to 10 managed policy Amazon Resource Names (ARNs) to use as managed
64// session policies. The plaintext that you use for both inline and managed session
65// policies can't exceed 2,048 characters. Passing policies to this operation
66// returns new temporary credentials. The resulting session's permissions are the
67// intersection of the role's identity-based policy and the session policies. You
68// can use the role's temporary credentials in subsequent Amazon Web Services API
69// calls to access resources in the account that owns the role. You cannot use
70// session policies to grant more permissions than those allowed by the
71// identity-based policy of the role that is being assumed. For more information,
72// see [Session Policies]in the IAM User Guide.
73//
74// # Tags
75//
76// (Optional) You can configure your IdP to pass attributes into your web identity
77// token as session tags. Each session tag consists of a key name and an associated
78// value. For more information about session tags, see [Passing Session Tags in STS]in the IAM User Guide.
79//
80// You can pass up to 50 session tags. The plaintext session tag keys can’t exceed
81// 128 characters and the values can’t exceed 256 characters. For these and
82// additional limits, see [IAM and STS Character Limits]in the IAM User Guide.
83//
84// An Amazon Web Services conversion compresses the passed inline session policy,
85// managed policy ARNs, and session tags into a packed binary format that has a
86// separate limit. Your request can fail for this limit even if your plaintext
87// meets the other requirements. The PackedPolicySize response element indicates
88// by percentage how close the policies and tags for your request are to the upper
89// size limit.
90//
91// You can pass a session tag with the same key as a tag that is attached to the
92// role. When you do, the session tag overrides the role tag with the same key.
93//
94// An administrator must grant you the permissions necessary to pass session tags.
95// The administrator can also create granular permissions to allow you to pass only
96// specific session tags. For more information, see [Tutorial: Using Tags for Attribute-Based Access Control]in the IAM User Guide.
97//
98// You can set the session tags as transitive. Transitive tags persist during role
99// chaining. For more information, see [Chaining Roles with Session Tags]in the IAM User Guide.
100//
101// # Identities
102//
103// Before your application can call AssumeRoleWithWebIdentity , you must have an
104// identity token from a supported identity provider and create a role that the
105// application can assume. The role that your application assumes must trust the
106// identity provider that is associated with the identity token. In other words,
107// the identity provider must be specified in the role's trust policy.
108//
109// Calling AssumeRoleWithWebIdentity can result in an entry in your CloudTrail
110// logs. The entry includes the [Subject]of the provided web identity token. We recommend
111// that you avoid using any personally identifiable information (PII) in this
112// field. For example, you could instead use a GUID or a pairwise identifier, as [suggested in the OIDC specification].
113//
114// For more information about how to use web identity federation and the
115// AssumeRoleWithWebIdentity API, see the following resources:
116//
117// [Using Web Identity Federation API Operations for Mobile Apps]
118// - and [Federation Through a Web-based Identity Provider].
119//
120// [Web Identity Federation Playground]
121// - . Walk through the process of authenticating through Login with Amazon,
122// Facebook, or Google, getting temporary security credentials, and then using
123// those credentials to make a request to Amazon Web Services.
124//
125// [Amazon Web Services SDK for iOS Developer Guide]
126// - and [Amazon Web Services SDK for Android Developer Guide]. These toolkits contain sample apps that show how to invoke the
127// identity providers. The toolkits then show how to use the information from these
128// providers to get and use temporary security credentials.
129//
130// [Web Identity Federation with Mobile Applications]
131// - . This article discusses web identity federation and shows an example of
132// how to use web identity federation to get access to content in Amazon S3.
133//
134// [Amazon Web Services SDK for iOS Developer Guide]: http://aws.amazon.com/sdkforios/
135// [View the Maximum Session Duration Setting for a Role]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html#id_roles_use_view-role-max-session
136// [Web Identity Federation Playground]: https://aws.amazon.com/blogs/aws/the-aws-web-identity-federation-playground/
137// [Amazon Web Services SDK for Android Developer Guide]: http://aws.amazon.com/sdkforandroid/
138// [IAM and STS Character Limits]: https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_iam-limits.html#reference_iam-limits-entity-length
139// [Comparing the Amazon Web Services STS API operations]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_request.html#stsapi_comparison
140// [session policies]: https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_session
141// [Requesting Temporary Security Credentials]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_request.html
142// [Subject]: http://openid.net/specs/openid-connect-core-1_0.html#Claims
143// [Tutorial: Using Tags for Attribute-Based Access Control]: https://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_attribute-based-access-control.html
144// [Amazon Cognito identity pools]: https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html
145// [Federation Through a Web-based Identity Provider]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_request.html#api_assumerolewithwebidentity
146// [Using IAM Roles]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html
147// [Session Policies]: https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_session
148// [Amazon Cognito federated identities]: https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html
149// [Passing Session Tags in STS]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_session-tags.html
150// [Chaining Roles with Session Tags]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_session-tags.html#id_session-tags_role-chaining
151// [Web Identity Federation with Mobile Applications]: http://aws.amazon.com/articles/web-identity-federation-with-mobile-applications
152// [Using Web Identity Federation API Operations for Mobile Apps]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc_manual.html
153// [suggested in the OIDC specification]: http://openid.net/specs/openid-connect-core-1_0.html#SubjectIDTypes
154func (c *Client) AssumeRoleWithWebIdentity(ctx context.Context, params *AssumeRoleWithWebIdentityInput, optFns ...func(*Options)) (*AssumeRoleWithWebIdentityOutput, error) {
155 if params == nil {
156 params = &AssumeRoleWithWebIdentityInput{}
157 }
158
159 result, metadata, err := c.invokeOperation(ctx, "AssumeRoleWithWebIdentity", params, optFns, c.addOperationAssumeRoleWithWebIdentityMiddlewares)
160 if err != nil {
161 return nil, err
162 }
163
164 out := result.(*AssumeRoleWithWebIdentityOutput)
165 out.ResultMetadata = metadata
166 return out, nil
167}
168
169type AssumeRoleWithWebIdentityInput struct {
170
171 // The Amazon Resource Name (ARN) of the role that the caller is assuming.
172 //
173 // This member is required.
174 RoleArn *string
175
176 // An identifier for the assumed role session. Typically, you pass the name or
177 // identifier that is associated with the user who is using your application. That
178 // way, the temporary security credentials that your application will use are
179 // associated with that user. This session name is included as part of the ARN and
180 // assumed role ID in the AssumedRoleUser response element.
181 //
182 // The regex used to validate this parameter is a string of characters consisting
183 // of upper- and lower-case alphanumeric characters with no spaces. You can also
184 // include underscores or any of the following characters: =,.@-
185 //
186 // This member is required.
187 RoleSessionName *string
188
189 // The OAuth 2.0 access token or OpenID Connect ID token that is provided by the
190 // identity provider. Your application must get this token by authenticating the
191 // user who is using your application with a web identity provider before the
192 // application makes an AssumeRoleWithWebIdentity call. Only tokens with RSA
193 // algorithms (RS256) are supported.
194 //
195 // This member is required.
196 WebIdentityToken *string
197
198 // The duration, in seconds, of the role session. The value can range from 900
199 // seconds (15 minutes) up to the maximum session duration setting for the role.
200 // This setting can have a value from 1 hour to 12 hours. If you specify a value
201 // higher than this setting, the operation fails. For example, if you specify a
202 // session duration of 12 hours, but your administrator set the maximum session
203 // duration to 6 hours, your operation fails. To learn how to view the maximum
204 // value for your role, see [View the Maximum Session Duration Setting for a Role]in the IAM User Guide.
205 //
206 // By default, the value is set to 3600 seconds.
207 //
208 // The DurationSeconds parameter is separate from the duration of a console
209 // session that you might request using the returned credentials. The request to
210 // the federation endpoint for a console sign-in token takes a SessionDuration
211 // parameter that specifies the maximum length of the console session. For more
212 // information, see [Creating a URL that Enables Federated Users to Access the Amazon Web Services Management Console]in the IAM User Guide.
213 //
214 // [View the Maximum Session Duration Setting for a Role]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html#id_roles_use_view-role-max-session
215 // [Creating a URL that Enables Federated Users to Access the Amazon Web Services Management Console]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_enable-console-custom-url.html
216 DurationSeconds *int32
217
218 // An IAM policy in JSON format that you want to use as an inline session policy.
219 //
220 // This parameter is optional. Passing policies to this operation returns new
221 // temporary credentials. The resulting session's permissions are the intersection
222 // of the role's identity-based policy and the session policies. You can use the
223 // role's temporary credentials in subsequent Amazon Web Services API calls to
224 // access resources in the account that owns the role. You cannot use session
225 // policies to grant more permissions than those allowed by the identity-based
226 // policy of the role that is being assumed. For more information, see [Session Policies]in the IAM
227 // User Guide.
228 //
229 // The plaintext that you use for both inline and managed session policies can't
230 // exceed 2,048 characters. The JSON policy characters can be any ASCII character
231 // from the space character to the end of the valid character list (\u0020 through
232 // \u00FF). It can also include the tab (\u0009), linefeed (\u000A), and carriage
233 // return (\u000D) characters.
234 //
235 // An Amazon Web Services conversion compresses the passed inline session policy,
236 // managed policy ARNs, and session tags into a packed binary format that has a
237 // separate limit. Your request can fail for this limit even if your plaintext
238 // meets the other requirements. The PackedPolicySize response element indicates
239 // by percentage how close the policies and tags for your request are to the upper
240 // size limit.
241 //
242 // [Session Policies]: https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_session
243 Policy *string
244
245 // The Amazon Resource Names (ARNs) of the IAM managed policies that you want to
246 // use as managed session policies. The policies must exist in the same account as
247 // the role.
248 //
249 // This parameter is optional. You can provide up to 10 managed policy ARNs.
250 // However, the plaintext that you use for both inline and managed session policies
251 // can't exceed 2,048 characters. For more information about ARNs, see [Amazon Resource Names (ARNs) and Amazon Web Services Service Namespaces]in the
252 // Amazon Web Services General Reference.
253 //
254 // An Amazon Web Services conversion compresses the passed inline session policy,
255 // managed policy ARNs, and session tags into a packed binary format that has a
256 // separate limit. Your request can fail for this limit even if your plaintext
257 // meets the other requirements. The PackedPolicySize response element indicates
258 // by percentage how close the policies and tags for your request are to the upper
259 // size limit.
260 //
261 // Passing policies to this operation returns new temporary credentials. The
262 // resulting session's permissions are the intersection of the role's
263 // identity-based policy and the session policies. You can use the role's temporary
264 // credentials in subsequent Amazon Web Services API calls to access resources in
265 // the account that owns the role. You cannot use session policies to grant more
266 // permissions than those allowed by the identity-based policy of the role that is
267 // being assumed. For more information, see [Session Policies]in the IAM User Guide.
268 //
269 // [Session Policies]: https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_session
270 // [Amazon Resource Names (ARNs) and Amazon Web Services Service Namespaces]: https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html
271 PolicyArns []types.PolicyDescriptorType
272
273 // The fully qualified host component of the domain name of the OAuth 2.0 identity
274 // provider. Do not specify this value for an OpenID Connect identity provider.
275 //
276 // Currently www.amazon.com and graph.facebook.com are the only supported identity
277 // providers for OAuth 2.0 access tokens. Do not include URL schemes and port
278 // numbers.
279 //
280 // Do not specify this value for OpenID Connect ID tokens.
281 ProviderId *string
282
283 noSmithyDocumentSerde
284}
285
286// Contains the response to a successful AssumeRoleWithWebIdentity request, including temporary Amazon Web
287// Services credentials that can be used to make Amazon Web Services requests.
288type AssumeRoleWithWebIdentityOutput struct {
289
290 // The Amazon Resource Name (ARN) and the assumed role ID, which are identifiers
291 // that you can use to refer to the resulting temporary security credentials. For
292 // example, you can reference these credentials as a principal in a resource-based
293 // policy by using the ARN or assumed role ID. The ARN and ID include the
294 // RoleSessionName that you specified when you called AssumeRole .
295 AssumedRoleUser *types.AssumedRoleUser
296
297 // The intended audience (also known as client ID) of the web identity token. This
298 // is traditionally the client identifier issued to the application that requested
299 // the web identity token.
300 Audience *string
301
302 // The temporary security credentials, which include an access key ID, a secret
303 // access key, and a security token.
304 //
305 // The size of the security token that STS API operations return is not fixed. We
306 // strongly recommend that you make no assumptions about the maximum size.
307 Credentials *types.Credentials
308
309 // A percentage value that indicates the packed size of the session policies and
310 // session tags combined passed in the request. The request fails if the packed
311 // size is greater than 100 percent, which means the policies and tags exceeded the
312 // allowed space.
313 PackedPolicySize *int32
314
315 // The issuing authority of the web identity token presented. For OpenID Connect
316 // ID tokens, this contains the value of the iss field. For OAuth 2.0 access
317 // tokens, this contains the value of the ProviderId parameter that was passed in
318 // the AssumeRoleWithWebIdentity request.
319 Provider *string
320
321 // The value of the source identity that is returned in the JSON web token (JWT)
322 // from the identity provider.
323 //
324 // You can require users to set a source identity value when they assume a role.
325 // You do this by using the sts:SourceIdentity condition key in a role trust
326 // policy. That way, actions that are taken with the role are associated with that
327 // user. After the source identity is set, the value cannot be changed. It is
328 // present in the request for all actions that are taken by the role and persists
329 // across [chained role]sessions. You can configure your identity provider to use an attribute
330 // associated with your users, like user name or email, as the source identity when
331 // calling AssumeRoleWithWebIdentity . You do this by adding a claim to the JSON
332 // web token. To learn more about OIDC tokens and claims, see [Using Tokens with User Pools]in the Amazon
333 // Cognito Developer Guide. For more information about using source identity, see [Monitor and control actions taken with assumed roles]
334 // in the IAM User Guide.
335 //
336 // The regex used to validate this parameter is a string of characters consisting
337 // of upper- and lower-case alphanumeric characters with no spaces. You can also
338 // include underscores or any of the following characters: =,.@-
339 //
340 // [chained role]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts#iam-term-role-chaining
341 // [Monitor and control actions taken with assumed roles]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_control-access_monitor.html
342 // [Using Tokens with User Pools]: https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html
343 SourceIdentity *string
344
345 // The unique user identifier that is returned by the identity provider. This
346 // identifier is associated with the WebIdentityToken that was submitted with the
347 // AssumeRoleWithWebIdentity call. The identifier is typically unique to the user
348 // and the application that acquired the WebIdentityToken (pairwise identifier).
349 // For OpenID Connect ID tokens, this field contains the value returned by the
350 // identity provider as the token's sub (Subject) claim.
351 SubjectFromWebIdentityToken *string
352
353 // Metadata pertaining to the operation's result.
354 ResultMetadata middleware.Metadata
355
356 noSmithyDocumentSerde
357}
358
359func (c *Client) addOperationAssumeRoleWithWebIdentityMiddlewares(stack *middleware.Stack, options Options) (err error) {
360 if err := stack.Serialize.Add(&setOperationInputMiddleware{}, middleware.After); err != nil {
361 return err
362 }
363 err = stack.Serialize.Add(&awsAwsquery_serializeOpAssumeRoleWithWebIdentity{}, middleware.After)
364 if err != nil {
365 return err
366 }
367 err = stack.Deserialize.Add(&awsAwsquery_deserializeOpAssumeRoleWithWebIdentity{}, middleware.After)
368 if err != nil {
369 return err
370 }
371 if err := addProtocolFinalizerMiddlewares(stack, options, "AssumeRoleWithWebIdentity"); err != nil {
372 return fmt.Errorf("add protocol finalizers: %v", err)
373 }
374
375 if err = addlegacyEndpointContextSetter(stack, options); err != nil {
376 return err
377 }
378 if err = addSetLoggerMiddleware(stack, options); err != nil {
379 return err
380 }
381 if err = addClientRequestID(stack); err != nil {
382 return err
383 }
384 if err = addComputeContentLength(stack); err != nil {
385 return err
386 }
387 if err = addResolveEndpointMiddleware(stack, options); err != nil {
388 return err
389 }
390 if err = addRetry(stack, options); err != nil {
391 return err
392 }
393 if err = addRawResponseToMetadata(stack); err != nil {
394 return err
395 }
396 if err = addRecordResponseTiming(stack); err != nil {
397 return err
398 }
399 if err = addClientUserAgent(stack, options); err != nil {
400 return err
401 }
402 if err = smithyhttp.AddErrorCloseResponseBodyMiddleware(stack); err != nil {
403 return err
404 }
405 if err = smithyhttp.AddCloseResponseBodyMiddleware(stack); err != nil {
406 return err
407 }
408 if err = addSetLegacyContextSigningOptionsMiddleware(stack); err != nil {
409 return err
410 }
411 if err = addTimeOffsetBuild(stack, c); err != nil {
412 return err
413 }
414 if err = addUserAgentRetryMode(stack, options); err != nil {
415 return err
416 }
417 if err = addOpAssumeRoleWithWebIdentityValidationMiddleware(stack); err != nil {
418 return err
419 }
420 if err = stack.Initialize.Add(newServiceMetadataMiddleware_opAssumeRoleWithWebIdentity(options.Region), middleware.Before); err != nil {
421 return err
422 }
423 if err = addRecursionDetection(stack); err != nil {
424 return err
425 }
426 if err = addRequestIDRetrieverMiddleware(stack); err != nil {
427 return err
428 }
429 if err = addResponseErrorMiddleware(stack); err != nil {
430 return err
431 }
432 if err = addRequestResponseLogging(stack, options); err != nil {
433 return err
434 }
435 if err = addDisableHTTPSMiddleware(stack, options); err != nil {
436 return err
437 }
438 return nil
439}
440
441func newServiceMetadataMiddleware_opAssumeRoleWithWebIdentity(region string) *awsmiddleware.RegisterServiceMetadata {
442 return &awsmiddleware.RegisterServiceMetadata{
443 Region: region,
444 ServiceID: ServiceID,
445 OperationName: "AssumeRoleWithWebIdentity",
446 }
447}