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