Sorry, you need to enable JavaScript to visit this website.

Using OAuth 2.0 to Access Rabobank APIs

Some of Rabobank’s APIs use OAuth 2.0. OAuth 2.0 enables your application to communicate with the Rabobank APIs, on behalf of a user, in a way that keeps their usernames, passwords, and other information private.

In this document

In this document, we describe:

The Rabobank APIs that require OAuth 2.0

If an API requires OAuth 2.0, this will be stated in the API reference documentation. For example:

Note: The Consent Details Service API provides Third Party Providers (TPPs) with information on the consents that they have been granted by end users. It also allows TPPs to revoke the consent.

How to use the Rabobank APIs that require OAuth 2.0

Before you can use the Rabobank APIs that require OAuth 2.0, you must:

  1. Create an application in the Rabobank Developer Portal.
  2. Configure the OAuth 2.0 redirect URI for your application.
    (See: "Step 1.c. Rabobank redirects the user agent to the application")
    Subscribe your application to the OAuth 2.0 services API. For more information, see “ Subscribing your application to the OAuth 2.0 Services API” below.
  3. Subscribe your application to the API you want to use.
  4. Check the requirements of the API you want to use.

About the OAuth 2.0 services API

To access the Rabobank APIs that use OAuth 2.0, your application will need to use Rabobank’s OAuth 2.0 services API. This API provides the services needed to obtain tokens for OAuth 2.0 secured APIs.

Endpoint:

https://oauth.rabobank.nl/openapi/oauth2

Subscribing your application to the OAuth 2.0 Services API

To subscribe your application to the OAuth 2.0 Services API, follow these steps:

  1. Click API-Documentation.
  2. Click Subscribe App in the OAuth 2.0 Services tile.
  3. Click Subscribe.
  4. Select the Application you want to sign up.
  5. Click Subscribe.

An overview of the OAuth 2.0 Authorization Code Flow

Any applications you develop for any APIs that require OAuth 2.0 must use the OAuth 2.0 Authorization Code Flow. This flow enables your applications to get access to resources, with the user’s approval.

The OAuth 2.0 Authorization Code Flow works in this way:

  1. Your application identifies the permissions (these are known as “scopes”) it needs.
  2. Your application requests permission from the user for these scopes. It does this by redirecting the user to Rabobank, together with the scopes it wants the user to approve.
  3. A dialog window appears, asking the user to give their consent to your application accessing their information.
  4. The user decides whether to grant the permissions to your application. They use the relevant buttons in the dialog window to approve (or not) the request.
     
    If user approves the authorization request:
     
  5. Rabobank’s OAuth 2.0 services API will redirect the user to your application, together with an authorization code.
  6. Your application uses this authorization code to request an access token from one of Rabobank’s APIs.
  7. The Rabobank API sends your application an access token and a refresh token.
  8. Your application includes the access token in its API request for data from a resource in the Rabobank API.
  9. The Rabobank API sends a response to your application.

A detailed description of the OAuth 2.0 Authorization Code Flow

Figure 1: Rabobank OAuth 2.0 Authorization Code flow

 

Step 1. Obtain Authorization

The first step is creating and sending the authorization request. Your application requests authorization from the resource owner to access (some of) their private information.

This involves redirecting the user to Rabobank, where they can approve the authorization requested by your application. The user is then redirected back to your application with a code that can be used in the next step.

Using the state parameter

You can use the The state parameter to maintain state during the authorization code flow and to prevent Cross Site Request Forgery (CSRF) attacks.

 
Use a non-guessable value to prevent malicious users from being able to manipulate the state parameter.

Step 1a. Request Authorization Code

Your application redirects the user to /oauth2/authorize?response_type=code&scope=SCOPES&client_id=CLIENT_ID&state=SOME_IDENTIFIER

The request contains the:

  • Parameters that identify your application.
  • Permissions the user will be asked to grant to your application.
URI Parameter Required? Example Description
response_type* Yes response_type=code

This indicates the authorization grant flow.

Value = code. Other response types are currently not supported.

scope Yes scope="ais.transactions.read-90days ais.transactions.read-history”

Scopes represent permissions to resources which your application requests from the user. Your application can request multiple scopes using a space separated list.

A space separated list of scopes.

client_id* Yes ab588acc-2ac4-446c-abdd-06c2ea8b097a

This ID uniquely identifies your registered application.

The client_id is registered at Rabobank Developer Portal.

state No ABC123def567

An opaque value to maintain state between while the user is being redirected back and forth between the application and Rabobank.

The parameter should be used to prevent CSRF attacks.

redirect_uri No your.redirect.url Required only if the redirect_uri parameter was included in the authorization request /oauth2/authorize; their values MUST be identical.

 

Redirect the user to their preferred browser in which they can confirm that they are communicating with the genuine Rabobank website. Do NOT embed Rabobank's authorization page in your application in any way!

Step 1.b. Login and consent

The user (resource owner) decides whether to grant your application access to the data is has requested.

Rabobank displays:

  • A consent window showing the name of your application
  • The Rabobank API services that your application is requesting permission to access by using the user's authorization credentials
  • A summary of the scopes of access to be granted.

The user can decide to:

  • Grant authorization to your application for one or more scopes requested by your application.
  • Refuse the request.

If the user grants authorization to your application, this is done via the user agent (their web browser).

Your application doesn't need to do anything at this stage. It waits for the response from Rabobank’s OAuth 2.0 server indicating whether any access was granted.

Step 1.c. Rabobank redirects the user agent to the application

The Rabobank OAuth 2.0 server redirects the user agent back to your application. It uses the URL you entered on the “Edit application” screen in the settings of your application.

Step 1.d. Your application receives the autorization Code

If the user approved the access request, then the response from the Rabobank OAuth 2.0 server to your application's URL contains an authorization code and the state parameter:

https://your.redirect.url?code=AUTHORIZATION_CODE&state=SOME_IDENTIFIER

If the user does not approve the request

If the user does not approve the request, then the response from the Rabobank OAuth 2.0 server to your application's URL contains an error message ‘access_denied’:

https://your.redirect.url?error=access_denied

If the user cancels before authorizing your application

If the user cancels before authorizing your application, then the response from the Rabobank OAuth 2.0 server to your application's URL contains an error message ‘access_denied’:

https://your.redirect.url?error=access_denied

Step 2. Obtain an Access Token

After your application's server receives the authorization code (in Step 1.d), it can exchange it for an access token.

This is a request from your application's server directly to the Rabobank server. The user (agent) doesn't need to do anything at this stage.

Step 2.a. Request the tokens

Your application requests an access token in exchange for the authorization code by making a POST request to the /oauth2/token endpoint:

POST /oauth2/token
Headers:
    Content-Type: application/x-www-form-urlencoded
    Authorization: Basic BASE64(CLIENT_ID + ":" + CLIENT_SECRET)

Body (x-www-form-urlencoded):
    grant_type: authorization_code
    code: AUTHORIZATION_CODE

This request uses Basic authentication with your application's Client ID as username and Client Secret as password.

For example:

With

client id ab588acc-2ac4-446c-abdd-06c2ea8b097a 
client secret J6aA1fL8vJ6xV0iI5bX4nR4nA8pK7dG3cI0jK5mR6rN2qQ3pP0

you would get the following Authorization header:

Authorization: Basic YWI1ODhhY2MtMmFjNC00NDZjLWFiZGQtMDZjMmVhOGIwOTdhOko2YUExZkw4dko2eFYwaUk1Ylg0blI0bkE4cEs3ZEczY0kwaks1bVI2ck4ycVEzcFAw
 
The client secret should be stored securely and should only be used server side.
Parameter Example Description
grant_type authorization_code This states the methods an application can use to obtain an access token.There are several types of grants, which allow different types of access
code 2aks1bVI2ck4ycVEzcFAwYUExZkw4dko2eFYwaUk1Ylg0blI0bkE 4cEs3ZEczY0kwYWI1OD hhY2MtMmFjNC00NDZjLWFiZGQtMDZ jMmVhOGIwOTdhOko The AUTHORIZATION_CODE your application received in the previous step

Step 2.b. Receive Tokens

The response contains the access token, the refresh token, their expiration times in seconds and the timestamp when consent was given.

{
    "token_type": "bearer",
    "access_token": ACCESS_TOKEN,
    "expires_in": 3600,
    "consented_on": 1507267950,
    "metadata": "a:consentId 123a1a2a-888c-4015-8099-f88b080d0bbb",
    "scope": SCOPES,
    "refresh_token": REFRESH_TOKEN,
    "refresh_token_expires_in": 2592000
}

About the length of the access and refresh tokens

The lengths of the access token and the refresh token are not fixed, so you should not limit their size in your storage.

Step 3. Access the resource

In requests to Rabobank APIs secured with OAuth 2.0, you must add the access token in the Authorization header:

Authorization: Bearer ACCESS_TOKEN

If the token has expired or the consent has been revoked

If the token has expired or the consent has been revoked, your application will receive a response with the 401 Unauthorized status.

An overview of the Access Token Refresh Flow

Figure 2: Rabobank OAuth 2.0 Refresh Token flow

When your access token has expired, your application can use the refresh token to obtain a new access token if:

  • The user's consent is still active, and
  • The refresh token has not expired.
POST /oauth2/token
Headers:
    Content-Type: application/x-www-form-urlencoded
    Authorization: Basic BASE64(CLIENT_ID + ":" + CLIENT_SECRET)

Body (x-www-form-urlencoded):
    grant_type: refresh_token
    refresh_token: REFRESH_TOKEN

This works in the same way as before only now your application exchanges the refresh token for a new set of tokens.

Parameter Example Description
grant_type refresh_token This states the methods an application can use to obtain an access token. There are several types of grants, which allow different types of access.
refresh_token tGzv3JOkF0XG5Qx2TlKWIA The REFRESH_TOKEN that your application received with the previous set of tokens.

The response is the same as before. Your application can now use the new access token to make requests to the Rabobank APIs.

An overview of OAuth 2.0 concepts

This section describes the main OAuth 2.0 concepts, and how you must use them when implementing OAuth 2.0 for Rabobank APIs.

About the scopes

Here is a typical Use Case:

  • A user wants to use your application for creating payment requests, but they don’t want to share their account balance with it.

Scopes enable:

  • Your application to only request access to the API resources that it needs.
  • Users to control the amount of access they grant to your application.

This means your application must define one or more scopes when it requests authorization from a user.

About consent

When a user approves the authorization requested by your application, their consent is valid for a specific number of days.

The user can choose to revoke their consent (to your application having access to the Rabobank banking environment) at any time. If they do this, it voids the access token and the refresh token.

If the consent has been revoked or has expired, your application will receive a response with status 403 Forbidden. The only way to gain access again is by requesting authorization from the user.

You can use the Consent Details Service API to see the status of the consent and verify whether it has been revoked.

About the authorization Code

The authorization code is short-lived and can only be used once. Your application should use it immediately after receiving it. It does not need to remember the code afterwards.

About the access Token

The access token is short-lived. When the access token is expired, you can obtain a new one by using the refresh token.

Your application must include the access token in any API request that requires authorization from the user.

 
Access tokens should be stored securely and should only be used on the server side. If your application doesn't require constant access we recommend never storing the access token.

About the refresh Token

Your application can use the refresh token to obtain a new access token if:

  • The user's consent has not been revoked, and
  • The refresh token has not expired.

The refresh token is long-lived, but it can only be used once.

When your application obtains a new access token, it will also get a new refresh token.

Because the expiry time for access tokens is known, your application can predict when it needs to refresh a token.

Preventing your application from making unsuccessful requests

Most Rabobank APIs have a rate limit. We recommend your application refreshes the token before it expires, in order to prevent your application from making unsuccessful requests.

 
Refresh Tokens should be stored securely and should only be used on the server side.

About the expiration times

You will receive information about the expiration of the access token and refresh token in the token request response. When you are designing any business logic into your application that relates to refreshing the token, we recommend you always use the expiration times of the access token and the refresh token that is included in the token response.

The table below describes other limitations:

Tokens Expiration Times
Consent Depends on the requested scope
authorization code 5 minutes
refresh limit 4096 times

More information on OAuth 2.0

For more information on OAuth 2.0, see:

Troubleshooting common OAuth 2.0 related problems

See OAuth2 error and troubleshooting guide for information on common problems and solutions relating to connecting to the Rabobank OAuth 2.0 flow.

Security Considerations

The client secret, access tokens, refresh tokens and data that you have retrieved from Rabobank APIs are sensitive. They need to be handled carefully. Follow the recommendations below.

Keep tokens and client secret server side

The client secret of your application, the access tokens and the refresh tokens should never be sent out to the user (or be available in the front-end).

Any traffic that sends one of these items should be server to server communication.

Use HTTPS

OAuth 2.0 removed transport considerations from the protocol. Instead, it relies on you to handle the transport of codes and tokens. This means, in practical terms, that HTTPS is required to prevent hacking of tokens.

Type of Communication Requirement
Server – server communication When connecting your servers to the Rabobank’s API server the use of HTTPS is required. Furthermore always check the validity of our Rabobank HTTPS certificate.
Client – server communication When your client connects to your server:
  • make use of HTTPS to prevent hacking e.g. via a rogue wifi access point. Furthermore always check the certificate during the HTTPS handshake. It has to be your certificate and it has to be valid. This is also known as certificate pinning.
  • make use of HTTP Strict Transport Security (HSTS). This ensures that the client always uses HTTPS to the specified domain.

Redirect to the preferred browser of the user

The authorization page in Step 1 of the Authorization Code Flow must be opened in user's preferred browser. Rabobank users can only confirm they are authenticating with the genuine Rabobank site if they have the tools provided by their browser, such as the URL bar and Transport Layer Security (TLS) certificate information. For native applications, this means our authorization page must open in the default browser. Native applications can use custom URL schemes as redirect URIs to redirect the user back from the browser to the application requesting permission.

Redirecting authorization in native applications

For native applications, our authorization page must open in the default browser. Rabobank users can only confirm they are authenticating with the genuine Rabobank site if they have the tools provided by their browser, such as the URL bar and Transport Layer Security (TLS) certificate information.

Native applications can use custom URL schemes as redirect URIs, in order to redirect the user back from the browser to the application that is requesting permission.

 
Any attempt to embed Rabobank’s authorization page will result in your application being (permanently) banned from using Rabobank APIs.

Use Stable OAuth 2.0 Client Libraries

We recommend you use stable libraries for performing the OAuth 2.0 process, instead of implementing your own.

If we suspect that your application has been compromised or detect suspicious activity, your application could be (permanently) banned from using Rabobank APIs.

Keep your application and its environment secure

Your application should be protected against cross site scripting, SQL injection and other OWASP top 10 vulnerabilities. This is to prevent the leakage of sensitive information.

We recommend you do security tests on your application and its environment at regular intervals and with every major change.

Storing sensitive information

Make sure that only your application is capable of saving any sensitive information. We recommend you encrypt any sensitive data, and you limit the authorization of any storage devices.