Authorize API for Berlin

The banks who wish to override the default consent page and integrate their own page can perform this by using the Authorise API. This is a REST API and it provides the following functionalities:

Display information on the consent page.
Capture the data on the consent page and persist them

The above functionalities are fulfilled by the following API resources:

The retrieval endpoint invokes this an API to retrieve consent data from the solution and account data from the bank back end. Then the consent page invokes the GET /consent/data/{session-data-key} endpoint.

If you have the following configured in the <WSO2_OB_IAM_HOME>/repository/conf/deployment.toml file:

[oauth]
prompt_consent=false

If prompt_consent is set to false, the value for the session-data-key path parameter should the session-data-key in the current communication session.
If prompt_consent is set to true or not configured in the file, the value for the session-data-key path parameter should be the sessionDataKeyConsent attribute in the current session.

Manual user authentication adds the above attributes to the session. For manual user authentication, you need to invoke the /commonauth endpoint.

Click here to see how it done...

Open the <WSO2_OB_IAM_HOME>/repository/conf/deployment.toml file and set the following configuration to false. This is to retain the sessionDataKey attribute to the following redirections, if the value is set to true, the sessionDataKey attribute is removed after the first redirection.
```
remove_on_consume_from_api = "false"
```
Restart the Identity and Access Management server.
Create a consent and generate the authorize URL to authorize the consent. For more information on this, see Initiate an account consent.

Then, you are redirected to the solution's login page and the redirected URL is as follows:

https://localhost:9446/authenticationendpoint/login.do?sessionDataKey=8d8f5ded-df91-4be8-94d9-c6fa933901d3&relyingParty=PSDDE-BAFIN-104114&authenticators=BasicAuthenticator%3ALOCAL

Extract the sessionDataKey attribute from the above URL and invoke the /commonauth endpoint. This is to manually perform the user authentication.

curl --location --request POST 'https://localhost:9446/commonauth?username=admin@wso2.com&sessionDataKey=<session-data-key-from-browser-url>&password=wso2123' --header 'Content-Type: application/x-www-form-urlencoded'   -i

The response is as follows:

HTTP/1.1 302
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Set-Cookie: pastr-8d8f5ded-df91-4be8-94d9-c6fa933901d3=4f7c4985-5b03-469c-8c22-7a7f82679b33; Path=/; Secure; HttpOnly
Set-Cookie: pastr-8d8f5ded-df91-4be8-94d9-c6fa933901d3=4f7c4985-5b03-469c-8c22-7a7f82679b33; Max-Age=0; Expires=Thu, 01-Jan-1970 00:00:10 GMT; Path=/; Secure; HttpOnly
Set-Cookie: commonAuthId=39f71840-915c-4949-a446-87a08c819a86; Path=/; Secure; HttpOnly
Location: https://localhost:9446/oauth2/authorize?sessionDataKey=155d9494-ef4a-467b-adf0-0607a47b6200
Content-Length: 0
Date: Thu, 25 Feb 2021 18:56:29 GMT
Server: WSO2 Carbon Server

HTTP/1.1 302
X-Frame-Options: DENY
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Location: https://localhost:9446/ob/authenticationendpoint/oauth2_authz.do?sessionDataKeyConsent=45a3495a-ab37-4572-8b3f-8380ec38acc7
Date: Thu, 25 Feb 2021 18:56:29 GMT
Content-Length: 0
Server: WSO2 Carbon Server

Note the new sessionDataKey, sessionDataKeyConsent, and the commonAuthId attributes in the response.

Invoke the GET /consent/data/{session-data-key} endpoint with the sessionDataKey from the above the /commonauth response.
Invoke the PATCH /authorize/{consent-id} endpoint using the:
- commonAuthId from the /commonauth response
- authorisationId from the GET /consent/data/{session-data-key} response
Invoke the POST /oauth2/authorize endpoint using the sessionDataKeyConsent attribute from the /commonauth response. The response of the POST /oauth2/authorize endpoint contains authorization_code, use this code to generate a user access token.

You can capture the information on the consent page and persist them. The consent page needs to invoke the PATCH /authorize/{consent-id} endpoint to capture and persist information. By default, account and consent information is persisted.

Authorising accounts consents

Given below are sample requests and responses when you authorise an account consent.

It is mandatory to include the userId, authorisationId, and permission fields in the request body.
For the authorisationId field in the request payload, you can use authorisationId that you have retrieved from the above GET /consent/data/{session-data-key} request.
For the permission field, the available permission levels are AllPsd2, AvailableAccounts, AvailableAccountsWithBalances, and Default.
- If the value of the permission field is set to Default, it is mandatory to set the allAccountsList, transactionsList, balancesList values in the request body. If these values are not available, you can pass an empty array like this [].
- If the permissions value is set to either availableAccountsWithBalance, availableAccounts or allPsd2, it is mandatory to have the allAccountsList array in the request.

When the permission field is set to Default:

When the permission field is set to availableAccountsWithBalance:

The availableAccounts and allPsd2 permissions also follow the same format as availableAccountsWithBalance.

Authorising payment consents

Given below are sample requests and responses when you authorise a payment consent.

It is mandatory to include the userId and authorisationId fields in the request body.
For the authorisationId field in the request payload, you can use authorisationId that you have retrieved from the above GET /consent/data/{session-data-key} request.

Authorising funds-confirmation consents

Given below are sample requests and responses when you authorise a funds-confirmation consent.

It is mandatory to include the userId and authorisationId fields in the request body.
For the authorisationId field in the request payload, you can use authorisationId that you have retrieved from the above GET /consent/data/{session-data-key} request.

POST /oauth2/authorize

This resource is to generate an URL with an authorisation code. Given below is a sample request and response for all types of consents (accounts, payments, funds-confirmation consents).