IMPORTANT: DON'T FORGET TO HANDLE TOKENS, SECRETS, CERTIFICATES(public and private keys), CLIENT_IDS AND PASSWORDS SECURELY.
openbanking-accountinformation is a complete application to process account information journeys of Open Banking UK. To be able to run these journeys, user needs;
1- to complete dynamic or manual registration process with each aspsp(configs added for Danske and OzoneBank)
2- to collect clientId and password(optional) and update in config_table
You can either use an .env file or export env variables to pass below values. It is recommended to keep keys in a secure environment rather than public access.
.env file:
#Port for account service
PORT=8080
#Port for callback service
PORT_CALLBACK=8081
#shared secret key to be used for signing internal jwts
INTERNAL_SIGN_KEY=<internal_signing.key>
#this key is used to sign JWT. It can be obtained from OpenBanking Portal
OB_SIGN_KEY=<client_signing.key>
#KID value will be the same with your sign public cert. This can be obtained from
KID=<CLIENT_SIGNING_KID>
#This can be the issuer of Open Banking certificate chain
CLIENT_CA_CERT_PEM=<ob_issuer.cer>
#Key pairs of TPP's transport and used for TLS-MA. This can be obtained from Open Banking portal.
CLIENT_CERT_PEM=<client_transport.pem>
CLIENT_KEY_PEM=<client_transport.key>
#database driver
DRIVER_NAME=postgres
#database connection url
DATASOURCE_URL=postgres://postgres:postgres@localhost:5432/accountinformation?sslmode=disable
#database migration properties. version should be logical with sql files prefixes; 1_,2_ etc
MIGRATE_VERSION=2
MIGRATE_SCRIPT_URL=file://scripts/postgresql
MIGRATE_DATABASE_URL=postgres://postgres:postgres@localhost:5432/accountinformation?sslmode=disableWe can use either an in memory database or a relational database to store our data. Here, primarily Postgresql is used and for fast testing, sqlite is preferred. Once you make ready your database, then migration process should be triggered.
-
If you want to complete it on your local; run
/cmd/migrate/migrate.go. Make sure you have correct values for env variables; MIGRATE_VERSION, MIGRATE_SCRIPT_URL, MIGRATE_DATABASE_URL. Once this is successfull, you need to see messagemigration has been completed, then check the database and the tables. -
If you want to run in your docker environment, docker-compose handles it directly. Please check
docker-compose.ymlfor more information. -
You can also check the github action flow to understand how it is handled during the deployment flow.
Account service is the main service which exposes APIs and functions which interact with Open Banking UK and ASPSPs. It picks PORT from environment variables and can be built as a standalone application.
- to run on your local, go to /cmd/account/account.go and run/debug the go file.
- to build via command line, you can run
go build -o account ./cmd/account - or you can run it directly by calling
go run ./cmd/account
Callback service is used to handle redirected response from ASPSPs to complete consent authorization journey. It picks PORT_CALLBACK from environment variables and can be built as a standalone application.
- to run on your local, go to /cmd/callback/callback.go and run/debug the go file.
- to build via command line, you can run
go build -o callback ./cmd/callback - or you can run it directly by calling
go run ./cmd/callback
As there are 2 different applications in the platform as account and callback, we need to handle this either with in a single Dockerfile or separate file for each service.
Here, we used one single configuration file, and we didn't use any command, so we need run each separate container for each service by passing its own name from the same image. After the CI/CD pipeline builds account and callback in the Build step, the binaries is picked up and put into the Docker image in the next step.
Once your image is ready, the containers can be created with;
docker run -p 8080:8080 <repo-domain-name>/openbanking-accountinformation ./account
docker run -p 8081:8081 <repo-domain-name>/openbanking-accountinformation ./callback
We can use Dockerfile.standalone file, if we want to build the image in our local environment. Once the process is completed successfully, we can use the same commands above to run the containers.
Docker compose provides us a compact environment, which includes all dependencies with Postgresql and Redis. Once it runs successfully, we can see two services up as openbanking-accountinformation and openbanking-accountinformation_callback. Another difference here is, all environment variables pass to the system in the docker-compose.yml file instead of .env file
Initiate Session is used to create a session on the application, and the reference number is returned with a valid token for 60 minutes by default. After the token expires, it is necessary to create a new token to access the system.
{url}/internal/access/initiate/{user_name}/{tpp}/{tid}
url: should be pointing your application's domain name and port number.
user_name: can be preferred if the same tpp has multiple users. Otherwise, this may be set with a static value.
tpp: points the tpp name. An organization can manage more than one tpp and this needs to be set with the name of each specific tpp which makes request to the system.
tid: is the unique number to retrieve a new token and reference number from the application. Tt is combined with tpp to provide uniqueness on the table, so the same tid can be used by different tpps.
Example
curl -v localhost:8080/internal/access/initiate/MyUser/MyTpp/e12ed6e0-aec2- 489a-bee6-d24e4f2da3e0
{ "internal_access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MDk0Mjc3MDEsImlhdCI6MTYwOTQyNDEwMSwidGlkIjoiZTEyZWQ2ZTAtYWVjMi00ODlhLWJlZTYtZDI0ZTRmMmRhM2UwIiwidHBwSWQiOiJUcHBfMSJ9.1gGKp007QqcGA1ZMjogK1GL0koikqTfeRyFj57FmisU", "reference_id": "c5e1d69000758b4ab3a368c4b446488cf2d96905" }
The first thing users need to do to manage their accounts is to allow TPP for the respective accounts. For this, the TPP has to call the Create Permission service and show the next ASPSP web page to its user. Thus, the user can log in through the web page and complete the requested permissions.
Endpoint
{url}/{aspspId}/account-access-consents/reference/{reference}
url: should be pointing your application's domain name and port number.
aspspId: needs to be set with the aspspId which service will be called from.
reference: is an internal trackingId and should be unique for each consent request. Once consentId is created on the system, authorization flow will try to match with this ID after redirection.
Example
curl -d '{ "Data": { "Permissions": [ "ReadAccountsBasic" ], "ExpirationDateTime": "2022-12-31T21:35:00Z", "TransactionFromDateTime": "2018-06-13T19:39:00Z", "TransactionToDateTime": "2019-06-13T19:39:00Z" }, "Risk": {} }' -H 'Content-Type: application/json' -H 'Authorization: Bearer <internal_access_token>' http://localhost:8080/danske/account-access-consents/reference/6541561651516165
The url which is retrieved after the request needs to be handled by the TPP in a way. The url will open a web page for the user to give consent for their accounts to the TPP.
This service retrieves authenticated consents for the selected ASPSP. Then, the consent reference(consentTid) of the consent needs to be selected and passed for each API calls.
Endpoint
{url}/{aspspId}/internal/consent/active
url: should be pointing your application's domain name and port number.
aspspId: needs to be set with the aspspId which service will be called from.
Example
curl -v -H 'Authorization: Bearer <internal_access_token>' http://localhost:8080/danske/internal/consent/active
[{"consentTid":10,"aspspId":"danske"}]
ConsentId parameter will be sent as a parameter in Open Banking API calls.
This service returns the detail of selected consent from ASPSP directly.
Endpoint
{url}/{aspspId}/account-access-consents/{consentTid}
url: should be pointing your application's domain name and port number.
aspspId: needs to be set with the aspspId which service will be called from.
consentTid: needs to be set with a consentTid which is retrieved from Retrieve Active Consents.
Example
curl -v -H 'Authorization: Bearer <internal_access_token>' http://localhost:8080/danske/account-access-consents/10
"{Data":{"ConsentId":"urn:accounts:v3:d4c55300-8690-4521-8a53-8071dbc4b0a7","Status":"Authorised","CreationDateTime":"2021-01-01T11:34:45.265611+02:00","Permissions":["ReadAccountsBasic"],"ExpirationDateTime":"2021-01-05T23:35:00+02:00","TransactionFromDateTime":"2018-06-13T22:39:00+03:00","TransactionToDateTime":"2019-06-13T22:39:00+03:00","StatusUpdateDateTime":"2021-01-01T11:35:39.591842+02:00"},"Risk":{},"Links":{"Self":"https://sandbox-obp-api.danskebank.com/sandbox-open-banking/v3.1/aisp/account-access-consents/urn:accounts:v3:d4c55300-8690-4521-8a53-8071dbc4b0a7"},"Meta":{}}"
ConsentId needs to be sent as a parameter with each Open Banking API call.
This service returns the detail of attached accounts to the consent. If accountId isn't specified, all accounts will be appeared in th response.
Endpoint
{url}/{aspspId}/accounts/{accountId}/cid/{consentTid}
{url}/{aspspId}/accounts/cid/{consentTid}
url: should be pointing your application's domain name and port number.
aspspId: needs to be set with the aspspId which service will be called from.
cid: needs to be set with a consentTid which is retrieved from Retrieve Active Consents.
accountId: needs to be set with an accountId, if it is intended to retrieve a specific one.
Example
curl -v -H 'Authorization: Bearer <internal_access_token>' http://localhost:8080/danske/accounts/cid/10
{"Data":{"Account":[{"AccountId":"654f239a-5b8b-4f06-8aa6-8622d41d518b","Currency":"GBP","AccountType":"Personal","AccountSubType":"Savings","Nickname":"Sandbox Test Nickname","SwitchStatus":"UK.CASS.SwitchCompleted"},{"AccountId":"6c62c3dc-2763-4f70-9f4a-ffbc65dbcfaa","Currency":"GBP","AccountType":"Personal","AccountSubType":"Savings","Nickname":"Sandbox Test Nickname","SwitchStatus":"UK.CASS.SwitchCompleted"}]},"Links":{"Self":"https://sandbox-obp-api.danskebank.com/sandbox-open-banking/v3.1/aisp/accounts/"},"Meta":{}}
curl -v -H 'Authorization: Bearer <internal_access_token>' http://localhost:8080/danske/accounts/6c62c3dc-2763-4f70-9f4a-ffbc65dbcfaa/cid/10
{"Data":{"Account":[{"AccountId":"6c62c3dc-2763-4f70-9f4a-ffbc65dbcfaa","Currency":"GBP","AccountType":"Personal","AccountSubType":"Savings","Nickname":"Sandbox Test Nickname","SwitchStatus":"UK.CASS.NotSwitched"}]},"Links":{"Self":"https://sandbox-obp-api.danskebank.com/sandbox-open-banking/accounts/6c62c3dc-2763-4f70-9f4a-ffbc65dbcfaa/"},"Meta":{}}