openapi: 3.0.1
info:
  title: Auth Identity Provider Connector REST APIs
  description: Identity Provider Integration Auth REST APIs
  version: '1'
servers:
  - url: 'https://api.plumery.com'
    description: Live Server
tags:
  - name: Custom Authentication
  - name: Custom Signing
paths:
  '/internal/v1/custom-auth/login:initiate':
    post:
      tags:
        - Custom Authentication
      description: |
        Validates session and initiates authentication session in identity provider system.
        Rereturns URL to redirect user to the Identity Provider for authentication.
      operationId: initiateIdentityProviderAuthentication
      summary: Initiate Identity Provider authentication
      parameters:
        - $ref: '#/components/parameters/xRequestId'
      requestBody:
        $ref: '#/components/requestBodies/InitIdentityProviderAuthRequest'
      responses:
        '200':
          $ref: '#/components/responses/InitIdentityProviderAuthResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/ServerError'

  '/internal/v1/custom-auth/login/status':
    get:
      tags:
        - Custom Authentication
      description: |
        Check whether the authentication in Identity Provider was successfully or not and returns the status.
      operationId: checkIdentityProviderAuthenticationStatus
      summary: Check Identity Provider authentication status
      parameters:
        - $ref: '#/components/parameters/xRequestId'
        - $ref: '#/components/parameters/correlationId'
      responses:
        '200':
          $ref: '#/components/responses/IdentityProviderAuthStatusResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/ServerError'

  '/internal/v1/custom-auth:init-signature':
    post:
      tags:
        - Custom Signing
      description: |
        Endpoint to initiate custom signature process in external Identity Provider system.
      operationId: Initiate custom signature
      summary: Initiate custom signature
      parameters:
        - $ref: '#/components/parameters/xRequestId'
      requestBody:
        $ref: '#/components/requestBodies/IdentityProviderInitSignatureRequest'
      responses:
        '204':
          $ref: '#/components/responses/NoContent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/ServerError'

  '/internal/v1/custom-auth:confirm-signature':
    post:
      tags:
        - Custom Signing
      description: |
        Endpoint to confirm custom signature process in external Identity Provider system.
        operationId: Confirm custom signing
        summary: Confirm custom signing
      parameters:
        - $ref: '#/components/parameters/xRequestId'
      requestBody:
        $ref: '#/components/requestBodies/IdentityProviderConfirmSigningRequest'
      responses:
        '200':
          $ref: '#/components/responses/IdentityProviderConfirmSigningResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  parameters:
    xRequestId:
      in: header
      name: X-Request-ID
      description: Request ID used for tracing. A new one will be generated if not provided.
      required: false
      example: 36a22460-ebc8-4ffe-a213-1683c5a420c5
      schema:
        type: string
    correlationId:
      in: query
      name: correlationId
      description: Correlation ID to correlate with init authentication request
      required: true
      example: 22dd73ae-a31f-4422-a1e9-0372c4da0f24
      schema:
        type: string
  requestBodies:
    InitIdentityProviderAuthRequest:
      description: Initiate Identity Provider authentication request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InitIdentityProviderAuthRequest'

    IdentityProviderInitSignatureRequest:
      description: Identity Provider signature initiation request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IdentityProviderInitSignatureRequest'

    IdentityProviderConfirmSigningRequest:
      description: Identity Provider custom signing confirmation request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IdentityProviderConfirmSigningRequest'

  responses:
    NoContent:
      description: Request was successfully executed, without further response being returned.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/NoContentResponse"
    BadRequest:
      description: Invalid request was provided
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ServerError:
      description: Internal server error occurred
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InitIdentityProviderAuthResponse:
      description: Identity Provider authentication initiation response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InitIdentityProviderAuthResponse'
    IdentityProviderAuthStatusResponse:
      description: Identity Provider authentication status response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IdentityProviderAuthStatusResponse'
    IdentityProviderConfirmSigningResponse:
      description: Identity Provider custom signing confirmation response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IdentityProviderConfirmSigningResponse'

  schemas:
    InitIdentityProviderAuthRequest:
      type: object
      properties:
        correlationId:
          type: string
          description: Correlation ID to help correlate with status check request
          example: 22dd73ae-a31f-4422-a1e9-0372c4da0f24
        initAuthDetails:
          type: object
          description: Details required to initiate authentication in Identity Provider
          additionalProperties: true

    InitIdentityProviderAuthResponse:
      type: object
      properties:
        redirectUrl:
          type: string
          description: URL to redirect user to Identity Provider for authentication
          example: 'https://eparaksts.sk.ee/auth?sessionId=abc123'

    IdentityProviderAuthStatusResponse:
      description: Identity Provider authentication status response
      type: object
      properties:
        status:
          type: string
          description: Status of the authentication initiation in Identity Provider
          enum:
            - PENDING
            - SUCCESS
            - FAILED
          example: SUCCESS
        userId:
          type: string
          description: Identifier of the authenticated user in Plumery system
          example: john.doe
        error:
          type: string
          description: Error message in case of authentication failure. This message will be forwarded to mobile/web app for user display.
          example: User did not complete confirmation in external application
        code:
          type: string
          description: Error code in case of authentication failure
          example: IDP_AUTH_FAILED

    ErrorResponse:
      description: Returned in case of an error, internal server error or invalid request
      type: object
      properties:
        error:
          type: string
          description: Error message
        code:
          type: string
          description: Error code

    NoContentResponse:
      type: string
      description: |
        Request was successfully executed, without further response being returned.

    DataToSign:
      description: Data that needs to be hashed by connector and signed by Identity Provider application
      type: object
      properties:
        username:
          type: string
          example: 'john.snow'
        action:
          type: string
          description: Action for which the data is being signed
          example: 'LOGIN'
        nonce:
          type: string
          description: Unique nonce to ensure the signature is unique
          example: 'b3c9e1f4-8f3a-4d2e-9c6b-1a2b3c4d5e6f'

    SignatureContextData:
      description: Context data related to the signature being performed
      type: object
      properties:
        dataToSign:
          $ref: '#/components/schemas/DataToSign'

    IdentityProviderInitSignatureRequest:
      description: Identity Provider signature initiation request
      type: object
      properties:
        correlationId:
          type: string
          description: Correlation ID to help correlate with signature confirmation request
          example: 22dd73ae-a31f-4422-a1e9-0372c4da0f24
        signatureContextData:
          $ref: '#/components/schemas/SignatureContextData'
        additionalDetails:
          type: object
          description: Details required to initiate signature in Identity Provider
          additionalProperties: true

    IdentityProviderConfirmSigningResponse:
      description: Identity Provider custom signing confirmation response
      type: object
      properties:
        signature:
          type: string
          description: Base64 encoded signature value returned from Identity Provider after successful signature confirmation
          example: 'MEUCIQDfX9+5s6j3Z2V1yQ1F7Zx3G5vYz1+8j3F4vX9+5s6j3ZgIgL5s6j3Z2V1yQ1F7Zx3G5vYz1+8j3F4vX9+5s6j3Zg=='
        signatureTimestamp:
          type: string
          format: date-time
          description: Timestamp indicating when the signature was created
          example: '2024-10-01T12:34:56Z'
        certificate:
          type: string
          description: Base64 encoded certificate used to create the signature
          example: 'MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQ...'
        status:
          type: string
          description: Status of the signature confirmation in Identity Provider
          enum:
            - PENDING
            - SUCCESS
            - FAILED
          example: SUCCESS
        error:
          type: string
          description: Error message in case of signature confirmation failure. This message will be forwarded to mobile/web app for user display.
          example: User did not complete signature confirmation in external application
        code:
          type: string
          description: Error code in case of signature confirmation failure
          example: IDP_SIGNATURE_FAILED


    IdentityProviderConfirmSigningRequest:
      description: |
        Identity Provider custom signing confirmation request
      type: object
      properties:
        correlationId:
          type: string
          description: Correlation ID to correlate with signature initiation request
          example: 22dd73ae-a31f-4422-a1e9-0372c4da0f24
        username:
          type: string
          description: Plumery user identifier
          example: john.doe
        additionalDetails:
          type: object
          description: Details required to confirm signature in Identity Provider
          additionalProperties: true