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