Using OAuth 2.0 to Access Rabobank APIs

OAuth 2.0 enables your application to communicate with the Rabobank APIs on behalf of a user without handling the user's password.

Your application can only obtain access with input from the user through the Authorization Code Grant flow [RFC 6749 section 4.1]. Initially your application can request permission from the user for specific scopes. When the user approves the authorization requested by your application, an authorization code will be sent to your application. This code can in turn be used to obtain an access token. Once your application has an access token it can use it to access the resource it asked permission for. The access token can be used and refreshed without user interaction until the user's consent expires or has been revoked by the user.

Requirements
OAuth 2.0 and consent
OAuth 2.0 Authorization Code Flow
Access Token Refresh Flow
Security Considerations

Requirements

Before you can use Rabobank APIs with OAuth 2.0 you need to:

Create an application in the Rabobank Developer Portal.
Configure the OAuth 2.0 redirect URI for your application.
Subscribe your application to the OAuth 2.0 services.
Subscribe your application to the API you want to use.
Check the requirements of the API you want to use.

Please read about the concepts below to understand what they are and how you need to use them when implementing OAuth 2.0 for Rabobank APIs.

Scope

While users may want to use your application for creating payment requests, they may not want to share their account balance with it. Scopes enable users to choose what authorization they want to grant to an application. Therefore your application must define one or more scopes when requesting authorization from the users.

Consent

When a user approves the authorization requested by your application their consent is usually valid for 90 days. At any given moment the user can choose to revoke their consent which voids the access token and refresh token. So even when a token has not expired, your application will receive a response with status 401 Unauthorized if the consent has been revoked or has expired. The only way to gain access again is by requesting authorization from the user.

Authorization Code

After a user has given consent she will be redirected to your application with a code that can be used to obtain an access token. The authorization code is very short-lived (5 minutes) and can only be used once. Your application should use it immediately after receiving it and does not need to remember it afterwards. Your application receives an access token as well as a refresh token in return for the authorization code.

Access Token

The access token is short-lived and can be used as many times as required until it expires. Your application needs to include the access token in any API request that requires authorization from the user. When the access token is expired you can obtain a new one with the refresh token.

Refresh Token

If the user's consent has not been revoked and has not expired, your application can obtain a new access token with the refresh token. The refresh token is long-lived, but 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. Keep in mind that most Rabobank APIs have a rate limit, so it would be beneficial to refresh the token before it expires and prevent unsuccessful requests. The number of times you can renew your authorization with a refresh token is also limited, please refer to the table below for more information.

Expiration times

You can use the table below in combination with the use case for your application to decide whether or not it makes sense to store the tokens.

consent	Depends on the requested scope
authorization code	5 minutes
access token	1 hour
refresh token	5 years
refresh limit	4096 times

OAuth 2.0 Authorization Code Flow

rabo_oauth_authorization_flow.png

Figure 1: Rabobank OAuth 2.0 Authorization Code flow

1. Obtain Authorization

The first step in the OAuth flow is to request authorization from the resource owner to access (some of) their private resources. This involves redirecting the user to the Rabobank, where she 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. The state parameter can be used to maintain state during the authorization code flow and to prevent CSRF attacks.

a. Request Authorization Code

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

URI Parameter	Description
response_type*	Value = code. This indicates the authorization grant flow. Other response types are currently not supported.
scope*	A space separated list of scopes. Scopes represent permissions to resources which your application requests from the user. Your application can request multiple scopes using a space separated list.
client_id*	This ID uniquely identifies your registered application. The client_id is registered at Rabobank Developer Portal.
state	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.

* required

1.b. Authorization grant

The user (resource owner) authenticates at Rabobank and grants authorization to your application for the requested scopes via the user-agent (browser).

1.c. Redirect to application

Rabobank redirects the user agent back to your application. It uses the URL you provided in the settings of your application.

1.d. Receive Autorization Code

When the user-agent is being redirected to your application's URL it contains the authorization code and the state parameter:

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

In case the user cancels before authorizing your application, Rabobank will redirect the user to the plain URL:

https://your.redirect.url/

2. Obtain Access Token

The authorization code received in 1.d can be exchanged for an access token. This is a request from your application's server straight to the Rabobank server, no user (agent) interaction is required here.

2.a. Request Tokens

Your application requests an access token in exchange for the authorization code by executing a POST request:

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 and client secret J6aA1fL8vJ6xV0iI5bX4nR4nA8pK7dG3cI0jK5mR6rN2qQ3pP0 you would get the following Authorization header:

Authorization: Basic YWI1ODhhY2MtMmFjNC00NDZjLWFiZGQtMDZjMmVhOGIwOTdhOko2YUExZkw4dko2eFYwaUk1Ylg0blI0bkE4cEs3ZEczY0kwaks1bVI2ck4ycVEzcFAw

parameter	description
grant_type	authorization_code
code	The `AUTHORIZATION_CODE` your application received in the previous 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,
    "scope": SCOPES,
    "refresh_token": REFRESH_TOKEN,
    "refresh_token_expires_in": 157784760
}

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

3. Access Resource

In requests to Rabobank APIs secured with OAuth 2.0 you need to add the access token in the Authorization header: Authorization: Bearer ACCESS_TOKEN

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

Access Token Refresh Flow

rabo_oauth_refresh_flow.png

Figure 2: Rabobank OAuth 2.0 Refresh Token flow

When your access token has expired but the consent is still active, your application can use the refresh token to obtain a new set of tokens without the need for the user to give consent again.

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	description
grant_type	refresh_token
refresh_token	The `REFRESH_TOKEN` that your application received with the previous set of tokens.

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

Security Considerations

Your client secret, access tokens, refresh tokens and data you have retrieved from Rabobank APIs are sensitive and need to be handled carefully. Please consider 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). All traffic that sends one of these items should be server to server communication.

Use HTTPS

OAuth 2.0 removed transport considerations from the protocol and instead 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.

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 the first step 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.

OAuth 2.0 client libraries

We highly recommended that 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 can be (permanently) banned from using Rabobank APIs.

Keep your application and it's environment secure

To prevent leakage of sensitive information your application should be protected against cross site scripting, SQL injection and other OWASP top 10 vulnerabilities. We recommend executing security tests on your application and it's environment both periodically and with every major change. The storage of sensitive information should only be accessible by the application. Limiting the authorization to the storage and encrypting sensitive data is highly recommended.