api_op_AssumeRoleWithSAML.go (19997B)
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/service/sts/types" 9 "github.com/aws/smithy-go/middleware" 10 smithyhttp "github.com/aws/smithy-go/transport/http" 11 ) 12 13 // Returns a set of temporary security credentials for users who have been 14 // authenticated via a SAML authentication response. This operation provides a 15 // mechanism for tying an enterprise identity store or directory to role-based 16 // Amazon Web Services access without user-specific credentials or configuration. 17 // For a comparison of AssumeRoleWithSAML with the other API operations that 18 // produce temporary credentials, see Requesting Temporary Security Credentials 19 // (https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_request.html) 20 // and Comparing the Amazon Web Services STS API operations 21 // (https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_request.html#stsapi_comparison) 22 // in the IAM User Guide. The temporary security credentials returned by this 23 // operation consist of an access key ID, a secret access key, and a security 24 // token. Applications can use these temporary security credentials to sign calls 25 // to Amazon Web Services services. Session Duration By default, the temporary 26 // security credentials created by AssumeRoleWithSAML last for one hour. However, 27 // you can use the optional DurationSeconds parameter to specify the duration of 28 // your session. Your role session lasts for the duration that you specify, or 29 // until the time specified in the SAML authentication response's 30 // SessionNotOnOrAfter value, whichever is shorter. You can provide a 31 // DurationSeconds value from 900 seconds (15 minutes) up to the maximum session 32 // duration setting for the role. This setting can have a value from 1 hour to 12 33 // hours. To learn how to view the maximum value for your role, see View the 34 // Maximum Session Duration Setting for a Role 35 // (https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html#id_roles_use_view-role-max-session) 36 // in the IAM User Guide. The maximum session duration limit applies when you use 37 // the AssumeRole* API operations or the assume-role* CLI commands. However the 38 // limit does not apply when you use those operations to create a console URL. For 39 // more information, see Using IAM Roles 40 // (https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html) in the IAM 41 // User Guide. Role chaining 42 // (https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html#iam-term-role-chaining) 43 // limits your CLI or Amazon Web Services API role session to a maximum of one 44 // hour. When you use the AssumeRole API operation to assume a role, you can 45 // specify the duration of your role session with the DurationSeconds parameter. 46 // You can specify a parameter value of up to 43200 seconds (12 hours), depending 47 // on the maximum session duration setting for your role. However, if you assume a 48 // role using role chaining and provide a DurationSeconds parameter value greater 49 // than one hour, the operation fails. Permissions The temporary security 50 // credentials created by AssumeRoleWithSAML can be used to make API calls to any 51 // Amazon Web Services service with the following exception: you cannot call the 52 // STS GetFederationToken or GetSessionToken API operations. (Optional) You can 53 // pass inline or managed session policies 54 // (https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_session) 55 // to this operation. You can pass a single JSON policy document to use as an 56 // inline session policy. You can also specify up to 10 managed policies to use as 57 // managed session policies. The plaintext that you use for both inline and managed 58 // session policies can't exceed 2,048 characters. Passing policies to this 59 // operation returns new temporary credentials. The resulting session's permissions 60 // are the intersection of the role's identity-based policy and the session 61 // policies. You can use the role's temporary credentials in subsequent Amazon Web 62 // Services API calls to access resources in the account that owns the role. You 63 // cannot use session policies to grant more permissions than those allowed by the 64 // identity-based policy of the role that is being assumed. For more information, 65 // see Session Policies 66 // (https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_session) 67 // in the IAM User Guide. Calling AssumeRoleWithSAML does not require the use of 68 // Amazon Web Services security credentials. The identity of the caller is 69 // validated by using keys in the metadata document that is uploaded for the SAML 70 // provider entity for your identity provider. Calling AssumeRoleWithSAML can 71 // result in an entry in your CloudTrail logs. The entry includes the value in the 72 // NameID element of the SAML assertion. We recommend that you use a NameIDType 73 // that is not associated with any personally identifiable information (PII). For 74 // example, you could instead use the persistent identifier 75 // (urn:oasis:names:tc:SAML:2.0:nameid-format:persistent). Tags (Optional) You can 76 // configure your IdP to pass attributes into your SAML assertion as session tags. 77 // Each session tag consists of a key name and an associated value. For more 78 // information about session tags, see Passing Session Tags in STS 79 // (https://docs.aws.amazon.com/IAM/latest/UserGuide/id_session-tags.html) in the 80 // IAM User Guide. You can pass up to 50 session tags. The plaintext session tag 81 // keys can’t exceed 128 characters and the values can’t exceed 256 characters. For 82 // these and additional limits, see IAM and STS Character Limits 83 // (https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_iam-limits.html#reference_iam-limits-entity-length) 84 // in the IAM User Guide. An Amazon Web Services conversion compresses the passed 85 // session policies 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 by 88 // percentage how close the policies and tags for your request are to the upper 89 // size limit. You can pass a session tag with the same key as a tag that is 90 // attached to the role. When you do, session tags override the role's tags with 91 // the same key. An administrator must grant you the permissions necessary to pass 92 // session tags. The administrator can also create granular permissions to allow 93 // you to pass only specific session tags. For more information, see Tutorial: 94 // Using Tags for Attribute-Based Access Control 95 // (https://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_attribute-based-access-control.html) 96 // in the IAM User Guide. You can set the session tags as transitive. Transitive 97 // tags persist during role chaining. For more information, see Chaining Roles with 98 // Session Tags 99 // (https://docs.aws.amazon.com/IAM/latest/UserGuide/id_session-tags.html#id_session-tags_role-chaining) 100 // in the IAM User Guide. SAML Configuration Before your application can call 101 // AssumeRoleWithSAML, you must configure your SAML identity provider (IdP) to 102 // issue the claims required by Amazon Web Services. Additionally, you must use 103 // Identity and Access Management (IAM) to create a SAML provider entity in your 104 // Amazon Web Services account that represents your identity provider. You must 105 // also create an IAM role that specifies this SAML provider in its trust policy. 106 // For more information, see the following resources: 107 // 108 // * About SAML 2.0-based 109 // Federation 110 // (https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_saml.html) 111 // in the IAM User Guide. 112 // 113 // * Creating SAML Identity Providers 114 // (https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml.html) 115 // in the IAM User Guide. 116 // 117 // * Configuring a Relying Party and Claims 118 // (https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml_relying-party.html) 119 // in the IAM User Guide. 120 // 121 // * Creating a Role for SAML 2.0 Federation 122 // (https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_saml.html) 123 // in the IAM User Guide. 124 func (c *Client) AssumeRoleWithSAML(ctx context.Context, params *AssumeRoleWithSAMLInput, optFns ...func(*Options)) (*AssumeRoleWithSAMLOutput, error) { 125 if params == nil { 126 params = &AssumeRoleWithSAMLInput{} 127 } 128 129 result, metadata, err := c.invokeOperation(ctx, "AssumeRoleWithSAML", params, optFns, c.addOperationAssumeRoleWithSAMLMiddlewares) 130 if err != nil { 131 return nil, err 132 } 133 134 out := result.(*AssumeRoleWithSAMLOutput) 135 out.ResultMetadata = metadata 136 return out, nil 137 } 138 139 type AssumeRoleWithSAMLInput struct { 140 141 // The Amazon Resource Name (ARN) of the SAML provider in IAM that describes the 142 // IdP. 143 // 144 // This member is required. 145 PrincipalArn *string 146 147 // The Amazon Resource Name (ARN) of the role that the caller is assuming. 148 // 149 // This member is required. 150 RoleArn *string 151 152 // The base64 encoded SAML authentication response provided by the IdP. For more 153 // information, see Configuring a Relying Party and Adding Claims 154 // (https://docs.aws.amazon.com/IAM/latest/UserGuide/create-role-saml-IdP-tasks.html) 155 // in the IAM User Guide. 156 // 157 // This member is required. 158 SAMLAssertion *string 159 160 // The duration, in seconds, of the role session. Your role session lasts for the 161 // duration that you specify for the DurationSeconds parameter, or until the time 162 // specified in the SAML authentication response's SessionNotOnOrAfter value, 163 // whichever is shorter. You can provide a DurationSeconds value from 900 seconds 164 // (15 minutes) up to the maximum session duration setting for the role. This 165 // setting can have a value from 1 hour to 12 hours. If you specify a value higher 166 // than this setting, the operation fails. For example, if you specify a session 167 // duration of 12 hours, but your administrator set the maximum session duration to 168 // 6 hours, your operation fails. To learn how to view the maximum value for your 169 // role, see View the Maximum Session Duration Setting for a Role 170 // (https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html#id_roles_use_view-role-max-session) 171 // in the IAM User Guide. By default, the value is set to 3600 seconds. The 172 // DurationSeconds parameter is separate from the duration of a console session 173 // that you might request using the returned credentials. The request to the 174 // federation endpoint for a console sign-in token takes a SessionDuration 175 // parameter that specifies the maximum length of the console session. For more 176 // information, see Creating a URL that Enables Federated Users to Access the 177 // Amazon Web Services Management Console 178 // (https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_enable-console-custom-url.html) 179 // in the IAM User Guide. 180 DurationSeconds *int32 181 182 // An IAM policy in JSON format that you want to use as an inline session policy. 183 // This parameter is optional. Passing policies to this operation returns new 184 // temporary credentials. The resulting session's permissions are the intersection 185 // of the role's identity-based policy and the session policies. You can use the 186 // role's temporary credentials in subsequent Amazon Web Services API calls to 187 // access resources in the account that owns the role. You cannot use session 188 // policies to grant more permissions than those allowed by the identity-based 189 // policy of the role that is being assumed. For more information, see Session 190 // Policies 191 // (https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_session) 192 // in the IAM User Guide. The plaintext that you use for both inline and managed 193 // session policies can't exceed 2,048 characters. The JSON policy characters can 194 // be any ASCII character from the space character to the end of the valid 195 // character list (\u0020 through \u00FF). It can also include the tab (\u0009), 196 // linefeed (\u000A), and carriage return (\u000D) characters. An Amazon Web 197 // Services conversion compresses the passed session policies and session tags into 198 // a packed binary format that has a separate limit. Your request can fail for this 199 // limit even if your plaintext meets the other requirements. The PackedPolicySize 200 // response element indicates by percentage how close the policies and tags for 201 // your request are to the upper size limit. 202 Policy *string 203 204 // The Amazon Resource Names (ARNs) of the IAM managed policies that you want to 205 // use as managed session policies. The policies must exist in the same account as 206 // the role. This parameter is optional. You can provide up to 10 managed policy 207 // ARNs. However, the plaintext that you use for both inline and managed session 208 // policies can't exceed 2,048 characters. For more information about ARNs, see 209 // Amazon Resource Names (ARNs) and Amazon Web Services Service Namespaces 210 // (https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) in 211 // the Amazon Web Services General Reference. An Amazon Web Services conversion 212 // compresses the passed session policies and session tags into a packed binary 213 // format that has a separate limit. Your request can fail for this limit even if 214 // your plaintext meets the other requirements. The PackedPolicySize response 215 // element indicates by percentage how close the policies and tags for your request 216 // are to the upper size limit. Passing policies to this operation returns new 217 // temporary credentials. The resulting session's permissions are the intersection 218 // of the role's identity-based policy and the session policies. You can use the 219 // role's temporary credentials in subsequent Amazon Web Services API calls to 220 // access resources in the account that owns the role. You cannot use session 221 // policies to grant more permissions than those allowed by the identity-based 222 // policy of the role that is being assumed. For more information, see Session 223 // Policies 224 // (https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_session) 225 // in the IAM User Guide. 226 PolicyArns []types.PolicyDescriptorType 227 228 noSmithyDocumentSerde 229 } 230 231 // Contains the response to a successful AssumeRoleWithSAML request, including 232 // temporary Amazon Web Services credentials that can be used to make Amazon Web 233 // Services requests. 234 type AssumeRoleWithSAMLOutput struct { 235 236 // The identifiers for the temporary security credentials that the operation 237 // returns. 238 AssumedRoleUser *types.AssumedRoleUser 239 240 // The value of the Recipient attribute of the SubjectConfirmationData element of 241 // the SAML assertion. 242 Audience *string 243 244 // The temporary security credentials, which include an access key ID, a secret 245 // access key, and a security (or session) token. The size of the security token 246 // that STS API operations return is not fixed. We strongly recommend that you make 247 // no assumptions about the maximum size. 248 Credentials *types.Credentials 249 250 // The value of the Issuer element of the SAML assertion. 251 Issuer *string 252 253 // A hash value based on the concatenation of the following: 254 // 255 // * The Issuer response 256 // value. 257 // 258 // * The Amazon Web Services account ID. 259 // 260 // * The friendly name (the last 261 // part of the ARN) of the SAML provider in IAM. 262 // 263 // The combination of NameQualifier 264 // and Subject can be used to uniquely identify a federated user. The following 265 // pseudocode shows how the hash value is calculated: BASE64 ( SHA1 ( 266 // "https://example.com/saml" + "123456789012" + "/MySAMLIdP" ) ) 267 NameQualifier *string 268 269 // A percentage value that indicates the packed size of the session policies and 270 // session tags combined passed in the request. The request fails if the packed 271 // size is greater than 100 percent, which means the policies and tags exceeded the 272 // allowed space. 273 PackedPolicySize *int32 274 275 // The value in the SourceIdentity attribute in the SAML assertion. You can require 276 // users to set a source identity value when they assume a role. You do this by 277 // using the sts:SourceIdentity condition key in a role trust policy. That way, 278 // actions that are taken with the role are associated with that user. After the 279 // source identity is set, the value cannot be changed. It is present in the 280 // request for all actions that are taken by the role and persists across chained 281 // role 282 // (https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts#iam-term-role-chaining) 283 // sessions. You can configure your SAML identity provider to use an attribute 284 // associated with your users, like user name or email, as the source identity when 285 // calling AssumeRoleWithSAML. You do this by adding an attribute to the SAML 286 // assertion. For more information about using source identity, see Monitor and 287 // control actions taken with assumed roles 288 // (https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_control-access_monitor.html) 289 // in the IAM User Guide. The regex used to validate this parameter is a string of 290 // characters consisting of upper- and lower-case alphanumeric characters with no 291 // spaces. You can also include underscores or any of the following characters: 292 // =,.@- 293 SourceIdentity *string 294 295 // The value of the NameID element in the Subject element of the SAML assertion. 296 Subject *string 297 298 // The format of the name ID, as defined by the Format attribute in the NameID 299 // element of the SAML assertion. Typical examples of the format are transient or 300 // persistent. If the format includes the prefix 301 // urn:oasis:names:tc:SAML:2.0:nameid-format, that prefix is removed. For example, 302 // urn:oasis:names:tc:SAML:2.0:nameid-format:transient is returned as transient. If 303 // the format includes any other prefix, the format is returned with no 304 // modifications. 305 SubjectType *string 306 307 // Metadata pertaining to the operation's result. 308 ResultMetadata middleware.Metadata 309 310 noSmithyDocumentSerde 311 } 312 313 func (c *Client) addOperationAssumeRoleWithSAMLMiddlewares(stack *middleware.Stack, options Options) (err error) { 314 err = stack.Serialize.Add(&awsAwsquery_serializeOpAssumeRoleWithSAML{}, middleware.After) 315 if err != nil { 316 return err 317 } 318 err = stack.Deserialize.Add(&awsAwsquery_deserializeOpAssumeRoleWithSAML{}, middleware.After) 319 if err != nil { 320 return err 321 } 322 if err = addSetLoggerMiddleware(stack, options); err != nil { 323 return err 324 } 325 if err = awsmiddleware.AddClientRequestIDMiddleware(stack); err != nil { 326 return err 327 } 328 if err = smithyhttp.AddComputeContentLengthMiddleware(stack); err != nil { 329 return err 330 } 331 if err = addResolveEndpointMiddleware(stack, options); err != nil { 332 return err 333 } 334 if err = addRetryMiddlewares(stack, options); err != nil { 335 return err 336 } 337 if err = awsmiddleware.AddRawResponseToMetadata(stack); err != nil { 338 return err 339 } 340 if err = awsmiddleware.AddRecordResponseTiming(stack); err != nil { 341 return err 342 } 343 if err = addClientUserAgent(stack); err != nil { 344 return err 345 } 346 if err = smithyhttp.AddErrorCloseResponseBodyMiddleware(stack); err != nil { 347 return err 348 } 349 if err = smithyhttp.AddCloseResponseBodyMiddleware(stack); err != nil { 350 return err 351 } 352 if err = addOpAssumeRoleWithSAMLValidationMiddleware(stack); err != nil { 353 return err 354 } 355 if err = stack.Initialize.Add(newServiceMetadataMiddleware_opAssumeRoleWithSAML(options.Region), middleware.Before); err != nil { 356 return err 357 } 358 if err = addRequestIDRetrieverMiddleware(stack); err != nil { 359 return err 360 } 361 if err = addResponseErrorMiddleware(stack); err != nil { 362 return err 363 } 364 if err = addRequestResponseLogging(stack, options); err != nil { 365 return err 366 } 367 return nil 368 } 369 370 func newServiceMetadataMiddleware_opAssumeRoleWithSAML(region string) *awsmiddleware.RegisterServiceMetadata { 371 return &awsmiddleware.RegisterServiceMetadata{ 372 Region: region, 373 ServiceID: ServiceID, 374 SigningName: "sts", 375 OperationName: "AssumeRoleWithSAML", 376 } 377 }