Skip to content

Oauth access tokens management

Andrea Di Lisio edited this page Aug 29, 2023 · 4 revisions

This wiki entry is meant to give some more context on how Oauth tokens are actually managed by the library.

Default behavior

The main purpose of our library is to let users integrate easily with our APIs. As such, the library is designed so that you don't have to care about authenticating requests. All you have to do is configuring your client credentials and your signing options:

TrueLayerClient client = TrueLayerClient.New()
        .clientCredentials(
                ClientCredentials.builder()
                        .clientId("a-client-id")
                        .clientSecret("a-secret").build())
        .signingOptions(
                SigningOptions.builder()
                        .keyId("a-key-id")
                        .privateKey(Files.readAllBytes(Path.of("my-private-key.pem")))
                        .build())
        .build();

Oauth scopes

By default the library uses a very minimal set of scopes, which are specific to the features of the library that you're using. For instance, when using /payments or /merchant-accounts endpoints, the library uses a single payments scope, whereas when interacting with /mandates/* endpoints a recurring_payments:sweeping scope is used.

Using specific scopes naturally mitigates the risk of improper/undesired token reuse, but if caching is enabled it affects the number of token that the library caches, and you need to be aware of this if you have provided a custom implementation for the ICredentialsCache interface.

Client credentials token caching

To get up to speed with the caching capabilities offered by the library, see this page.

Starting from version 10.0.0 of the library, caching takes into account scopes as well, as the library might need to cache multiple tokens at the time (all related to the same client, but associated with different scopes).

This new way of caching is particularly relevant if you have a custom ICredentialsCache implementation: your cached tokens are different if the underlying used scopes are different, and your cache key retrieval mechanism needs to take this into account.

Customisations

The default library behaviour can be customised to some extent.

Custom caching

It's possible to specify a custom cache implementation, if the default in-memory cache does not really fit your use case.

Global Oauth scopes

You can override the default scopes used by the library by specifying custom global scopes:

TrueLayerClient.New()
      .clientCredentials(getClientCredentials())
      .signingOptions(TestUtils.getSigningOptions())
      .withGlobalScopes(RequestScopes.builder().scopes(CUSTOM_SCOPES).build())
      .build();

As of today, this feature helps when:

  • you want to interact with our APIs with different scopes: for instance you want to opt-in for Commercial VRP and use the recurring_payments:commercial scope when interacting with mandates endpoint.
  • you want to manage only one single cached access token (This requires custom caching to be enabled)

As the name of the feature suggests, these scopes are applied to all authenticated requests!