1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
|
# 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"
}
]
```
|
