openapi: "3.1.0"
info:
  title: Authentication OpenID WS Client
  description: |
    This document describes the OpenID 1.0 interfaces exposed by an external authentication platform and expected by Authentication HUB as client server.
    
    | Changes | Versions  | Date       |
    |---------|-----------|------------|
    | None    | 26R1_1.0  | 26/09/2025 |
  version: ""
paths:
  /authorize:
    get:
      tags:
        - "openId"
      operationId: "authorize"
      description: |
        The Authorization Endpoint performs Authentication of the End-User. 
        This is done by sending the User Agent to the Authorization Server’s Authorization Endpoint for Authentication and Authorization,
        using request parameters defined by OAuth 2.0 and additional parameters and parameter values defined by OpenID Connect.
      parameters:
        - name: scope
          in: query
          required: true
          schema:
            type: string
            const: "openid"
        - name: response_type
          in: query
          required: true
          schema:
            type: string
            const: "code"
        - name: client_id
          in: query
          required: true
          schema:
            type: string
            maxLength: 255
          description: "Client identifier retrieved during registration"
          example: "s6BhdRkqt3"
        - name: redirect_uri
          in: query
          required: true
          schema:
            type: string
            maxLength: 2048
          description: "ACS redirect uri"
          example: "https://client.example.org/cb"
        - name: state
          in: query
          required: true
          schema:
            type: string
          description: "MUST contain at least 128 bits of entropy (for example at least 22 random characters A-Z, a-z, 0-9)."
          example: "af0ifjsldkj"
        - name: Nonce
          in: query
          required: true
          schema:
            type: string
          description: "MUST contain at least 128 bits of entropy (for example at least 22 random characters A-Z, a-z, 0-9)."
          example: "n-0S6_WzA2Mj"
        - name: Prompt
          in: query
          required: true
          schema:
            type: string
            const: "login"
        - name: transaction_id
          in: query
          required: true
          schema:
            type: string
            maxLength: 36
          description: "UUID HUB authentication id"
          example: "077106be-ec98-491d-bc8d-f9a794e4ab41"
        - name: ui_locales
          in: query
          schema:
            type: string
          description: "Format described in rfc5646. End user language preference tags (BCP 47)"
        - name: session_id
          in: query
          schema:
            type: string
            maxLength: 36
          description: "HUB / ACS session id"
          example: "3a6f4695-e791-45c4-9a9f-95bf0e416346"
        - name: payee
          in: query
          schema:
            type: string
          description: "Areq.merchantName Optional for NPA"
          example: "merchant"
        - name: amount
          in: query
          schema:
            type: string
          description: "Amount without exponent. Areq.purchaseAmount Optional for NPA"
          example: "10000"
        - name: currency_code
          in: query
          schema:
            type: string
            maxLength: 3
          description: "Currency code on 3 digits as defined in ISO 4217. Areq.purchaseCurrency Optional for NPA"
          example: "978"
        - name: currency_exponent
          in: query
          schema:
            type: string
          description: "Minor units of currency as specified in the ISO 4217 currency exponent. Areq.purchaseExponent Optional for NPA"
          example: "2"
        - name: trusted_enrollment_request
          in: query
          schema:
            type: boolean
          description: "Contains trusted beneficiary consent information"
          example: true
        - name: login_hint
          in: query
          schema:
            type: string
          description: "Hint to the Authorization Server about the login identifier the End-User might use to log in (if necessary)"
          example: "571a48b12"
        - name: code_challenge
          in: query
          schema:
            type: string
          description: "PKCE challenge code. B64 encoding of SHA256 of code verifier"
          example: "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"
        - name: code_challenge_method
          in: query
          schema:
            type: string
          description: "Constant equals S256 when code verifier transformation method is SHA256."
          example: "S256"
      responses:
        "302":
          description: Default response
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/Response'
                  - $ref: '#/components/schemas/ErrorResponse'
  /token:
    post:
      tags:
        - "openId"
      description: |
        To obtain an Access Token, an ID Token, and optionally a Refresh Token, 
        the HUB (Relying Party - Client) sends a Token Request to the Token Endpoint to obtain a Token Response, as described in Section 3.2 of OAuth 2.0 [RFC6749], 
        when using the Authorization Code Flow.
      operationId: "token"
      parameters:
        - name: "Authorization"
          in: "header"
          description: "OAuth2 Authorization"
          schema:
            type: "string"
            example: "Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW"
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  description: The type of grant (authorization code flow)
                  example: "authorization_code"
                code:
                  type: string
                  description: The authorization code received from the authorization server
                  example: "SplxlOBeZQQYbYS6WxSbIA"
                redirect_uri:
                  type: string
                  description: ACS redirect uri (same as authorization request)
                  minLength: 1
                  maxLength: 2048
                  example: "https://client.example.org/cb"
                code_verifier:
                  type: string
                  description: PKCE code verifier. High-entropy cryptographic random with a minimum length of 43 characters and a maximum length of 128 characters
                  example: "4KPEjoZGlz_2FMB4dQi1UqtKMdIb97jvKsCANOM7XuA"
              required:
                - grant_type
                - code
                - redirect_uri
      responses:
        '200':
          description: Successful token exchange
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                    description: The access token issued by the authorization server. Not used by the HUB
                  token_type:
                    type: string
                    description: The type of the token
                    example: "Bearer"
                  expires_in:
                    type: integer
                    description: The lifetime in seconds of the access token. Not used by the HUB
                  id_token:
                    oneOf:
                      - $ref: '#/components/schemas/JWSToken'
                      - $ref: '#/components/schemas/JWEToken'
        '400':
          description: Bad Request - Invalid request parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                      - "invalid_request"
                      - "invalid_grant"
                      - "unauthorized_client"
                      - "unsupported_grant_type"
                  error_description:
                    type: string
                    enum:
                      - "The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed."
                      - "The provided authorization grant (e.g., authorization code, resource owner credentials) is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client."
                      - "The authenticated client is not authorized to use this authorization grant type."
                      - "The authorization grant type is not supported by the authorization server."
        '401':
          description: Client authentication failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "invalid_client"
                  error_description:
                    type: string
                    example: "Client authentication failed"
  /.well-known/openid-configuration:
    get:
      summary: OpenID Connect Provider Configuration
      description: Returns metadata about the OpenID Connect Provider.
      responses:
        '200':
          description: Successful response with provider configuration
          content:
            application/json:
              schema:
                type: object
                properties:
                  issuer:
                    type: string
                    format: uri
                    example: "https://server.example.com"
                  authorization_endpoint:
                    type: string
                    format: uri
                    example: "https://server.example.com/oauth2/authorize"
                  token_endpoint:
                    type: string
                    format: uri
                    example: "https://server.example.com/oauth2/token"
                  jwks_uri:
                    type: string
                    format: uri
                    example: "https://server.example.com/.well-known/jwks.json"
  /.well-known/jwks:
    get:
      summary: JSON Web Key Set endpoint
      description: |
        The HUB will keep the signing keys in cache session with the corresponding kid value.
        A call to the JWKS endpoint is done to retrieve the public key only in the following cases:
        - On each restarting the application,
        - On each renewing of the public key; when a new “kid” value is returned by OpenID Provider,
        - Once a day to check the availability of the service.

      responses:
        '200':
          description: Successful response returning JWKS
          content:
            application/json:
              schema:
                type: object
                properties:
                  keys:
                    type: array
                    description: Array of JSON Web Keys
                    items:
                      type: object
                      required:
                        - kty
                        - kid
                        - use
                        - alg
                        - n
                        - e
                      properties:
                        kty:
                          type: string
                          example: RSA
                          description: Key type
                        kid:
                          type: string
                          example: "b3d7f8a9-2c5e-4a3f-8e6a-123456789abc"
                          description: Key ID
                        use:
                          type: string
                          example: sig
                          description: Public key use (signature)
                        alg:
                          type: string
                          example: RS256
                          description: Algorithm
                        n:
                          type: string
                          description: RSA modulus, base64url-encoded
                        e:
                          type: string
                          description: RSA public exponent, base64url-encoded
components:
  schemas:
    Response:
      type: object
      properties:
        code:
          type: string
          description: "Code from authentication Response (could be null or not provided see remark below)"
        state:
          type: string
          description: "MUST contain at least 128 bits of entropy (for example at least 22 random characters A-Z, a-z, 0-9)."
    ErrorResponse:
      type: object
      properties:
        state:
          type: string
          description: "MUST contain at least 128 bits of entropy (for example at least 22 random characters A-Z, a-z, 0-9)."
        error:
          type: string
          enum:
            - invalid_request
            - unauthorized_client
            - access_denied
            - unsupported_response_type
            - invalid_scope
            - server_error
            - temporarily_unavailable
        error_description:
          type: string
          description: "Error Description"
          examples:
            - "The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed."
            - "The client is not authorized to request an authorization code using this method."
            - "The resource owner or authorization server denied the request."
            - "The authorization server does not support obtaining an authorization code using this method."
            - "The requested scope is invalid, unknown, or malformed."
            - "Internal server error."
            - "The authorization server is currently unable to handle the request."
    JWSToken:
      type: object
      properties:
        header:
          type: object
          properties:
            alg:
              type: string
              description: The algorithm used to sign the JWT token. RSA SSA-PKCS1-v1_5 using SHA-256.
              example: "RS256"
              enum:
                - "RS256"
            kid:
              type: string
              description: The key ID (kid) should correspond to the key in the server's JWKS URL endpoint.
              example: "my-key-id"
          required:
            - alg
            - kid
        payload:
          type: object
          properties:
            iss:
              type: string
              description: Issuer identifier URL (without URI).
              example: "https://server.example.com"
            sub:
              type: string
              description: Subject identifier (unique for the transaction).
              example: "transaction-12345"
            aud:
              type: string
              description: Client ID (same as provided by client in authorization request).
              example: "client-id-67890"
            exp:
              type: integer
              description: Expiration time (Unix timestamp, current time + 5 minutes). NumericDate (RFC7519)
              example: 1616239022
            iat:
              type: integer
              description: Time at which the token was generated (Unix timestamp). NumericDate (RFC7519)
              example: 1616234922
            auth_time:
              type: integer
              description: Time when the authentication occurred (Unix timestamp). NumericDate (RFC7519)
              example: 1616232922
            nonce:
              type: string
              description: A nonce value, should match the previous value from the initial authentication request.
              example: "nonce-value-xyz"
          required:
            - iss
            - sub
            - aud
            - exp
            - iat
            - auth_time
            - nonce
    JWEToken:
      type: object
      properties:
        protected_header:
          type: object
          required: [ alg, enc, kid ]
          properties:
            alg:
              type: string
              enum: [ RSA-OAEP ]
              description: RSA ES OAEP using default parameters
            enc:
              type: string
              enum: [ A128GCM ]
              description: Encryption algorithm
            kid:
              type: string
              description: Key ID from server JWKS. Kid should be in server JWKS url endpoint
        encrypted_key:
          type: string
          description: Base64-encoded encrypted symmetric key
        iv:
          type: string
          description: Initialization Vector (Base64-encoded)
        ciphertext:
          $ref: '#/components/schemas/JWECiphertext'
        tag:
          type: string
          description: Authentication tag (Base64-encoded)
    JWECiphertext:
      type: object
      description: Encrypted JWS token (Base64-encoded string of the signed payload)
      properties:
        protected_header:
          type: object
          required: [ alg, kid ]
          properties:
            alg:
              type: string
              enum: [ RS256 ]
              description: RSA SSA-PKCS1-v1_5 using SHA-256
            kid:
              type: string
              description: Kid should be in server JWKS url endpoint
        payload:
          $ref: '#/components/schemas/JWSPayload'
        signature:
          type: string
          description: Base64-encoded JWS signature
    JWSPayload:
      type: object
      required:
        - iss
        - sub
        - aud
        - exp
        - iat
        - auth_time
        - nonce
        - data_type_1
        - data_value_1
      properties:
        iss:
          type: string
          format: uri
          description: Issuer identifier URL
        sub:
          type: string
          description: Subject identifier (unique per transaction)
        aud:
          type: string
          description: Audience (client ID)
        exp:
          type: integer
          format: int64
          description: Current time + 5m. NumericDate (RFC7519)
        iat:
          type: integer
          format: int64
          description: Time at which the token was generated. NumericDate (RFC7519)
        auth_time:
          type: integer
          format: int64
          description: Time when the authentication occurred. NumericDate (RFC7519)
        nonce:
          type: string
          description: Same value as in previous messages
        data_type_1:
          type: string
          description: Authentication data type
          examples:
            - SSN
            - DDN
            - PWD
        data_value_1:
          type: string
          description: Authentication data value
        data_type_2:
          type: string
          description: Optional. Authentication data type
        data_value_2:
          type: string
          description: Optional. Authentication data value
        data_type_3:
          type: string
          description: Optional. Authentication data type
        data_value_3:
          type: string
          description: Optional. Authentication data value
        data_type_4:
          type: string
          description: Optional. Authentication data type
        data_value_4:
          type: string
          description: Optional. Authentication data value
        data_type_5:
          type: string
          description: Optional. Authentication data type
        data_value_5:
          type: string
          description: Optional. Authentication data value