From 2f7886d1940d30c271e216dc47a2e14a60d172cc Mon Sep 17 00:00:00 2001 From: "Pouatcha,Francis (ext)" Date: Thu, 12 Dec 2019 16:06:51 -0500 Subject: [PATCH 1/4] SYnchronized api definition and sequence diagram for ConsentAuthoriazationApi --- .../architecture/5-redirectPsuToConsentAPI.md | 10 ++--- .../architecture/5a-psuAuthEmbeddedConsent.md | 20 ++++----- .../architecture/5b-psuAuthRedirectConsent.md | 24 ++++++----- docs/architecture/README.md | 2 +- .../useCases/4-initiateAisConsent.puml | 4 +- .../useCases/5-redirectPsuToConsentAPI.puml | 2 +- .../useCases/5a-psuAuthEmbeddedConsent.puml | 4 +- .../useCases/5b-psuAuthRedirectConsent.puml | 8 ++-- docs/architecture/dictionary.md | 42 ++++++++++++++++--- 9 files changed, 75 insertions(+), 41 deletions(-) diff --git a/docs/architecture/5-redirectPsuToConsentAPI.md b/docs/architecture/5-redirectPsuToConsentAPI.md index 6b645f8043..6dbeb22a9d 100644 --- a/docs/architecture/5-redirectPsuToConsentAPI.md +++ b/docs/architecture/5-redirectPsuToConsentAPI.md @@ -1,15 +1,15 @@ # Redirect PSU to consent API -## 1. [ConsentAuthorisationApi](dictionary.md#ConsentAuthorisationApi) -The redirect start with a get request to the entryPoint of the ConsentAuthorisationApi, for authorizing a consent initiated on the TppBankingApi side. +## Redirect-010 [ConsentAuthorisationApi](dictionary.md#ConsentAuthorisationApi) +The redirect starts with a get request to ConsentAuthorisationApi.auth. The entryPoint of the ConsentAuthorisationApi, for processing a consent initiated on the TppBankingApi side. ## Diagram ![Session diagram](http://www.plantuml.com/plantuml/proxy?src=https://raw.githubusercontent.com/adorsys/open-banking-gateway/gh-pages/docs/architecture/diagrams/useCases/5-redirectPsuToConsentAPI.puml&fmt=svg&vvv=1&sanitize=true) -## Request processing ConsentAPI +## Request processing ConsentAuthorisationApi -### 2.1 Retrieve Corresponding BankingProtocol -ConsentAuthorisationApi will use the given redirectCode to load the matching BankingProtocol. +### Redirect-021 Retrieve Corresponding BankingProtocol +ConsentAuthorisationApi will use the given redirectCode to load the matching BankingProtocol. This means that the protocol selection information must be encoded in the redirectCode. See [Issue #54](https://github.com/adorsys/open-banking-gateway/issues/54). ### 2.2 .. 2.6 Retrieve associated TppConsentSession ConsentAuthorisationApi will let BankingProtocol use the redirectCode to retrieve the TppConsentSession diff --git a/docs/architecture/5a-psuAuthEmbeddedConsent.md b/docs/architecture/5a-psuAuthEmbeddedConsent.md index d0412408ef..724d86d759 100644 --- a/docs/architecture/5a-psuAuthEmbeddedConsent.md +++ b/docs/architecture/5a-psuAuthEmbeddedConsent.md @@ -10,23 +10,23 @@ Implements the process of collecting consent authorization credentials in an int ## Use Cases -### 1.0 Create ConsentAuthSessionCookie +### AuthEmbedded-010 : Create ConsentAuthSessionCookie If the TppConsentSession has an authChallenge, the interaction starts with the initialization of a [ConsentAuthSessionCookie](dictionary.md#ConsentAuthSessionCookie). The ConsentAuthSessionCookie is encrypted with a key stored in the [consentSessionState](dictionary.md#consentSessionState). -### 2.0 Redirect to EmbeddedAuthInitScreen +### AuthEmbedded-020 : Redirect to EmbeddedAuthInitScreen After preparation of the ConsentAuthSessionCookie, the UserAgent is redirected to the EmbeddedAuthInitScreen of the ConsentAuthorisationUI. -### 30 .. 40 Load AuthChallenge -The authChallenge returns the ConsentAuthorizeResponse that contains all information necessary to display the challenge to the PSU. An ScaUIMetadaData object contain UI customization parameter. +### AuthEmbedded-030&-040 : Load AuthChallenges +The generic endpoint at ConsentAuthorisationApi.embeddedAuth allows the ConsentAuthorisationUI to load AuthChallenges if any. The call returns the AuthorizeResponse that contains all information necessary to display returned challenges to the PSU. An ScaUIMetadaData object contain UI customization parameter. -### 50 .. 60 Display Auth Screen and Collect PSU Auth Data -This STep will display the Auth Screen and collect PSU auth data. +### AuthEmbedded-050&-060 : Display Auth Screen and Collect PSU Auth Data +Using information contained in the AuthorizeResponse object, the ConsentAuthorisationUI will display the suitable AuthScreen to the PSU and use it to collect PsuAuthData. -### 70 .. 85 Send PSU Auth Data to ConsentAuthorisationApi -The psuAuth endpoint of the ConsentAuthorisationApi will finally be called to process authentication data entered by the PSU. +### AuthEmbedded-070..-087 : Send PsuAuthData to ConsentAuthorisationApi +The generic endpoint at ConsentAuthorisationApi.embeddedAuth will finally be called again to send authentication data entered by the PSU to the BankingProtocol. -### 90 .. 94 Redirect to FinTechApi -As the TppConsentSession present no more AuthChallenge, a redirect session is prepared and the PSU is redirected back to the FinTechApi. +### AuthEmbedded-090..-094 : Redirect to FinTechApi +As the TppConsentSession presents no more AuthChallenge, a RedirectSession is prepared and the PSU is redirected back to the FinTechApi. diff --git a/docs/architecture/5b-psuAuthRedirectConsent.md b/docs/architecture/5b-psuAuthRedirectConsent.md index e74baf5951..b5ef26b00a 100644 --- a/docs/architecture/5b-psuAuthRedirectConsent.md +++ b/docs/architecture/5b-psuAuthRedirectConsent.md @@ -10,25 +10,29 @@ Describes the process of redirecting a PSU to the Online Banking interface of it ## Use Cases -### 010 .. 040 Display RedirectInfoPage -A redirection to the ASPSP OnlineBanking interface start with a information of the PSU about the redirect process. After a confirmation of the redirection process through the PSU, a redirection is initiated by the ConsentAuthorizeApi. +### AuthRedirect-010 & -020 : Display RedirectInfoPage +ConsentAuthorisationUI.infoPanel page uses information provided by the AuthorizeResponse to display a redirect to ASPSP info page to the PSU. + +### AuthRedirect-030 & -040 : Grant Redirect +The PSU interface might decide to either allow the PSU to explicitly confirm or deny the redirection to the ASPSP, or automatically proceed with this without the consent of the PSU. In both case, the ConsentAuthorisationUI has to invoke the FinTechApi.toAspspGrant that will in turn invoke the ConsentAuthorisationApi.toAspspGrant endpoint to generate the redirect response. ### Managing Redirection -#### 050 Redirecting PSU to the ASPSP +#### AuthRedirect-050 : Redirecting PSU to the ASPSP Detailed specification of the redirect process might depend on the specification of the ASPSP interface. Nevertheless, the returned redirect link carries an ConsentAuthSessionCookie that is used to store consent details in the User Agent of the PSU. -As well the consentAuthState shall be part of any BackRedirectURL (OKUrl, NOKURL) so we can decrypt the ConsentAuthSessionCookie when ASPSP sends back PSU to TPP. +As well, the consentAuthState shall be part of any BackRedirectURL (OKUrl, nokUrl) so ConsentAuthorisationApi can read the ConsentAuthSessionCookie when ASPSP sends back PSU to the ConsentAuthorisationApi. -#### 060 Back-Redirecting PSU to the ConsentAuthorisationAPI -The ASPSP url used to redirect the PSU to the ASPSP contains the consentAuthState. The consentAuthState will the be used to retrieve the attached ConsentAuthSessionCookie and retrieve the TppConsentSession. +#### AuthRedirect-060 : Back-Redirecting PSU to the ConsentAuthorisationAPI +The endpoint ConsentAuthorisationAPI.fromAspspOk consumes a redirect call from the ASPSP Online Banking. The corresponding URL +contains a consentAuthState. The consentAuthState will the be used to retrieve the attached ConsentAuthSessionCookie whose content will in turn be used to read the TppConsentSession. -#### 071 .. 073 Forward call to BankingProtocol -The aspspAuthSuccess method of the BankingProtocol is called with TppConsentSession and aspspAuthCode. +#### AuthRedirect-071 .. AuthRedirect-073 : Forward call to BankingProtocol +The fromAspspOk method of the BankingProtocol is called with TppConsentSession and aspspAuthCode. - The aspspAuthCode can be use to retrieve Token from ASPSP Token endpoint in case of an oAuth Approach. - The consent session contains any other information needed to manage the consent process. -#### 077 Redirect PSU to FinTechAPI -The TppConsentSession is temporarily encrypted and stored. Corresponding redirectCode is used to redirect PSU to the FinTechAPI redirect endpoint. ConsentAuthSessionCookie is deleted with the redirect process. +#### AuthRedirect-077 Redirect PSU to FinTechAPI +The TppConsentSession is temporarily encrypted and stored in the form of a RedirectSession. Corresponding redirectCode is used to redirect PSU to the FinTechAPI redirect endpoint. ConsentAuthSessionCookie is deleted with start of this back redirect process. diff --git a/docs/architecture/README.md b/docs/architecture/README.md index b0deb169fe..569b1ab522 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -6,7 +6,7 @@ - [List of Transactions](4-initiateAisConsent.md) - [Redirect to Consent Authorization API](5-redirectPsuToConsentAPI.md) - [Authorize Consent Redirect Approach](5b-psuAuthRedirectConsent.md) -- [Authorize Consent Embedded Approach](5a-psuAuthRedirectConsent.md) +- [Authorize Consent Embedded Approach](5a-psuAuthEmbeddedConsent.md) diff --git a/docs/architecture/diagrams/useCases/4-initiateAisConsent.puml b/docs/architecture/diagrams/useCases/4-initiateAisConsent.puml index 3bce471dbf..d03df96d03 100644 --- a/docs/architecture/diagrams/useCases/4-initiateAisConsent.puml +++ b/docs/architecture/diagrams/useCases/4-initiateAisConsent.puml @@ -49,9 +49,9 @@ alt TppConsentSession.noConsentPresent() return 200_OK[](redirectCode)<> BankingProtocol -> BankingProtocol : TppConsentSession.psuConsentSession()\n:PsuConsentSession return 200_OK(PsuConsentSession, AspspRedirectInfo) - return 200_Ok(PsuConsentSession,\nConsentAuthorisationApi\n.entryPoint()) + return 200_Ok(PsuConsentSession,\nConsentAuthorisationApi\n.auth) FinTechApi -> FinTechApi : finTechConsentSessionCookie(PsuConsentSession,\nfinTechConsentSessionState):FinTechConsentSessionCookie - return redirect302[ConsentAuthorisationApi.entryPoint(),\nFinTechConsentSessionCookie]() + return redirect302[ConsentAuthorisationApi.auth,\nFinTechConsentSessionCookie]() else TppConsentSession.consentPresent() autonumber 71 1 "[InitConsent-000]" activate BankingProtocol diff --git a/docs/architecture/diagrams/useCases/5-redirectPsuToConsentAPI.puml b/docs/architecture/diagrams/useCases/5-redirectPsuToConsentAPI.puml index e58e50bd5d..8e875de2af 100644 --- a/docs/architecture/diagrams/useCases/5-redirectPsuToConsentAPI.puml +++ b/docs/architecture/diagrams/useCases/5-redirectPsuToConsentAPI.puml @@ -25,7 +25,7 @@ box "AspspDC" #LightSkyBlue end box == TPPAuthorize consent upon PSU transaction display request - method:endpoint[header](body) return code[header](body) == -FinTechUI -> ConsentAuthorisationApi ++ : GET:ConsentAuthorisationApi.authEntryPoint[UserAgentContext]() +FinTechUI -> ConsentAuthorisationApi ++ : GET:ConsentAuthorisationApi.auth[UserAgentContext]() autonumber 21 1 "[Redirect-000]" ConsentAuthorisationApi -> ConsentAuthorisationApi : selectProtocol(redirectCode) ConsentAuthorisationApi -> BankingProtocol ++ : redirectSession(redirectCode) diff --git a/docs/architecture/diagrams/useCases/5a-psuAuthEmbeddedConsent.puml b/docs/architecture/diagrams/useCases/5a-psuAuthEmbeddedConsent.puml index 25c274bbec..4b524fde3d 100644 --- a/docs/architecture/diagrams/useCases/5a-psuAuthEmbeddedConsent.puml +++ b/docs/architecture/diagrams/useCases/5a-psuAuthEmbeddedConsent.puml @@ -30,13 +30,13 @@ ConsentAuthorisationApi -> ConsentAuthorisationApi : TppConsentSession.getCookie ConsentAuthorisationApi --> ConsentAuthorisationUI : redirect302[ConsentAuthSessionCookie,\nConsentAuthorisationUI.embeddedAuthInitScreen]() deactivate ConsentAuthorisationApi activate ConsentAuthorisationUI -ConsentAuthorisationUI -> ConsentAuthorisationApi ++ : GET:ConsentAuthorisationApi.authChallenge\n[ConsentAuthSessionCookie, UserAgentContext]() +ConsentAuthorisationUI -> ConsentAuthorisationApi ++ : GET:ConsentAuthorisationApi.embeddedAuth\n[ConsentAuthSessionCookie, UserAgentContext]() return 200_OK[ConsentAuthSessionCookie]\n(ConsentAuthorizeResponse{Transactions[],AisConsent,ScaUIMetadaData}) loop #LightCyan while(ConsentAuthorizeResponse.hasAuthChallenge()) ConsentAuthorisationUI --> psu : displayAuthScreen(ScaUIMetadaData) deactivate ConsentAuthorisationUI psu -> ConsentAuthorisationUI ++ : enterAuthData(PsuAuthData) - ConsentAuthorisationUI -> ConsentAuthorisationApi ++ : POST:ConsentAuthorisationApi.psuAuth\n[ConsentAuthSessionCookie, UserAgentContext](PsuAuthData) + ConsentAuthorisationUI -> ConsentAuthorisationApi ++ : POST:ConsentAuthorisationApi.embeddedAuth\n[ConsentAuthSessionCookie, UserAgentContext](PsuAuthData) autonumber 80 1 "[AuthEmbedded-000]" ConsentAuthorisationApi -> BankingProtocol ++ : updatePsuAuth[TppConsentSession](PsuAuthData)<> BankingProtocol -> BankingProtocol : TppConsentSession.aspspConsentSession()\n:TppConsentSession diff --git a/docs/architecture/diagrams/useCases/5b-psuAuthRedirectConsent.puml b/docs/architecture/diagrams/useCases/5b-psuAuthRedirectConsent.puml index d99a47bc59..8bb2e5080d 100644 --- a/docs/architecture/diagrams/useCases/5b-psuAuthRedirectConsent.puml +++ b/docs/architecture/diagrams/useCases/5b-psuAuthRedirectConsent.puml @@ -29,8 +29,8 @@ end box ConsentAuthorisationApi --> ConsentAuthorisationUI ++ : displayRedirectInfoPage[ConsentAuthSessionCookie,\nConsentAuthorisationUI.infoPanel](AuthorizeResponse) ConsentAuthorisationUI --> psu : displayRedirectInfoPage() deactivate ConsentAuthorisationUI -psu -> ConsentAuthorisationUI ++ : confirmRedirect() -ConsentAuthorisationUI -> ConsentAuthorisationApi ++ : GET:confirmRedirect\n[ConsentAuthSessionCookie]() +psu -> ConsentAuthorisationUI ++ : toAspspGrant +ConsentAuthorisationUI -> ConsentAuthorisationApi ++ : GET:toAspspGrant\n[ConsentAuthSessionCookie]() deactivate ConsentAuthorisationUI ConsentAuthorisationApi --> OnlineBankingUI ++ : redirect302[ConsentAuthSessionCookie,\nOnlineBankingApi.redirectEntryPoint]\n() deactivate ConsentAuthorisationApi @@ -61,11 +61,11 @@ group OnlineBankingConsent end autonumber resume activate ConsentAuthorisationUI -ConsentAuthorisationUI -> ConsentAuthorisationApi ++ : GET:aspspAuthSuccess[ConsentAuthSessionCookie]() +ConsentAuthorisationUI -> ConsentAuthorisationApi ++ : GET:fromAspspOk[ConsentAuthSessionCookie]() autonumber 71 1 "[AuthRedirect-000]" ConsentAuthorisationApi -> ConsentAuthorisationApi : ConsentAuthSessionCookie.tppConsentSession\n(consentAuthState):TppConsentSession ConsentAuthorisationApi -> ConsentAuthorisationApi : getBankingProtocol(TppConsentSession) -ConsentAuthorisationApi -> BankingProtocol ++ : aspspAuthSuccess(TppConsentSession, aspspAuthCode) +ConsentAuthorisationApi -> BankingProtocol ++ : fromAspspOk(TppConsentSession, aspspAuthCode) group RetrievASPSPConsent BankingProtocol -> OnlineBankingApi ++ : getConsentStatus or getToken[TppConsentSession, TppContext, aspspAuthCode]() return TppConsentSession diff --git a/docs/architecture/dictionary.md b/docs/architecture/dictionary.md index 4aaa6753b4..0f7f5bfb2a 100644 --- a/docs/architecture/dictionary.md +++ b/docs/architecture/dictionary.md @@ -1,5 +1,25 @@ # Dictionary +## ConsentData +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 +- [TppConsentSession](dictionary.md#TppConsentSession) +- [RedirectSession](dictionary.md#RedirectSession) +- [PsuConsentSession](dictionary.md#PsuConsentSession) + ## PsuUserDevice A PSU user device runs applications used by the PSU to access banking functionality. Those applications are generally called PsuUgerAgents. @@ -19,7 +39,7 @@ The use of cookies provides the most elaborated way to protect a session establi - Expired Cookies (attribute __Expires__) are not resent to the server. - Cookies shall never be transmitted to a domain not matching it's origin. -#### Redirection +#### Redirection The server can request the WebBrowser to redirect the user to another page by returning a 30\[X\] response code to the WebBrowser. Redirection will generally happens in the same Browser environment. We will be using redirection to switch the user context from one application to another one. Following redirection will generally be found in this framework: - FinTechApi to-> ConsentAuthorisationApi - ConsentAuthorisationApi to-> OnlineBankingApi @@ -115,7 +135,8 @@ Information used to identify the FinTech application at the TppBankingApi. For e ### PsuConsentSession 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) +- 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. @@ -129,6 +150,8 @@ Interface used by the PSU to authorize a consent. ### ConsentAuthSessionCookie This is the cookie object used to maintain the consent session between the ConsentAuthorisationUI and the ConsentAuthorisationApi. It will generated and set as a __httpOnly, Secure__ +This cookie will generally contain the identifier of the TppContentSession and the cryptographic key used to read that TppContentSession. + ### consentAuthState This is the CSRF-State String of the ConsentAuthorisationApi. It is a transient reference of the consent request. It encodes a key that is used to encrypt information stored in the corresponding ConsentAuthSessionCookie. @@ -144,6 +167,9 @@ The consentAuthState shall never be stored in the ConsentAuthSessionCookie. As a redirect request carries the consentAuthState in parameter, a new consentAuthState shall be generated after each redirect and returned back to the client, as the old one is probably leaked into log files as part of a request URI. +### RedirectSession +Holds consent information for the duration of a redirect. Redirect patterns are described [below](dictionary.md#Redirection). + ### RedirectSessionStoreApi Storage of temporary redirect sessions. Redirect session are stored only for the duration of the redirect request while redirecting from the TppBankingApi to the ConsentAuthorisationApi and from the ConsentAuthorisationApi back to the TppBankingApi. @@ -167,9 +193,15 @@ Api banking provided by ASPSP. This interface is not directly accessed by the PS Information used to identify the Tpp application in the ASPSP environment. Like a TPP QWAC certificate. ### TppConsentSession +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](dictionary.md#FinTechContext): Data needed to authorize the FinTechApi (FinTechSSLCertificate, ApiKey, SignedJWT) -- [PsuConsentSession](dictionary.md#PsuConsentSession): Information associated with the consent initialized by the TPP at the ASPSP interface. -- Additional information not available in the PsuConsentSession: Containing ConsentId, ConsentData, AspspConsentSessionRedirectUrl. +- Additional information needed for interaction between TPP and ASPSP but without any concern to the PSU. ### OnlineBankingApi 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. @@ -183,6 +215,4 @@ It is recommended to inform the PSU prior to redirecting the PSU back to the TPP ### 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. -## ConsentData -Specification of the requested consent. BankAccount, frequencyPerDay, validUntil, ..., From 64049e4572546c1b64bb798d160685e212aa916b Mon Sep 17 00:00:00 2001 From: "Pouatcha,Francis (ext)" Date: Thu, 12 Dec 2019 19:21:44 -0500 Subject: [PATCH 2/4] Added files for version and release notes. --- README.md | 2 +- docs/README.md | 14 ++++++++++++++ docs/releasenotes.md | 1 + docs/version_policy.md | 1 + 4 files changed, 17 insertions(+), 1 deletion(-) create mode 100644 docs/README.md create mode 100644 docs/releasenotes.md create mode 100644 docs/version_policy.md diff --git a/README.md b/README.md index a9862ca6ca..b0c661c4fe 100644 --- a/README.md +++ b/README.md @@ -23,9 +23,9 @@ The following picture displays the overall architecture of this banking gateway: ## Releases and versions * [Versioning, Release and Support policy](docs/Version_Policy.md) - * [Release notes](docs/releasenotes.md) * [Roadmap for next features development](docs/roadmap.md) +* [Initial Requirements](docs/README.md) ### Testing API with Postman json collections diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000000..1d74822f53 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,14 @@ +# Documentation + +Still in a draft state. We are working on the process of aligning documentation and code. Till that is done, we will be documenting using the gh-pages branch. + +What can you find here: + +- [Initial Use Case definition](architecture/README.md) +- [BankingProtocol POC](architecture/drafts/README.md) + + + + + + diff --git a/docs/releasenotes.md b/docs/releasenotes.md new file mode 100644 index 0000000000..abf7bdee69 --- /dev/null +++ b/docs/releasenotes.md @@ -0,0 +1 @@ +# Release Notes \ No newline at end of file diff --git a/docs/version_policy.md b/docs/version_policy.md new file mode 100644 index 0000000000..88ef72d8ae --- /dev/null +++ b/docs/version_policy.md @@ -0,0 +1 @@ +# Version Policy \ No newline at end of file From 79e4b8d44462abec31ba08822e567e492619b95e Mon Sep 17 00:00:00 2001 From: "Pouatcha,Francis (ext)" Date: Thu, 12 Dec 2019 20:03:41 -0500 Subject: [PATCH 3/4] Normalized consume api --- ...6-consume_api.puml.md => 6-consume_api.md} | 24 +++++++++---------- docs/architecture/README.md | 1 + .../diagrams/useCases/6-consume_api.puml | 8 +++---- 3 files changed, 16 insertions(+), 17 deletions(-) rename docs/architecture/{6-consume_api.puml.md => 6-consume_api.md} (75%) diff --git a/docs/architecture/6-consume_api.puml.md b/docs/architecture/6-consume_api.md similarity index 75% rename from docs/architecture/6-consume_api.puml.md rename to docs/architecture/6-consume_api.md index 6cef81bd71..dda136c071 100644 --- a/docs/architecture/6-consume_api.puml.md +++ b/docs/architecture/6-consume_api.md @@ -1,7 +1,7 @@ # Consume API after Consent Authorization ## Description -This workflow starts with the redirect link leaving from either [Authorize Consent Redirect Approach](5b-psuAuthRedirectConsent.md) or [Authorize Consent Embedded Approach](5a-psuAuthRedirectConsent.md). This redirect link will be used by the FinTechApi to retrieve a corresponding Token that can be used to request services on behalf of the PSU. +This workflow starts with the redirect link leaving from either [Authorize Consent Redirect Approach](5b-psuAuthRedirectConsent.md) or [Authorize Consent Embedded Approach](5a-psuAuthEmbeddedConsent.md). This redirect link will be used by the FinTechApi to retrieve a corresponding Token that can be used to request services on behalf of the PSU. As long as this token is valid, token will be used to perform corresponding service request on behalf on the PSU. @@ -11,31 +11,29 @@ As long as this token is valid, token will be used to perform corresponding serv ## Use Cases -### 010. FinTechApi.consentAuthDone +### BankingService-010 : FinTechApi.fromConsentOk The redirect request coming from the [ConsentAuthorisationApi](dictionary.md#ConsentAuthorisationApi) contains a redirectCode. This request will be forwarded by the FinTechApi to the TppBankingApi. The request contains following information: #### redirectCode -Available in the redirect url. This information will be used to retrieve the authorization token from the TppBankingApi. So the information needs not be processed by th FinTechApi +Available in the redirect url. This information will be used to retrieve the authorization token from the TppBankingApi. So the information needs not be processed by the FinTechApi #### FinTechConsentSessionCookie -Available in the request header. This cookie shall be set for the Max time given to the PSU for the authorization of the corresponding consent. The cookie can be bound to the end point FinTechApi.consentAuthDone so it does no need to be transported to the server on other requests. +Available in the request header. This cookie shall be set for the Max time given to the PSU for the authorization of the corresponding consent. The cookie can be bound to the end point FinTechApi.fromConsentOk so it does not need to be transported to the server on other requests. #### finTechConsentSessionState Available in the redirect url. Will be used to read and validate the corresponding FinTechConsentSessionCookie. -### 020. Validate the redirectLink +### BankingService-020 : Validate the redirectLink The finTechConsentSessionState will be used to read and validate the corresponding FinTechConsentSessionCookie. -### 030. TppBankingApi.code2Token -This end point is invoked by the FinTechApi to retrieve token used to send subsequent service requests to the TppBankingApi. +### BankingService-030 : TppBankingApi.code2Token +This end point is invoked by the FinTechApi to retrieve token used to send subsequent service requests to the TppBankingApi. We call this token PsuConsentSession. -### 040. BankingProtocol.code2Token +### BankingService-040 : BankingProtocol.code2Token Forward request to banking protocol. -### 050. Store Token (PsuConsentSession) +### BankingService-050 : storePsuConsent The returned PsuConsentSession is stored by the FinTechApi for future use. -### 060 .. 67 Service Request -The returned token is used to invoke the service request (ListTransactions). Service result is returned to the FinTechApi and displayed to the PSU. - - \ No newline at end of file +### BankingService-060 .. BankingService-067 Service Requests +The returned token is used to invoke the service request (ListTransactions). Service result is returned to the FinTechApi and displayed to the PSU. \ No newline at end of file diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 569b1ab522..1e9c522da6 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -7,6 +7,7 @@ - [Redirect to Consent Authorization API](5-redirectPsuToConsentAPI.md) - [Authorize Consent Redirect Approach](5b-psuAuthRedirectConsent.md) - [Authorize Consent Embedded Approach](5a-psuAuthEmbeddedConsent.md) +- [Consume Service](6-consume_api.md) diff --git a/docs/architecture/diagrams/useCases/6-consume_api.puml b/docs/architecture/diagrams/useCases/6-consume_api.puml index 2f9d6d73b4..8d2b96bd82 100644 --- a/docs/architecture/diagrams/useCases/6-consume_api.puml +++ b/docs/architecture/diagrams/useCases/6-consume_api.puml @@ -1,6 +1,6 @@ @startuml -autonumber 10 10 "[Service-000]" +autonumber 10 10 "[BankingService-000]" actor psu box "PsuUserAgent" #LightGray @@ -29,7 +29,7 @@ end box FinTechUI -> FinTechApi ++ : GET:FinTech-Redirect-URI[UserAgentContext,\nFinTechConsentSessionCookie]()\n FinTechApi -> FinTechApi : validateRedirectCall\n(finTechConsentSessionState,FinTechConsentSessionCookie) FinTechApi -> TppBankingApi ++ : GET:code2Token[UserAgentContext,\nFinTechContext]\n(redirectCode)<> -autonumber 40 1 "[Service-000]" +autonumber 40 1 "[BankingService-000]" TppBankingApi -> BankingProtocol ++ : code2Token(redirectCode) BankingProtocol -> RedirectSessionStoreApi ++ : redirectSession(redirectCode) RedirectSessionStoreApi -> RedirectSessionStoreApi : loadDeryptDeleteRedirectSession\n(redirectCode):TppConsentSession @@ -37,10 +37,10 @@ return TppConsentSession return TppConsentSession TppBankingApi -> TppBankingApi: TppConsentSession.PsuConsentSession() return PsuConsentSession -autonumber 50 10 "[Service-000]" +autonumber 50 10 "[BankingService-000]" FinTechApi -> FinTechApi : storePsuConsent(PsuConsentSession) loop FinTech2TppConsentToken.isValid() - autonumber 60 1 "[Service-000]" + autonumber 60 1 "[BankingService-000]" FinTechApi -> TppBankingApi ++ : POST:listTransactions[PsuConsentSession](requestSpec) TppBankingApi -> BankingProtocol ++ : listTransactions[TppConsentSession]\n(requestSpec) BankingProtocol -> AspspBankingApi ++ : listTransactions[TppContext](AisConsent, requestSpec) From 4ccc7569b0df980c71eb1a9f4babde266c289fc8 Mon Sep 17 00:00:00 2001 From: "Pouatcha,Francis (ext)" Date: Thu, 12 Dec 2019 23:04:39 -0500 Subject: [PATCH 4/4] Normalized init consent --- docs/architecture/4-initiateAisConsent.md | 71 ++++++++++--------- .../useCases/4-initiateAisConsent.puml | 2 +- docs/architecture/dictionary.md | 5 +- 3 files changed, 41 insertions(+), 37 deletions(-) diff --git a/docs/architecture/4-initiateAisConsent.md b/docs/architecture/4-initiateAisConsent.md index 4e95245a43..3153465f04 100644 --- a/docs/architecture/4-initiateAisConsent.md +++ b/docs/architecture/4-initiateAisConsent.md @@ -8,90 +8,91 @@ Request the list of transactions for a given bank account. Initiates a consent r ![Session diagram](http://www.plantuml.com/plantuml/proxy?src=https://raw.githubusercontent.com/adorsys/open-banking-gateway/gh-pages/docs/architecture/diagrams/useCases/4-initiateAisConsent.puml&fmt=svg&vvv=1&sanitize=true) ## Use Cases -### 1. FinTechUI displays BankProfile to PSU -==> FinTechUI --> psu : displayBankServices(BankProfile) -The result of a bank selection ist that the FinTechUI displays the list of services offered by the selected bank to the PSU. +### InitConsent-010 : FinTechUI displays BankProfile to PSU +The result of a bank selection is that the FinTechUI displays the [BankProfile](describes.md#BankProfile) to the PSU. The bank profile also contains the list of services offered by the selected bank. -### 2. PSU selects a service (Like listTransactions) -==> psu -> FinTechUI ++ : selectService\n"listTransactions(BankProfile)" +### InitConsent-020 : PSU selects a service (Like listTransactions) +The FinTechUI will forward the service selected to the FinTechApi. In this case listTransactions(BankProfile). The selection might be accompanied with some service specifications. For example in the case of listTransactions, this can be the iban of the target account. We will call this ListTransactionsSpec. -### 3. FinTechUI forwards service request to FinTechApi -==> FinTechUI -> FinTechApi ++ : listTransactions\[FinTechLoginSessionCookie,\nUserAgentContext\](BankProfile,ListTransactionsSpec)<> +### InitConsent-030 : FinTechUI to FinTechApi.listTransactions - The attached [FinTechLoginSessionCookie](dictionary.md#FinTechLoginSessionCookie) is used to maintain session between PSU and FinTech. - The attached [UserAgentContext](dictionary.md#UserAgentContext) describes details associated with the user agent of the PSU. - The given [BankProfile](dictionary.md#BankProfile) contains meta information associated with the selected Bank. - The ListTransactionsSpec specifies details of the service requested by the PSU. -#### 3.1 Load PsuConsentSession -==> FinTechApi -> FinTechApi : psuConsentSession\n(FinTechLoginSessionCookie,\nBankProfile,ListTransactionsSpec)<> -FinTechApi loads any matching existing [PsuConsentSession](dictionary.md#PsuConsentSession). The FinTechLoginSessionCookie holds the reference of the PSU in the system of the FinTech. +#### InitConsent-031 : Load PsuConsentSession +A [PsuConsentSession](dictionary.md#PsuConsentSession) is a reusable token, that can be used to request service with the TppBankingApi. It is reference to the PSU in the realm of the TPP. +Whether a service request is covered by an existing PsuConsent is decided by the TppBankingApi. The Task of the FinTechApi is to load any existing PsuConsentSession and associate it with the PSU. -### 4. FinTechApi forwards service request to TppBankingApi -==> FinTechApi -> TppBankingApi ++ : listTransactions\[UserAgentContext,\nPsuConsentSession,FinTechContext\]\n(BankProfile,ListTransactionsSpec)<> -The associated [FinTechContext](dictionary.md#FinTechContext) contains identification information associated with the FinTech. +### InitConsent-040 : FinTechApi to TppBankingApi.listTransactions +- The associated [FinTechContext](dictionary.md#FinTechContext) contains identification information associated with the FinTech. +- PsuConsentSession +- UserAgentContext +- BankProfile +- ListTransactionsSpec -#### 4.1 Loads the BankingProtocol from the given BankProfile +#### InitConsent-041 : Loads the BankingProtocol from the given BankProfile TppBankingApi selects the [BankingProtocol](dictionary.md#BankingProtocol) based on the given BankProfile. -### 5. TppBankingApi forwards service request to BankingProtocol +### InitConsent-050 : TppBankingApi to BankingProtocol.listTransactions The [BankingProtocol](dictionary.md#BankingProtocol) associated with the given BankProfile decides on how to proceed with the request. BankingProtocol can: -#### 5.1 Load TppConsentSession -- Use an eventual consentId contained in the given [PsuConsentSession](dictionary.md#PsuConsentSession) to load an existing [TppConsentSession](dictionary.md#TppConsentSession). +#### InitConsent-051 : Load TppConsentSession +- If there is existing consent associated with the PSU for the given service, the BankingProtocol will load the corresponding [TppConsentSession](dictionary.md#TppConsentSession). Information needed to load the TppConsentSession is contained in the given [PsuConsentSession](dictionary.md#PsuConsentSession). - Use the loaded [TppConsentSession](dictionary.md#TppConsentSession) to retrieve an existing consent and proceed to the ASPSP with the service request. -### 6. No Suitable Consent Present -#### 6.0 Initiating a Consent with the ASPSP +### No Suitable Consent Present +#### InitConsent-060 : Initiating a Consent with the ASPSP If there is no suitable consent available, the BankingProtocol will first proceed with a consent initiation request.. This is, an initiated service request will either ends up in the expected service response or first redirect the PSU to the [ConsentAuthorisationApi](dictionary.md#ConsentAuthorisationApi). Whether this operation is necessary or not depends on the [AspspBankingApi](dictionary.mdAspspBankingApi) interface. The selected banking protocol will know how to deal with this. The Associated [TppContext](dictionary.md#TppContext) contains Tpp identifying information. -#### 6.1 ConsentInit Response +#### InitConsent-061 : ConsentInit Response The response of the consent init request depends on the ASPSP implementation. It generally provides information needed to collect PSU identification information in the embedded case or information needed to redirect the PSU to the [OnlineBankingApi](dictionary.md#OnlineBankingApi). The result of a consent init session also carries an [TppConsentSession](dictionary.md#TppConsentSession), containing all information needed to be stored by the Tpp for the reference of the started consent session. -#### 6.2 BankingProtocol calls RedirectSessionStoreApi for a redirectCode +#### InitConsent-062 : BankingProtocol calls RedirectSessionStoreApi for a redirectCode -#### 6.3 RedirectSessionStoreApi +#### InitConsent-063 : RedirectSessionStoreApi The [RedirectSessionStoreApi](dictionary.md#RedirectSessionStoreApi) will encrypt and store the redirect session, indexing it with a redirectCode that can be used upon redirection by the ConsentAuthorisationApi to retrieve the corresponding [TppConsentSession](dictionary.md#TppConsentSession). -##### 6.3a Encryption +##### InitConsent-063a : Encryption Encryption is performed to prevent unlawfull use of contained information in the Tpp's backend environment during the redirect session. -##### 6.3b Storage an Expiration +##### InitConsent-063b : Storage an Expiration Encrypted [TppConsentSession](dictionary.md#TppConsentSession) shall only be stored for the duration of the redirect session. -##### 6.3c Auto Cleanup +##### InitConsent-063c : Auto Cleanup Auto Cleanup process will make sure all expired redirect sessions are removed from that storage. -#### 6.4 RedirectSessionStoreApi returns redirectCode to BankingProtocol +#### InitConsent-064 : RedirectSessionStoreApi returns redirectCode to BankingProtocol The [redirectCode](dictionary.md#redirectCode) is a one time string that contains information used to retrieve redirectInfo from the TPP Server in a back channel. The redirectCode is short lived (like 10 seconds). This is, TPP server does not need to hold the record indexed by this redirectCode for more than the given expiration time. Record must also be deleted by the TPP on first retrieval by the ConsentAPI. -#### 6.5 BankingProtocol reproduces PsuConsentSession from the TppConsentSession +#### InitConsent-065 : BankingProtocol reproduces PsuConsentSession from the TppConsentSession -#### 6.6 Resulting Redirect Information is returned to the TppBankingApi +#### InitConsent-066 : Resulting Redirect Information is returned to the TppBankingApi The attached [AspspRedirectInfo](dictionary.md#AspspRedirectInfo) contains all information necessary to redirect the PSU to the [ConsentAuthorisationApi](dictionary.md#ConsentAuthorisationApi). -#### 6.7 TppBankingApi returns the PsuConsentSession an a redirectCode to FinTechApi +#### InitConsent-067 : TppBankingApi returns the PsuConsentSession an a redirectCode to FinTechApi -#### 6.8 FinTechConsentSessionCookie +#### InitConsent-068 : FinTechConsentSessionCookie Available in the request header. This cookie shall be set for the Max time given to the PSU for the authorization of the corresponding consent. The cookie can be bound to the end point FinTechApi.consentAuthDone so it does no need to be transported to the server on other requests. -#### 6.8a finTechConsentSessionState +##### InitConsent-068a : finTechConsentSessionState Will be used to read and validate the corresponding FinTechConsentSessionCookie. -#### 6.9 FinTechApi redirects userAgent to the ConsentAuthorisationApi +#### InitConsent-069 : FinTechApi redirects userAgent to the ConsentAuthorisationApi - [PsuUserAgent](dictionary.md#PsuUserAgent) redirection happens using a HTTP_302 - redirectCode is attached as a query parameter - produced [FinTechLoginSessionCookie](dictionary.md#FinTechLoginSessionCookie) is returned as a cookie to the [PsuUserAgent](dictionary.md#PsuUserAgent) -### 7. Suitable Consent Present +### InitConsent-070 : Suitable Consent Present -#### 7.1 Forward Service Request to ASPSP +#### InitConsent-071 : Forward Service Request to ASPSP Service request is forwarded to the [AspspBankingApi](dictionary.md#AspspBankingApi) together with a reference to the consent. The Associated [TppContext](dictionary.md#TppContext) contains Tpp identifying information. -#### 7.2 Returned Service Response if sent and displayed to the PSU. +#### InitConsent-072 : Returned Service Response if sent and displayed to the PSU. diff --git a/docs/architecture/diagrams/useCases/4-initiateAisConsent.puml b/docs/architecture/diagrams/useCases/4-initiateAisConsent.puml index d03df96d03..ce60952936 100644 --- a/docs/architecture/diagrams/useCases/4-initiateAisConsent.puml +++ b/docs/architecture/diagrams/useCases/4-initiateAisConsent.puml @@ -28,7 +28,7 @@ end box FinTechUI --> psu : displayBankServices(BankProfile) psu -> FinTechUI ++ : selectService\n"listTransactions(BankProfile)" -FinTechUI -> FinTechApi ++ : listTransactions[FinTechLoginSessionCookie,\nUserAgentContext](BankProfile,ListTransactionsSpec)<> +FinTechUI -> FinTechApi ++ : listTransactions[FinTechLoginSessionCookie,\nUserAgentContext](BankProfile,ListTransactionsSpec) autonumber 31 1 "[InitConsent-000]" FinTechApi -> FinTechApi : psuConsentSession\n(FinTechLoginSessionCookie,\nBankProfile,ListTransactionsSpec)<> autonumber 40 1 "[InitConsent-000]" diff --git a/docs/architecture/dictionary.md b/docs/architecture/dictionary.md index 0f7f5bfb2a..e6d1b45a24 100644 --- a/docs/architecture/dictionary.md +++ b/docs/architecture/dictionary.md @@ -93,6 +93,9 @@ Financial web service provided by the FinTech. ### FinTechLoginSessionCookie This is a cookie used to maintain the login session between the FinTechUI and the FinTechApi. As this maintains the login state of the PSU in the FinTechUI, this session can be kept open for the life span of the interaction between the FinTechUI and the FinTechApi. +### FinTechLoginSessionState +This is the CSRF-State String associated with the FinTechLoginSessionCookie. This information must be presented whenever the FinTechApi consumes the FinTechLoginSessionCookie. It encodes a key that is used to encrypt/decrypt information stored in the corresponding FinTechLoginSessionCookie. + ### Fintech2TppRedirectInfoPage This panel will be used to inform the PSU upon redirecting the PSU to the ConsentAuthorisationApi. This information step is recommended as changes in UI display between the FinTechUI and the ConsentAuthorisationUI might confuse the PSU. @@ -153,7 +156,7 @@ This is the cookie object used to maintain the consent session between the Conse This cookie will generally contain the identifier of the TppContentSession and the cryptographic key used to read that TppContentSession. ### consentAuthState -This is the CSRF-State String of the ConsentAuthorisationApi. It is a transient reference of the consent request. It encodes a key that is used to encrypt information stored in the corresponding ConsentAuthSessionCookie. +This is the CSRF-State String associated with the ConsentAuthSessionCookie. It encodes a key that is used to encrypt information stored in the corresponding ConsentAuthSessionCookie. This is: consentAuthState = state-id + consentEncryptionKey