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