Salt Edge PSD2 ASPSP Docs represents a blend of Connector and Salt Edge Endpoints, which enable an ASPSP to provide Open Banking UK compatible API to potential Third Party Providers.

Connector Endpoints are responsible for handling requests sent by Salt Edge PSD2 Compliance SaaS. Through Connector Endpoints ASPSP implements handling of PSU authentication and fetching process of account information data.

Due to the asynchronous nature of PSU authentication API, Connector is required to communicate with Salt Edge PSD2 Compliance SaaS using Salt Edge Callback Endpoints. Salt Edge Endpoints are responsible for receiving callbacks related to the redirect page for PSU authentication as well as the current state of this process.

Changelog

Definitions

Minimal requirements

TLS

Salt Edge PSD2 Compliance Solution supports the following versions: TLSv1.2 and TLSv1.3.

Why does this matter?

Older TLS versions are vulnerable to security breaches with the wrong cipher suites. Be sure to upgrade your TLS version up to TLSv1.3.

What is TLS?

TLS stands for “Transport Layer Security.” It provides privacy and data integrity between two communicating applications. It is used to authenticate one or both applications, and protect the confidentiality and integrity of information that passes between them.

Registration and API keys

In order to start setting up the API keys, you will have to register into the ASPSP dashboard by following these steps:

1. Go to the ASPSP dashboard registration page and provide your full name and email address.
2. Confirm your email address, you should have received a confirmation instruction email.
3. Set up a password, read and agree to the Terms of Service and Privacy Policy.
4. Login into your account and link your account to Salt Edge Authenticator to keep it safe. The Authenticator can be download via:
1. Play Market
2. App Store
5. Provide more details about your business, such as: Bank name, legal name, email address, phone number and business address.
6. Account has been created, however it is still in the pending stage.

In order to move from Pending status to Test status, please follow the steps below:

1. Either click on Configure connection settings , or go to the Environments tab and click on your newly created environment. An environment is a set of configurations for a specific connector implementation. The configuration consists of:
• Connector name - the name displayed to the TPP before creating a connection.
• Code - unique identifier of connector in Salt Edge Compliance Service. Used by TPP to establish connection.
• App id - generated credentials that are required for sending requests from Connector Service to Salt Edge Compliance Service.
• App secret - generated credentials that are required for sending requests from Connector Service to Salt Edge Compliance Service. Can be generated indefinitely.
• Connector url - URL of connector service which implements Connector API.
• Public key - used by Salt Edge Compliance Service to verify JWT signature while validating requests from Connector Service.
2. Fill in the Connector url and Public key fields in order to switch your account to Test mode.
3. Please note: we strongly recommend enabling the Troubleshooting option during the development stage in order to access the Troubleshooting tab.

In order to create a new environment, it is required to fill only Name, Connector url and Public key.

Private and public keys

Since all the communication between Salt Edge Compliance and Connector happens via JWT payloads, a pair of private and public keys has to be generated. To generate the keys, please run the following commands in terminal:

Save the “private.pem” file, and never share it with anyone. It should be present only on machines that will make requests to Salt Edge Compliance. Additionally, “public.pem” has to be uploaded to Salt Edge Compliance to the Public key label of the environment settings.

Once you’ve set up the environment and were switched to Test, please reach out to our representative at compliance-hub@saltedge.com in order to receive access to a Demo TPP interface for further development.

Request verification using JWT

JSON Web Token (JWT) is an open standard (RFC 7519) that defines a way to securely transmit information. Salt Edge PSD2 Compliance API requires JWTs to authorize each API request. Implementing a standard that allows Providers and TPPs to securely transmit information provides greater protection of sensitive data and the entire Salt Edge PSD2 Compliance Solution.

Salt Edge PSD2 Compliance uses JWTs as a vehicle to send and receive signed requests to and from Connector. Connector is supposed to receive JWT signed requests from Salt Edge PSD2 Compliance on any of Connector Endpoints described in documentation and respond with a JSON. Connector is required to send a JWT signed request (RS256, RS384, RS512 alghorithm) on any of Salt Edge Endpoints described in documentation and receive an empty JSON with a HTTP status code as a response.

Salt Edge PSD2 Compliance will always send requests with a JWT signed by its private key. This allows Connector the ability to validate that the request form Salt Edge PSD2 Compliance has not been tampered with.

Example of decoded JWT header

{ "typ": "JWT", "alg": "RS256" }

Example of decoded JWT payload

{ "data": { "provider_code": "demobank", "scopes": [ "accounts", "transactions", "kyc", "payments", "funds_availability" ], "consent_period_days": 90, "credentials": { "required_key": "value" }, "redirect_url": "https://user.will.be/redirected/here" }, "exp": 1560162919 }

Salt Edge PSD2 Compliance public key

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw+4UebzWIN9SNnFm9WBv
rvH7CiVyuobh5i2V1bKH7floZSh71xbBnvZ2FsL2kleSJrOj03gh5zpdSxmR/Nj9
MyskswkFSO09bZo2C5ZWMsnFpH0oHRdBWl5hQWJFeuV9TVJkuSuO9XyrsdQMakVK
eCRisxseCOo4wux1/tRl7smAlJXoOYF1QEkhoVB6K91JjmBi1DmI0J7W0RET9gsS
EHzwVi12WrjCiEKplzN0u7b2i1ydiga2GKXZLxfBu0MfQVD/RI2eCEHmh3/sJPeV
u4K5bbwD3hamIM1v4DaGBs7DtR6tk9Xtms79s/hEQWiFd0fjdW2rrp4vEnljobz5
GQIDAQAB
-----END PUBLIC KEY-----

JWT Anatomy

A JWT is comprised of 3 sections of url base64 encoded strings of data separated by a period. The first 2 sections are JSON objects while the last section is a digital signature that has been url base64 encoded. The sections are as such:

• header - A small JSON object that specifies what type of algorithm was used to generate the digital signature. This section is denoted in the below example in red.
• payload - A JSON object that contains the data being sent from one party to another. This section is denoted in the below example in green.
• signature - A url base64 encoded hash value of the header and payload. This is used to verify the contents of the JWT have not been tampered with. Signatures are created with RS256 alghorithm, using a public/private key pair. The identity provider uses his private key to generate the signature, and the consumer of the JWT uses the requester public key to validate the signature. Since the public key, as opposed to the private key, doesn't need to be kept secured, most identity providers make it easily available for consumers to obtain and use (usually through a metadata URL).

Example of JWT:

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9. eyJkYXRhIjp7InByb3ZpZGVyX2NvZGUiOiJkZW1vYmFuayIsInNjb3BlcyI6WyJhY2NvdW50cyIsInRyYW5zYWN0aW9ucyIsImt5YyIsInBheW1lbnRzIiwiZnVuZHNfYXZhaWxhYmlsaXR5Il0sImNvbnNlbnRfcGVyaW9kX2RheXMiOjkwLCJjcmVkZW50aWFscyI6eyJyZXF1aXJlZF9rZXkiOiJ2YWx1ZSJ9LCJyZWRpcmVjdF91cmwiOiJodHRwczovL3VzZXIud2lsbC5iZS9yZWRpcmVjdGVkL2hlcmUifSwiZXhwIjoxNTYwMTYyOTE5fQ. O6edlfyG_tuh_ZHJC05gua1g9ZjIBDLev7wCJdDwm2ovCFWRR3vTOHhDf87dCNT3to-xW84iiYpeGWTDEzBQNug7TcJAIQF69bXr-Jh2hyT2Szlq44aWut-Qxr_nlQ7nfXaOfC30FfiG7TFq-njVY4-Z4Ham8hpnXkMy5b6PlMGaSmN6L9-QccdxpkS0ocXG3s0wHYi3P6WSUuGZIfXKVBDtud7qMkKzTEEl9xqhWHQiXeHxiM9SugzvU5CYfQd1H0KFw-qEUGIhXQc1OdaZNOAljawMCe8xwyqe5mYGnfCX6Cf1mR9zrp9MAxBB1Tfz61Km0aAYXKaa8HkQcqLDgA

JWT libraries

In order to use JWT tokens, you'll need to have a token generator. You can generate JWT tokens by utilizing one of the many libraries available on the JWT website.

How to use JWT

All requests that are either forwarded by or originated on Salt Edge PSD2 Compliance will be signed using Salt Edge PSD2 Compliance private key (RS256 alghorithm) in the form of a JWT containing exp and data claims that can be verified using Salt Edge PSD2 Compliance public key.

• exp is an UTC timestamp in seconds, preferred value is current time plus 120 seconds.
• data may include the original_request parameters that were sent to Salt Edge PSD2 Compliance by TPP applications. This is done to ensure that no Man-in-the-Middle attacks have occurred during request life cycle and that no data was tampered on its way from TPP to Salt Edge PSD2 Compliance to Connector. In seldom cases along parameters encoded into JWT there will be regular HTTP parameters.

During any request or flow originating either on TPP or Salt Edge PSD2 Compliance side, a number of errors may appear. In order to standardize errors while still giving some degree of freedom in explaining an error callback, parameters should include both error_class and error_message. Error message serves the purpose of communicating the issue to the Customer, whereas error class should be used by TPPs in order to be able to handle various scenarios.

Contents of the error_message are entirely up to the Provider, they may even be localized. However, values sent within error_class parameter should be from the standardized list. This list may and will be extended over time.