Merge pull request #55 from adorsys/doc/#53-refine-documentation

Doc/#53 refine documentation

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
 

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)
+
+
+
+
+
+

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.
 

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

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.
 

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.