API mapping

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.
  3.  
    Advice

    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“.
  4. 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:

  5. 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

  7. Select Authentication Flow “One-Shot with body” (the body is required for IAM to be able to verify the HTTP request signatures)
  8. Define the “Denied access URL” such that it points to Airlock IAM's one-shot endpoint. Typically: “/auth/login-oneshot”.
  9. The “Session handling” setting must be set to “Sessionless”
  10. Ensure that “SSL client certificate” is set to “Inherit from Virtual Host”
  11. Add the following "Apache Expert Setting" to the mapping: RequestHeader set AL_ENV_REQUEST_LINE expr=%{THE_REQUEST}

  12. This is required for IAM to be able to verify the HTTP request signatures.

  13. Enable “Send environment cookies” (this is also required for IAM to be able to verify the HTTP request signatures.)
  14. 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”
  16. To allow the “Signature” and the “TTP-Signature-Certificate” headers, you need to add the following deny rule exceptions:

  17. for Airlock Gateway 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$