diff options
Diffstat (limited to 'README_BROKER.md')
-rw-r--r-- | README_BROKER.md | 228 |
1 files changed, 228 insertions, 0 deletions
diff --git a/README_BROKER.md b/README_BROKER.md new file mode 100644 index 0000000..03db1af --- /dev/null +++ b/README_BROKER.md | |||
@@ -0,0 +1,228 @@ | |||
1 | # AWS Identity Broker | ||
2 | |||
3 | The identity broker is used to obtain short-lived and per-region credentials | ||
4 | for an account. Opt-in regions require the use of a long-lived credential (e.g. | ||
5 | IAM user), enabling global STS tokens, or an STS token sourced in that region. | ||
6 | The identity broker holds long-term credentials and uses them to acquire | ||
7 | short-term credentials in a given region. The broker also provides a list of | ||
8 | opt-in regions and should be used to enumerate regions. | ||
9 | |||
10 | For human-interactive users the identity broker performs OAUTH against GitHub | ||
11 | to chain the user's GitHub identity to the tokens they are given from the | ||
12 | broker. The broker also provides the user an API key to use when interacting | ||
13 | with the broker programmatically. | ||
14 | |||
15 | # The API | ||
16 | |||
17 | The identity broker API is a REST-ful service with an entry-point of | ||
18 | `/api/account`. All further navigation through the API follows links within the | ||
19 | hypertext. | ||
20 | |||
21 | **Note:** Outside of the account entry-point, URI formats should be considered | ||
22 | opaque implementation details of the broker API and should never be templated. | ||
23 | Beyond the account entry-point, nothing in this specification is normative with | ||
24 | respect to URI paths and locations. | ||
25 | |||
26 | ## Media Formats | ||
27 | |||
28 | There are two supported media types in the API `application/vnd.broker.v1+json` | ||
29 | and `application/vnd.broker.v2+json`. A client that requests the default media | ||
30 | type or `application/json` will recieve the V1 media type. | ||
31 | |||
32 | To request a specific media type use the `Accept` header: | ||
33 | |||
34 | ``` | ||
35 | Accept: application/vnd.broker.v2+json | ||
36 | ``` | ||
37 | |||
38 | ## Authentication | ||
39 | |||
40 | All requests to the API must be authenticated with a broker-specific key. That | ||
41 | key is provided to the broker in the `Authorization` header with a sub-type of | ||
42 | `Bearer`. When the broker determines that the key is either expired or invalid | ||
43 | it must redirect the user to `/logout` to indicate that the user is logged out | ||
44 | and must log-in again. | ||
45 | |||
46 | API keys are bearer tokens and thus must only be exchanged over HTTPS. | ||
47 | |||
48 | Example of authorization header: | ||
49 | |||
50 | ``` | ||
51 | Authorization: Bearer ...an auth token... | ||
52 | ``` | ||
53 | |||
54 | Legacy versions of the API supported an `X-API-Key` header, which is now | ||
55 | deprecated but remains supported for backwards compatability. | ||
56 | |||
57 | ## Status Codes | ||
58 | |||
59 | `200 OK`: indicates that the request to the broker was successful. | ||
60 | |||
61 | `302 Found`: indicates that the broker is providing a redirect. Users should | ||
62 | check the redirect, if it is to the location `/logout` the user should consider | ||
63 | themselves logged out and proceed to login. This condition should not be | ||
64 | followed. Otherwise the user should follow all redirects. | ||
65 | |||
66 | `400 Bad Request`: indicates that some part of the request is invalid as | ||
67 | submitted. The hypertext MAY provide a description of this error and how to | ||
68 | remedy it. | ||
69 | |||
70 | `401 Unauthorized`: indicates that the authentication or authorzation for the | ||
71 | user has failed. This is not retryable, a user should obtain a new | ||
72 | authorization token before attempting another request. | ||
73 | |||
74 | `429 Rate Limit Exceeded`: indicates that the broker has rate-limited the user. | ||
75 | A user should discontinue requests to the broker immediately and wait for at | ||
76 | least 30 seconds before continuing their requests. The rate limit parameters | ||
77 | are specific to the broker and not controlled by this spec. | ||
78 | |||
79 | `500 Server Error`: indicates a server error condition that is not under the | ||
80 | user's control. | ||
81 | |||
82 | ## Account End-point | ||
83 | |||
84 | ### V1 Media Type | ||
85 | |||
86 | The account end-point acts as a index of the rest of the API. It presents a | ||
87 | list of accounts to which the user has access as well as links to navigate | ||
88 | further into the API. The format of this document is: | ||
89 | |||
90 | `short_name` (string): a url-safe name for the account, used as the primary | ||
91 | account identifier within the broker. | ||
92 | |||
93 | `account_number` (integer): the AWS account number | ||
94 | |||
95 | `name` (string): a user-friendly name for the account | ||
96 | |||
97 | `vendor` (string): the name of the cloud vendor (currently only `aws`) | ||
98 | |||
99 | `console_redirect_url` (uri): a URI that, when followed, leads to a resource | ||
100 | that redirects the user to an authenticated console session. | ||
101 | |||
102 | `get_console_url` (uri): a URI that, when followed, leads to a console URL | ||
103 | resource. | ||
104 | |||
105 | `credentials_url` (uri): a URI that, when followed, leads to a region list | ||
106 | resource. | ||
107 | |||
108 | `global_credential_url` (uri): a URI that, when followed, leads to a credential | ||
109 | resource which provides a credential usable by all non-opt-in regions. The | ||
110 | contents of this resource are a STS global credential which is not usable in | ||
111 | opt-in regions. | ||
112 | |||
113 | ``` | ||
114 | [ | ||
115 | { | ||
116 | "short_name": "primary-account", | ||
117 | "vendor": "aws", | ||
118 | "account_number": 123456789012, | ||
119 | "name": "Primary AWS Account", | ||
120 | "console_redirect_url": "https://broker/api/account/primary-account/console?redirect=1", | ||
121 | "get_console_url": "https://broker/api/account/primary-account/console", | ||
122 | "credentials_url": "https://broker/api/account/primary-account/credentials", | ||
123 | "global_credential_url": "https://broker/api/account/primary-account/credentials/global" | ||
124 | } | ||
125 | ] | ||
126 | ``` | ||
127 | |||
128 | ### V2 Media Type | ||
129 | |||
130 | The fiends in the V2 media type have identical meaning to those in the V1 media | ||
131 | type but the top level container format is different. Instead of containing a | ||
132 | list of accounts with a `vendor` field V2 responses are a map of vendors to a | ||
133 | list of accounts. | ||
134 | |||
135 | ``` | ||
136 | { | ||
137 | "aws": [ | ||
138 | { | ||
139 | "short_name": "primary-account", | ||
140 | "account_number": 123456789012, | ||
141 | "name": "Primary AWS Account", | ||
142 | "console_redirect_url": "https://broker/api/account/primary-account/console?redirect=1", | ||
143 | "get_console_url": "https://broker/api/account/primary-account/console", | ||
144 | "credentials_url": "https://broker/api/account/primary-account/credentials", | ||
145 | "global_credential_url": "https://broker/api/account/primary-account/credentials/global" | ||
146 | } | ||
147 | ] | ||
148 | } | ||
149 | ``` | ||
150 | |||
151 | ## Console URL Resource | ||
152 | |||
153 | **Note:** This resource is not used by the build scripts. | ||
154 | |||
155 | The console URL resource provides a URL to the AWS console. This resource is | ||
156 | designed for interactive use. | ||
157 | |||
158 | When provided the query parameter `redirect` with a value of `1` this resource | ||
159 | will not generate a body and will instead redirect to the URL that would have | ||
160 | been returned for `console_url`. | ||
161 | |||
162 | `console_url` (uri): a link to the AWS console with authentication credentials | ||
163 | embedded. | ||
164 | |||
165 | ``` | ||
166 | { | ||
167 | "console_url": "https://signin.aws.amazon.com/federation?..." | ||
168 | } | ||
169 | ``` | ||
170 | |||
171 | ## Credential Resource | ||
172 | |||
173 | The credential resource provides a set of credentials that can be used to | ||
174 | configure AWS tools to access an account. | ||
175 | |||
176 | `access_key` (string): the AWS access key ID | ||
177 | |||
178 | `secret_key` (string): the AWS secret access key | ||
179 | |||
180 | `session_token` (string): the AWS session token | ||
181 | |||
182 | `expiration` (iso-formatted date): the date and time when the credential will | ||
183 | expire | ||
184 | |||
185 | ``` | ||
186 | { | ||
187 | "access_key": "ASIA123ABC456DEF567G", | ||
188 | "secret_key": "r7KcIuGdPwoUG2YOLISX2XDrVts55IFGTGaY5Tqa", | ||
189 | "session_token": "7C7FyvzyneaS/eRCVDcjHOSTTIHQyvhGqW...", | ||
190 | "expiration": "2020-01-01T00:00:00Z" | ||
191 | } | ||
192 | ``` | ||
193 | |||
194 | The API will set a valid `Expires` header that matches the `expiration` field | ||
195 | of this resource to facilitate use of HTTP caches. | ||
196 | |||
197 | ## Region List Resource | ||
198 | |||
199 | The region list resource provides a list of regions associated with the account | ||
200 | both opted-in and not. For opted-in regions the resource includes a link to a | ||
201 | credential resource for that region. | ||
202 | |||
203 | `name` (string): AWS name for the region | ||
204 | |||
205 | `enabled` (boolean): indicates if the region is enabled and opted-in for this | ||
206 | account. | ||
207 | |||
208 | `credentials_url` (uri): a URI that, when followed, leads to a credential | ||
209 | resource containing a credential for access to that region. The credential | ||
210 | provided will be usable against the region-local STS endpoint for the specified | ||
211 | region. This also applies for classic regions, which typically use a global | ||
212 | endpoint and credential. The returned credential is scoped to the acquiring | ||
213 | region and may not be usable against the global endpoints or a different | ||
214 | regional endpoint. | ||
215 | |||
216 | ``` | ||
217 | [ | ||
218 | { | ||
219 | "name": "af-south-1", | ||
220 | "enabled": false | ||
221 | }, | ||
222 | { | ||
223 | "name": "us-west-2", | ||
224 | "enabled": true, | ||
225 | "credentials_url": "https://broker/api/account/primary-account/credentials/us-west-2" | ||
226 | } | ||
227 | ] | ||
228 | ``` | ||