Introduction to OAuth2
For the security of our products (Unifeed, Webservices), we use the open standard OAuth2. The OAuth2 standard is a widely accepted standard that is used by many software parties and has an abundance of libraries available. With the OAuth2 autorisation protocol, it is possible for third-party applications to acquire limited access to our http services. To access these services, the application needs client-credentials (client_id/client_secret). To gain access to the data, the user additionally needs to be identified by his/her username and password. More complete information about the OAuth2 specification can be found here: OAuth2 website
2BA supports 2 authorization flows from the OAuth spec. These flows are: “Resource Owner Password Credentials Grant” and “Authorization Code“.
Steps:
- Choose one of the supported flows. Choose the flow that best matches your situation.
- Use these flows to retrieve the Access Token / Refresh Token one time.
- Refresh the Access Token, if expired, by utilising the Refresh Token.
- Invoke the desired JSON or SOAP service or Unifeed and provide the Access Token.
Resource Owner Password Credentials Grant
This flow can be used when there is a trusted relation between the application and the end user. The end user enters his/her username and password in the application. This flow can be used, for example, when the application is installed on the end user’s computer.
More details and example code can be found here: Resource Owner Password Credentials Grant.
Authorization Code
This flow can be used when there is no trusted relation between the application and the end user, for example, when the application resides on the internet. The user will, in that case, NOT enter their 2BA credentials in a third-party application. The application can use this flow to redirect the user to the 2BA website, where the user will enter his/her credentials and 2BA will return an autorization code to the third-party application.
More details and example code can be found here: Authorization Code
Parameters
| Authorization URL | https://authorize.2ba.nl/OAuth/Authorize |
|---|---|
| Access token URL | https://authorize.2ba.nl/OAuth/Token |
| Client ID | (as received from 2BA) |
| Client secret | (as received from 2BA) |
| Preferred grand type | Authorization Code |
| see also: https://authorize.2ba.nl/.well-known/openid-configuration |
OAuth token
Description
This service is used to get an Access Token / Refresh Token. You can use the new Access Token to access the webservices.
Don’t forget to replace your old Refresh Token with the new one! Refresh Tokens also time out once. When you issue an invalid Request Token, this service will respond with a “bad request” (http statuscode 400) result. In this case the user has to login again to aquire a new Refresh Token.
More details and example code can be found here: Refresh Acces Token
See our introduction to OAuth2 here.
This is a POST request!
Resource URL
json: https://authorize.2ba.nl/OAuth/Token soap:
Parameters
| grant_type required | possible options are “password”, “refresh_token”, “authorization_code”
Example value: password |
| username optional | Login name for the end-user (resource owner). Required when grant_type=password
Example value: user@2ba.nl |
| password optional | Password that comes with the previous username. Required when grant_type=password
Example value: myPassword |
| code optional | Authorization code received from the authorization server. Required when grant_type=authorization_code
Example value: sdfsdfsGEasd |
| refresh_token optional | Refresh token received within a previous request. Required when grant_type=refresh_token
Example value: tGzv3JOkF0XG5Qx2TIKWIA |
| client_id optional | String that identifies the client application. Required when grant_type=password|refresh_token
Example value: myApplication |
| client_secret optional | Secret string that comes with the client_id. Required when grant_type=password|refresh_token
Example value: myApplicationSecret |
| redirect_uri optional | Redirect Uri. Required when redirect_uri was included in the Authorization request for Authorization Code Grant, and the redirect_uri has to be the same!
Example value: |
| callback optional | Only available for JSON format. If supplied, the response will use the JSONP format with a callback of the given name.
Example value: |
Response Object
| Field | Type | Description |
|---|---|---|
| access_token | string | String which should be send with each service request.
Example value: gAAAGw231OZXwzMiH_wV….. |
| token_type | string | Type of the Access Token.
Example value: bearer |
| expires_in | integer | Expiry time of the Acces Token in seconds.
Example value: 120 |
| refresh_token | string | This token can be used to obtain a new Access Token.
Example value: LwfI!IAAAAFLDVUewBJ04M3z8SutDTR… |
Example Request
Request URL:https://authorize.2ba.nl/OAuth/Token
Request Method:POST
Content-Type: application/x-www-form-urlencoded
'''''Form Data'''''
grant_type=password&username=myUsername&password=myPassword&client_id=myApplicationId&client_secret=myClientSecret
Request URL:https://authorize.2ba.nl/OAuth/Token
Request Method:POST
Content-Type: application/x-www-form-urlencoded
'''''Form Data'''''
grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA&client_id=myApplicationId&client_secret=myClientSecret
Example Response
{
"access_token":"gAAAAH8hTQhI_uYzULg7g.......",
"token_type":"bearer",
"expires_in":120,
"refresh_token":"LwfI!IAAAAANi5l-g.........."
}
