- AisConsentSpec
- App
- ASPSP
- AspspBankingApi
- BankDescriptor
- BankingProtocolSelector
- BankingProtocol
- BankProfile
- ConsentAuthorisationApi
- ConsentAuthorisationUI
- ConsentData
- Dictionary
- FinTech
- FinTechApi
- FinTechContext
- FinTechDC
- FinTechUI
- Information
- OnlineBanking2ConsentAuthRedirectInfoPage
- OnlineBankingApi
- OnlineBankingConsentSessionCookie
- OnlineBankingLoginSessionCookie
- OnlineBankingUI
- PSU
- PsuConsentSession
- PsuIdentifier
- PsuUserAgent
- PsuUserDevice
- RedirectSession
- SessionCookie
- Sharing
- TppBankingApi
- TppBankSearchApi
- TppConsentSession
- TppContext
- TPP
- UserAgentContext
- WebBrowser
In the context of Open Banking, a consent encompasses all information necessary to provide a third party with the authorization to access banking services on behalf of the PSU. These are:
- PSU banking identifier information known as (psuId, psuCorporateId)
- PSU account details information (like account numbers, iban, ...)
- PSU payment orders (including beneficiary names, amounts, ...)
- PSU authentication methods
All these information are stored in different devices during the consent authorization session. Form of storages are among others:
- Held in the browser page for display to the PSU
- Stored in the Cookie for reuse by the corresponding backend
- Stored in backend databases for transfer to other server components
- Stored in backend databases for reuse by server components.
For the purpose of protecting these data, framework is designed to always have consent data encrypted while at rest or on transit. General logic is that encrypted payload and encryption key do not reside in the same environment, unless need for decryption and processing of those data.
Following object hold consent data
A PSU user device runs applications used by the PSU to access banking functionality. Those applications are generally called PsuUgerAgents.
Application running on a PSU device and used by the PSU to access banking functionality. We are describing the two main types of PsuUserAgents.
A Web browser is considered compliant in the context of this framework when it can protect specific information used between the PusUserDevice and the the corresponding server application to track the user session. For session tracking, this framework uses Cookies RFC6265.
We assume all three applications FinTechApi, ConsentAuthorisationApi, OnlineBankingApi are hosted on different domains. This is, we are not expecting Cookies set by one application to be visible to another application (this might still happen on some local development environment, where everything runs on localhost). We also do not advice adding persistent information to RedirectUrl, as these are log files everywhere on infrastructure components in data centers. RedirectUrl shall instead carry OneTime and ShortLived authorization code we call code, that can be used to retrieved shared payload through an authenticated back channel connection. This is the practice borrowed from oAuth2 RFC6749. Following table shows defined redirects and corresponding back chanel endpoints.
| Origin Application | Redirecting Application | Response Code; Location ; AuthCodeParam; Expiration | Redirect Target Application | Destination Application | Data EndPoint at Origin Application |
|---|---|---|---|---|---|
| TppBankingApi | FinTechApi | 302 ; /auth ; code ; 5s | ConsentAuthorisationApi | ConsentAuthorisationApi | /loadTppConsentSession |
| ConsentAuthorisationApi | ConsentAuthorisationApi | Proprietary banking API. Assume RFC6749. /auth | OnlineBankingApi | OnlineBankingApi | none |
| OnlineBankingApi | OnlineBankingApi | 302 ; [/ok|/nok] ; code ; 5s | ConsentAuthorisationApi | ConsentAuthorisationApi | /token |
| ConsentAuthorisationApi | ConsentAuthorisationApi | 302 ; [/ok|/nok] ; code ; 5s | FinTechApi | TppBankingApi | /loadTppConsentSession |
We assume all three applications FinTechApi, ConsentAuthorisationApi, OnlineBankingApi maintain their own session information. This framework uses following terms to name the session information held by an application on the UserAgent of the PSU.
| Application | SessionCookie |
|---|---|
| FinTechApi | Psu2FintechLoginSession |
| ConsentAuthorisationApi | ConsentAuthSessionCookie |
| OnlineBankingApi | OnlineBankingConsentSessionCookie |
Session information can also be kept across redirect life cycles. Upon redirecting the UserAgent to another application, the redirecting application can set Cookies that will be resent to the domain with future requests. This way, there will be no need to maintain user session information in temporary databases on the server, thus keeping server tiny.
The UserAgent might be a native application running on a user mobile device or a desktop computer. In this case, redirection might still take place, but with consideration of the physical transition between source and target UI-Application. Following specifications deal with security threads associated with the redirection between UI-Application on a user device: RFC8252:OAuth 2.0 for Native Apps,RFC7636:Proof Key for Code Exchange by OAuth Public Clients For the purpose of kepping the overall architecture of this framework simple, we will require native applications to provide the same behavior as the WebBrowser described above.
Independent on the type of PsuUgerAgent, OpenBanking interfaces will require transmission of a class of information associated with the PsuUserAgent so they can perform verification of the authenticity of the original PSU request and customize the response produced for intermediary layers. We group these data under the name "UserAgentContext". Following header names account among the UserAgentContext: IP-Address, IP-Port, Accept, Accept-Charset, Accept-Encoding, Accept-Language, Device-ID, User-Agent, Geo-Location, Http-Method.
UI Application running on the PsuUserAgent and used by the PSU to access the FinTechApi
UI used by PSU to authoraise consent in embedded case.
This UI manages the interaction between the PSU and the ASPSP in redirect cases.
Organisation that uses Online Banking Services provided by TPP to service PSU with additional services. FinTech may or may not have own TPP License.
Data center environment of the FinTech. Host the FinTechApi.
Financial web service provided by the FinTech.
Data center environment of the TPP
Tpp backend providing access to ASPSP banking functionality. This interface is not directly accessed by the PSU but by the FinTechApi. FinTechApi will use a FinTechContext to authenticate with the TppBankingApi.
Repository of banks maintained in the TPP's banking gateway. The banking search API will later presen an interface to configure profiles attached to listed banks.
Descriptive information assocaited with a bank like:
- The name of the Bank
- The address of the bank
- The bank identification code
BankingApi profile information associated with a bank like:
- The BankingProtocol used to connect with the bank
- List of Banking services provided by the BankingApi of the bank
- SCA approcahes associated with the BankingApi
- ScaUIMetadaData: Screens and field used to collect user authentication data.
- Actions to be performed by the PSU prior to using the BankingProtocol
Specification associated with an AisConsent. This is highly dependent on the BankProfile. Following information might be carried by an AisConsentSpec object:
- recurringIndicator
- validUntil
- frequencyPerDay
- combinedService
- accountAccessTemplate
- availableAccounts[availableAccountsWithBalances, allAccounts]
- allPsd2[allAccounts]
Information used to identify the FinTech application at the TppBankingApi. For example a FinTech SSL client certificate or an APIKey or an oAuth2 Password Grant Credential.
A Payment Services User is a natural or legal person making use of a payment service as a payee, payer or both.
Information associated with the consent as exchanged between the FinTechApi and the TppBankingApi. Generally contains:
- Data needed to customize psu access at the ConsentAuthorisationApi (showInfoPanel, fintechStateHash)
- Data needed to manage redirection of PSU from the TppConsentSession to the FintechUI like (FinTech-Redirect-URI, FinTech-Nok-Redirect-URI, FinTech-Explicit-Authorisation-Preferred, FinTech-Content-Negotiation)
Object also contains information associated with the PSU requesting service if available.
- The identifier of the PSU in the realm of the Tpp PsuIdentifier
- Existing Consent References if any.
This is the identifier of the PSU in the FinTech2Tpp relationship. This identifier can be saved once a consent has been successfully established to allow for reuse of existing consent in future sessions.
Interface used by the PSU to authorize a consent.
We assume all three applications FinTeApi, ConsentAuthorisationApi, OnlineBakingApi maintain their own session information with corresponding UIs. We assume those APIs use cookies to maintain session with the corresponding user agents. In the context of this framework, those cookies are called SessionCookies. We also expect a following behavior from APIs and UserAgents:
- A response that sets a SessionCookie also carries a corresponding X-XSRF-TOKEN in the response header.
- A request that authenticates with a session cookie must also add the X-XSRF-TOKEN to the request header.
Holds consent information for the duration of a redirect. Redirect patterns are described below.
Component managing access to a banking interface initiative. WE will have to deal with many protocols like NextGenPSD2, HBCI, OpenBanking UK, PolishAPI.
Help select a banking protocol.
Data center environment of the ASPSP
Account Servicing Payment Service Providers provide and maintain a payment account for a payer as defined by the PSRs and, in the context of the Open Banking Ecosystem are entities that publish Read/Write APIs to permit, with customer consent, payments initiated by third party providers and/or make their customers’ account transaction data available to third party providers via their API end points.
Api banking provided by ASPSP. This interface is not directly accessed by the PSU but by the TppBankingApi. TppBankingApi will use a TppContext to authenticate with the TppBankingApi.
Information used to identify the Tpp application in the ASPSP environment. Like a TPP QWAC certificate.
Storage for consent data in the realm of the BankingProtocol. The banking protocol is both accessible to the TppBankingApi and the ConsentAuthorizationApi.
The cryptographic key needed to recover the TppConsentSession is always delivered by the calling layer. These are:
- FinTechUI -> FinTechApi -> TppBankingApi -> BankingProtocol : in this case the key needed to recover the TppConsentSession in contained in the PsuConsentSession. Generally that key will transitively originate from an interaction with the user agent.
- CosentAuthorizationUI -> CosentAuthorizationApi -> BankingProtocol : in this case the key needed to recover the TppConsentSession originate from the ConsentAuthSessionCookie.
Beside consent data, additional data might be held in the TppConsentSession:
- FinTechContext: Data needed to authorize the FinTechApi (FinTechSSLCertificate, ApiKey, SignedJWT)
- Additional information needed for interaction between TPP and ASPSP but without any concern to the PSU.
Generally the online banking application on an ASPSP. In redirect cases, the ASPSP OnlineBankingApi establishes a direct session with the PSU to allow the PSU to identify himself, review and authorize the consent.
This is a Cookie used to maintain the session between the OnlineBankingUI and the OnlineBankingApi. As a recommendation, the validity of this Cookie shall be limited to the life span of the consent session. As the OnlineBankingApi redirects the PSU back to the ConsentAuthorisationApi up on completion of the consent session. Redirection happens independently on whether the consent was authorized or not.
It is recommended to inform the PSU prior to redirecting the PSU back to the TPP. This UI-Panel will be called OnlineBanking2ConsentAuthRedirectInfoPage. If the ASPSP is using a trusted environment (Native App) and wants to keep the relationship to the PSU alive, it is necessary to store this relationship in a separated OnlineBankingLoginSessionCookie.
This Cookie will be used by the ASPSP to keep a login session of the PSU over the life span of consent session. This will prevent the PSU from performing the login step for upcoming consent sessions.
A TPP is a Third Party Provider - a legal entity that holds a TPP License provided by NCA (PISP, AISP etc). and operates with corresponding QWAC Certificate. TPP may serve FinTech companies with XS2A Services.