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.
OAuth 2.0 and consent
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 403 Forbidden
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
In the table below you can find the expiration times of different tokens and other limitations. For the access token and the refresh token you should always use the expiration times included in the token response for any business logic related to refreshing the token.
consent | Depends on the requested scope |
authorization code | 5 minutes |
access token | 1 hour |
refresh token | 30 days |
refresh limit | 4096 times |
OAuth 2.0 Authorization Code Flow
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. |
redirect_uri | Required only if the redirect_uri parameter was included in the authorization request /oauth2/authorize; their values MUST be identical. |
* 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 redirect url provided by you during application registration along with the error code ‘access_denied’.
https://your.redirect.url?error=access_denied
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,
"metadata": "a:consentId 6dfa1a2a-888c-4015-8099-f88b080d0bbb",
"scope": SCOPES,
"refresh_token": REFRESH_TOKEN,
"refresh_token_expires_in": 2592000
}
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
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:
|
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.