openapi: 3.0.0
info:
  title: Internal Auth API
  version: 0.0.1
  description: |
    Auth API to provide JWT tokens for internal API access that work with the epilot custom authorizer.

    Converts AWS credentials into a JWT token with caller's ARN `callerIdentity` and list of `policies` granting access to API Gateway as claims.
paths:
  /auth:
    get:
      operationId: getToken
      summary: getToken
      description: |
        Generates token for internal API access

        Example JWT payload:

        ```json
        {
          "callerIdentity": "arn:aws:sts::912468240823:assumed-role/ep_prod_access_admin/awsmfa_20210225T193753",
          "policies": [
            {
              "Version": "2012-10-17",
              "Statement": [
                {
                  "Effect": "Allow",
                  "Action": "*",
                  "Resource": "*"
                }
              ]
            }
          ],
          "iss": "https://internal-auth.sls.epilot.io/v1/internal-auth",
          "iat": 1614278397,
          "exp": 1614281997
        }
        ```
      security:
      - sigv4: []
      responses:
        '200':
          description: JWT Token
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                    description: JWT Token
                    example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0IiwibmFtZSI6IkhlbGxvIGVwaWxvdCIsImlhdCI6MTUxNjIzOTAyMn0.FhoeinGX4X3wh6K4KFJbdIJ3JAG12Ezi-s6BhT-ngK4
    post:
      operationId: getTokenV2
      summary: getTokenV2
      description: |
        Generates token for internal API access with internal roles

        Example JWT payload:

        ```json
        {
          "callerIdentity": "arn:aws:sts::912468240823:assumed-role/ep_prod_access_admin/awsmfa_20210225T193753",
          "policies": [
            {
              "Version": "2012-10-17",
              "Statement": [
                {
                  "Effect": "Allow",
                  "Action": "*",
                  "Resource": "*"
                }
              ]
            }
          ],
          "assume_roles": ["org_id:note_role", "org_id:file_role"],
          "org_id": "org_id",
          "iss": "https://internal-auth.sls.epilot.io/v1/internal-auth",
          "iat": 1614278397,
          "exp": 1614281997
        }
        ```
      security:
      - sigv4: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthRequest'
      responses:
        '200':
          description: JWT Token
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                    description: JWT Token
                    example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0IiwibmFtZSI6IkhlbGxvIGVwaWxvdCIsImlhdCI6MTUxNjIzOTAyMn0.FhoeinGX4X3wh6K4KFJbdIJ3JAG12Ezi-s6BhT-ngK4
  /.well-known/jwks.json:
    get:
      operationId: getJwks
      summary: getJwks
      description: Get jwks public key set to verify tokens generated by this API
      responses:
        '200':
          description: Set of jwks
          content:
            application/json:
              schema:
                type: object
                properties:
                  keys:
                    type: array
                    items:
                      type: object
                      properties:
                        alg:
                          type: string
                          example: RS256
                        e:
                          type: string
                          example: AQAB
                        kid:
                          type: string
                          example: tXWU5mPMbRPczpbQwi6vbhLF4GgF3wlMDSyqo7pfeiw=
                        kty:
                          type: string
                          example: RSA
                        'n':
                          type: string
                          example: >-
                            h_QDoCjZ8W_trtYXaP7_S22wf5r5Wd9XBLED78oT44bJjQXn8ddcFV8Hik65_4IYXVX_hTTU4zpxe3H8vx2j7-Zz3O59mYMp5S0MzODNEdf5Y_2o19eis0brmAJniixsNlQ9LlYkdrVamrgaxHu3ZpP_99zkfFybYeuYoQNzb3PyrT8xVnz_USs_nlFMHpGUxvvz7gfKPqxcLvgLJr4cwI9yzaSY9CD4qW181QVcnL_WzpQ8xx6AuhhHZQ1l_3GG4InTk8ahE7U2ZHVu8RrX6d01pMgc3piEcet9RgFLnhbTg3YIiKGoAbN42wJn_x3lgIAC42T9mbmTsHyUdS6nUQ
                        use:
                          type: string
                          example: sig
  /.well-known/openid-configuration:
    get:
      operationId: getOpenIDConfiguration
      summary: getOpenIDConfiguration
      description: |
        OpenID Connect configuration for internal auth as identity provider

        Note: This API is not a fully compliant OAuth2.0 / OIDC identity provider, but this endpoint is useful to
        automate the process of verifying JWT tokens.
      responses:
        '200':
          description: OpenID Configuration
          content:
            application/json:
              schema:
                type: object
                properties:
                  issuer:
                    type: string
                    format: uri
                    example: https://internal-auth.sls.epilot.io/v1/internal-auth
                  jwks_uri:
                    type: string
                    format: uri
                    example: https://internal-auth.sls.epilot.io/v1/internal-auth/.well-known/jwks.json
components:
  securitySchemes:
    sigv4:
      type: apiKey
      in: header
      name: Authorization
      x-amazon-apigateway-authtype: awsSigv4
  schemas:
    AuthRequest:
      type: object
      additionalProperties: true
      properties:
        assume_roles:
          description: List of assumed roles
          type: array
          items:
            type: string
            example: org_id:root
        org_id:
          description: Organization Id
          type: string
          example: '12345'
        expires:
          oneOf:
          - type: string
            example: 1h
            description: |
              Expiration expressed in seconds or a string describing a time span [zeit/ms](https://github.com/zeit/ms.js).  Eg: 60, "2 days", "10h", "7d" */
          - type: integer
servers:
- url: https://internal-auth.sls.epilot.io/v1/internal-auth

