Documentation

Client credential flow

Last updated Nov 2, 2020

This article describes how to get an access token through the client credential flow. This flow is part of the security flow.


Introduction

Explaining the client credential flow is outside the scope of this article. Instead, this article gives you an overview of what the client credential looks like to help you understand it. You can see an example of a client credential in the ForgeRock sample project.

You should also familiarize yourself with this flow by reviewing the standards section on the Client authentication flow.

Client credential flow

There are two types of client credential flows you can use with ForgeRock ASPSP:

  • Client authentication JWT - this is recommended by the standard.
  • Client secret post or basic - this is NOT recommended by the standard.

Client authentication JWT (recommended by the standard)

You should generate a Client Authentication JWT per the standard.

The following example shows what this JWT looks like in our sample code:

{ "kid": "8h_w0rFrMqyJnNy2aQT1BDk8jeU", "alg": "RS256" } . { "sub": "31b155b7-5a5f-4e28-986b-74d3d623055f", "aud": "https://as.aspsp.dev-ob.forgerock.financial:8443/oauth2/openbanking", "iss": "31b155b7-5a5f-4e28-986b-74d3d623055f", "exp": 1516965840, "iat": 1516965241, "jti": "998634f0-b67d-473c-9d43-3a6d149b7bcb" }

The following table describes the key fields included in this JWT:

Claim name Description
kid The key ID must match the signing kid provided by the Open Banking directory. The ForgeRock AS reads our JWK_URIs and looks for the JWK that corresponds to this kid. Therefore, it is essential that this kid matches the correct JWK, which is why you must specify the kid of the signing key here.
alg The algorithm used for signing this JWT. Currently, only RSA can be used.
sub The subject must be your client ID. The inclusion of the subject is what make this JWT a credential. The JWT becomes your identity because you sign a JWT that has a subject equal to your client ID; therefore, you must never share this JWT on a public channel.
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 

iss The issuer must be your client ID. This JWT is a credential JWT because the issuer matches the subject.
exp The expiration time. After this time, this JWT won't be considered a valid credential. For security reasons, we recommend you set a short period of life, such as 1 or 2 minutes.

Here is an example of the Postman request (as a curl command) that we used for testing the client authentication JWT flow:

$ curl -X POST \ https://as.aspsp.ob.forgerock.financial/oauth2/realms/root/realms/openbanking/access_token \ -H 'Cache-Control: no-cache' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'grant_type=client_credentials&scope=openid%20accounts%20payments&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion=eyJraWQiOiI1YWNkYWZmYy0yMmU1LTRiYzItODA4OC1kY2EzZTkyMTBkYWYiLCJhbGciOiJFUzI1NiJ9.eyJzdWIiOiI1YjhjY2E4NS0xODcwLTQ1MzYtYTAxNi00ZjI2YmJlYWU3NDIiLCJhdWQiOiJodHRwczpcL1wvYXMuYXNwc3AuaW50ZWctb2IuZm9yZ2Vyb2NrLmZpbmFuY2lhbFwvb2F1dGgyXC9vcGVuYmFua2luZyIsImlzcyI6IjViOGNjYTg1LTE4NzAtNDUzNi1hMDE2LTRmMjZiYmVhZTc0MiIsImV4cCI6MTUxMzc3NjI2Mn0.OkDkz9s9zPhw_sFXzDdmBXd7NpmWLpk-B6oI8RtkRG33-lh2LzctnQtR-E2tPsvhFfp3h700VrLKhevFI3QJNw'
Note

The scope value depends on your TPP type. For an AISP, the scope must be "openid accounts" and for a PISP, it must be "openid payments". If you are both an AISP and PISP, it must be "openid accounts payments"; you would use the same JWT for both the AISP and PISP flow.

Client secret post or basic (NOT recommended by the standard):

When you onboard with the ASPSP, you will receive a client secret. You can choose to use this to authenticate and get an access token. You will find more information about the Access Token Request in the standard.

The AS will return an access token in the response that you can use to create an account request with the ASPSP-RS.

Conclusion

After completing this flow, you will have an access token that allows you to create an account or payment setup request:

It is important to understand that an access token is a bearer token for a specific set of scopes; in other words, an access token is for a specific usage. This access token is designed for account or payment setup requests only; you cannot use it for other purposes such as consuming the accounts API.


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