# 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.

# 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
opaque 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.

## Media Formats

There are two supported media types in the API `application/vnd.broker.v1+json`
and `application/vnd.broker.v2+json`. A client that requests the default media
type or `application/json` will recieve the V1 media type.

To request a specific media type use the `Accept` header:

```
Accept: application/vnd.broker.v2+json
```

## Authentication

All requests to the API must be authenticated with a broker-specific key. That
key is provided to the broker in the `Authorization` header with a sub-type of
`Bearer`. 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.

Example of authorization header:

```
Authorization: Bearer ...an auth token...
```

Legacy versions of the API supported an `X-API-Key` header, which is now
deprecated but remains supported for backwards compatability.

## 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.

`401 Unauthorized`: indicates that the authentication or authorzation for the
user has failed. This is not retryable, a user should obtain a new
authorization token before attempting another request.

`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

### V1 Media Type

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

`vendor` (string): the name of the cloud vendor (currently only `aws`)

`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",
        "vendor": "aws",
        "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"
    }
]
```

### V2 Media Type

The fiends in the V2 media type have identical meaning to those in the V1 media
type but the top level container format is different. Instead of containing a
list of accounts with a `vendor` field V2 responses are a map of vendors to a
list of accounts.

```
{
    "aws": [
        {
            "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"
}
```

The API will set a valid `Expires` header that matches the `expiration` field
of this resource to facilitate use of HTTP caches.

## 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"
    }
]
```