6.3 KiB
AWS Identity Broker
The identity broker is used to obtain short-lived and per-region credentials for an account. Opt-in regions require the use of a long-lived credential (e.g. IAM user), enabling global STS tokens, or an STS token sourced in that region. The identity broker holds long-term credentials and uses them to acquire short-term credentials in a given region. The broker also provides a list of opt-in regions and should be used to enumerate regions.
For human-interactive users the identity broker performs OAUTH against GitHub to chain the user's GitHub identity to the tokens they are given from the broker. The broker also provides the user an API key to use when interacting with the broker programmatically.
As of May 2020 the identity broker is not open sourced. If you want to provide your own identity broker, the rest of this document specifies the URLs endpoints and response formats to do so.
The API
The identity broker API is a REST-ful service with an entry-point of
/api/account
. All further navigation through the API follows links within the
hypertext.
Note: Outside of the account entry-point, URI formats should be considered implementation details of the broker API and should never be templated. Beyond the account entry-point, nothing in this specification is normative with respect to URI paths and locations.
Authentication
All requests to the API must be authenticated with a broker-specific key. That
key is provided to the broker in the X-API-Key
header. When the broker
determines that the key is either expired or invalid it must redirect the user
to /logout
to indicate that the user is logged out and must log-in again.
API keys are bearer tokens and thus must only be exchanged over HTTPS.
Status Codes
200 OK
: indicates that the request to the broker was successful.
302 Found
: indicates that the broker is providing a redirect. Users should
check the redirect, if it is to the location /logout
the user should consider
themselves logged out and proceed to login. This condition should not be
followed. Otherwise the user should follow all redirects.
400 Bad Request
: indicates that some part of the request is invalid as
submitted. The hypertext MAY provide a description of this error and how to
remedy it.
429 Rate Limit Exceeded
: indicates that the broker has rate-limited the user.
A user should discontinue requests to the broker immediately and wait for at
least 30 seconds before continuing their requests. The rate limit parameters
are specific to the broker and not controlled by this spec.
500 Server Error
: indicates a server error condition that is not under the
user's control.
Account End-point
The account end-point acts as a index of the rest of the API. It presents a list of accounts to which the user has access as well as links to navigate further into the API. The format of this document is:
short_name
(string): a url-safe name for the account, used as the primary
account identifier within the broker.
account_number
(integer): the AWS account number
name
(string): a user-friendly name for the account
console_redirect_url
(uri): a URI that, when followed, leads to a resource
that redirects the user to an authenticated console session.
get_console_url
(uri): a URI that, when followed, leads to a console URL
resource.
credentials_url
(uri): a URI that, when followed, leads to a region list
resource.
global_credential_url
(uri): a URI that, when followed, leads to a credential
resource which provides a credential usable by all non-opt-in regions. The
contents of this resource are a STS global credential which is not usable in
opt-in regions.
[
{
"short_name": "primary-account",
"account_number": 123456789012,
"name": "Primary AWS Account",
"console_redirect_url": "https://broker/api/account/primary-account/console?redirect=1",
"get_console_url": "https://broker/api/account/primary-account/console",
"credentials_url": "https://broker/api/account/primary-account/credentials",
"global_credential_url": "https://broker/api/account/primary-account/credentials/global"
}
]
Console URL Resource
Note: This resource is not used by the build scripts.
The console URL resource provides a URL to the AWS console. This resource is designed for interactive use.
When provided the query parameter redirect
with a value of 1
this resource
will not generate a body and will instead redirect to the URL that would have
been returned for console_url
.
console_url
(uri): a link to the AWS console with authentication credentials
embedded.
{
"console_url": "https://signin.aws.amazon.com/federation?..."
}
Credential Resource
The credential resource provides a set of credentials that can be used to configure AWS tools to access an account.
access_key
(string): the AWS access key ID
secret_key
(string): the AWS secret access key
session_token
(string): the AWS session token
expiration
(iso-formatted date): the date and time when the credential will
expire
{
"access_key": "ASIA123ABC456DEF567G",
"secret_key": "r7KcIuGdPwoUG2YOLISX2XDrVts55IFGTGaY5Tqa",
"session_token": "7C7FyvzyneaS/eRCVDcjHOSTTIHQyvhGqW...",
"expiration": "2020-01-01T00:00:00Z"
}
Region List Resource
The region list resource provides a list of regions associated with the account both opted-in and not. For opted-in regions the resource includes a link to a credential resource for that region.
name
(string): AWS name for the region
enabled
(boolean): indicates if the region is enabled and opted-in for this
account.
credentials_url
(uri): a URI that, when followed, leads to a credential
resource containing a credential for access to that region. The credential
provided will be usable against the region-local STS endpoint for the specified
region. This also applies for classic regions, which typically use a global
endpoint and credential. The returned credential is scoped to the acquiring
region and may not be usable against the global endpoints or a different
regional endpoint.
[
{
"name": "af-south-1",
"enabled": false
},
{
"name": "us-west-2",
"enabled": true,
"credentials_url": "https://broker/api/account/primary-account/credentials/us-west-2"
}
]