github.com/thetreep/go-swagger@v0.0.0-20240223100711-35af64f14f01/fixtures/bugs/2919/edge-api/shared/current-identity-mfa.yml (about)

     1  ---
     2  paths:
     3    current-identity-mfa:
     4      post:
     5        summary: Initiate MFA enrollment
     6        description: >
     7          Allows authenticator based MFA enrollment. If enrollment has already been completed, it must be
     8          disabled before attempting to re-enroll. Subsequent enrollment request is completed via
     9          `POST /current-identity/mfa/verify`
    10        security:
    11          - ztSession: [ ]
    12        tags:
    13          - Current Identity
    14          - MFA
    15        operationId: enrollMfa
    16        responses:
    17          '201':
    18            $ref: 'standard-responses.yml#/responses/createResponse'
    19          '401':
    20            $ref: 'standard-responses.yml#/responses/unauthorizedResponse'
    21          '409':
    22            $ref: '#/responses/alreadyMfaEnrolledResponse'
    23      get:
    24        summary: Returns the current status of MFA enrollment
    25        description: >
    26          Returns details about the current MFA enrollment. If enrollment has not been completed it will
    27          return the current MFA configuration details necessary to complete a `POST /current-identity/mfa/verify`.
    28        security:
    29          - ztSession: [ ]
    30        tags:
    31          - Current Identity
    32          - MFA
    33        operationId: detailMfa
    34        responses:
    35          '200':
    36            $ref: '#/responses/detailMfa'
    37          '401':
    38            $ref: 'standard-responses.yml#/responses/unauthorizedResponse'
    39          '404':
    40            $ref: 'standard-responses.yml#/responses/notFoundResponse'
    41      delete:
    42        summary: Disable MFA for the current identity
    43        description: >
    44          Disable MFA for the current identity. Requires a current valid time based one time password if MFA enrollment
    45          has been completed. If not, code should be an empty string. If one time passwords are not available and admin
    46          account can be used to remove MFA from the identity via `DELETE /identities/<id>/mfa`.
    47        security:
    48          - ztSession: [ ]
    49        tags:
    50          - Current Identity
    51          - MFA
    52        operationId: deleteMfa
    53        parameters:
    54          - name: mfaValidation
    55            in: body
    56            required: false
    57            description: 'An MFA validation request'
    58            schema:
    59              $ref: 'authenticate.yml#/definitions/mfaCode'
    60          - name: mfa-validation-code
    61            in: header
    62            required: false
    63            type: string
    64        responses:
    65          '200':
    66            $ref: 'standard-responses.yml#/responses/emptyResponse'
    67          '401':
    68            $ref: 'standard-responses.yml#/responses/unauthorizedResponse'
    69          '404':
    70            $ref: 'standard-responses.yml#/responses/notFoundResponse'
    71    current-identity-mfa-qr-code:
    72      get:
    73        summary: Show a QR code for unverified MFA enrollments
    74        description: >
    75          Shows an QR code image for unverified MFA enrollments. 404s if the MFA enrollment has been completed or
    76          not started.
    77        security:
    78          - ztSession: [ ]
    79        tags:
    80          - Current Identity
    81          - MFA
    82        operationId: detailMfaQrCode
    83        produces:
    84          - image/png
    85          - application/json
    86        responses:
    87          200:
    88            description: OK
    89          404:
    90            description: No MFA enrollment or MFA enrollment is completed
    91    current-identity-mfa-verify:
    92      post:
    93        summary: Complete MFA enrollment by verifying a time based one time token
    94        description: >
    95          Completes MFA enrollment by accepting a time based one time password as verification. Called
    96          after MFA enrollment has been initiated via `POST /current-identity/mfa`.
    97        security:
    98          - ztSession: [ ]
    99        tags:
   100          - Current Identity
   101          - MFA
   102        operationId: verifyMfa
   103        parameters:
   104          - name: mfaValidation
   105            in: body
   106            required: true
   107            description: 'An MFA validation request'
   108            schema:
   109              $ref: 'authenticate.yml#/definitions/mfaCode'
   110        responses:
   111          '200':
   112            $ref: 'standard-responses.yml#/responses/emptyResponse'
   113          '401':
   114            $ref: 'standard-responses.yml#/responses/unauthorizedResponse'
   115          '404':
   116            $ref: 'standard-responses.yml#/responses/notFoundResponse'
   117    current-identity-mfa-recovery-codes:
   118      get:
   119        summary: For a completed MFA enrollment view the current recovery codes
   120        description: >
   121          Allows the viewing of recovery codes of an MFA enrollment. Requires a current valid
   122          time based one time password to interact with. Available after a completed MFA enrollment.
   123        security:
   124          - ztSession: [ ]
   125        tags:
   126          - Current Identity
   127          - MFA
   128        operationId: detailMfaRecoveryCodes
   129        parameters:
   130          - name: mfaValidation
   131            in: body
   132            required: false
   133            description: 'An MFA validation request'
   134            schema:
   135              $ref: 'authenticate.yml#/definitions/mfaCode'
   136          - name: mfa-validation-code
   137            in: header
   138            required: false
   139            type: string
   140        responses:
   141          '200':
   142            $ref: 'standard-responses.yml#/responses/emptyResponse'
   143          '401':
   144            $ref: 'standard-responses.yml#/responses/unauthorizedResponse'
   145          '404':
   146            $ref: 'standard-responses.yml#/responses/notFoundResponse'
   147      post:
   148        summary: For a completed MFA enrollment regenerate the recovery codes
   149        description: >
   150          Allows regeneration of recovery codes of an MFA enrollment. Requires a current valid
   151          time based one time password to interact with. Available after a completed MFA enrollment. This replaces
   152          all existing recovery codes.
   153        security:
   154          - ztSession: [ ]
   155        tags:
   156          - Current Identity
   157          - MFA
   158        operationId: createMfaRecoveryCodes
   159        parameters:
   160          - name: mfaValidation
   161            in: body
   162            required: true
   163            description: 'An MFA validation request'
   164            schema:
   165              $ref: 'authenticate.yml#/definitions/mfaCode'
   166        responses:
   167          '200':
   168            $ref: '#/responses/detailMfaRecoveryCodes'
   169          '401':
   170            $ref: 'standard-responses.yml#/responses/unauthorizedResponse'
   171          '404':
   172            $ref: 'standard-responses.yml#/responses/notFoundResponse'
   173  
   174  responses:
   175    alreadyMfaEnrolledResponse:
   176      description: The identity is already enrolled in MFA
   177      schema:
   178        $ref: 'standard-responses.yml#/definitions/apiErrorEnvelope'
   179      examples:
   180        'application/json':
   181          error:
   182            args:
   183            cause:
   184            causeMessage: ''
   185            code: ALREADY_MFA_ENROLLED
   186            message: The identity is already enrolled in MFA
   187            requestId: 270908d6-f2ef-4577-b973-67bec18ae376
   188          meta:
   189            apiEnrollmentVersion: 0.0.1
   190            apiVersion: 0.0.1
   191    mfaCreatedResponse:
   192      description: The create request was succesful and the response contains the location and details to complete MFA enrollment
   193      schema:
   194        $ref: '#/definitions/mfaCreatedEnvelope'
   195  
   196    detailMfa:
   197      description: The details of an MFA enrollment
   198      schema:
   199        $ref: '#/definitions/detailMfaEnvelope'
   200  
   201    detailMfaRecoveryCodes:
   202      description: The recovery codes of an MFA enrollment
   203      schema:
   204        $ref: '#/definitions/detailMfaRecoveryCodesEnvelope'
   205  
   206  definitions:
   207    mfaFormats:
   208      type: string
   209      enum:
   210        - numeric
   211        - alpha
   212        - alphaNumeric
   213    mfaProviders:
   214      type: string
   215      enum:
   216        - ziti
   217        - url
   218    mfaCreatedEnvelope:
   219      type: object
   220      required:
   221        - meta
   222        - error
   223      properties:
   224        meta:
   225          $ref: 'standard-responses.yml#/definitions/meta'
   226        error:
   227          $ref: '#/definitions/apiError'
   228    detailMfaEnvelope:
   229      type: object
   230      required:
   231        - meta
   232        - data
   233      properties:
   234        meta:
   235          $ref: 'standard-responses.yml#/definitions/meta'
   236        data:
   237          $ref: '#/definitions/detailMfa'
   238    detailMfa:
   239      type: object
   240      allOf:
   241        - $ref: 'base-entity.yml#/definitions/baseEntity'
   242        - required:
   243            - isVerified
   244          properties:
   245            isVerified:
   246              type: boolean
   247            recoveryCodes:
   248              type: array
   249              items:
   250                type: string
   251              description: Not provided if MFA verification has been completed
   252            provisioningUrl:
   253              type: string
   254              description: Not provided if MFA verification has been completed
   255    detailMfaRecoveryCodesEnvelope:
   256      type: object
   257      required:
   258        - meta
   259        - error
   260      properties:
   261        meta:
   262          $ref: 'standard-responses.yml#/definitions/meta'
   263        error:
   264          $ref: '#/definitions/detailMfaRecoveryCodes'
   265    detailMfaRecoveryCodes:
   266      type: object
   267      allOf:
   268        - $ref: '../shared/base-entity.yml#/definitions/baseEntity'
   269        - required:
   270            - recoveryCodes
   271          properties:
   272            recoveryCodes:
   273              type: array
   274              items:
   275                type: string