1 // Code generated by smithy-go-codegen DO NOT EDIT. 2 3 package sts 4 5 import ( 6 "context" 7 "fmt" 8 awsmiddleware "github.com/aws/aws-sdk-go-v2/aws/middleware" 9 "github.com/aws/aws-sdk-go-v2/aws/signer/v4" 10 "github.com/aws/aws-sdk-go-v2/service/sts/types" 11 "github.com/aws/smithy-go/middleware" 12 smithyhttp "github.com/aws/smithy-go/transport/http" 13 ) 14 15 // Returns a set of temporary security credentials that you can use to access 16 // Amazon Web Services resources. These temporary credentials consist of an access 17 // key ID, a secret access key, and a security token. Typically, you use AssumeRole 18 // within your account or for cross-account access. For a comparison of AssumeRole 19 // with other API operations that produce temporary credentials, see Requesting 20 // Temporary Security Credentials (https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_request.html) 21 // and Comparing the Amazon Web Services STS API operations (https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_request.html#stsapi_comparison) 22 // in the IAM User Guide. Permissions The temporary security credentials created by 23 // AssumeRole can be used to make API calls to any Amazon Web Services service 24 // with the following exception: You cannot call the Amazon Web Services STS 25 // GetFederationToken or GetSessionToken API operations. (Optional) You can pass 26 // inline or managed session policies (https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_session) 27 // to this operation. You can pass a single JSON policy document to use as an 28 // inline session policy. You can also specify up to 10 managed policy Amazon 29 // Resource Names (ARNs) to use as managed session policies. The plaintext that you 30 // use for both inline and managed session policies can't exceed 2,048 characters. 31 // Passing policies to this operation returns new temporary credentials. The 32 // resulting session's permissions are the intersection of the role's 33 // identity-based policy and the session policies. You can use the role's temporary 34 // credentials in subsequent Amazon Web Services API calls to access resources in 35 // the account that owns the role. You cannot use session policies to grant more 36 // permissions than those allowed by the identity-based policy of the role that is 37 // being assumed. For more information, see Session Policies (https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_session) 38 // in the IAM User Guide. When you create a role, you create two policies: a role 39 // trust policy that specifies who can assume the role, and a permissions policy 40 // that specifies what can be done with the role. You specify the trusted principal 41 // that is allowed to assume the role in the role trust policy. To assume a role 42 // from a different account, your Amazon Web Services account must be trusted by 43 // the role. The trust relationship is defined in the role's trust policy when the 44 // role is created. That trust policy states which accounts are allowed to delegate 45 // that access to users in the account. A user who wants to access a role in a 46 // different account must also have permissions that are delegated from the account 47 // administrator. The administrator must attach a policy that allows the user to 48 // call AssumeRole for the ARN of the role in the other account. To allow a user 49 // to assume a role in the same account, you can do either of the following: 50 // - Attach a policy to the user that allows the user to call AssumeRole (as long 51 // as the role's trust policy trusts the account). 52 // - Add the user as a principal directly in the role's trust policy. 53 // 54 // You can do either because the role’s trust policy acts as an IAM resource-based 55 // policy. When a resource-based policy grants access to a principal in the same 56 // account, no additional identity-based policy is required. For more information 57 // about trust policies and resource-based policies, see IAM Policies (https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) 58 // in the IAM User Guide. Tags (Optional) You can pass tag key-value pairs to your 59 // session. These tags are called session tags. For more information about session 60 // tags, see Passing Session Tags in STS (https://docs.aws.amazon.com/IAM/latest/UserGuide/id_session-tags.html) 61 // in the IAM User Guide. An administrator must grant you the permissions necessary 62 // to pass session tags. The administrator can also create granular permissions to 63 // allow you to pass only specific session tags. For more information, see 64 // Tutorial: Using Tags for Attribute-Based Access Control (https://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_attribute-based-access-control.html) 65 // in the IAM User Guide. You can set the session tags as transitive. Transitive 66 // tags persist during role chaining. For more information, see Chaining Roles 67 // with Session Tags (https://docs.aws.amazon.com/IAM/latest/UserGuide/id_session-tags.html#id_session-tags_role-chaining) 68 // in the IAM User Guide. Using MFA with AssumeRole (Optional) You can include 69 // multi-factor authentication (MFA) information when you call AssumeRole . This is 70 // useful for cross-account scenarios to ensure that the user that assumes the role 71 // has been authenticated with an Amazon Web Services MFA device. In that scenario, 72 // the trust policy of the role being assumed includes a condition that tests for 73 // MFA authentication. If the caller does not include valid MFA information, the 74 // request to assume the role is denied. The condition in a trust policy that tests 75 // for MFA authentication might look like the following example. "Condition": 76 // {"Bool": {"aws:MultiFactorAuthPresent": true}} For more information, see 77 // Configuring MFA-Protected API Access (https://docs.aws.amazon.com/IAM/latest/UserGuide/MFAProtectedAPI.html) 78 // in the IAM User Guide guide. To use MFA with AssumeRole , you pass values for 79 // the SerialNumber and TokenCode parameters. The SerialNumber value identifies 80 // the user's hardware or virtual MFA device. The TokenCode is the time-based 81 // one-time password (TOTP) that the MFA device produces. 82 func (c *Client) AssumeRole(ctx context.Context, params *AssumeRoleInput, optFns ...func(*Options)) (*AssumeRoleOutput, error) { 83 if params == nil { 84 params = &AssumeRoleInput{} 85 } 86 87 result, metadata, err := c.invokeOperation(ctx, "AssumeRole", params, optFns, c.addOperationAssumeRoleMiddlewares) 88 if err != nil { 89 return nil, err 90 } 91 92 out := result.(*AssumeRoleOutput) 93 out.ResultMetadata = metadata 94 return out, nil 95 } 96 97 type AssumeRoleInput struct { 98 99 // The Amazon Resource Name (ARN) of the role to assume. 100 // 101 // This member is required. 102 RoleArn *string 103 104 // An identifier for the assumed role session. Use the role session name to 105 // uniquely identify a session when the same role is assumed by different 106 // principals or for different reasons. In cross-account scenarios, the role 107 // session name is visible to, and can be logged by the account that owns the role. 108 // The role session name is also used in the ARN of the assumed role principal. 109 // This means that subsequent cross-account API requests that use the temporary 110 // security credentials will expose the role session name to the external account 111 // in their CloudTrail logs. The regex used to validate this parameter is a string 112 // of characters consisting of upper- and lower-case alphanumeric characters with 113 // no spaces. You can also include underscores or any of the following characters: 114 // =,.@- 115 // 116 // This member is required. 117 RoleSessionName *string 118 119 // The duration, in seconds, of the role session. The value specified can range 120 // from 900 seconds (15 minutes) up to the maximum session duration set for the 121 // role. The maximum session duration setting can have a value from 1 hour to 12 122 // hours. If you specify a value higher than this setting or the administrator 123 // setting (whichever is lower), the operation fails. For example, if you specify a 124 // session duration of 12 hours, but your administrator set the maximum session 125 // duration to 6 hours, your operation fails. Role chaining limits your Amazon Web 126 // Services CLI or Amazon Web Services API role session to a maximum of one hour. 127 // When you use the AssumeRole API operation to assume a role, you can specify the 128 // duration of your role session with the DurationSeconds parameter. You can 129 // specify a parameter value of up to 43200 seconds (12 hours), depending on the 130 // maximum session duration setting for your role. However, if you assume a role 131 // using role chaining and provide a DurationSeconds parameter value greater than 132 // one hour, the operation fails. To learn how to view the maximum value for your 133 // role, see 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) 134 // in the IAM User Guide. By default, the value is set to 3600 seconds. The 135 // DurationSeconds parameter is separate from the duration of a console session 136 // that you might request using the returned credentials. The request to the 137 // federation endpoint for a console sign-in token takes a SessionDuration 138 // parameter that specifies the maximum length of the console session. For more 139 // information, see Creating a URL that Enables Federated Users to Access the 140 // Amazon Web Services Management Console (https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_enable-console-custom-url.html) 141 // in the IAM User Guide. 142 DurationSeconds *int32 143 144 // A unique identifier that might be required when you assume a role in another 145 // account. If the administrator of the account to which the role belongs provided 146 // you with an external ID, then provide that value in the ExternalId parameter. 147 // This value can be any string, such as a passphrase or account number. A 148 // cross-account role is usually set up to trust everyone in an account. Therefore, 149 // the administrator of the trusting account might send an external ID to the 150 // administrator of the trusted account. That way, only someone with the ID can 151 // assume the role, rather than everyone in the account. For more information about 152 // the external ID, see How to Use an External ID When Granting Access to Your 153 // Amazon Web Services Resources to a Third Party (https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html) 154 // in the IAM User Guide. The regex used to validate this parameter is a string of 155 // characters consisting of upper- and lower-case alphanumeric characters with no 156 // spaces. You can also include underscores or any of the following characters: 157 // =,.@:/- 158 ExternalId *string 159 160 // An IAM policy in JSON format that you want to use as an inline session policy. 161 // This parameter is optional. Passing policies to this operation returns new 162 // temporary credentials. The resulting session's permissions are the intersection 163 // of the role's identity-based policy and the session policies. You can use the 164 // role's temporary credentials in subsequent Amazon Web Services API calls to 165 // access resources in the account that owns the role. You cannot use session 166 // policies to grant more permissions than those allowed by the identity-based 167 // policy of the role that is being assumed. For more information, see Session 168 // Policies (https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_session) 169 // in the IAM User Guide. The plaintext that you use for both inline and managed 170 // session policies can't exceed 2,048 characters. The JSON policy characters can 171 // be any ASCII character from the space character to the end of the valid 172 // character list (\u0020 through \u00FF). It can also include the tab (\u0009), 173 // linefeed (\u000A), and carriage return (\u000D) characters. An Amazon Web 174 // Services conversion compresses the passed inline session policy, managed policy 175 // ARNs, and session tags into a packed binary format that has a separate limit. 176 // Your request can fail for this limit even if your plaintext meets the other 177 // requirements. The PackedPolicySize response element indicates by percentage how 178 // close the policies and tags for your request are to the upper size limit. 179 Policy *string 180 181 // The Amazon Resource Names (ARNs) of the IAM managed policies that you want to 182 // use as managed session policies. The policies must exist in the same account as 183 // the role. This parameter is optional. You can provide up to 10 managed policy 184 // ARNs. However, the plaintext that you use for both inline and managed session 185 // policies can't exceed 2,048 characters. For more information about ARNs, see 186 // Amazon Resource Names (ARNs) and Amazon Web Services Service Namespaces (https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) 187 // in the Amazon Web Services General Reference. An Amazon Web Services conversion 188 // compresses the passed inline session policy, managed policy ARNs, and session 189 // tags into a packed binary format that has a separate limit. Your request can 190 // fail for this limit even if your plaintext meets the other requirements. The 191 // PackedPolicySize response element indicates by percentage how close the policies 192 // and tags for your request are to the upper size limit. Passing policies to this 193 // operation returns new temporary credentials. The resulting session's permissions 194 // are the intersection of the role's identity-based policy and the session 195 // policies. You can use the role's temporary credentials in subsequent Amazon Web 196 // Services API calls to access resources in the account that owns the role. You 197 // cannot use session policies to grant more permissions than those allowed by the 198 // identity-based policy of the role that is being assumed. For more information, 199 // see Session Policies (https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_session) 200 // in the IAM User Guide. 201 PolicyArns []types.PolicyDescriptorType 202 203 // A list of previously acquired trusted context assertions in the format of a 204 // JSON array. The trusted context assertion is signed and encrypted by Amazon Web 205 // Services STS. The following is an example of a ProvidedContext value that 206 // includes a single trusted context assertion and the ARN of the context provider 207 // from which the trusted context assertion was generated. 208 // [{"ProviderArn":"arn:aws:iam::aws:contextProvider/IdentityCenter","ContextAssertion":"trusted-context-assertion"}] 209 ProvidedContexts []types.ProvidedContext 210 211 // The identification number of the MFA device that is associated with the user 212 // who is making the AssumeRole call. Specify this value if the trust policy of 213 // the role being assumed includes a condition that requires MFA authentication. 214 // The value is either the serial number for a hardware device (such as 215 // GAHT12345678 ) or an Amazon Resource Name (ARN) for a virtual device (such as 216 // arn:aws:iam::123456789012:mfa/user ). The regex used to validate this parameter 217 // is a string of characters consisting of upper- and lower-case alphanumeric 218 // characters with no spaces. You can also include underscores or any of the 219 // following characters: =,.@- 220 SerialNumber *string 221 222 // The source identity specified by the principal that is calling the AssumeRole 223 // operation. You can require users to specify a source identity when they assume a 224 // role. You do this by using the sts:SourceIdentity condition key in a role trust 225 // policy. You can use source identity information in CloudTrail logs to determine 226 // who took actions with a role. You can use the aws:SourceIdentity condition key 227 // to further control access to Amazon Web Services resources based on the value of 228 // source identity. For more information about using source identity, see Monitor 229 // and control actions taken with assumed roles (https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_control-access_monitor.html) 230 // in the IAM User Guide. The regex used to validate this parameter is a string of 231 // characters consisting of upper- and lower-case alphanumeric characters with no 232 // spaces. You can also include underscores or any of the following characters: 233 // =,.@-. You cannot use a value that begins with the text aws: . This prefix is 234 // reserved for Amazon Web Services internal use. 235 SourceIdentity *string 236 237 // A list of session tags that you want to pass. Each session tag consists of a 238 // key name and an associated value. For more information about session tags, see 239 // Tagging Amazon Web Services STS Sessions (https://docs.aws.amazon.com/IAM/latest/UserGuide/id_session-tags.html) 240 // in the IAM User Guide. This parameter is optional. You can pass up to 50 session 241 // tags. The plaintext session tag keys can’t exceed 128 characters, and the values 242 // can’t exceed 256 characters. For these and additional limits, see IAM and STS 243 // Character Limits (https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_iam-limits.html#reference_iam-limits-entity-length) 244 // in the IAM User Guide. An Amazon Web Services conversion compresses the passed 245 // inline session policy, managed policy ARNs, and session tags into a packed 246 // binary format that has a separate limit. Your request can fail for this limit 247 // even if your plaintext meets the other requirements. The PackedPolicySize 248 // response element indicates by percentage how close the policies and tags for 249 // your request are to the upper size limit. You can pass a session tag with the 250 // same key as a tag that is already attached to the role. When you do, session 251 // tags override a role tag with the same key. Tag key–value pairs are not case 252 // sensitive, but case is preserved. This means that you cannot have separate 253 // Department and department tag keys. Assume that the role has the Department = 254 // Marketing tag and you pass the department = engineering session tag. Department 255 // and department are not saved as separate tags, and the session tag passed in 256 // the request takes precedence over the role tag. Additionally, if you used 257 // temporary credentials to perform this operation, the new session inherits any 258 // transitive session tags from the calling session. If you pass a session tag with 259 // the same key as an inherited tag, the operation fails. To view the inherited 260 // tags for a session, see the CloudTrail logs. For more information, see Viewing 261 // Session Tags in CloudTrail (https://docs.aws.amazon.com/IAM/latest/UserGuide/id_session-tags.html#id_session-tags_ctlogs) 262 // in the IAM User Guide. 263 Tags []types.Tag 264 265 // The value provided by the MFA device, if the trust policy of the role being 266 // assumed requires MFA. (In other words, if the policy includes a condition that 267 // tests for MFA). If the role being assumed requires MFA and if the TokenCode 268 // value is missing or expired, the AssumeRole call returns an "access denied" 269 // error. The format for this parameter, as described by its regex pattern, is a 270 // sequence of six numeric digits. 271 TokenCode *string 272 273 // A list of keys for session tags that you want to set as transitive. If you set 274 // a tag key as transitive, the corresponding key and value passes to subsequent 275 // sessions in a role chain. For more information, see Chaining Roles with Session 276 // Tags (https://docs.aws.amazon.com/IAM/latest/UserGuide/id_session-tags.html#id_session-tags_role-chaining) 277 // in the IAM User Guide. This parameter is optional. When you set session tags as 278 // transitive, the session policy and session tags packed binary limit is not 279 // affected. If you choose not to specify a transitive tag key, then no tags are 280 // passed from this session to any subsequent sessions. 281 TransitiveTagKeys []string 282 283 noSmithyDocumentSerde 284 } 285 286 // Contains the response to a successful AssumeRole request, including temporary 287 // Amazon Web Services credentials that can be used to make Amazon Web Services 288 // requests. 289 type AssumeRoleOutput struct { 290 291 // The Amazon Resource Name (ARN) and the assumed role ID, which are identifiers 292 // that you can use to refer to the resulting temporary security credentials. For 293 // example, you can reference these credentials as a principal in a resource-based 294 // policy by using the ARN or assumed role ID. The ARN and ID include the 295 // RoleSessionName that you specified when you called AssumeRole . 296 AssumedRoleUser *types.AssumedRoleUser 297 298 // The temporary security credentials, which include an access key ID, a secret 299 // access key, and a security (or session) token. The size of the security token 300 // that STS API operations return is not fixed. We strongly recommend that you make 301 // no assumptions about the maximum size. 302 Credentials *types.Credentials 303 304 // A percentage value that indicates the packed size of the session policies and 305 // session tags combined passed in the request. The request fails if the packed 306 // size is greater than 100 percent, which means the policies and tags exceeded the 307 // allowed space. 308 PackedPolicySize *int32 309 310 // The source identity specified by the principal that is calling the AssumeRole 311 // operation. You can require users to specify a source identity when they assume a 312 // role. You do this by using the sts:SourceIdentity condition key in a role trust 313 // policy. You can use source identity information in CloudTrail logs to determine 314 // who took actions with a role. You can use the aws:SourceIdentity condition key 315 // to further control access to Amazon Web Services resources based on the value of 316 // source identity. For more information about using source identity, see Monitor 317 // and control actions taken with assumed roles (https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_control-access_monitor.html) 318 // in the IAM User Guide. The regex used to validate this parameter is a string of 319 // characters consisting of upper- and lower-case alphanumeric characters with no 320 // spaces. You can also include underscores or any of the following characters: 321 // =,.@- 322 SourceIdentity *string 323 324 // Metadata pertaining to the operation's result. 325 ResultMetadata middleware.Metadata 326 327 noSmithyDocumentSerde 328 } 329 330 func (c *Client) addOperationAssumeRoleMiddlewares(stack *middleware.Stack, options Options) (err error) { 331 if err := stack.Serialize.Add(&setOperationInputMiddleware{}, middleware.After); err != nil { 332 return err 333 } 334 err = stack.Serialize.Add(&awsAwsquery_serializeOpAssumeRole{}, middleware.After) 335 if err != nil { 336 return err 337 } 338 err = stack.Deserialize.Add(&awsAwsquery_deserializeOpAssumeRole{}, middleware.After) 339 if err != nil { 340 return err 341 } 342 if err := addProtocolFinalizerMiddlewares(stack, options, "AssumeRole"); err != nil { 343 return fmt.Errorf("add protocol finalizers: %v", err) 344 } 345 346 if err = addlegacyEndpointContextSetter(stack, options); err != nil { 347 return err 348 } 349 if err = addSetLoggerMiddleware(stack, options); err != nil { 350 return err 351 } 352 if err = addClientRequestID(stack); err != nil { 353 return err 354 } 355 if err = addComputeContentLength(stack); err != nil { 356 return err 357 } 358 if err = addResolveEndpointMiddleware(stack, options); err != nil { 359 return err 360 } 361 if err = addComputePayloadSHA256(stack); err != nil { 362 return err 363 } 364 if err = addRetry(stack, options); err != nil { 365 return err 366 } 367 if err = addRawResponseToMetadata(stack); err != nil { 368 return err 369 } 370 if err = addRecordResponseTiming(stack); err != nil { 371 return err 372 } 373 if err = addClientUserAgent(stack, options); err != nil { 374 return err 375 } 376 if err = smithyhttp.AddErrorCloseResponseBodyMiddleware(stack); err != nil { 377 return err 378 } 379 if err = smithyhttp.AddCloseResponseBodyMiddleware(stack); err != nil { 380 return err 381 } 382 if err = addSetLegacyContextSigningOptionsMiddleware(stack); err != nil { 383 return err 384 } 385 if err = addOpAssumeRoleValidationMiddleware(stack); err != nil { 386 return err 387 } 388 if err = stack.Initialize.Add(newServiceMetadataMiddleware_opAssumeRole(options.Region), middleware.Before); err != nil { 389 return err 390 } 391 if err = addRecursionDetection(stack); err != nil { 392 return err 393 } 394 if err = addRequestIDRetrieverMiddleware(stack); err != nil { 395 return err 396 } 397 if err = addResponseErrorMiddleware(stack); err != nil { 398 return err 399 } 400 if err = addRequestResponseLogging(stack, options); err != nil { 401 return err 402 } 403 if err = addDisableHTTPSMiddleware(stack, options); err != nil { 404 return err 405 } 406 return nil 407 } 408 409 func newServiceMetadataMiddleware_opAssumeRole(region string) *awsmiddleware.RegisterServiceMetadata { 410 return &awsmiddleware.RegisterServiceMetadata{ 411 Region: region, 412 ServiceID: ServiceID, 413 OperationName: "AssumeRole", 414 } 415 } 416 417 // PresignAssumeRole is used to generate a presigned HTTP Request which contains 418 // presigned URL, signed headers and HTTP method used. 419 func (c *PresignClient) PresignAssumeRole(ctx context.Context, params *AssumeRoleInput, optFns ...func(*PresignOptions)) (*v4.PresignedHTTPRequest, error) { 420 if params == nil { 421 params = &AssumeRoleInput{} 422 } 423 options := c.options.copy() 424 for _, fn := range optFns { 425 fn(&options) 426 } 427 clientOptFns := append(options.ClientOptions, withNopHTTPClientAPIOption) 428 429 result, _, err := c.client.invokeOperation(ctx, "AssumeRole", params, clientOptFns, 430 c.client.addOperationAssumeRoleMiddlewares, 431 presignConverter(options).convertToPresignMiddleware, 432 ) 433 if err != nil { 434 return nil, err 435 } 436 437 out := result.(*v4.PresignedHTTPRequest) 438 return out, nil 439 } 440