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