edge-api/source/client/enroll.yml

---
paths:
  enroll:
    parameters:
      - $ref: '../shared/parameters.yml#/token-optional'
      - $ref: '../shared/parameters.yml#/method-optional'
      - in: body
        name: body
        schema:
          $ref: '#/definitions/genericEnroll'
    post:
      summary: Enroll an identity via one-time-token
      description: present a OTT and CSR to receive a long-lived client certificate
      operationId: enroll
      tags:
        - Enroll
      consumes:
        - application/pkcs7
        - application/json
        - application/x-pem-file
        - text/plain
      produces:
        - application/json
      responses:
        '200':
          $ref: '#/responses/enrollmentCerts'
        '400':
          $ref: '../shared/standard-responses.yml#/responses/badRequestResponse'
        '404':
          $ref: '../shared/standard-responses.yml#/responses/notFoundResponse'
        '429':
          $ref: '../shared/standard-responses.yml#/responses/rateLimitedResponse'
        '503':
          $ref: '../shared/standard-responses.yml#/responses/serverUnavailableResponse'
        '409':
          $ref: '../shared/standard-responses.yml#/responses/conflictResponse'
        '410':
          $ref: '../shared/standard-responses.yml#/responses/goneResponse'

  enroll-ca:
    post:
      summary: Enroll an identity with a pre-exchanged certificate
      description: |
        For CA auto enrollment, an identity is not created beforehand.
        Instead one will be created during enrollment. The client will present a client certificate that is signed by a
        Certificate Authority that has been added and verified (See POST /cas and POST /cas/{id}/verify).

        During this process no CSRs are requires as the client should already be in possession of a valid certificate.
      operationId: enrollCa
      tags:
        - Enroll
      responses:
        '200':
          $ref: '../shared/standard-responses.yml#/responses/emptyResponse'
        '400':
          $ref: '../shared/standard-responses.yml#/responses/badRequestResponse'
        '404':
          $ref: '../shared/standard-responses.yml#/responses/notFoundResponse'
        '429':
          $ref: '../shared/standard-responses.yml#/responses/rateLimitedResponse'
        '503':
          $ref: '../shared/standard-responses.yml#/responses/serverUnavailableResponse'

  enroll-ott:
    parameters:
      - name: ottEnrollmentRequest
        in: body
        required: true
        description: An OTT enrollment request
        schema:
          $ref: '#/definitions/ottEnrollmentRequest'

    post:
      summary: Enroll an identity via one-time-token
      description: |
        Enroll an identity via a one-time-token which is supplied via a query string parameter. This enrollment method
        expects a PEM encoded CSRs to be provided for fulfillment. It is up to the enrolling identity to manage the
        private key backing the CSR request.
      operationId: enrollOtt
      tags:
        - Enroll
      responses:
        '200':
          $ref: '#/responses/enrollmentCerts'
        '400':
          $ref: '../shared/standard-responses.yml#/responses/badRequestResponse'
        '404':
          $ref: '../shared/standard-responses.yml#/responses/notFoundResponse'
        '429':
          $ref: '../shared/standard-responses.yml#/responses/rateLimitedResponse'
        '503':
          $ref: '../shared/standard-responses.yml#/responses/serverUnavailableResponse'

  enroll-ottca:
    parameters:
      - name: ottEnrollmentRequest
        in: body
        required: true
        description: An OTT enrollment request
        schema:
          $ref: '#/definitions/ottEnrollmentRequest'
    post:
      summary: Enroll an identity via one-time-token with a pre-exchanged client certificate
      description: |
        Enroll an identity via a one-time-token that also requires a pre-exchanged client certificate to match a
        Certificate Authority that has been added and verified (See POST /cas and POST /cas{id}/verify). The client
        must present a client certificate signed by CA associated with the enrollment. This enrollment is similar to
        CA auto enrollment except that is required the identity to be pre-created.

        As the client certificate has been pre-exchanged there is no CSR input to this enrollment method.
      operationId: enrollOttCa
      tags:
        - Enroll
      responses:
        '200':
          $ref: '../shared/standard-responses.yml#/responses/emptyResponse'
        '400':
          $ref: '../shared/standard-responses.yml#/responses/badRequestResponse'
        '429':
          $ref: '../shared/standard-responses.yml#/responses/rateLimitedResponse'
        '503':
          $ref: '../shared/standard-responses.yml#/responses/serverUnavailableResponse'
  enroll-token:
    summary: Enroll an identity via external tokens (e.g. OAuth2).
    description: |
      Enroll an identity via external tokens (e.g. OAuth2). If a CSR is provided, the identity will be created with
      a certificate. If no CSR is provided, the identity will perform future authentication via tokens. The
      backing external JWT signer must be configured to allow enrollment.
    operationId: enrollToken
    tags:
      - Enroll
    post:
      parameters:
        - name: zt-token-issuer-id
          in: header
          description: The id of the token issuer to use for enrollment, optional as long the the token is not opaque
          required: false
          type: string
        - name: Authorization
          in: header
          description: An identifying token to enroll with
          required: true
          type: string
        - name: tokenEnrollmentRequest
          in: body
          required: true
          description: |
            A  enrollment request with or without a CSR. Including a CSR indicated an attempt to enroll with certificate 
            credentials. If no CSR is included, the request is assumed to be a token enrollment request that will
            authenticate via tokens.
          schema:
            $ref: '#/definitions/tokenEnrollmentRequest'
      operationId: enrollToken
      tags:
        - Enroll
      responses:
        '200':
          $ref: '#/responses/enrollmentCerts'
        '400':
          $ref: '../shared/standard-responses.yml#/responses/badRequestResponse'
        '404':
          $ref: '../shared/standard-responses.yml#/responses/notFoundResponse'
        '429':
          $ref: '../shared/standard-responses.yml#/responses/rateLimitedResponse'
        '503':
          $ref: '../shared/standard-responses.yml#/responses/serverUnavailableResponse'
        '409':
          $ref: '../shared/standard-responses.yml#/responses/conflictResponse'
        '410':
          $ref: '../shared/standard-responses.yml#/responses/goneResponse'
  enroll-updb:
    parameters:
      - $ref: '../shared/parameters.yml#/token'
      - name: updbCredentials
        in: body
        required: true
        schema:
          type: object
          properties:
            username:
              $ref: '../shared/authenticate.yml#/definitions/username'
            password:
              $ref: '../shared/authenticate.yml#/definitions/password'
    post:
      summary: Enroll an identity via one-time-token
      description: |
        Enrolls an identity via a one-time-token to establish an initial username and password combination
      operationId: enrollUpdb
      tags:
        - Enroll
      responses:
        '200':
          $ref: '../shared/standard-responses.yml#/responses/emptyResponse'
        '400':
          $ref: '../shared/standard-responses.yml#/responses/badRequestResponse'
        '404':
          $ref: '../shared/standard-responses.yml#/responses/notFoundResponse'
        '429':
          $ref: '../shared/standard-responses.yml#/responses/rateLimitedResponse'
        '503':
          $ref: '../shared/standard-responses.yml#/responses/serverUnavailableResponse'

  enroll-erott:
    parameters:
      - name: erOttEnrollmentRequest
        in: body
        required: true
        description: An OTT enrollment request
        schema:
          $ref: '#/definitions/erOttEnrollmentRequest'
    post:
      summary: Enroll an edge-router
      description: |
        Enrolls an edge-router via a one-time-token to establish a certificate based identity.
      operationId: enrollErOtt
      tags:
        - Enroll
      responses:
        '200':
          $ref: '#/responses/erOttResponse'
        '400':
          $ref: '../shared/standard-responses.yml#/responses/badRequestResponse'
        '429':
          $ref: '../shared/standard-responses.yml#/responses/rateLimitedResponse'
        '503':
          $ref: '../shared/standard-responses.yml#/responses/serverUnavailableResponse'

  enroll-extend-router:
    post:
      summary: Extend the life of a currently enrolled router's certificates
      description: |
        Allows a router to extend its certificates' expiration date by
        using its current and valid client certificate to submit a CSR. This CSR may
        be passed in using a new private key, thus allowing private key rotation or swapping.

        After completion any new connections must be made with certificates returned from a 200 OK
        response. The previous client certificate is rendered invalid for use with the controller even if it
        has not expired.

        This request must be made using the existing, valid, client certificate.
      operationId: extendRouterEnrollment
      parameters:
        - name: routerExtendEnrollmentRequest
          in: body
          required: true
          schema:
            $ref: '#/definitions/routerExtendEnrollmentRequest'
      tags:
        - Enroll
        - Extend Enrollment
      responses:
        '200':
          $ref: '#/responses/routerExtendEnrollmentResponse'
        '400':
          $ref: '../shared/standard-responses.yml#/responses/badRequestResponse'
        '401':
          $ref: '../shared/standard-responses.yml#/responses/unauthorizedResponse'
        '429':
          $ref: '../shared/standard-responses.yml#/responses/rateLimitedResponse'
  enroll-jwks:
    get:
      summary: List JSON Web Keys associated with enrollment
      description: |
        Returns a list of JSON Web Keys (JWKS) that are used for enrollment signing. The keys listed here are used
        to sign and co-sign enrollment JWTs. They can be verified through a challenge endpoint, using the public keys
        from this endpoint to verify the target machine has possession of the related private key.
      operationId: getEnrollmentJwks
      tags:
        - Enroll
      responses:
        '200':
          $ref: '#/responses/getJwksResponse'
  enroll-challenge:
    post:
      summary: Allows verification of a controller or cluster of controllers as being the valid target for enrollment.
      description: |
        A caller may submit a nonce and a key id (kid) from the enrollment JWKS endpoint or enrollment JWT that will
        be used to sign the nonce. The resulting signature may be validated with the associated public key in order
        to verify a networks identity during enrollment. The nonce must be a valid formatted UUID.
      operationId: enrollmentChallenge
      parameters:
        - name: nonce
          in: body
          required: true
          schema:
            $ref: '#/definitions/nonceChallenge'
      tags:
        - Enroll
      responses:
        '200':
          $ref: '#/responses/nonceChallengeResponse'
        '400':
          $ref: '../shared/standard-responses.yml#/responses/badRequestResponse'
        '429':
          $ref: '../shared/standard-responses.yml#/responses/rateLimitedResponse'

responses:
  erOttResponse:
    description: A response containing the edge routers signed certificates (server chain, server cert, CAs).
    headers:
      WWW-Authenticate:
        description: "Denotes different type of security token related information"
        type: array
        items:
          type: string
    schema:
      $ref: '#/definitions/enrollmentCertsEnvelope'
  routerExtendEnrollmentResponse:
    description: A response containing the edge routers new signed certificates (server chain, server cert, CAs).
    headers:
      WWW-Authenticate:
        description: "Denotes different type of security token related information"
        type: array
        items:
          type: string
    schema:
      $ref: '#/definitions/enrollmentCertsEnvelope'
  enrollmentCerts:
    description: A response containing and identities client certificate chains
    headers:
      WWW-Authenticate:
        description: "Denotes different type of security token related information"
        type: array
        items:
          type: string
    schema:
      $ref: '#/definitions/enrollmentCertsEnvelope'
  getJwksResponse:
    description: A JWKS response for enrollment.
    headers:
      WWW-Authenticate:
        description: "Denotes different type of security token related information"
        type: array
        items:
          type: string
    schema:
      $ref: '../shared/jwks.yml#/definitions/jwks'
  nonceChallengeResponse:
    description: A nonce challenge response. The contents will be the signature of the nonce, the key id used, and algorithm used to produce the signature.
    headers:
      WWW-Authenticate:
        description: "Denotes different type of security token related information"
        type: array
        items:
          type: string
    schema:
      $ref: '#/definitions/nonceSignature'

definitions:
  genericEnroll:
    type: object
    # the properties here are all over the place due to legacy behavior
    properties:
      # for identity enrollment (ca), this is the "requested name"
      name:
        type: string

        # for identity enrollment (updb)
      username:
        $ref: '../shared/authenticate.yml#/definitions/username'
      password:
        $ref: '../shared/authenticate.yml#/definitions/password'

      # for identity enrollment (ott) enrollment
      clientCsr:
        type: string

      # for erott
      serverCertCsr:
        type: string
      certCsr:
        type: string
  tokenEnrollmentRequest:
    type: object
    properties:
      clientCsr:
        type: string
  ottEnrollmentRequest:
    type: object
    properties:
      token:
        type: string
      clientCsr:
        type: string
  erOttEnrollmentRequest:
    type: object
    properties:
      token:
        type: string
      clientCsr:
        type: string
      serverCsr:
        type: string
  enrollmentCertsEnvelope:
    type: object
    properties:
      meta:
        $ref: '../shared/standard-responses.yml#/definitions/meta'
      data:
        $ref: '#/definitions/enrollmentCerts'
  enrollmentCerts:
    type: object
    properties:
      serverCert:
        type: string
        description: A PEM encoded set of certificates to use as the servers chain
      cert:
        type: string
        description: A PEM encoded set of certificates to use as the client chain
      ca:
        type: string
        description: A PEM encoded set of CA certificates to trust
  routerExtendEnrollmentRequest:
    type: object
    required:
      - serverCertCsr
      - certCsr
    properties:
      serverCertCsr:
        type: string
      certCsr:
        type: string
  nonceSignature:
    type: object
    required:
      - signature
      - algorithm
      - kid
      - caPool
    properties:
      signature:
        type: string
      algorithm:
        type: string
      kid:
        type: string
      caPool:
        type: string
  nonceChallenge:
    type: object
    required:
      - nonce
      - keyId
    properties:
      nonce:
        type: string
        format: uuid
      keyId:
        type: string