Skip to content

HTTP_API_SPEC.md

Latest commit

 

History

History
84 lines (61 loc) · 2.77 KB

HTTP_API_SPEC.md

File metadata and controls

84 lines (61 loc) · 2.77 KB
Raw

Credential Server API

If you don't have the AWS SSO instance, you need to run your own credential vending server to serve AWS credentials for your Mairu users. You may use a known compatible implementations, or implement your own.

Authentication

Mairu acts as a OAuth 2.0 public client and supports and authorization code grant with PKCE. Retrieved access token will be sent as a bearer token in Authorization header field (RFC 6750 Section 2.1.).

Therefore, a credential server must implement OAuth 2.0 endpoints for a one of supported grant types (at least):

  • For authorization code grant
    • Authentication server MUST support PKCE for auth code grant type
    • authorization endpoint (default to {url}/oauth/authorize)
    • token endpoint (default to {url}/oauth/token)

Assume Role Credentials API

Request
POST {url}/assume-role
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "Role": "{role to assume}"
}
  • Role may be a role ARN or something else. Mairu pass-through a string given to a credential provider server, so it's up to a server implementation to decide what strings to accept.
Response

Compatible with https://docs.aws.amazon.com/sdkref/latest/guide/feature-process-credentials.html

{
    "Version": 1,
    "AccessKeyId": "an AWS access key",
    "SecretAccessKey": "your AWS secret access key",
    "SessionToken": "the AWS session token for temporary credentials", 
    "Expiration": "RFC3339 timestamp for when the credentials expire",

    // Mairu specific, optional
    "Mairu": {
        "NoCache": true // Optional default to false. When specified, Mairu doesn't cache this credential and always request to a server for every credential request.
    }
}

Mairu will prompt reauthentication for a response with 401 Unauthorized HTTP status code.

List Roles API (optional)

mairu list-roles uses this API to allow users to list their allowed roles.

Request
GET {url}/roles
Content-Type: application/json
Authorization: Bearer {access_token}
Response
{
    "Roles": [
        {"Name": "..."}, // Return possible role name (which will be passed to .Role in assume-role API)
        {"Name": "..."}
        // ...
    ]
}
  • Mairu considers it is unimplemented if a server returns 404 Not Found or 405 Method Not Allowed response.