openapi: 3.0.3
info:
  title: E-Ident API
  version: "1.0"
  description: |
    The E-Ident identity broker services allows customers to access multiple
    electronic ID services/schemes through one common interface.
    This specification documents the API for accessing E-Ident.

    __This specification manages the following resources__
    * token endpoint - ID token retrieval
    * userinfo endpoint - authenticated user info
    * authorisation endpoint - the authentication request
    * global logout service - logging out
    
     __Terms and expressions__
    * Merchant/customer - the client or customer using this API to manage orders
    * eID - Electronic ID is a digital identity that allows to authenticate online and access service securely
    * IDP - an Identity Provider is a service that authenticates customer and provides identity information
    * Transaction - the process of authenticating a user with an IDP
    * Transaction ID - a unique identifier assigned to a specific transaction which is used to track the transaction
    * PKCE flow - The Proof Key for Code Exchange flow allows Single Page Application (SPA) and native apps to retrieve the ID token directly in a secure way without revealing the password and not through a backend call.
    * CIBA flow - The Client Initiated Backchannel Authentication flow enables authentication sessions to be initiated and processed in a different channel than the browser through the E-Ident web UI.
    * Binding Message - A message that establishes a secure connection between systems
    
    A merchant identifier (MID) and a secret code are required to integrate with E-Ident APIs. 
    
    The identifier and the code can be received by using the [Contact us form](https://ingroupe.com/in-trust-services-support-contact-page/) to IN Groupe support.
    To receive a dedicated setup, you need to be an E-Ident customer. To become a customer, [ Contact our sales department](https://ingroupe.com/in-trust-services-support-contact-page/)

    [The OAuth 2.0 Authorization Framework, RFC 7636](https://tools.ietf.org/html/rfc7636)
  contact:
    email: support.esecurity@nets.eu

paths:

###############################################################
#
# Authorization server endpoints
#
  /oidc/.well-known/openid-configuration:
    get:
      operationId: metadataEndpoint
      summary: Get OpenID Provider configuration information
      description: Discovery endpoint used by OpenID Connect Relying Party to discover the End-User's OpenID Provider and obtain information needed to interact with it, including its OAuth 2.0 endpoint locations.
      tags:
        - Discovery
      responses:
        '200':
          description: The OpenID Provider Metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenIDProviderMetadataResponse'

  /oidc/token:
    post:
      operationId: tokenRetrieve
      security:
        - basicAuth: []
      summary: Request Access Token
      tags:
        - Tokens
      description: |
        Retrieve the ID token for the authorisation whose code has been issued. This is also used for CIBA flow.
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/AuthorizationCodeTokenRequest'
      responses:
        '200':
          description: Authorization token (Bearer)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IDTokenResponse'
              example:
                access_token: 3049076c-d365-4b05-9e76
                token_type: Bearer
                id_token: eyJzdWIiOiIxMjM0NTY3ODkwIiwiaWF0IjoxNTE2MjM5MDIyfQo
                expires_in: 3600
        '400':
          description: As per RFC authorisation server responds with 400 in case of error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IDTokenErrorResponse'
              example:
                error: invalid_request
    delete:
      operationId: deleteToken
      security:
        - basicAuth: []
      summary: Invalidate access token
      tags:
        - Tokens
      responses:
        '200':
          description: Empty body with 200 code
        '403':
          description: Access Token already invalidated or not found
        '500':
          description: Internal server error

  /oidc/userinfo:
    get:
      operationId: userInfoGet
      security:
        - bearerAuth: []
      summary: Get claims about the authenticated End-User
      description: |
        The UserInfo Endpoint is an OAuth 2.0 Protected Resource that returns Claims about the authenticated End-User.
      tags:
        - Tokens
      responses:
        '400':
          description: Invalid Request
        '401':
          description: Invalid Token
        '200':
          description: Claims about the authenticated End-User
          content:
            application/jwt:
              schema:
                $ref: '#/components/schemas/UserInfoJWT'
    post:
      operationId: userInfoPost
      security:
        - bearerAuth: []
      summary: Get claims about the authenticated End-User
      description: |
        The UserInfo Endpoint is an OAuth 2.0 Protected Resource that returns Claims about the authenticated End-User.
      tags:
        - Tokens
      responses:
        '400':
          description: Invalid Request
        '401':
          description: Invalid Token
        '200':
          description: Claims about the authenticated End-User
          content:
            application/jwt:
              schema:
                $ref: '#/components/schemas/UserInfoJWT'

  /its/index.html:
    get:
      operationId: authorizeRedirect
      summary: The authorization endpoint for the 'authorization_code' flow.
      description: |
        ## Specification
        This is the [Authorization Endpoint][RFC 6749 §3.1], used as part of
        the [Authorization Code Grant][RFC 6749 §4.1], with the [PKCE
        extension][RFC 7636 §4.3].

        ## PSD2 Implementation notes
        For PSD2 TPPs, all clients must use the PKCE extension with the
        SHA-256 code challenge method.

        ## Documentation notes
        This endpoint is documented here mostly in order to document its
        parameters.

        The actual URLs of the authorization endpoints are documented on the
        [OAuth 2 Endpoints] page on the developer portal.

      tags:
        - Auth request

      parameters:
        - $ref: '#/components/parameters/client_id'
        - $ref: '#/components/parameters/redirect_uri'
        - $ref: '#/components/parameters/scope'
        - $ref: '#/components/parameters/response_type'
        - $ref: '#/components/parameters/state'
        - $ref: '#/components/parameters/nonce'
        - $ref: '#/components/parameters/ui_locale'
        - $ref: '#/components/parameters/display'
        - $ref: '#/components/parameters/prompt'
        - $ref: '#/components/parameters/max_age'
        - $ref: '#/components/parameters/id_token_hint'
        - $ref: '#/components/parameters/login_hint'
        - $ref: '#/components/parameters/acr_values'
        - $ref: '#/components/parameters/code_challenge'
        - $ref: '#/components/parameters/code_challenge_method'
        - $ref: '#/components/parameters/binding_message'
        - $ref: '#/components/parameters/eident_context'
        - $ref: '#/components/parameters/request'
        - $ref: '#/components/parameters/request_uri'

      responses:
        'default':
          description: |
            A HTML content shown to a user agent to begin the OAuth 2 authorization
            process. This endpoint will eventually redirect to the redirection
            endpoint specified by the TPP, which will receive the `code` and
            `state` parameters as specified by [RFC 6749 §4.1.2].

            In case parameters are missing or wrong, an error page will be
            shown. In case the `client_id` and the `redirect_uri` match, the
            user will also be redirected to the redirection endpoint specified
            by the TPP, with parameters `error` and `error_description` filled
            as specified by [RFC 6749 §4.1.2.1].

          content:
            text/html: {}

  /oidc/ciba.html:
    post:
      operationId: authorizeBackchannel
      security:
        - basicAuth: []
      summary: The CIBA authorization endpoint.
      description: |
        ## Specification
        This is the [Authorization Endpoint][RFC 6749 §3.1], used as part of
        the [Authorization Code Grant][RFC 6749 §4.1], with the [PKCE
        extension][RFC 7636 §4.3].

      tags:
        - Auth request

      parameters:
        - $ref: '#/components/parameters/scope'
        - $ref: '#/components/parameters/client_notification_token'
        - $ref: '#/components/parameters/login_hint_token'
        - $ref: '#/components/parameters/acr_values'
        - $ref: '#/components/parameters/id_token_hint'
        - $ref: '#/components/parameters/login_hint'
        - $ref: '#/components/parameters/user_code'
        - $ref: '#/components/parameters/binding_message'
        - $ref: '#/components/parameters/requested_expiry'

      responses:
        '200':
          description: Claims about the authenticated End-User
          content:
            application/jwt:
              schema:
                $ref: '#/components/schemas/CibaResponseJwt'
        '400':
          description: As per RFC authorisation server responds with 400 in case of error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationErrorResponse'
              example:
                error: invalid_request

  /auth_files/fetch.html:
    post:
      operationId: authFilesFetch
      security:
        - basicAuth: []
      summary: Auth-files endpoint
      description: |
        ## Specification
        This endpoint allows customers to fetch PDF or PNG files as documentation for an recent authentication through Passport Reader.

      tags:
        - Auth-files request

      parameters:
        - $ref: '#/components/parameters/tid'

      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                params:
                  type: object
                  required:
                    - type
                  properties:
                    type:
                      type: string
                      enum: [application/pdf, image/png]
                      description: MIME type of file to download
                    source:
                      type: string
                      enum: [document, selfie]
                      description: Required if type is image/png
                    pagesize:
                      type: string
                      enum: [a4, letter]
                      description: Optional if type is application/pdf
                    locale:
                      type: string
                      enum: [nb-NO, nn-NO, en-GB, da-DK, sv-SE, fi-FI, sv-FI]
                    user-password:
                      type: string
                    owner-password:
                      type: string
                    noprint:
                      type: boolean
                    noprinthq:
                      type: boolean
                    nocopy:
                      type: boolean
                    noedit:
                      type: boolean
                    noannotations:
                      type: boolean
                    nofillinforms:
                      type: boolean
                    noaccesscontent:
                      type: boolean
                    noassembledoc:
                      type: boolean
                    encrypt-metadata:
                      type: boolean
                    encryption-length:
                      type: integer
                      enum: [40, 48, 56, 64, 72, 80, 88, 96, 104, 112, 120, 128, 256]
                      default: 128
                    pdf-a-mode:
                      type: string
                      description: PDF/A profile compliance mode
                    generate-pades:
                      type: boolean
                addendum:
                  type: object
                  additionalProperties:
                    type: string
                  description: Custom merchant-defined attributes
                metadata:
                  type: object
                  properties:
                    dc:
                      type: object
                      additionalProperties:
                        type: string
                      description: Dublin Core properties
                    xmp:
                      type: object
                      additionalProperties:
                        type: string
                      description: XMP properties
                    pdf:
                      type: object
                      additionalProperties:
                        type: string
                      description: PDF-specific metadata
                    custom:
                      type: object
                      additionalProperties:
                        type: string
                      description: Custom metadata attributes

      responses:
        '200':
          description: Auth file successfully fetched
          content:
            application/jwt:
              schema:
                $ref: '#/components/schemas/AuthFilesResponseJson'
        '400':
          description: Authorisation server responds with 400 in case of error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthFilesErrorResponseJson'

###############################################################
#
# Merchant self service
#
#  /register:
#  /register/{client_id}:
#  /register/{client_id}/renew_secret:

###############################################################
#
# Component schemas
#
components:
  schemas:

    OpenIDProviderMetadataResponse:
      type: object
      required:
        [issuer, authorization_endpoint, jwks_uri, response_types_supported, subject_types_supported, id_token_signing_alg_values_supported, token_endpoint, backchannel_token_delivery_modes_supported, backchannel_authentication_endpoint, entity_statement_uri]
      properties:
        issuer:
          type: string
          description: |
            REQUIRED. URL using the https scheme with no query or fragment component that the OP asserts as its Issuer Identifier
        authorization_endpoint:
          type: string
          description: |
            REQUIRED. URL of the OP's OAuth 2.0 Authorization Endpoint
        token_endpoint:
          type: string
          description: |
            URL of the OP's OAuth 2.0 Token Endpoint
        userinfo_endpoint:
          type: string
          description: |
            RECOMMENDED. URL of the OP's UserInfo Endpoint
        jwks_uri:
          type: string
          description: |
            REQUIRED. URL of the OP's JSON Web Key Set [JWK] document.
        registration_endpoint:
          type: string
          description: |
            RECOMMENDED. URL of the OP's Dynamic Client Registration Endpoint
        scopes_supported:
          type: array
          items:
            $ref: '#/components/schemas/ScopesEnum'
          description: |
            RECOMMENDED. JSON array containing a list of the OAuth 2.0 [RFC6749] scope values that this server supports
          example: [openid, profile]
        response_types_supported:
          type: array
          items:
            $ref: '#/components/schemas/ResponseTypeEnum'
          description: |
            REQUIRED. JSON array containing a list of the OAuth 2.0 response_type values that this OP supports
        response_modes_supported:
          type: string
          description: |
            OPTIONAL. JSON array containing a list of the OAuth 2.0 response_mode values that this OP supports
        grant_types_supported:
          type: array
          items:
            $ref: '#/components/schemas/GrantTypeEnum'
          description: |
            OPTIONAL. JSON array containing a list of the OAuth 2.0 Grant Type values that this OP supports
        acr_values_supported:
          type: string
          description: |
            OPTIONAL. JSON array containing a list of the Authentication Context Class References that this OP supports
        subject_types_supported:
          type: array
          items:
            $ref: '#/components/schemas/SubjectTypeEnum'
          description: |
            REQUIRED. JSON array containing a list of the Subject Identifier types that this OP supports
        id_token_signing_alg_values_supported:
          type: array
          items:
            $ref: '#/components/schemas/IdTokenSignAlgEnum'
          description: |
            REQUIRED. JSON array containing a list of the JWS signing algorithms (alg values) supported by the OP for the ID Token to encode the Claims in a JWT
        id_token_encryption_alg_values_supported:
          type: string
          description: |
            OPTIONAL. JSON array containing a list of the JWE encryption algorithms (alg values) supported by the OP for the ID Token to encode the Claims in a JWT
        id_token_encryption_enc_values_supported:
          type: string
          description: |
            OPTIONAL. JSON array containing a list of the JWE encryption algorithms (enc values) supported by the OP for the ID Token to encode the Claims in a JWT
        userinfo_signing_alg_values_supported:
          type: string
          description: |
            OPTIONAL. JSON array containing a list of the JWS signing algorithms (alg values) [JWA] supported by the UserInfo Endpoint to encode the Claims in a JWT
        userinfo_encryption_alg_values_supported:
          type: string
          description: |
            OPTIONAL. JSON array containing a list of the JWE encryption algorithms (alg values) [JWA] supported by the UserInfo Endpoint to encode the Claims in a JWT
        userinfo_encryption_enc_values_supported:
          type: string
          description: |
            OPTIONAL. JSON array containing a list of the JWE encryption algorithms (enc values) [JWA] supported by the UserInfo Endpoint to encode the Claims in a JWT
        request_object_signing_alg_values_supported:
          type: string
          description: |
            OPTIONAL. JSON array containing a list of the JWS signing algorithms (alg values) supported by the OP for Request Objects
        request_object_encryption_alg_values_supported:
          type: string
          description: |
            OPTIONAL. JSON array containing a list of the JWE encryption algorithms (alg values) supported by the OP for Request Objects
        request_object_encryption_enc_values_supported:
          type: string
          description: |
            OPTIONAL. JSON array containing a list of the JWE encryption algorithms (enc values) supported by the OP for Request Objects
        token_endpoint_auth_methods_supported:
          type: array
          items:
            $ref: '#/components/schemas/TokenAuthMethodEnum'
          description: |
            OPTIONAL. JSON array containing a list of Client Authentication methods supported by this Token Endpoint
        token_endpoint_auth_signing_alg_values_supported:
          type: array
          items:
            $ref: '#/components/schemas/TokenSignAlgEnum'
          description: |
            OPTIONAL. JSON array containing a list of the JWS signing algorithms (alg values) supported by the Token Endpoint for the signature on the JWT
        display_values_supported:
          type: string
          description: |
            OPTIONAL. JSON array containing a list of the display parameter values that the OpenID Provider supports
        claim_types_supported:
          type: array
          items:
            $ref: '#/components/schemas/ClaimTypeEnum'
          description: |
            OPTIONAL. JSON array containing a list of the Claim Types that the OpenID Provider supports
        claims_supported:
          type: string
          description: |
            RECOMMENDED. JSON array containing a list of the Claim Names of the Claims that the OpenID Provider MAY be able to supply values for
        service_documentation:
          type: string
          description: |
            OPTIONAL. URL of a page containing human-readable information that developers might want or need to know when using the OpenID Provider
        claims_locales_supported:
          type: string
          description: |
            OPTIONAL. Languages and scripts supported for values in Claims being returned, represented as a JSON array of BCP47 [RFC5646] language tag values
        ui_locales_supported:
          type: array
          items:
            $ref: '#/components/schemas/LanguageCodesEnum'
          description: |
            OPTIONAL. Languages and scripts supported for the user interface, represented as a JSON array of BCP47 [RFC5646] language tag values
        claims_parameter_supported:
          type: boolean
          description: |
            OPTIONAL. Boolean value specifying whether the OP supports use of the claims parameter, with true indicating support. If omitted, the default value is false
        request_parameter_supported:
          type: boolean
          description: |
            OPTIONAL. Boolean value specifying whether the OP supports use of the request parameter, with true indicating support. If omitted, the default value is false
        request_uri_parameter_supported:
          type: boolean
          description: |
            OPTIONAL. Boolean value specifying whether the OP supports use of the request_uri parameter, with true indicating support. If omitted, the default value is true
        require_request_uri_registration:
          type: boolean
          description: |
            OPTIONAL. Boolean value specifying whether the OP requires any request_uri values used to be pre-registered using the request_uris registration parameter
        op_policy_uri:
          type: string
          description: |
            OPTIONAL. URL that the OpenID Provider provides to the person registering the Client to read about the OP's requirements on how the Relying Party can use the data provided by the OP
        op_tos_uri:
          type: boolean
          description: |
            OPTIONAL. URL that the OpenID Provider provides to the person registering the Client to read about OpenID Provider's terms of service
        backchannel_token_delivery_modes_supported:
          type: array
          items :
            $ref: '#/components/schemas/CIBADeliveryModesEnum'
          description: |
            REQUIRED. JSON array containing one or more of the following values-
        backchannel_authentication_endpoint:
          type: string
          description: |
            REQUIRED. URL of the OP's Backchannel Authentication Endpoint
        entity_statement_uri:
          type: string
          description: |
            REQUIRED. NOT AVAIALABLE

    AuthorizationCodeTokenRequest:
      type: object
      required:
        [grant_type, code]
      properties:
        grant_type:
          type: string
          description: Value MUST be set to "authorization_code" as per RFC
          enum:
            - authorization_code
        code:
          type: string
          description: |
            The authorization code obtained by the redirection
            endpoint in the `code` query string parameter.
        redirect_uri:
          type: string
          description: |
            The `redirect_uri` that was given as a parameter on the
            authorization endpoint.
        client_id:
          $ref: '#/components/schemas/MerchantIdentification'
        code_verifier:
          type: string
          description: |
            The `code_verifier` to check the PKCE challenge.
      additionalProperties: false

    IDTokenResponse:
      type: object
      required:
        [access_token, token_type, id_token]
      properties:
        access_token:
          type: string
          description: The access token value.
        token_type:
          $ref: '#/components/schemas/TokenTypeEnum'
        expires_in:
          type: number
          description: The lifetime of the access token, in seconds.
        id_token:
          type: string
          format: jwt
          description: A signed and/or encrypted Jwt containing ID token claims. The decoded payload matches the `IdTokenDef` type definition.
        refresh_token:
          type: string
          description: The refresh token to use, for an `authorization_code` token request.
        scope:
          $ref: '#/components/schemas/ScopesEnum'

    IDTokenErrorResponse:
      type: object
      required:
        [error]
      properties:
        error:
          $ref: '#/components/schemas/TokenErrorEnum'
        error_description:
          type: string
          description: A human-readable error message that gives details about the error.
        error_uri:
          type: string
          description: A URL that gives more information about the error.

    AuthorizationErrorResponse:
      type: object
      required:
        [error]
      properties:
        error:
          $ref: '#/components/schemas/AuthorizationErrorEnum'
        error_description:
          type: string
          description: A human-readable error message that gives details about the error.
        error_uri:
          type: string
          description: A URL that gives more information about the error.

    AuthFilesErrorResponseJson:
      type: object
      properties:
        response-type:
          type: string
          description: Status of a response like VOID, FAIL, RETRY etc.
        response-code:
          type: string
          description: Error code
        response-message:
          type: string
          description: A human-readable error message that gives details about the error.

    CibaResponseJwt:
      type: object
      required:
        [auth_req_id, expires_in]
      properties:
        auth_req_id:
          type: string
          description: This is a unique identifier to identify the authentication request made by the Client.
        expires_in:
          type: number
          description: A JSON number with a positive integer value indicating the expiration time of the `auth_req_id` in seconds since the authentication request was received.
        interval:
          type: number
          description: A JSON number with a positive integer value indicating the minimum amount of time in seconds that the Client MUST wait between polling requests to the token endpoint.

    AuthFilesResponseJson:
      type: object
      properties:
        response-type:
          type: string
          enum: [DATA, PASS, FAIL]
          description: Status of a response.
        pdf:
          type: string
          description: The PDF as a base64 encoded string
        png:
          type: string
          description: The PNG as a base64 encoded string.
        content-type:
          type: string
          description: Content type of the response data (image/png, application/pdf).
        content-format:
          type: string
          enum: [PDF, PADES]
          description: Actual content format delivered.
        content-source:
          type: string
          description: Source of the file in attribute png.
        content-reason:
          type: string
          description: Explanation, if PDF signature was not applied.

    MerchantIdentification:
      type: string
      description: |
        The client ID assigned upon registration.

    UserInfoJWT:
      type: string
      format: jwt
      description: |
        A signed and/or encrypted Jwt containing user claims. The decoded payload matches the `UserInfoResponseDef` type definition.

###############################################################
#
# Type defs
#

    UserInfoResponseDef:
      type: object
      properties:
        sub:
          $ref: '#/components/schemas/SubClaimDef'
        name:
          type: string
        given_name:
          type: string
          description: Given name(s) or first name(s) of the End-User
        family_name:
          type: string
          description: Surname(s) or last name(s) of the End-User
        middle_name:
          type: string
          description: Middle name(s) of the End-User
        nickname:
          type: string
        preferred_username:
          type: string
        profile:
          type: string
          description: URL of the End-User's profile page
        picture:
          type: string
          description: URL of the End-User's profile picture
        website:
          type: string
          description: URL of the End-User's Web page or blog
        email:
          type: string
          format: email
          description: End-User's preferred e-mail address
        email_verified:
          type: boolean
          description: User at the time the verification was performed
        gender:
          type: string
          description: End-User's gender
        birthdate:
          type: string
          description: |
            End-User's birthday, represented as an ISO 8601:2004 [ISO8601‑2004] YYYY-MM-DD format
        zoneinfo:
          type: string
          description: String from zoneinfo [zoneinfo] time zone database representing the End-User's time zone
        locale:
          type: string
          description: End-User's locale, represented as a BCP47 [RFC5646] language tag
        phone_number:
          type: string
          description: End-User's preferred telephone number
        phone_number_verified:
          type: boolean
          description: User at the time the verification was performed
        address:
          $ref: '#/components/schemas/AddressClaimDef'
        updated_at:
          type: integer
          description: Time the End-User's information was last updated

    IdTokenDef:
      type: object
      required: [iss, sub, aud, exp, iat]
      properties:
        iss:
          type: string
          description: Issuer Identifier for the Issuer of the response.
        sub:
          $ref: '#/components/schemas/SubClaimDef'
        aud:
          $ref: '#/components/schemas/AudClaimDef'
        exp:
          $ref: '#/components/schemas/ExpClaimDef'
        iat:
          type: integer
          format: int64
          description: Time at which the JWT was issued.
        auth_time:
          type: integer
          format: int64
          description: Time when the End-User authentication occurred.
        nonce:
          type: string
          description: |
            String value used to associate a Client session with an ID Token, and to mitigate replay attacks.
        acr:
          type: string
          description: Authentication Context Class Reference.
        amr:
          $ref: '#/components/schemas/AmrClaimDef'
        azp:
          type: string
          description: |
            Authorized party - the party to which the ID Token was issued
        name:
          type: string
        given_name:
          type: string
          description: Given name(s) or first name(s) of the End-User
        family_name:
          type: string
          description: Surname(s) or last name(s) of the End-User
        middle_name:
          type: string
          description: Middle name(s) of the End-User
        nickname:
          type: string
        preferred_username:
          type: string
        profile:
          type: string
          description: URL of the End-User's profile page
        picture:
          type: string
          description: URL of the End-User's profile picture
        website:
          type: string
          description: URL of the End-User's Web page or blog
        email:
          type: string
          format: email
          description: End-User's preferred e-mail address
        email_verified:
          type: boolean
          description: User at the time the verification was performed
        gender:
          type: string
          description: End-User's gender
        birthdate:
          type: string
          description: |
            End-User's birthday, represented as an ISO 8601:2004 [ISO8601‑2004] YYYY-MM-DD format
        zoneinfo:
          type: string
          description: String from zoneinfo [zoneinfo] time zone database representing the End-User's time zone
        locale:
          type: string
          description: End-User's locale, represented as a BCP47 [RFC5646] language tag
        phone_number:
          type: string
          description: End-User's preferred telephone number
        phone_number_verified:
          type: boolean
          description: User at the time the verification was performed
        address:
          $ref: '#/components/schemas/AddressClaimDef'
        updated_at:
          type: integer
          description: Time the End-User's information was last updated

    AddressClaimDef:
      type: object
      description: End-User's preferred postal address
      properties:
        formatted:
          type: string
          description: Full mailing address formatted for display
        street_address:
          type: string
          description: Street address portion of the address
        locality:
          type: string
          description: City or locality
        region:
          type: string
          description: State, province, or region
        postal_code:
          type: string
          description: ZIP or postal code
        country:
          type: string
          description: Country name

    AudClaimDef:
      oneOf:
            - type: string
            - type: array
              items:
                type: string
      description: Audience that this ID Token is intended for.

    ExpClaimDef:
      type: integer
      format: int64
      description: |
        Expiration time on or after which the ID Token MUST NOT be accepted by the RP when performing authentication with the OP.

    SubClaimDef:
      type: string
      description: Subject - Identifier for the End-User at the Issuer

    AmrClaimDef:
      oneOf:
        - type: string
        - type: array
          items:
            type: string
      description:  Authentication Methods References.

    RequestObjectDef:
      type: object
      properties:
        iss:
            $ref: '#/components/parameters/iss'
        aud:
            $ref: '#/components/parameters/aud'
        response_type:
            $ref: '#/components/parameters/response_type'
        client_id:
            $ref: '#/components/parameters/client_id'
        reqirect_uri:
            $ref: '#/components/parameters/redirect_uri'
        scope:
            $ref: '#/components/parameters/scope'
        state:
            $ref: '#/components/parameters/state'
        nocne:
            $ref: '#/components/parameters/nonce'
        max_age:
            $ref: '#/components/parameters/max_age'

###############################################################
#
# Enumerations
#

    ScopesEnum:
      type: string
      pattern: ^(openid|profile|email|phone|address|cert|ssn|organisation|offline_access|ageverify[0-9]{1,2})$
      description: >
        Supported scopes:
        - openid
        - profile
        - email
        - phone
        - address
        - cert
        - ssn
        - organisation
        - offline_access
        - ageverify followed by 1 or 2 digits (e.g., ageverify18, ageverify99)

    TokenTypeEnum:
      type: string
      enum:
        - BEARER

    LanguageCodesEnum:
      type: string
      enum:
        - nb_NO
        - en_GB
        - da_DK
        - sv_SE
        - fi_FI
        - sv_FI
        - nn_NO
        - et_EE
        - lv_LV
        - de_DE
        - nl_NL
        - fr_FR

    DisplayTypesEnum:
      type: string
      enum:
        - page
        - popup
        - touch
        - wap

    PromptEnum:
      type: string
      enum:
        - none
        - login
        - consent
        - select_account

    AuthorizationErrorEnum:
      type: string
      enum:
        - invalid_request
        - invalid_client
        - invalid_grant
        - unauthorized_client
        - unsupported_grant_type
        - invalid_scope

    TokenErrorEnum:
      type: string
      enum:
        - invalid_request
        - invalid_grant
        - unsupported_grant_type
        - invalid_scope

    CIBADeliveryModesEnum:
      type: string
      enum:
        - poll
        - ping
        - push

    TokenSignAlgEnum :
      type: string
      enum :
        - RS256
        - ES256

    TokenAuthMethodEnum :
      type: string
      enum :
        - client_secret_post
        - client_secret_basic
        - client_secret_jwt
        - private_key_jwt

    GrantTypeEnum :
      type : string
      enum :
        - authorization_code
        - implicit
        - urn:openid:params:grant-type:ciba

    SubjectTypeEnum :
      type : string
      enum :
        - public
        - pairwise

    ClaimTypeEnum :
      type : string
      enum :
        - normal
        - aggregated
        - distributed

    IdTokenSignAlgEnum:
      type : string
      enum :
        - RS256
        - ES256

    ResponseTypeEnum :
      type : string
      enum :
        - code
        - code id_token
        - id_token
        - id_token token

###############################################################
#
# Parameters
#
  parameters:

    client_id:
      in: query
      name: client_id
      description: |
        The OAuth2 `client_id` assigned to the client when it was
        registered.
      required: true
      schema:
        $ref: '#/components/schemas/MerchantIdentification'

    redirect_uri:
      in: query
      name: redirect_uri
      description: |
        The OAuth2 `redirect_uri`, which must be one of the
        registered URIs for the client.
      required: true
      schema:
        type: string

    TARGET:
      in: query
      name: redirect_uri
      description: |
        SAML merchant target.
      required: false
      schema:
        type: string

    scope:
      in: query
      name: scope
      description: |
        The OAuth2 `scope` on which the client requires access.
        It is required because no default scope is positioned.
      required: true
      schema:
        $ref: '#/components/schemas/ScopesEnum'

    client_notification_token:
      in: query
      name: client_notification_token
      description: |
        REQUIRED if the Client is registered to use Ping or Push modes. It is a bearer token provided by the Client that will be used by the OpenID Provider to authenticate the callback request to the Client.
      required: false
      schema:
        type: string

    login_hint_token:
      in: query
      name: login_hint_token
      description: |
        A token containing information identifying the end-user for whom authentication is being requested.
      required: false
      schema:
        type: string

    user_code:
      in: query
      name: user_code
      description: |
        A secret code, such as a password or pin, that is known only to the user but verifiable by the OP.
      required: false
      schema:
        type: string

    response_type:
      in: query
      name: response_type
      description: |
        The OAuth2 `response_type`. Only the authorization code
        workflow is supported.
      required: true
      schema:
        type: string
        enum:
          - code

    state:
      in: query
      name: state
      description: |
        The OAuth2 `state`, to be retransmitted in the query
        string when redirecting to the TPP redirection endpoint. We have
        made this parameter mandatory because its absence implies the
        presence of a CSRF vulnerability for the TPP.
      required: true
      schema:
        type: string

    nonce:
      in: query
      name: nonce
      description: |
        String value used to associate a Client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authentication Request to the ID Token. Sufficient entropy MUST be present in the `nonce` values used to prevent attackers from guessing values.
      required: false
      schema:
        type: string

    ui_locale:
      in: query
      name: ui_locale
      description: |
        The ISO 639-2 code of the language in which the
        authorization page will be displayed.
      required: false
      schema:
        $ref: '#/components/schemas/LanguageCodesEnum'

    display:
      in: query
      name: display
      description: |
        Display types for auth and consent UIs.
      required: false
      schema:
        $ref: '#/components/schemas/DisplayTypesEnum'

    prompt:
      in: query
      name: prompt
      description: |
        Space-delimited, case-sensitive list of ASCII string values that specifies whether the Authorization Server prompts the End-User for reauthentication and consent.
      required: false
      schema:
        $ref: '#/components/schemas/PromptEnum'

    max_age:
      in: query
      name: max_age
      description: |
        Maximum Authentication Age. Specifies the allowable elapsed time in seconds since the last time the End-User was actively authenticated by the OP. If the elapsed time is greater than this value, the OP MUST attempt to actively re-authenticate the End-User.
      required: false
      schema:
        type: number

    id_token_hint:
      in: query
      name: id_token_hint
      description: |
        ID Token previously issued by the Authorization Server being passed as a hint about the End-User's current or past authenticated session with the Client.
      required: false
      schema:
        type: string

    login_hint:
      in: query
      name: login_hint
      description: |
        Hint to the Authorization Server about the login identifier the End-User might use to log in (if necessary).
      required: false
      schema:
        type: string

    acr_values:
      in: query
      name: acr_values
      description: |
        Requested Authentication Context Class Reference values. Space-separated string that specifies the acr values that the Authorization Server is being requested to use for processing this Authentication Request, with the values appearing in order of preference.
      required: false
      schema:
        type: string

    code_challenge:
      in: query
      name: code_challenge
      description: |
        The OAuth2 PKCE `code_challenge`. Its use is mandatory
        for PSD2-related clients.
      required: false
      schema:
        type: string
        pattern: '[a-zA-Z0-9._~-]{43}'

    code_challenge_method:
      in: query
      name: code_challenge_method
      description: |
        The OAuth2 PKCE `code_challenge_method`. Only the S256
        method (hashing the `code_verifier` with SHA-256) is supported.
      required: false
      schema:
        type: string
        enum:
          - S256

    binding_message:
      in: query
      name: binding_message
      description: |
        A human-readable identifier or message intended to be displayed on both the consumption device and the authentication device to interlock them together for the transaction by way of a visual cue for the end-user. This can contain a text/json/base64 encoded value.

        The following attributes can be provided if the JSON format is used:
        * ntdr-doc-types:
          A comma-separated list with I, P, D or V, for selecting the required documents for ID verification.
          I - ID cards, P - Passport booklets, D - Driver's license, V - Viza/crew credentials.
        * ntdr-app-doclist (type: boolean):
          Flag indicating whether the document type selection page will be shown to the user.
        * transactiontext:
          This can have values in plain text or in markdown. It can accept maximum of 1500 base64 encoded characters.
        * transactiontext_type:
          This will accept only “text" or “markdown" value which is a type of value passed in transactiontext.
        * operation:
          Contains values "cancel" which is passed to cancel an ongoing transaction.
        * auth_req_id:
          ID of an ongoing transaction which needs to be cancelled
        * requestType:
          To identify the purpose of request. It supports Provisioning & Authentication
        * appId:
          Application ID of the user.
        * bindingMessage:
          Text to be displayed on the end user's device in text format
        * userStatus:
          Used only for provisioning. If not provided the user status will be set to "active".
      required: false
      schema:
        type: string

    requested_expiry:
      in: query
      name: requested_expiry
      description: |
        A positive integer allowing the client to request the expires_in value for the auth_req_id the server will return.
      required: false
      schema:
        type: number

    request:
      in: query
      name: request
      description: |
        This parameter enables OpenID Connect requests to be passed in a single, self-contained parameter and to be optionally signed and/or encrypted. The parameter value is a Request Object value, as specified in `RequestObjectDef`. It represents the request as a JWT whose Claims are the request parameters.
      required: false
      schema:
        type: string

    request_uri:
      in: query
      name: request_uri
      description: |
        This parameter enables OpenID Connect requests to be passed by reference, rather than by value. The request_uri value is a URL referencing a resource containing a Request Object value, which is a JWT containing the request parameters. This URL MUST use the https scheme unless the target Request Object is signed in a way that is verifiable by the OP.
      required: false
      schema:
        type: string

    iss:
      in: query
      name: iss
      description: Issuer Identifier for the Issuer of the response.
      required: false
      schema:
        type: string

    aud:
      in: query
      name: aud
      description: Audience that a token is intended for.
      required: false
      schema:
        type: string

    eident_context:
      in: query
      name: eident_context
      description: Text to be displayed on the end user's device in JSON format (Base 64 encoded).
      schema:
        type: string

    tid:
      in: query
      name: tid
      description: Auth file identifier.
      required: true
      schema:
        type: string

###############################################################
#
# Security
#

# Define security schemes
  securitySchemes:
    basicAuth:            # arbitrary name for the security scheme
      type: http
      scheme: basic

    bearerAuth:            # arbitrary name for the security scheme
      type: http
      scheme: bearer
      bearerFormat: JWT    # optional, arbitrary value for documentation purposes

servers:
  - url: https://www.ident-preprod1.nets.eu
    variables: {}
    description: Preprod (customer test)
  - url: https://www.ident.nets.eu
    variables: {}
    description: Production
