Documentation

Register your TPP with ForgeRock ASPSP

Last updated Nov 2, 2020

This article describes the steps required for registering a TPP (Third Party Provider) with ForgeRock ASPSP (Account Servicing Payment Service Providers). This registration process is commonly referred to as onboarding. By the end of this article, you will be able to create an account request or a payment request using your TPP credentials.


Introduction

In order to consume the REST API provided by banks, TPPs need to onboard with each bank; in the same way, they also need to onboard with ForgeRock ASPSP.

You can onboard with ForgeRock ASPSP as follows:

  1. Enrol with the Open Banking directory. See Open Banking Directory for further information.
  2. Create a Software Statement in the Open Banking directory that corresponds to your application.
  3. Generate a set of keys (signing and transport) and register them with the Open Banking directory.
  4. Download your Software Statement Assertion (SSA) from the Open Banking directory for your Software Statement.
  5. Generate the TPP registration request.
  6. Send the request to the TPP registration endpoint.

Steps 1 to 4 are outside the scope of this article. You should refer to the Open Banking documentation for information on completing these steps. However, this article does provide additional information on these concepts, which you may find helpful:

In ForgeRock's set of video tutorials, we go through this entire process for the sample code. You can watch this video to see an example of onboarding with the Open Banking directory.

Transport and signing keys

To use any ASPSP APIs, you need to use a transport certificate as your client certificate and a signing certificate to sign the JWS:

  • The transport certificate is used for MATLS; it is this certificate that authenticates you.
  • The signing certificate is reserved for signing JWS, similar to the request parameter or the client authentication JWT.

The Open Banking directory is a certificate authority, which means it will deliver your certificates, issued by their CA. At the end, you will see that your certificate has the Open Banking CA and issuer in its chain. For ForgeRock, it looks like this:

It is important to understand that Open Banking is just a CA and therefore won't generate the private key for you. The correct flow is:

  1. You generate a key and use this key to generate a CSR (Certificate Signing Request).
  2. The Open Banking CA signs your certificate and provides you with a PEM.
  3. You then use this PEM as a public key.

ForgeRock's sample project has an example for generating keys.

SSA example

The SSA is not a bearer token, which means you can share it. The following is an example SSA that ForgeRock use for their TPP:

eyJhbGciOiJSUzI1NiIsImtpZCI6IkVxYzBQSnlJVDEzS3NNQ3Z5aDJyQm9aeHlxWUhuM2J3MllkMlhFdF90R2MiLCJ0eXAiOiJKV1QifQ.eyJpYXQiOjE1MTY5MjEwMjUsImlzcyI6Ik9wZW5CYW5raW5nIEx0ZCIsImp0aSI6IjJVNXVGVEFRTlB5OTRhaGFJN0pQejUiLCJvYl9yZWdpc3RyeV90b3MiOiJodHRwczovL3JlZ2lzdHJ5Lm9wZW5iYW5raW5nLm9yZy51ay90b3MuaHRtbCIsIm9yZ19jb250YWN0cyI6W10sIm9yZ19jcmVhdGVkX2RhdGUiOm51bGwsIm9yZ19pZCI6InNPY1BYVmZNZ0VIR3Myd3B2QSIsIm9yZ19qd2tzX2VuZHBvaW50IjoiaHR0cHM6Ly9rZXlzdG9yZS5taXQub3BlbmJhbmtpbmcucWEvc09jUFhWZk1nRUhHczJ3cHZBL3NPY1BYVmZNZ0VIR3Myd3B2QS5qd2tzIiwib3JnX2p3a3NfcmV2b2tlZF9lbmRwb2ludCI6Imh0dHBzOi8va2V5c3RvcmUubWl0Lm9wZW5iYW5raW5nLnFhL3NPY1BYVmZNZ0VIR3Myd3B2QS9yZXZva2VkL3NPY1BYVmZNZ0VIR3Myd3B2QS5qd2tzIiwib3JnX2xhc3RfbW9kaWZpZWRfZGF0ZSI6bnVsbCwib3JnX25hbWUiOiJGb3JnZVJvY2sgQmFuayBUUFAgLSBBSVNQIGFuZCBQSVNQIiwib3JnX3N0YXR1cyI6IkFjdGl2ZSIsIm9yZ2FuaXNhdGlvbl9jb21wZXRlbnRfYXV0aG9yaXR5X2NsYWltcyI6eyJhdXRob3Jpc2F0aW9ucyI6W3sibWVtYmVyX3N0YXRlIjoiR0IiLCJyb2xlcyI6WyJBSVNQIiwiUElTUCJdfV0sImF1dGhvcml0eV9pZCI6IkZDQSIsInJlZ2lzdHJhdGlvbl9pZCI6IlJlZ0ZvcmdlUm9ja1BsQzAwMyIsInN0YXR1cyI6IkFjdGl2ZSJ9LCJzb2Z0d2FyZV9jbGllbnRfZGVzY3JpcHRpb24iOiJBIFRQUCBzYW1wbGUgZGV2ZWxvcGVkIGJ5IEZvcmdlUm9jayIsInNvZnR3YXJlX2NsaWVudF9pZCI6IjF4RmtSY2lxT0huQldqT1U5ejcyWDUiLCJzb2Z0d2FyZV9jbGllbnRfbmFtZSI6ImZvcmdlc2FtcGxlLXRwcCIsInNvZnR3YXJlX2NsaWVudF91cmkiOiJub3QgaW1wbGVtZW50ZWQiLCJzb2Z0d2FyZV9lbnZpcm9ubWVudCI6Im1pdCIsInNvZnR3YXJlX2lkIjoiMXhGa1JjaXFPSG5CV2pPVTl6NzJYNSIsInNvZnR3YXJlX2p3a3NfZW5kcG9pbnQiOiJodHRwczovL2tleXN0b3JlLm1pdC5vcGVuYmFua2luZy5xYS9zT2NQWFZmTWdFSEdzMndwdkEvMXhGa1JjaXFPSG5CV2pPVTl6NzJYNS5qd2tzIiwic29mdHdhcmVfandrc19yZXZva2VkX2VuZHBvaW50IjoiaHR0cHM6Ly9rZXlzdG9yZS5taXQub3BlbmJhbmtpbmcucWEvc09jUFhWZk1nRUhHczJ3cHZBL3Jldm9rZWQvMXhGa1JjaXFPSG5CV2pPVTl6NzJYNS5qd2tzIiwic29mdHdhcmVfbG9nb191cmkiOiJub3QgaW1wbGVtZW50ZWQiLCJzb2Z0d2FyZV9tb2RlIjoiVGVzdCIsInNvZnR3YXJlX29uX2JlaGFsZl9vZl9vcmciOiJzT2NQWFZmTWdFSEdzMndwdkEiLCJzb2Z0d2FyZV9wb2xpY3lfdXJpIjoiaHR0cHM6Ly9wb2xpY3kub2IuZm9yZ2Vyb2NrLmZpbmFuY2lhbCIsInNvZnR3YXJlX3JlZGlyZWN0X3VyaXMiOlsiaHR0cHM6Ly9nb29nbGUuZnIiLCJodHRwczovL3JlZGlyZWN0LnRwcC5zYW1wbGUub2IuZm9yZ2Vyb2NrLmZpbmFuY2lhbCJdLCJzb2Z0d2FyZV9yb2xlcyI6WyJQSVNQIiwiQUlTUCJdLCJzb2Z0d2FyZV90b3NfdXJpIjoiaHR0cHM6Ly90ZXJtcy5vYi5mb3JnZXJvY2suZmluYW5jaWFsIiwic29mdHdhcmVfdmVyc2lvbiI6MS4xfQ.ERq-jbdREsKk_mptTIdwqPqzG58azjkqypkPTOskd7ID_hJkUq8oG6N78JTAF5z8JGnmiGeYcACQ_Ekf65gGAmBHpmMLKxsIeCtXZYnknFwZF264pr7afN4_ovW69ivDQ240Ink9Sh1Eie9YQLwzTVsQ64JuLxQm4dB8BtZhDIMWNdYee7JyKAW_lzGGt6odrdJ1KrzwGwlVNl3dhbfJYigC2VIkk7MYmHbASwov0hnYthlff9oadOwiWJBi_h-u4RUi78Vf73LJueXk3NU8tc6oLylTfTszJv1KpEAMsvWL6SQ67J3DzQBwRJxoW50kifiPdmRw_Jwk86GQdFWzXw

The SSA contains all the information that banks need to know about your application. Since the SSA is essentially a JWT, you can decode it (for example, using https://jwt.davetonge.co.uk/).

This example SSA contains the following information when it is decoded; observe the claims "roles" as this indicates the FCA authorisations:

{ "iat": 1516921025, "iss": "OpenBanking Ltd", "jti": "2U5uFTAQNPy94ahaI7JPz5", "ob_registry_tos": "https://registry.openbanking.org.uk/tos.html", "org_contacts": [], "org_created_date": null, "org_id": "sOcPXVfMgEHGs2wpvA", "org_jwks_endpoint": "https://keystore.mit.openbanking.qa/sOcPXVfMgEHGs2wpvA/sOcPXVfMgEHGs2wpvA.jwks", "org_jwks_revoked_endpoint": "https://keystore.mit.openbanking.qa/sOcPXVfMgEHGs2wpvA/revoked/sOcPXVfMgEHGs2wpvA.jwks", "org_last_modified_date": null, "org_name": "ForgeRock Bank TPP - AISP and PISP", "org_status": "Active", "organisation_competent_authority_claims": { "authorisations": [ { "member_state": "GB", "roles": [ "AISP", "PISP" ] } ], "authority_id": "FCA", "registration_id": "RegForgeRockPlC003", "status": "Active" }, "software_client_description": "A TPP sample developed by ForgeRock", "software_client_id": "1xFkRciqOHnBWjOU9z72X5", "software_client_name": "forgesample-tpp", "software_client_uri": "not implemented", "software_environment": "mit", "software_id": "1xFkRciqOHnBWjOU9z72X5", "software_jwks_endpoint": "https://keystore.mit.openbanking.qa/sOcPXVfMgEHGs2wpvA/1xFkRciqOHnBWjOU9z72X5.jwks", "software_jwks_revoked_endpoint": "https://keystore.mit.openbanking.qa/sOcPXVfMgEHGs2wpvA/revoked/1xFkRciqOHnBWjOU9z72X5.jwks", "software_logo_uri": "not implemented", "software_mode": "Test", "software_on_behalf_of_org": "sOcPXVfMgEHGs2wpvA", "software_policy_uri": "https://policy.ob.forgerock.financial", "software_redirect_uris": [ "https://google.fr", "https://redirect.tpp.sample.ob.forgerock.financial" ], "software_roles": [ "PISP", "AISP" ], "software_tos_uri": "https://terms.ob.forgerock.financial", "software_version": 1.1 }

Generate the TPP registration request

As a TPP who wants to onboard, you must generate a TPP registration request JWT. This request will contain the SSA and other claims; the claims required will depend on your needs and configuration. If you require assistance with generating the request JWT, you should refer to the JWT standard and other online resources; you can also use JWT verifiers such as https://jwt.davetonge.co.uk/ to help you debug.

Note

You can find an example in ForgeRock's sample project or use the Register TPP to ASPSP request in the Postman collection, which triggers the code behind this example. Please see the readme in the sample project for more details.

Here is an example of the claims used in the TPP registration request in the sample project:

{ "token_endpoint_auth_signing_alg": "RS256", "request_object_encryption_alg": "RSA-OAEP-256", "grant_types": [ "authorization_code", "refresh_token", "client_credentials" ], "subject_type": "public", "application_type": "web", "iss": "1xFkRciqOHnBWjOU9z72X5", "redirect_uris": [ "https://google.fr" ], "token_endpoint_auth_method": "private_key_jwt", "aud": "https://as.aspsp.ob.forgerock.financial/oauth2/openbanking", "software_statement": "eyJhbGciOiJSUzI1NiIsImtpZCI6IkVxYzBQSnlJVDEzS3NNQ3Z5aDJyQm9aeHlxWUhuM2J3MllkMlhFdF90R2MiLCJ0eXAiOiJKV1QifQ.eyJpYXQiOjE1MTY5MjEwMjUsImlzcyI6Ik9wZW5CYW5raW5nIEx0ZCIsImp0aSI6IjJVNXVGVEFRTlB5OTRhaGFJN0pQejUiLCJvYl9yZWdpc3RyeV90b3MiOiJodHRwczovL3JlZ2lzdHJ5Lm9wZW5iYW5raW5nLm9yZy51ay90b3MuaHRtbCIsIm9yZ19jb250YWN0cyI6W10sIm9yZ19jcmVhdGVkX2RhdGUiOm51bGwsIm9yZ19pZCI6InNPY1BYVmZNZ0VIR3Myd3B2QSIsIm9yZ19qd2tzX2VuZHBvaW50IjoiaHR0cHM6Ly9rZXlzdG9yZS5taXQub3BlbmJhbmtpbmcucWEvc09jUFhWZk1nRUhHczJ3cHZBL3NPY1BYVmZNZ0VIR3Myd3B2QS5qd2tzIiwib3JnX2p3a3NfcmV2b2tlZF9lbmRwb2ludCI6Imh0dHBzOi8va2V5c3RvcmUubWl0Lm9wZW5iYW5raW5nLnFhL3NPY1BYVmZNZ0VIR3Myd3B2QS9yZXZva2VkL3NPY1BYVmZNZ0VIR3Myd3B2QS5qd2tzIiwib3JnX2xhc3RfbW9kaWZpZWRfZGF0ZSI6bnVsbCwib3JnX25hbWUiOiJGb3JnZVJvY2sgQmFuayBUUFAgLSBBSVNQIGFuZCBQSVNQIiwib3JnX3N0YXR1cyI6IkFjdGl2ZSIsIm9yZ2FuaXNhdGlvbl9jb21wZXRlbnRfYXV0aG9yaXR5X2NsYWltcyI6eyJhdXRob3Jpc2F0aW9ucyI6W3sibWVtYmVyX3N0YXRlIjoiR0IiLCJyb2xlcyI6WyJBSVNQIiwiUElTUCJdfV0sImF1dGhvcml0eV9pZCI6IkZDQSIsInJlZ2lzdHJhdGlvbl9pZCI6IlJlZ0ZvcmdlUm9ja1BsQzAwMyIsInN0YXR1cyI6IkFjdGl2ZSJ9LCJzb2Z0d2FyZV9jbGllbnRfZGVzY3JpcHRpb24iOiJBIFRQUCBzYW1wbGUgZGV2ZWxvcGVkIGJ5IEZvcmdlUm9jayIsInNvZnR3YXJlX2NsaWVudF9pZCI6IjF4RmtSY2lxT0huQldqT1U5ejcyWDUiLCJzb2Z0d2FyZV9jbGllbnRfbmFtZSI6ImZvcmdlc2FtcGxlLXRwcCIsInNvZnR3YXJlX2NsaWVudF91cmkiOiJub3QgaW1wbGVtZW50ZWQiLCJzb2Z0d2FyZV9lbnZpcm9ubWVudCI6Im1pdCIsInNvZnR3YXJlX2lkIjoiMXhGa1JjaXFPSG5CV2pPVTl6NzJYNSIsInNvZnR3YXJlX2p3a3NfZW5kcG9pbnQiOiJodHRwczovL2tleXN0b3JlLm1pdC5vcGVuYmFua2luZy5xYS9zT2NQWFZmTWdFSEdzMndwdkEvMXhGa1JjaXFPSG5CV2pPVTl6NzJYNS5qd2tzIiwic29mdHdhcmVfandrc19yZXZva2VkX2VuZHBvaW50IjoiaHR0cHM6Ly9rZXlzdG9yZS5taXQub3BlbmJhbmtpbmcucWEvc09jUFhWZk1nRUhHczJ3cHZBL3Jldm9rZWQvMXhGa1JjaXFPSG5CV2pPVTl6NzJYNS5qd2tzIiwic29mdHdhcmVfbG9nb191cmkiOiJub3QgaW1wbGVtZW50ZWQiLCJzb2Z0d2FyZV9tb2RlIjoiVGVzdCIsInNvZnR3YXJlX29uX2JlaGFsZl9vZl9vcmciOiJzT2NQWFZmTWdFSEdzMndwdkEiLCJzb2Z0d2FyZV9wb2xpY3lfdXJpIjoiaHR0cHM6Ly9wb2xpY3kub2IuZm9yZ2Vyb2NrLmZpbmFuY2lhbCIsInNvZnR3YXJlX3JlZGlyZWN0X3VyaXMiOlsiaHR0cHM6Ly9nb29nbGUuZnIiLCJodHRwczovL3JlZGlyZWN0LnRwcC5zYW1wbGUub2IuZm9yZ2Vyb2NrLmZpbmFuY2lhbCJdLCJzb2Z0d2FyZV9yb2xlcyI6WyJQSVNQIiwiQUlTUCJdLCJzb2Z0d2FyZV90b3NfdXJpIjoiaHR0cHM6Ly90ZXJtcy5vYi5mb3JnZXJvY2suZmluYW5jaWFsIiwic29mdHdhcmVfdmVyc2lvbiI6MS4xfQ.ERq-jbdREsKk_mptTIdwqPqzG58azjkqypkPTOskd7ID_hJkUq8oG6N78JTAF5z8JGnmiGeYcACQ_Ekf65gGAmBHpmMLKxsIeCtXZYnknFwZF264pr7afN4_ovW69ivDQ240Ink9Sh1Eie9YQLwzTVsQ64JuLxQm4dB8BtZhDIMWNdYee7JyKAW_lzGGt6odrdJ1KrzwGwlVNl3dhbfJYigC2VIkk7MYmHbASwov0hnYthlff9oadOwiWJBi_h-u4RUi78Vf73LJueXk3NU8tc6oLylTfTszJv1KpEAMsvWL6SQ67J3DzQBwRJxoW50kifiPdmRw_Jwk86GQdFWzXw", "scopes": [ "openid", "accounts", "payments" ], "request_object_signing_alg": "RS256", "exp": 1517564371, "request_object_encryption_enc": "A128CBC-HS256", "iat": 1516959572, "jti": "6f5b5557-e3d1-4f57-bead-42fcb6ee394a", "response_types": [ "code", "token", "code id_token" ], "id_token_signed_response_alg": "ES256" }

The fields in this JWT are the one described in the OIDC dynamic client registration standard. However, this table provides some specific recommendations for some of these fields:

Field Name Recommendation

iss

The issuer must be your software ID. This is important as we verify it matches the SSA software ID claim.

token_endpoint_auth_method

We recommend using the private_key_jwt method as a secure way to authenticate your TPP.
aud

The audience must match the AS issuer ID. ForgeRock's issuer ID is:

https://as.aspsp.ob.forgerock.financial/oauth2/openbanking

You can find the AS issuer ID for any bank by reading the well-known endpoint of the AS. ForgeRock's endpoint is: https://as.aspsp.ob.forgerock.financial/oauth2/.well-known/openid-configuration 

scopes

The scopes will depend on your role from the FCA (AISP and/or PISP):

  • AISP: openid and accounts
  • PISP: openid and payments
  • AISP and PISP: openid, accounts and payments

request_object_signing_alg

Use RSA; the Open Banking directory only allows use of the Elliptic Curve Digital Signature Algorithm (ECDSA).

Send the request to the TPP registration endpoint

Once you have generated your registration request JWT, you just need to send it to the registration endpoint as follows:

$ curl -X POST \ 'https://rs.aspsp.ob.forgerock.financial:443/open-banking/v1.1/registerTPP' \ -H 'Content-Type: application/jwt' \ -d YOUR_REGISTRATION_REQUEST_JWT

replacing YOUR_REGISTRATION_REQUEST_JWT with the request JWT you generated in the previous section.

Note

This endpoint is protected by MATLS. You therefore need to send your client certificate, which is your transport certificate. If you have difficulty configuring your TPP to use the transport certificate, you should refer to the Test your MATLS setup article for debug advice.

The response you get from this registration is exactly the same as the one described by the OIDC dynamic registration. Please verify the response and the values set up for your TPP as the AS is allowed to override values you have sent.

Conclusion

You should now have successfully onboarded your TPP with the ForgeRock ASPSP and received a client ID; you will need this client ID for future interactions with the ASPSP.

You can now Test your MATLS setup.


Copyright and Trademarks Copyright © 2020 ForgeRock, all rights reserved.