The SSA is a JSON Web Token (JWT) containing client metadata about an instance of Third Party Provider (TPP) client software. The JWT is created and signed by the TPP using their eIDAS certificate private key.
SSA Payload
The payload of an Nordea Open Banking SSA MUST be a compliant software statement according to [RFC7591]. The SSA MUST also be a compliant JWT according to [RFC7519].
The following metadata profiles the metadata in [RFC7591] and [RFC7519]:
Metadata
|
Description
|
Source Specification
|
---|---|---|
iss |
SSA Issuer (TPP organization Legal Name ) | [RFC7519] |
iat |
Time SSA issued This claim can be used to determine the age of the JWT.Its value MUST be a number containing a NumericDate value | [RFC7519] |
jti |
The "jti" (JWT ID) claim provides a unique identifier for the JWT. TPP Should use a UUID for it | [RFC7519] |
The following software metadata is additionally defined for this profile:
Metadata
|
Description
|
---|---|
software_client_description (optional) |
Human-readable detailed description of the client |
software_client_name |
Human-readable Software Name |
software_client_uri (optional) |
The website or resource root uri |
software_version(optional) |
The version number of the software should a TPP choose to register and / or maintain it |
software_redirect_uris |
Registered client callback endpoints as registered with Open Banking |
software_roles |
A multi value list of PSD2 roles that this software is authorized to perform. |
The following Organisational metadata is defined for this profile:
Metadata
|
Description
|
---|---|
organisation_competent_authority_claims |
Authorizations granted to the organisation by an NCA |
org_name |
Legal Entity Identifier or other known organisation name |
org_contacts |
JSON array of objects containing a triplet of name, email, and phone number |
SSA header
The SSA header MUST comply with [RFC7519].
Metadata
|
Description
|
---|---|
typ |
MUST be set to JWT |
alg |
MUST be set to RS256 |
kid |
The kid will be kept the same as the "x5t" parameter. (X.509 Certificate SHA-1 Thumbprint) of the signing certificate. |
Example SSA
{
"typ": "JWT", "alg": "RS256", "kid": "BF1DBE546F12ABC8E83B37A0FC40C78B702A6613" } { "iss": "TPP XYZ Ltd", "iat": 1492756331, "jti": "d4a1d1ae-15b2-11ea-8d71-362b9e155667", "software_client_name": "TPP Awesome APP", "software_client_description": "Awesome app for personal finance", "software_version": "2.2", "software_redirect_uris": [ "https://tpp.com/cb", "https://tpp.uk/cb" ], "software_roles": [ "PISP", "AISP" ], "organisation_competent_authority_claims": [ { "authority_id": "FMA", "registration_id": "111111", "status": "Active", "authorisations": [ { "member_state": "GBR", "roles": [ "PISP", "AISP" ] }, { "member_state": "ROI", "roles": [ "PISP" ] } ] } ], "org_id": "Amazing TPPID", "org_name": "OpenBanking TPP Registered Name", "org_contacts": [ { "name": "contact name", "email": "contact@contact.com", "phone": "+447890130558", "type": "business" }, { "name": "contact name", "email": "contact@contact.com", "phone": "+447890130558", "type": "technical" } ] } { Signature }
The Base64 encoded JWT created with above header and payload:
eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IkJGMURCRTU0NkYxMkFCQzhFODNCMzdBMEZDNDBDNzhCNzAyQTY2MTMifQ.eyJpc3MiOiJUUFAgWFlaIEx0ZCIsImlhdCI6MTQ5Mjc1NjMzMSwianRpIjoiZDRhMWQxYWUtMTViMi0xMWVhLThkNzEtMzYyYjllMTU1NjY3Iiwic29mdHdhcmVfY2xpZW50X25hbWUiOiJUUFAgQXdlc29tZSBBUFAiLCJzb2Z0d2FyZV9jbGllbnRfZGVzY3JpcHRpb24iOiJBd2Vzb21lIGFwcCBmb3IgcGVyc29uYWwgZmluYW5jZSIsInNvZnR3YXJlX3ZlcnNpb24iOiIyLjIiLCJzb2Z0d2FyZV9yZWRpcmVjdF91cmlzIjpbImh0dHBzOi8vdHBwLmNvbS9jYiIsImh0dHBzOi8vdHBwLnVrL2NiIl0sInNvZnR3YXJlX3JvbGVzIjpbIlBJU1AiLCJBSVNQIl0sIm9yZ2FuaXNhdGlvbl9jb21wZXRlbnRfYXV0aG9yaXR5X2NsYWltcyI6W3siYXV0aG9yaXR5X2lkIjoiRk1BIiwicmVnaXN0cmF0aW9uX2lkIjoiMTExMTExIiwic3RhdHVzIjoiQWN0aXZlIiwiYXV0aG9yaXNhdGlvbnMiOlt7Im1lbWJlcl9zdGF0ZSI6IkdCUiIsInJvbGVzIjpbIlBJU1AiLCJBSVNQIl19LHsibWVtYmVyX3N0YXRlIjoiUk9JIiwicm9sZXMiOlsiUElTUCJdfV19XSwib3JnX2lkIjoiQW1hem9uIFRQUElEIiwib3JnX25hbWUiOiJPcGVuQmFua2luZyBUUFAgUmVnaXN0ZXJlZCBOYW1lIiwib3JnX2NvbnRhY3RzIjpbeyJuYW1lIjoiY29udGFjdCBuYW1lIiwiZW1haWwiOiJjb250YWN0QGNvbnRhY3QuY29tIiwicGhvbmUiOiIrNDQ3ODkwMTMwNTU4IiwidHlwZSI6ImJ1c2luZXNzIn0seyJuYW1lIjoiY29udGFjdCBuYW1lIiwiZW1haWwiOiJjb250YWN0QGNvbnRhY3QuY29tIiwicGhvbmUiOiIrNDQ3ODkwMTMwNTU4IiwidHlwZSI6InRlY2huaWNhbCJ9XX0.gwrWkv8FwToAhB0XcobplySx5mNtuv7ZSDr5PvUbUtRx22171p8veejw2ZtE4hNsIa5JGTlAJ4fi4oGTQCzWhx6uPYsYhAEvro2FbCH5jYErMB6u67kMDxvmeXpra82IKk_iN8HrrVr7ogkxiZipNvj_dAhHbp83kbq_f2dcL4v5HwCXvOYTz94zsb1syyWWElDCpLUeQTbssFw8yAKqs3m9dPo9A1MufeZzW7KTi0sXagYL0trbnXcXqYJUF1Zi7SQYryI6pAyHi7TJ0jfl7xodUGpuQEudmTo0znITBECIBlw9vc4j_ZgXhKAW4A6u8F213ZnWBSerXCUaDf3ROA
Note: Software statement token needs to contain 3 parts separated with dots:
{header}.{payload}.{signature}
and the expected JWT signing algorithm is RS256.
Error texts and responses
The problems regarding the eIDAS certificate validations can be caused by several reasons. Below is a list of reasons for situations when the eIDAS certificate cannot be correctly validated.
- The certificate has been revoked = Certificate not longer valid.
- The certificate is not trusted = Certificate root path is not valid or incorrect.
- The certificate is malformed = Certificate string pasted into eIDAS textbox in the registration form is not valid or not readable.
- The certificate has expired = Certificate has expired and needs to be renewed.
- Certificate validation service is not responding = Nordea is unable to process the request. Please resend the request.
Role validation in eIDAS certificate
QTSP providers have a connection to National Competent Authorities to verify the PSD2 license, license number and PSD2 roles before issuing the eIDAS certificate to the TPP acquiring it. The key-thing in this certificate is the unique ID (authorization number of the PSP) which originates from the TPP’s ‘Home National Competent Authority’ (NCA), the local authority that grants the PSD2 licenses to TPPs. By this number it is possible to find the TPP in question from official public registers. Within such registers, it is possible to see what PSD2 ‘roles’ the TPP is licensed to play (AISP, PISP, CBPII). Note that role information can be found in the certificate "Qualified Certificate statement".
If these options did not help, there might be other reasons why the eIDAS validation fails. Reach out to your QTSP provider for support.
FAQ
Question
While submitting the onboarding form:
Compliance (PSD2) API Products Onboarding
I get "Registration failed as the Software Statement token is invalid. Please, edit the Software Statement token and try again. For more information, see OAuth 2.0 Software Statement." error:
Answer
Make sure that:
- your SSA is signed with your eIDAS Certificate private key
- your SSA doesn't contain any redundant characters at the beginning and the end, e.g.: "\", \""
Note: create a new SSA without those characters since cleaning the result (characters) might brake SSA
- "roles" under "authorisations" are according to specification/our sample code above
- "software_version" is a string, e.g.: "1.0"