Enable custom identity broker access to the AWS console

To give roles and federated principals access to your resources from the AWS Management Console

1. Authenticate the user in your identity and authorization system.

2. Obtain temporary security credentials for the user. The temporary credentials consist of an access key ID, a secret access key, and a session token. For more information about creating temporary credentials, see Temporary security credentials in IAM.

   To get temporary credentials, you call either the AWS STS AssumeRole API (recommended) or the GetFederationToken API. For more information about the differences between these API operations, see Understanding the API Options for Securely Delegating Access to Your AWS Account in the AWS Security Blog.

   Important

   When you use the GetFederationToken API to create temporary security credentials, you must specify the permissions that the credentials grant to the user who assumes the role. For any of the API operations that begin with AssumeRole*, you use an IAM role to assign permissions. For the other API operations, the mechanism varies with the API. For more details, see Permissions for temporary security credentials. Additionally, if you use the AssumeRole* API operations, you must call them as an IAM user with long-term credentials. Otherwise, the call to the federation endpoint in step 3 fails.

3. After you obtain the temporary security credentials, build them into a JSON session string to exchange them for a sign-in token. The following example shows how to encode the credentials. You replace the placeholder text with the appropriate values from the credentials that you receive in the previous step.

   {"sessionId":"*** temporary access key ID ***",
   "sessionKey":"*** temporary secret access key ***",
   "sessionToken":"*** session token ***"}

4. URL encode the session string from the previous step. Because the information that you are encoding is sensitive, we recommend that you avoid using a web service for this encoding. Instead, use a locally installed function or feature in your development toolkit to securely encode this information. You can use the urllib.quote_plus function in Python, the URLEncoder.encode function in Java, or the CGI.escape function in Ruby. See the examples later in this topic.

5. Note

   AWS supports POST requests here.

   Send your request to the AWS federation endpoint:

   For a list of possible region-code values, see the Region column in AWS Sign-In endpoints. You can optionally use the default AWS Sign-In federation endpoint:

   The request must include the Action and Session parameters, and (optionally) if you used an AssumeRole* API operation, a SessionDuration HTTP parameter as shown in the following example.

   Action = getSigninToken
   SessionDuration = time in seconds
   Session = *** the URL encoded JSON string created in steps 3 & 4 ***

   Note

   The following instructions in this step only work using GET requests.

   The SessionDuration HTTP parameter specifies the duration of the console session. This is separate from the duration of the temporary credentials that you specify using the DurationSeconds parameter. You can specify a SessionDuration maximum value of 43,200 (12 hours). If the SessionDuration parameter is missing, then the session defaults to the duration of the credentials that you retrieved from AWS STS in step 2 (which defaults to one hour). See the documentation for the AssumeRole API for details about how to specify a duration using the DurationSeconds parameter. The ability to create a console session that is longer than one hour is intrinsic to the getSigninToken operation of the federation endpoint.

   Note

   • Your SessionDuration cannot be greater than or equal to the maximum session duration setting for the role you're assuming. For example, you're set the maximum session duration for the role you want to assume to 5 hours. Your SessionDuration parameter can be 16524 seconds or 4 hours and 59 seconds.

   • Do not use the SessionDuration HTTP parameter when you get temporary credentials with GetFederationToken. The operation will fail.

   • Using the credentials for one role to assume a different role is called role chaining. When you use role chaining, your new credentials are limited to a maximum duration of one hour. When you use roles to grant permissions to applications that run on EC2 instances, those applications are not subject to this limitation.

   • Do not use the SessionDuration HTTP parameter when you get temporary credentials through role chaining. The operation will fail.

   When you enable console sessions with an extended duration, you increase the risk of credential exposure. To help you mitigate this risk, you can immediately disable the active console sessions for any role by choosing Revoke Sessions on the Role Summary IAM console page. For more information, see Revoke IAM role temporary security credentials.

   The following is an example of what your request might look like. The lines are wrapped here for readability, but you should submit it as a one-line string.

   The response from the federation endpoint is a JSON document with a SigninToken value. It will look similar to the following example.

   {"SigninToken":"*** the SigninToken string ***"}

6. Note

   AWS supports POST requests here.

   Finally, create the URL that your users can use to access the AWS Management Console. The URL is the same federation URL endpoint that you used in Step 5, plus the following parameters:

   ?Action = login
   &Issuer = *** the form-urlencoded URL for your internal sign-in page ***
   &Destination = *** the form-urlencoded URL to the desired AWS console page ***
   &SigninToken = *** the value of SigninToken received in the previous step ***

   Note

   The following instructions in this step only work using GET API.

   The following example shows what the final URL might look like. The URL is valid for 15 minutes from the time it is created. The temporary security credentials and console session embedded within the URL are valid for the duration you specify in the SessionDuration HTTP parameter when you initially request them.