Add identity broker docs
This commit is contained in:
parent
90f7408fc7
commit
8a09fdda0e
175
README_BROKER.md
Normal file
175
README_BROKER.md
Normal file
@ -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"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
```
|
@ -54,6 +54,13 @@ import pyhocon
|
|||||||
|
|
||||||
|
|
||||||
class IdentityBrokerClient:
|
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_ENDPOINT = "https://aws-access.crute.us/api/account"
|
||||||
_DEFAULT_ACCOUNT = "alpine-amis-user"
|
_DEFAULT_ACCOUNT = "alpine-amis-user"
|
||||||
|
Loading…
Reference in New Issue
Block a user