BBA Mastro System Authorization Process
- Rex Enage (Unlicensed)
Introduction
This document explains authorization process that used in the BBA Mastro system. The system implements OAuth 2.0 as an authorization protocol that commonly used, therefore this document also cover about how to work with OAuth 2.0.
Terminology
In order to understand authorization process in BBA Mastro system, it's important to first understand the relevant terminology.
OAuth 2.0
OAuth 2 is an authorization framework that enables applications to obtain limited access to user accounts on an HTTP service.
Authentication
Authentication is process of verifying the identity of a user. Authentication is typically performed by asking a user for a username and password. The username represents the user's claimed identity, and the application assumes if the user provides the correct password that they are indeed that user.
Authorization
Authorization is process of verifying that a user has the right to perform some action, such as reading data, or create data. This typically first requires valid identification of the user (authentication) in order to check the actual user is authorized.
Delegated Authorization
Delegated authorization is granting access to another person or application to perform action on your behalf.
Access Token
Access token is token that provided by authorization server after authentication process succeeded. It must be sent with client request in order to access resource server data. This token has limited lifespan and can cannot be used after expired.
Refresh Token
When the authorization process succeeded, authorization server also provides refresh token along with access token. This token is used to obtain a new access token when access token expired.
JWT
JSON Web Token (JWT) are open source, industry standard RFC 7519 method for representing claims securely between two parties.
OAuth Roles
OAuth defines four roles:
Resource server
The server hosting user-owned resource that are protected by OAuth. This is typically an API provider that holds and protects data.
Resource owner
Typically the user of an application, the resource owner has the ability to grant access to their own data hosted on the resource server.
Client
An application making API requests to perform actions on protected resources on behalf of the resource owner and with its authorization.
Authorization server
The authorization server gets consent from the resource owner and issues access tokens to clients for accessing protected resources hosted by a resource server. Smaller API providers may use the same application and URL space for both the authorization server and resource server.
Client Profiles
OAuth 2.0 defines several important client profiles
Server-side web application
An OAuth client running on a web server. The web application is accessed by a resource owner (user) and the application makes the appropriate API calls using a server-side programming language. The user has no access to the OAuth client secret or any access tokens issued by the authorization server.
Client-side application running in a web browser
An OAuth client running in a user’s web browser, where the client has access to the application code and/or API requests. The application could be distributed as JavaScript included in a web page, as a browser extension, or using a plug-in technology such as Flash. The OAuth credentials are not trusted to be kept confidential from the resource owner, so some API providers won’t issue client secrets for applications using this profile.
Native application
An OAuth client which is very similar to the client-side application, as the credentials are not trusted to be kept confidential. However, since it’s an installed application, it may not have access to the full capabilities of a web browser.
Client Application Registration
OAuth requires that client applications register with the authorization server so that API requests are able to be properly identified. After registration is complete, the authorization server issues client credentials:
- Client ID, specified as client_id when interacting with resource server.
- Client secret, specified as client_secret when exchanging an authorization code for an access token and refresh token using the server-side web application flow.
Authorization process
Authorization process flow allows exchanging the username and password of a user for an access token and a refresh token. The diagram below shows a step by step of authorization process.
The process of exchanging credentials for an access token is simply need to make a HTTP POST to authorization server, providing the credentials and client information.
The authorization server URL of BBA system is:
http://auth.bbamastro.com/oauth/token
Here are the required parameters:
| Parameter Name | Description |
|---|---|
| Specified as “password” for this flow. |
| scope | The data your application is requesting access to |
| client_id | The value provided to you when you registered your application |
client_secret | The value provided to you when you registered your application. While the name of this parameter implies that the value is secret, it is sometimes required by API providers for nonconfidential clients such as native mobile applications. In these cases, the value is not actually a secret, as it could be discovered by users of the application. |
| username | The username provided by the resource owner, encoded as UTF-8 |
| password | The password provided by the resource owner, encoded as UTF-8 |
Here’s an example request via the curl command-line HTTP client:
curl -vu clientapp:123456 http://auth.bbamastro.com/oauth/token -H "Accept: application/json" -d "password=password123&username=goharikgabrelyan@gmail.com&grant_type=password&scope=read%20write&client_secret=123456&client_id=clientapp"
or using HTTP Request
POST http://auth.bbamastro.com/oauth/token?password=password123&username=goharikgabrelyan@gmail.com&grant_type=password&scope=read%20write&client_secret=123456&client_id=clientapp
If the user-provided credentials are successfully authenticated, the OAuth authorization server will return an application/json response containing an access_token and an refresh_token:
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkZWZhdWx0RGltZW5zaW9uIjp7ImVuYWJsZURlZmF1bHREaW1lbnNpb24iOmZhbHNlLCJkZWZhdWx0SGVpZ2h0IjowLCJkZWZhdWx0TGVuZ3RoIjowLCJkZWZhdWx0V2lkdGgiOjAsImRlZmF1bHRXZWlnaHQiOjB9LCJ1c2VyX25hbWUiOiJnb2hhcmlrZ2FicmVseWFuQGdtYWlsLmNvbSIsInNjb3BlIjpbInJlYWQiLCJ3cml0ZSJdLCJub3RpZmljYXRpb25QcmVmZXJlbmNlcyI6eyJub3RpZnlRdW90ZUFuZEJvb2siOnRydWUsIm5vdGlmeVBlbmRpbmdTaGlwbWVudCI6dHJ1ZSwibm90aWZ5UmV0dXJucyI6dHJ1ZX0sImV4cCI6MTQ4NDY1NjE3NSwidXNlcklkIjoxMCwiYXV0aG9yaXRpZXMiOlsiUk9MRV9DT01QQU5ZX0FDQ09VTlRfTUFOQUdFUiIsIlJPTEVfQ09NUEFOWV9BRE1JTiIsIlJPTEVfQURNSU4iXSwianRpIjoiMDE4ZTE3NGEtZjRiYS00ZmE2LTgyNmEtOTUzMGIxYWU2NjA4IiwiY2xpZW50X2lkIjoiY2xpZW50YXBwIn0.6XbiDQVPl2M0LJLq0Jjkkgf1NO6oTCRaAghSoBZbGH8",
"token_type": "bearer",
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkZWZhdWx0RGltZW5zaW9uIjp7ImVuYWJsZURlZmF1bHREaW1lbnNpb24iOmZhbHNlLCJkZWZhdWx0SGVpZ2h0IjowLCJkZWZhdWx0TGVuZ3RoIjowLCJkZWZhdWx0V2lkdGgiOjAsImRlZmF1bHRXZWlnaHQiOjB9LCJ1c2VyX25hbWUiOiJnb2hhcmlrZ2FicmVseWFuQGdtYWlsLmNvbSIsInNjb3BlIjpbInJlYWQiLCJ3cml0ZSJdLCJhdGkiOiIwMThlMTc0YS1mNGJhLTRmYTYtODI2YS05NTMwYjFhZTY2MDgiLCJub3RpZmljYXRpb25QcmVmZXJlbmNlcyI6eyJub3RpZnlRdW90ZUFuZEJvb2siOnRydWUsIm5vdGlmeVBlbmRpbmdTaGlwbWVudCI6dHJ1ZSwibm90aWZ5UmV0dXJucyI6dHJ1ZX0sImV4cCI6MTQ4NzIwNDk3NSwidXNlcklkIjoxMCwiYXV0aG9yaXRpZXMiOlsiUk9MRV9DT01QQU5ZX0FDQ09VTlRfTUFOQUdFUiIsIlJPTEVfQ09NUEFOWV9BRE1JTiIsIlJPTEVfQURNSU4iXSwianRpIjoiOTg3ZTA5ZWQtODUzMy00OWRkLTlkMzktNzY2NmEzMjI2MzU0IiwiY2xpZW50X2lkIjoiY2xpZW50YXBwIn0.uRyj3I3Gg8lmmz736uSWMGG8FRq-JOeNBTyFt4DFBaI",
"expires_in": 43199,
"scope": "read write",
"defaultDimension": {
"enableDefaultDimension": false,
"defaultHeight": 0,
"defaultLength": 0,
"defaultWidth": 0,
"defaultWeight": 0
},
"notificationPreferences": {
"notifyQuoteAndBook": true,
"notifyPendingShipment": true,
"notifyReturns": true
},
"userId": 10,
"jti": "018e174a-f4ba-4fa6-826a-9530b1ae6608"
}
The response parameters are:
| Path | Type | Description |
|---|---|---|
access_token |
| The access token used to access the API on behalf of the user who provided their credentials. This is the only required item in the response. |
token_type |
| Type of access token. |
refresh_token | String | A token that can be used to acquire a new access token after the current one expires. |
expires_in | Number | The remaining lifetime of the access token, in seconds. |
scope | String | Scope of access token |
defaultDimension | Object | Default dimension of authenticated user. This data is used by BBA system |
notificationPreferences | Object | Notification preferences of authenticated user. This data is used by BBA system |
| user_id | String | User identifier. This data is used by BBA system |
| jti | String | JWT identifier |
Call The API
Since the OAuth access token issued by the authorization flow is a simple bearer token, you simply need to provide the access token via a HTTP Authorization header or query parameter value, depending on which the API provider supports.
Here’s an example of HTTP CURL request using access token:
curl http://api.bbamastro.com/carrier -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkZWZhdWx0RGltZW5zaW9uIjp7ImVuYWJsZURlZmF1bHREaW1lbnNpb24iOmZhbHNlLCJkZWZhdWx0SGVpZ2h0IjowLCJkZWZhdWx0TGVuZ3RoIjowLCJkZWZhdWx0V2lkdGgiOjAsImRlZmF1bHRXZWlnaHQiOjB9LCJ1c2VyX25hbWUiOiJnb2hhcmlrZ2FicmVseWFuQGdtYWlsLmNvbSIsInNjb3BlIjpbInJlYWQiLCJ3cml0ZSJdLCJub3RpZmljYXRpb25QcmVmZXJlbmNlcyI6eyJub3RpZnlRdW90ZUFuZEJvb2siOnRydWUsIm5vdGlmeVBlbmRpbmdTaGlwbWVudCI6dHJ1ZSwibm90aWZ5UmV0dXJucyI6dHJ1ZX0sImV4cCI6MTQ4NDY1NjE3NSwidXNlcklkIjoxMCwiYXV0aG9yaXRpZXMiOlsiUk9MRV9DT01QQU5ZX0FDQ09VTlRfTUFOQUdFUiIsIlJPTEVfQ09NUEFOWV9BRE1JTiIsIlJPTEVfQURNSU4iXSwianRpIjoiMDE4ZTE3NGEtZjRiYS00ZmE2LTgyNmEtOTUzMGIxYWU2NjA4IiwiY2xpZW50X2lkIjoiY2xpZW50YXBwIn0.6XbiDQVPl2M0LJLq0Jjkkgf1NO6oTCRaAghSoBZbGH8'
Example HTTP request using access token:
GET http://api.bbamastro.com/carrier HTTP/1.1 Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkZWZhdWx0RGltZW5zaW9uIjp7ImVuYWJsZURlZmF1bHREaW1lbnNpb24iOmZhbHNlLCJkZWZhdWx0SGVpZ2h0IjowLCJkZWZhdWx0TGVuZ3RoIjowLCJkZWZhdWx0V2lkdGgiOjAsImRlZmF1bHRXZWlnaHQiOjB9LCJ1c2VyX25hbWUiOiJnb2hhcmlrZ2FicmVseWFuQGdtYWlsLmNvbSIsInNjb3BlIjpbInJlYWQiLCJ3cml0ZSJdLCJub3RpZmljYXRpb25QcmVmZXJlbmNlcyI6eyJub3RpZnlRdW90ZUFuZEJvb2siOnRydWUsIm5vdGlmeVBlbmRpbmdTaGlwbWVudCI6dHJ1ZSwibm90aWZ5UmV0dXJucyI6dHJ1ZX0sImV4cCI6MTQ4NDY1NjE3NSwidXNlcklkIjoxMCwiYXV0aG9yaXRpZXMiOlsiUk9MRV9DT01QQU5ZX0FDQ09VTlRfTUFOQUdFUiIsIlJPTEVfQ09NUEFOWV9BRE1JTiIsIlJPTEVfQURNSU4iXSwianRpIjoiMDE4ZTE3NGEtZjRiYS00ZmE2LTgyNmEtOTUzMGIxYWU2NjA4IiwiY2xpZW50X2lkIjoiY2xpZW50YXBwIn0.6XbiDQVPl2M0LJLq0Jjkkgf1NO6oTCRaAghSoBZbGH8' Content-Type: application/json Cache-Control: no-cache
Refresh the Access Token
When an authorization code is exchanged for an access token, authorization server will issue short-lived access tokens. Although these access tokens have a limited lifespan, two additional parameters may be included in the response to enable long-lived access: expires_in and refresh_token. Expires_in indicates the remaining lifetime of the access_token, specified in seconds. When the access token expires, the refresh_token parameter can be used to obtain a new access token.
When access token is expired, authorization server will respond the request with the message below:
{
"error": "invalid_token",
"error_description": "Access token expired: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkZWZhdWx0RGltZW5zaW9uIjp7ImVuYWJsZURlZmF1bHREaW1lbnNpb24iOmZhbHNlLCJkZWZhdWx0SGVpZ2h0IjowLCJkZWZhdWx0TGVuZ3RoIjowLCJkZWZhdWx0V2lkdGgiOjAsImRlZmF1bHRXZWlnaHQiOjB9LCJ1c2VyX25hbWUiOiJnb2hhcmlrZ2FicmVseWFuQGdtYWlsLmNvbSIsInNjb3BlIjpbInJlYWQiLCJ3cml0ZSJdLCJub3RpZmljYXRpb25QcmVmZXJlbmNlcyI6eyJub3RpZnlRdW90ZUFuZEJvb2siOmZhbHNlLCJub3RpZnlQZW5kaW5nU2hpcG1lbnQiOmZhbHNlLCJub3RpZnlSZXR1cm5zIjpmYWxzZX0sImV4cCI6MTQ4NDU3NjU1NCwidXNlcklkIjoxMCwiYXV0aG9yaXRpZXMiOlsiUk9MRV9DT01QQU5ZX0FDQ09VTlRfTUFOQUdFUiIsIlJPTEVfQURNSU4iLCJST0xFX0NPTVBBTllfQURNSU4iXSwianRpIjoiNmU5MThlMWQtZDJlMS00OTEyLTg3ZWUtYjY0MzUyZjBkYzdmIiwiY2xpZW50X2lkIjoiY2xpZW50YXBwIn0.UsssCcRd1bzwpAEuAchwq3S7Ow1LWhi23EGESYZMi0U"
}
Refreshing the access token is accomplished by making a HTTP POST to the token endpoint, specifying the grant_type as refresh_token and including the refresh_token.
Here are the required parameters:
| Parameter Name | Description |
|---|---|
| Specified as “refresh_token” for this flow. |
| scope | The data your application is requesting access to |
| client_id | The value provided to you when you registered your application |
client_secret | The value provided to you when you registered your application. While the name of this parameter implies that the value is secret, it is sometimes required by API providers for nonconfidential clients such as native mobile applications. In these cases, the value is not actually a secret, as it could be discovered by users of the application. |
| username | The username provided by the resource owner, encoded as UTF-8 |
| password | The password provided by the resource owner, encoded as UTF-8 |
| refresh_token | The token that given by authorization server |
Below is the example of CURL request to obtain new access token using refresh token:
curl -vu clientapp:123456 http://auth.bbamastro.com/oauth/token -H "Accept: application/json" -d "password=password123&username=goharikgabrelyan@gmail.com&grant_type=refresh_token&client_secret=123456&client_id=clientapp&refresh_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkZWZhdWx0RGltZW5zaW9uIjp7ImVuYWJsZURlZmF1bHREaW1lbnNpb24iOmZhbHNlLCJkZWZhdWx0SGVpZ2h0IjowLCJkZWZhdWx0TGVuZ3RoIjowLCJkZWZhdWx0V2lkdGgiOjAsImRlZmF1bHRXZWlnaHQiOjB9LCJ1c2VyX25hbWUiOiJnb2hhcmlrZ2FicmVseWFuQGdtYWlsLmNvbSIsInNjb3BlIjpbInJlYWQiLCJ3cml0ZSJdLCJhdGkiOiIwMThlMTc0YS1mNGJhLTRmYTYtODI2YS05NTMwYjFhZTY2MDgiLCJub3RpZmljYXRpb25QcmVmZXJlbmNlcyI6eyJub3RpZnlRdW90ZUFuZEJvb2siOnRydWUsIm5vdGlmeVBlbmRpbmdTaGlwbWVudCI6dHJ1ZSwibm90aWZ5UmV0dXJucyI6dHJ1ZX0sImV4cCI6MTQ4NzIwNDk3NSwidXNlcklkIjoxMCwiYXV0aG9yaXRpZXMiOlsiUk9MRV9DT01QQU5ZX0FDQ09VTlRfTUFOQUdFUiIsIlJPTEVfQ09NUEFOWV9BRE1JTiIsIlJPTEVfQURNSU4iXSwianRpIjoiOTg3ZTA5ZWQtODUzMy00OWRkLTlkMzktNzY2NmEzMjI2MzU0IiwiY2xpZW50X2lkIjoiY2xpZW50YXBwIn0.uRyj3I3Gg8lmmz736uSWMGG8FRq-JOeNBTyFt4DFBaI"
POST http://auth.bbamastro.com/oauth/token -H "Accept: application/json" -d "password=password123&username=goharikgabrelyan@gmail.com&grant_type=refresh_token&client_secret=123456&client_id=clientapp&refresh_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkZWZhdWx0RGltZW5zaW9uIjp7ImVuYWJsZURlZmF1bHREaW1lbnNpb24iOmZhbHNlLCJkZWZhdWx0SGVpZ2h0IjowLCJkZWZhdWx0TGVuZ3RoIjowLCJkZWZhdWx0V2lkdGgiOjAsImRlZmF1bHRXZWlnaHQiOjB9LCJ1c2VyX25hbWUiOiJnb2hhcmlrZ2FicmVseWFuQGdtYWlsLmNvbSIsInNjb3BlIjpbInJlYWQiLCJ3cml0ZSJdLCJhdGkiOiIwMThlMTc0YS1mNGJhLTRmYTYtODI2YS05NTMwYjFhZTY2MDgiLCJub3RpZmljYXRpb25QcmVmZXJlbmNlcyI6eyJub3RpZnlRdW90ZUFuZEJvb2siOnRydWUsIm5vdGlmeVBlbmRpbmdTaGlwbWVudCI6dHJ1ZSwibm90aWZ5UmV0dXJucyI6dHJ1ZX0sImV4cCI6MTQ4NzIwNDk3NSwidXNlcklkIjoxMCwiYXV0aG9yaXRpZXMiOlsiUk9MRV9DT01QQU5ZX0FDQ09VTlRfTUFOQUdFUiIsIlJPTEVfQ09NUEFOWV9BRE1JTiIsIlJPTEVfQURNSU4iXSwianRpIjoiOTg3ZTA5ZWQtODUzMy00OWRkLTlkMzktNzY2NmEzMjI2MzU0IiwiY2xpZW50X2lkIjoiY2xpZW50YXBwIn0.uRyj3I3Gg8lmmz736uSWMGG8FRq-JOeNBTyFt4DFBaI"
Check Access Token
In development and debugging process, sometime we need to know information inside access token. In order to do that, we can use JWT online tools https://jwt.io (it can also installed as google chrome extension). Enter the access token there and the access token information will be shown.
References
Ryan Boyd. 2012. Getting started with OAuth 2.0.O'Reilly
Requesting Credentials
To obtain credentials for testing and live use please send a message to sales@bbamastro.com with the following details:
- Company
- First Name
- Last Name
- Contact Number
- Address
- Country
- Postcode
- Suburb
- List of Carriers
In this page: