API Mapping
12.6.2.2.1.1.2. Mapping for the bank API calls

For each type of bank API call (e.g. "/accounts", "/payments", "/consents"/) a mapping with the following PSD2-specific settings must be configured and connected to the just created virtual host.

  • 1.
    Define a mapping matching the corresponding API calls (e.g. "/accounts")
  • 2.
    Configure all security rules (Allow Rules, Deny Rules, API Security, etc.), "Request Actions" and "Response Actions" required by the bank's APIs.
  • Consider the following settings - they have proven to work in practice. It does not claim to be complete.

    • Define (and use) an allow rule allowing HTTP methods "GET", "POST", "PUT", and "DELETE". The default "Allow all" only allows "GET" and "POST".
    • In addition to the headers in the "(default) Request header whitelist"  "|Digest|Signature|ASPSP-SCA-Approach|Consent-ID".
  • 3.
    Restrict access to the mapping based on the TPP roles (exactly as in the TPP's client certificate). The following table lists the typical access restriction settings:
  • Mapping Name
    Entry Path
    Typically restricted to roles
    xs2a-accounts
    /v1/accounts
    PSP_AI
    xs2a-card-accounts
    /v1/card-accounts
    PSP_AI
    xs2a-consents
    /v1/consents
    PSP_AI
    xs2a-payments
    /v1/payments
    PSP_PI
    xs2a-bulk-payments
    /v1/bulk-payments
    PSP_PI
    xs2a-periodic-payments
    /v1/periodic-payments
    PSP_PI
    xs2a-funds-confirmations
    /v1/funds-confirmations
    PSP_IC
    xs2a-signing-baskets
    /v1/signing-baskets
    PSP_AI, PSP_IC
  • 4.
    Select Authentication Flow "One-Shot with body" (the body is required for IAM to be able to verify the HTTP request signatures)
  • 5.
    Define the "Denied access URL" such that it points to Airlock IAM's one-shot endpoint. Typically: "/auth/login-oneshot".
  • 6.
    The "Session handling" setting must be set to "Sessionless"
  • 7.
    Ensure that "SSL client certificate" is set to "Inherit from Virtual Host"
  • 8.
    Add the following "Apache Expert Setting" to the mapping: RequestHeader set AL_ENV_REQUEST_LINE expr=%{THE_REQUEST}
  • This is required for IAM to be able to verify the HTTP request signatures.

  • 9.
    Enable "Send environment cookies" (this is also required for IAM to be able to verify the HTTP request signatures.)
  • 10.
    Create a HTTP Header whitelist to allow non-standard HTTP headers required by NextGenPSD2 (for HTTP signature verification):
    • 1.
      Copy the "(default) Request header whitelist" (click on "customize this action")
    • 2.
      Add the following headers to the customized action (initially called "Copy of (default) ..."):|Date|X-Request-Id|PSU-.*|TPP-.*
    • 3.
      Enable the new whitelist
    • 4.
      Disable the "(default) Request header whitelist"
  • 11.
    To allow the "Signature" and the "TTP-Signature-Certificate" headers, you need to add the following deny rule exceptions:
  • for Airlock Gateway (WAF) Versions
    with deny rule "Security Level"
    add exception to "Deny Rule"
    using "Header Name Pattern"
    all
    Strict (recommended)
    (default HTML_003b) HTML attribute in quoted context in HTTP header value
    ^Signature$
    Standard
    (default HTML_004b) Known HTML attribute in quoted context in HTTP header value
    >= 7.1
    Strict
    (default SAN_060b) Header value longer than 300 characters
    ^Signature$
    ^TPP-Signature-Certificate$