public-api.yaml

openapi: "3.0.1"
info:
  title: "HMRC NINO Check Credential Issuer Public Api"
  version: "1.0"

paths:
  /.well-known/jwks.json:
    get:
      operationId: getWellKnownJwksJson
      summary: Retrieve the public encryption keys issued by Check HMRC CRI.
      description: >-
        Return the current valid public keys as a JSON Web Key Set used to Encrypt JAR(s) requests for Check HMRC CRI
      tags:
        - Backend - Check HMRC CRI
      responses:
        "200":
          description: >-
            OK - key ring returned
          headers:
            Cache-Control:
              schema:
                type: "string"
            Content-Type:
              schema:
                type: "string"
            Strict-Transport-Security:
              schema:
                type: "string"
            X-Content-Type-Options:
              schema:
                type: "string"
            X-Frame-Options:
              schema:
                type: "string"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JWKSFile"
        "400":
          description: 400 response
          headers:
            Cache-Control:
              schema:
                type: "string"
            Content-Type:
              schema:
                type: "string"
            Strict-Transport-Security:
              schema:
                type: "string"
            X-Content-Type-Options:
              schema:
                type: "string"
            X-Frame-Options:
              schema:
                type: "string"
        "500":
          description: Internal Server Error
          headers:
            Cache-Control:
              schema:
                type: "string"
            Content-Type:
              schema:
                type: "string"
            Strict-Transport-Security:
              schema:
                type: "string"
            X-Content-Type-Options:
              schema:
                type: "string"
            X-Frame-Options:
              schema:
                type: "string"
      x-amazon-apigateway-integration:
        httpMethod: "GET"
        credentials:
          Fn::GetAtt: ["JWKSBucketRole", "Arn"]
        uri:
          Fn::Sub:
            - "arn:aws:apigateway:${AWS::Region}:s3:path/govuk-one-login-hmrc-check-published-keys-${env}/jwks.json"
            - env:
                Fn::If:
                  - IsLocalDevEnvironment
                  - dev
                  - Ref: Environment
        responses:
          default:
            statusCode: "200"
            responseParameters:
              method.response.header.Cache-Control: "'max-age=300'"
        passthroughBehavior: "when_no_match"
        contentHandling: "CONVERT_TO_TEXT"
        type: "aws"

  /token:
    post:
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              required:
                - "grant_type"
                - "code"
                - "client_assertion_type"
                - "client_assertion"
                - "redirect_uri"
              properties:
                grant_type:
                  type: "string"
                  pattern: "authorization_code"
                  example: "authorization_code"
                code:
                  type: "string"
                  minLength: 1
                client_assertion_type:
                  type: "string"
                  pattern: "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
                  example: "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
                client_assertion:
                  type: "string"
                  pattern: "[a-zA-Z0-9_=]+\\.[a-zA-Z0-9_=]+\\.[a-zA-Z0-9_\\-\\+\\/=]+"
                redirect_uri:
                  type: "string"
                  format: "uri"
                  example: "https://di-ipv-core-stub.london.cloudapps.digital/callback"
            examples:
              201:
                summary: "Example body to receive a HTTP 201 response"
                value:
                  grant_type: "string"
                  code: "1fbc5730-9d17-416d-b2ca-0be90e1e93f5"
                  client_assertion_type: "string"
                  client_assertion: "string"
                  redirect_uri: "https://di-ipv-core-stub.london.cloudapps.digital/callback"
              400:
                summary: "Example body to receive a HTTP 400 response"
                value:
                  grant_type: "string"
                  code: "fad21bea-bce9-4aa7-8889-d50c7d26616e"
                  client_assertion_type: "string"
                  client_assertion: "string"
                  redirect_uri: "string"
              500:
                summary: "Example body to receive a HTTP 500 response"
                value:
                  grant_type: "string"
                  code: "f27b8afc-90ef-4e0f-83ad-00a2f5692590"
                  client_assertion_type: "string"
                  client_assertion: "string"
                  redirect_uri: "string"
      responses:
        "201":
          description: "201 response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenResponse"
              examples:
                201:
                  value:
                    access_token: "1fbc5730-9d17-416d-b2ca-0be90e1e93f5"
                    token_type: "Bearer"
                    expires_in: "3600"
                    refresh_token: "uuid"
        "400":
          description: "400 response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: "500 response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - api_key:
            Fn::If:
              - IsDevEnvironment
              - Ref: AWS::NoValue
              - []
      x-amazon-apigateway-request-validator: "Validate both"
      x-amazon-apigateway-integration:
        httpMethod: "POST"
        uri:
          Fn::Sub: arn:${AWS::Partition}:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/arn:${AWS::Partition}:lambda:${AWS::Region}:${AWS::AccountId}:function:${CommonStackName}-AccessTokenFunctionTS:live/invocations
        responses:
          default:
            statusCode: "200"
        passthroughBehavior: "when_no_match"
        contentHandling: "CONVERT_TO_TEXT"
        type: "aws_proxy"
  /credential/issue:
    summary: Resource for the HMRC KBV API
    description: >-
      This API is expected to be called by the IPV core backend directly as the
      final part of the OpenId/Oauth Flow
    parameters:
      - name: Authorization
        in: header
        required: true
        description: "A valid access_token (e.g.: Authorization: Bearer <access-token-value>)."
        schema:
          type: string
    post:
      summary: POST request using a valid access token
      responses:
        "200":
          description: 200 Ok
          content:
            application/jwt:
              schema:
                $ref: "#/components/schemas/VcResponse"
        "400":
          description: 400 Bad Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: 500 Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - api_key:
            Fn::If:
              - IsLocalDevEnvironment
              - Ref: AWS::NoValue
              - []
      x-amazon-apigateway-request-validator: "Validate both"
      x-amazon-apigateway-integration:
        httpMethod: "POST"
        passthroughBehavior: "when_no_templates"
        type: "aws"
        credentials:
          Fn::Sub: ${ExecuteStateMachineRole.Arn}
        uri:
          Fn::Sub: arn:${AWS::Partition}:apigateway:${AWS::Region}:states:action/StartSyncExecution
        requestTemplates:
          application/json:
            Fn::Sub: |-
              {
                "input": "{\"bearerToken\": \"$util.escapeJavaScript($input.params('Authorization').trim())\"}",
                "stateMachineArn": "${NinoIssueCredentialStateMachine.Arn}:live"
              }
        responses:
          default:
            statusCode: 500
            responseTemplates:
              application/jwt: |
                #set($response = $util.parseJson($input.body))
                #set($output = $util.parseJson($response.output))
                #if($response.status == "FAILED")
                #set($context.responseOverride.status = 500)
                #elseif($output.httpStatus)
                #set($context.responseOverride.status = $output.httpStatus)
                #else
                #set($context.responseOverride.status = 200)
                #end
                #set($context.responseOverride.header.Content-Type = "application/jwt")
                $output.jwt

components:
  schemas:
    JWKSFile:
      type: object
      required:
        - keys
      additionalProperties: true
      properties:
        keys:
          type: array
          description: >-
            The value of the `keys` parameter is an array of JWK values. By default, the order of the JWK
            values within the array does not imply an order of preference among them, although applications of
            JWK Sets can choose to assign a meaning to the order for their purposes, if desired.
          items:
            type: object
            additionalProperties: true
            description: >-
              A JSON Web Key (JWK) as defined by [RFC7517](https://www.rfc-editor.org/rfc/rfc7517)
            properties:
              kty:
                type: string
                description: >-
                  The `kty` (key type) parameter identifies the cryptographic algorithm family used with the
                  key, such as `RSA or `EC`
              use:
                type: string
                enum:
                  - sig
                  - enc
                description: >-
                  The "use" (public key use) parameter identifies the intended use of the public key.  The
                  "use" parameter is employed to indicate whether a public key is used for encrypting data or
                  verifying the signature on data. Valid values are `sig` (signature) and `enc` (encryption).
              alg:
                type: string
                description: >-
                  The `alg` (algorithm) parameter identifies the algorithm intended for use with the key.
              kid:
                type: string
                description: >-
                  The `kid` (key ID) parameter is used to match a specific key. This is used, for instance,
                  to choose among a set of keys within a JWK Set during key rollover.  The structure of the
                  `kid` value is unspecified.
              e:
                type: string
                description: >-
                  public exponent
              n:
                type: string
                description: >-
                  public modulus
            required:
              - kty
    VcResponse:
      title: "Vc"
      type: string
      format: application/jwt
      pattern: ^([a-zA-Z0-9_=]+)\.([a-zA-Z0-9_=]+)\.([a-zA-Z0-9_\-\+\/=]+)$
      example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
    TokenResponse:
      title: "AccessToken"
      required:
        - "access_token"
        - "expires_in"
      type: "object"
      properties:
        access_token:
          type: string
          description: "The access token for the given token request"
        token_type:
          type: string
          description: "The authentication scheme"
          example: Bearer
        expires_in:
          type: string
          description: "The token expiration time in seconds"
          example: "3600"
        refresh_token:
          type: string
          description: "The refresh token is optional and not currently applicable"
    Error:
      title: "Error Schema"
      type: "object"
      properties:
        message:
          type: "string"

x-amazon-apigateway-request-validators:
  Validate both:
    validateRequestBody: true
    validateRequestParameters: true
  Validate Param only:
    validateRequestParameters: true
    validateRequestBody: false