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 (consisting of an access key
15// ID, a secret access key, and a security token) for a user. A typical use is in a
16// proxy application that gets temporary security credentials on behalf of
17// distributed applications inside a corporate network.
18//
19// You must call the GetFederationToken operation using the long-term security
20// credentials of an IAM user. As a result, this call is appropriate in contexts
21// where those credentials can be safeguarded, usually in a server-based
22// application. For a comparison of GetFederationToken with the other API
23// operations that produce temporary credentials, see [Requesting Temporary Security Credentials]and [Comparing the Amazon Web Services STS API operations] in the IAM User Guide.
24//
25// Although it is possible to call GetFederationToken using the security
26// credentials of an Amazon Web Services account root user rather than an IAM user
27// that you create for the purpose of a proxy application, we do not recommend it.
28// For more information, see [Safeguard your root user credentials and don't use them for everyday tasks]in the IAM User Guide.
29//
30// You can create a mobile-based or browser-based app that can authenticate users
31// using a web identity provider like Login with Amazon, Facebook, Google, or an
32// OpenID Connect-compatible identity provider. In this case, we recommend that you
33// use [Amazon Cognito]or AssumeRoleWithWebIdentity . For more information, see [Federation Through a Web-based Identity Provider] in the IAM User
34// Guide.
35//
36// # Session duration
37//
38// The temporary credentials are valid for the specified duration, from 900
39// seconds (15 minutes) up to a maximum of 129,600 seconds (36 hours). The default
40// session duration is 43,200 seconds (12 hours). Temporary credentials obtained by
41// using the root user credentials have a maximum duration of 3,600 seconds (1
42// hour).
43//
44// # Permissions
45//
46// You can use the temporary credentials created by GetFederationToken in any
47// Amazon Web Services service with the following exceptions:
48//
49// - You cannot call any IAM operations using the CLI or the Amazon Web Services
50// API. This limitation does not apply to console sessions.
51//
52// - You cannot call any STS operations except GetCallerIdentity .
53//
54// You can use temporary credentials for single sign-on (SSO) to the console.
55//
56// You must pass an inline or managed [session policy] to this operation. You can pass a single
57// JSON policy document to use as an inline session policy. You can also specify up
58// to 10 managed policy Amazon Resource Names (ARNs) to use as managed session
59// policies. The plaintext that you use for both inline and managed session
60// policies can't exceed 2,048 characters.
61//
62// Though the session policy parameters are optional, if you do not pass a policy,
63// then the resulting federated user session has no permissions. When you pass
64// session policies, the session permissions are the intersection of the IAM user
65// policies and the session policies that you pass. This gives you a way to further
66// restrict the permissions for a federated user. You cannot use session policies
67// to grant more permissions than those that are defined in the permissions policy
68// of the IAM user. For more information, see [Session Policies]in the IAM User Guide. For
69// information about using GetFederationToken to create temporary security
70// credentials, see [GetFederationTokenâFederation Through a Custom Identity Broker].
71//
72// You can use the credentials to access a resource that has a resource-based
73// policy. If that policy specifically references the federated user session in the
74// Principal element of the policy, the session has the permissions allowed by the
75// policy. These permissions are granted in addition to the permissions granted by
76// the session policies.
77//
78// # Tags
79//
80// (Optional) You can pass tag key-value pairs to your session. These are called
81// session tags. For more information about session tags, see [Passing Session Tags in STS]in the IAM User
82// Guide.
83//
84// You can create a mobile-based or browser-based app that can authenticate users
85// using a web identity provider like Login with Amazon, Facebook, Google, or an
86// OpenID Connect-compatible identity provider. In this case, we recommend that you
87// use [Amazon Cognito]or AssumeRoleWithWebIdentity . For more information, see [Federation Through a Web-based Identity Provider] in the IAM User
88// Guide.
89//
90// An administrator must grant you the permissions necessary to pass session tags.
91// The administrator can also create granular permissions to allow you to pass only
92// specific session tags. For more information, see [Tutorial: Using Tags for Attribute-Based Access Control]in the IAM User Guide.
93//
94// Tag keyâvalue pairs are not case sensitive, but case is preserved. This means
95// that you cannot have separate Department and department tag keys. Assume that
96// the user that you are federating has the Department = Marketing tag and you
97// pass the department = engineering session tag. Department and department are
98// not saved as separate tags, and the session tag passed in the request takes
99// precedence over the user tag.
100//
101// [Federation Through a Web-based Identity Provider]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_request.html#api_assumerolewithwebidentity
102// [session policy]: https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_session
103// [Amazon Cognito]: http://aws.amazon.com/cognito/
104// [Session Policies]: https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_session
105// [Passing Session Tags in STS]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_session-tags.html
106// [GetFederationTokenâFederation Through a Custom Identity Broker]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_request.html#api_getfederationtoken
107// [Comparing the Amazon Web Services STS API operations]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_request.html#stsapi_comparison
108// [Safeguard your root user credentials and don't use them for everyday tasks]: https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#lock-away-credentials
109// [Requesting Temporary Security Credentials]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_request.html
110// [Tutorial: Using Tags for Attribute-Based Access Control]: https://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_attribute-based-access-control.html
111func (c *Client) GetFederationToken(ctx context.Context, params *GetFederationTokenInput, optFns ...func(*Options)) (*GetFederationTokenOutput, error) {
112 if params == nil {
113 params = &GetFederationTokenInput{}
114 }
115
116 result, metadata, err := c.invokeOperation(ctx, "GetFederationToken", params, optFns, c.addOperationGetFederationTokenMiddlewares)
117 if err != nil {
118 return nil, err
119 }
120
121 out := result.(*GetFederationTokenOutput)
122 out.ResultMetadata = metadata
123 return out, nil
124}
125
126type GetFederationTokenInput struct {
127
128 // The name of the federated user. The name is used as an identifier for the
129 // temporary security credentials (such as Bob ). For example, you can reference
130 // the federated user name in a resource-based policy, such as in an Amazon S3
131 // bucket policy.
132 //
133 // The regex used to validate this parameter is a string of characters consisting
134 // of upper- and lower-case alphanumeric characters with no spaces. You can also
135 // include underscores or any of the following characters: =,.@-
136 //
137 // This member is required.
138 Name *string
139
140 // The duration, in seconds, that the session should last. Acceptable durations
141 // for federation sessions range from 900 seconds (15 minutes) to 129,600 seconds
142 // (36 hours), with 43,200 seconds (12 hours) as the default. Sessions obtained
143 // using root user credentials are restricted to a maximum of 3,600 seconds (one
144 // hour). If the specified duration is longer than one hour, the session obtained
145 // by using root user credentials defaults to one hour.
146 DurationSeconds *int32
147
148 // An IAM policy in JSON format that you want to use as an inline session policy.
149 //
150 // You must pass an inline or managed [session policy] to this operation. You can pass a single
151 // JSON policy document to use as an inline session policy. You can also specify up
152 // to 10 managed policy Amazon Resource Names (ARNs) to use as managed session
153 // policies.
154 //
155 // This parameter is optional. However, if you do not pass any session policies,
156 // then the resulting federated user session has no permissions.
157 //
158 // When you pass session policies, the session permissions are the intersection of
159 // the IAM user policies and the session policies that you pass. This gives you a
160 // way to further restrict the permissions for a federated user. You cannot use
161 // session policies to grant more permissions than those that are defined in the
162 // permissions policy of the IAM user. For more information, see [Session Policies]in the IAM User
163 // Guide.
164 //
165 // The resulting credentials can be used to access a resource that has a
166 // resource-based policy. If that policy specifically references the federated user
167 // session in the Principal element of the policy, the session has the permissions
168 // allowed by the policy. These permissions are granted in addition to the
169 // permissions that are granted by the session policies.
170 //
171 // The plaintext that you use for both inline and managed session policies can't
172 // exceed 2,048 characters. The JSON policy characters can be any ASCII character
173 // from the space character to the end of the valid character list (\u0020 through
174 // \u00FF). It can also include the tab (\u0009), linefeed (\u000A), and carriage
175 // return (\u000D) characters.
176 //
177 // An Amazon Web Services conversion compresses the passed inline session policy,
178 // managed policy ARNs, and session tags into a packed binary format that has a
179 // separate limit. Your request can fail for this limit even if your plaintext
180 // meets the other requirements. The PackedPolicySize response element indicates
181 // by percentage how close the policies and tags for your request are to the upper
182 // size limit.
183 //
184 // [session policy]: https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_session
185 // [Session Policies]: https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_session
186 Policy *string
187
188 // The Amazon Resource Names (ARNs) of the IAM managed policies that you want to
189 // use as a managed session policy. The policies must exist in the same account as
190 // the IAM user that is requesting federated access.
191 //
192 // You must pass an inline or managed [session policy] to this operation. You can pass a single
193 // JSON policy document to use as an inline session policy. You can also specify up
194 // to 10 managed policy Amazon Resource Names (ARNs) to use as managed session
195 // policies. The plaintext that you use for both inline and managed session
196 // policies can't exceed 2,048 characters. You can provide up to 10 managed policy
197 // ARNs. For more information about ARNs, see [Amazon Resource Names (ARNs) and Amazon Web Services Service Namespaces]in the Amazon Web Services General
198 // Reference.
199 //
200 // This parameter is optional. However, if you do not pass any session policies,
201 // then the resulting federated user session has no permissions.
202 //
203 // When you pass session policies, the session permissions are the intersection of
204 // the IAM user policies and the session policies that you pass. This gives you a
205 // way to further restrict the permissions for a federated user. You cannot use
206 // session policies to grant more permissions than those that are defined in the
207 // permissions policy of the IAM user. For more information, see [Session Policies]in the IAM User
208 // Guide.
209 //
210 // The resulting credentials can be used to access a resource that has a
211 // resource-based policy. If that policy specifically references the federated user
212 // session in the Principal element of the policy, the session has the permissions
213 // allowed by the policy. These permissions are granted in addition to the
214 // permissions that are granted by the session policies.
215 //
216 // An Amazon Web Services conversion compresses the passed inline session policy,
217 // managed policy ARNs, and session tags into a packed binary format that has a
218 // separate limit. Your request can fail for this limit even if your plaintext
219 // meets the other requirements. The PackedPolicySize response element indicates
220 // by percentage how close the policies and tags for your request are to the upper
221 // size limit.
222 //
223 // [session policy]: https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_session
224 // [Session Policies]: https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_session
225 // [Amazon Resource Names (ARNs) and Amazon Web Services Service Namespaces]: https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html
226 PolicyArns []types.PolicyDescriptorType
227
228 // A list of session tags. Each session tag consists of a key name and an
229 // associated value. For more information about session tags, see [Passing Session Tags in STS]in the IAM User
230 // Guide.
231 //
232 // This parameter is optional. You can pass up to 50 session tags. The plaintext
233 // session tag keys canât exceed 128 characters and the values canât exceed 256
234 // characters. For these and additional limits, see [IAM and STS Character Limits]in the IAM User Guide.
235 //
236 // An Amazon Web Services conversion compresses the passed inline session policy,
237 // managed policy ARNs, and session tags into a packed binary format that has a
238 // separate limit. Your request can fail for this limit even if your plaintext
239 // meets the other requirements. The PackedPolicySize response element indicates
240 // by percentage how close the policies and tags for your request are to the upper
241 // size limit.
242 //
243 // You can pass a session tag with the same key as a tag that is already attached
244 // to the user you are federating. When you do, session tags override a user tag
245 // with the same key.
246 //
247 // Tag keyâvalue pairs are not case sensitive, but case is preserved. This means
248 // that you cannot have separate Department and department tag keys. Assume that
249 // the role has the Department = Marketing tag and you pass the department =
250 // engineering session tag. Department and department are not saved as separate
251 // tags, and the session tag passed in the request takes precedence over the role
252 // tag.
253 //
254 // [Passing Session Tags in STS]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_session-tags.html
255 // [IAM and STS Character Limits]: https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_iam-limits.html#reference_iam-limits-entity-length
256 Tags []types.Tag
257
258 noSmithyDocumentSerde
259}
260
261// Contains the response to a successful GetFederationToken request, including temporary Amazon Web
262// Services credentials that can be used to make Amazon Web Services requests.
263type GetFederationTokenOutput struct {
264
265 // The temporary security credentials, which include an access key ID, a secret
266 // access key, and a security (or session) token.
267 //
268 // The size of the security token that STS API operations return is not fixed. We
269 // strongly recommend that you make no assumptions about the maximum size.
270 Credentials *types.Credentials
271
272 // Identifiers for the federated user associated with the credentials (such as
273 // arn:aws:sts::123456789012:federated-user/Bob or 123456789012:Bob ). You can use
274 // the federated user's ARN in your resource-based policies, such as an Amazon S3
275 // bucket policy.
276 FederatedUser *types.FederatedUser
277
278 // A percentage value that indicates the packed size of the session policies and
279 // session tags combined passed in the request. The request fails if the packed
280 // size is greater than 100 percent, which means the policies and tags exceeded the
281 // allowed space.
282 PackedPolicySize *int32
283
284 // Metadata pertaining to the operation's result.
285 ResultMetadata middleware.Metadata
286
287 noSmithyDocumentSerde
288}
289
290func (c *Client) addOperationGetFederationTokenMiddlewares(stack *middleware.Stack, options Options) (err error) {
291 if err := stack.Serialize.Add(&setOperationInputMiddleware{}, middleware.After); err != nil {
292 return err
293 }
294 err = stack.Serialize.Add(&awsAwsquery_serializeOpGetFederationToken{}, middleware.After)
295 if err != nil {
296 return err
297 }
298 err = stack.Deserialize.Add(&awsAwsquery_deserializeOpGetFederationToken{}, middleware.After)
299 if err != nil {
300 return err
301 }
302 if err := addProtocolFinalizerMiddlewares(stack, options, "GetFederationToken"); err != nil {
303 return fmt.Errorf("add protocol finalizers: %v", err)
304 }
305
306 if err = addlegacyEndpointContextSetter(stack, options); err != nil {
307 return err
308 }
309 if err = addSetLoggerMiddleware(stack, options); err != nil {
310 return err
311 }
312 if err = addClientRequestID(stack); err != nil {
313 return err
314 }
315 if err = addComputeContentLength(stack); err != nil {
316 return err
317 }
318 if err = addResolveEndpointMiddleware(stack, options); err != nil {
319 return err
320 }
321 if err = addComputePayloadSHA256(stack); err != nil {
322 return err
323 }
324 if err = addRetry(stack, options); err != nil {
325 return err
326 }
327 if err = addRawResponseToMetadata(stack); err != nil {
328 return err
329 }
330 if err = addRecordResponseTiming(stack); err != nil {
331 return err
332 }
333 if err = addClientUserAgent(stack, options); err != nil {
334 return err
335 }
336 if err = smithyhttp.AddErrorCloseResponseBodyMiddleware(stack); err != nil {
337 return err
338 }
339 if err = smithyhttp.AddCloseResponseBodyMiddleware(stack); err != nil {
340 return err
341 }
342 if err = addSetLegacyContextSigningOptionsMiddleware(stack); err != nil {
343 return err
344 }
345 if err = addTimeOffsetBuild(stack, c); err != nil {
346 return err
347 }
348 if err = addUserAgentRetryMode(stack, options); err != nil {
349 return err
350 }
351 if err = addOpGetFederationTokenValidationMiddleware(stack); err != nil {
352 return err
353 }
354 if err = stack.Initialize.Add(newServiceMetadataMiddleware_opGetFederationToken(options.Region), middleware.Before); err != nil {
355 return err
356 }
357 if err = addRecursionDetection(stack); err != nil {
358 return err
359 }
360 if err = addRequestIDRetrieverMiddleware(stack); err != nil {
361 return err
362 }
363 if err = addResponseErrorMiddleware(stack); err != nil {
364 return err
365 }
366 if err = addRequestResponseLogging(stack, options); err != nil {
367 return err
368 }
369 if err = addDisableHTTPSMiddleware(stack, options); err != nil {
370 return err
371 }
372 return nil
373}
374
375func newServiceMetadataMiddleware_opGetFederationToken(region string) *awsmiddleware.RegisterServiceMetadata {
376 return &awsmiddleware.RegisterServiceMetadata{
377 Region: region,
378 ServiceID: ServiceID,
379 OperationName: "GetFederationToken",
380 }
381}