Add identity broker docs

2 files changed, 182 insertions, 0 deletions

diff --git a/README_BROKER.md b/README_BROKER.md
new file mode 100644
index 0000000..13e1af3
--- /dev/null
+++ b/README_BROKER.md
@@ -0,0 +1,175 @@
+# 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"
+    }
+]
+```
diff --git a/scripts/builder.py b/scripts/builder.py
index 6ab9ed7..c249ba9 100755
--- a/scripts/builder.py
+++ b/scripts/builder.py
@@ -54,6 +54,13 @@ import pyhocon
 
 
 class IdentityBrokerClient:
+    """Client for identity broker
+
+    Export IDENTITY_BROKER_ENDPOINT to override the default broker endpoint.
+    Export IDENTITY_BROKER_API_KEY to specify an API key for the broker.
+
+    See README_BROKER.md for more information and a spec.
+    """
 
     _DEFAULT_ENDPOINT = "https://aws-access.crute.us/api/account"
     _DEFAULT_ACCOUNT = "alpine-amis-user"