OAuth APIs for Access Token
OAuth is a simple and secure authorization framework. For secure access to the APIs, the Aruba Central API Framework plug-in supports OAuth protocol for authentication and authorization. It allows applications to acquire an access token for Aruba Central through a variety of work flows supported within the OAuth 2.0 specification.
OAuth Mechanism
This protocol follows a three step process to obtain a new access token. Once the token is acquired, it can be refreshed multiple times without having to create a new access token. An administrator has the ability to revoke the token, if needed.
- Login using user credentials to get valid session and CSRF token from Aruba Central
- Obtain Authorization code
- Exchange Authorization code for Access Token
The access tokens have a limited lifetime. A refresh token is provided during authorization that can be used to get a new access token. If you are writing a long running applications (web app) or native mobile application you should refresh the token periodically.
Requirements
The following items are required to obtain access token via OAuth. Steps to obtain them are covered in the previous sections
- Aruba Central Customer ID
- Client id and client secret from API Gateway by creating an application.
- Username and Password for the user in your Aruba Central account.
- Domain Base URL for Aruba Central API Gateway based on the geographical cluster where your account is registered.
Table: Domain URLs for API Gateway Access
Region | API Gateway Domain Name |
---|---|
US-1 | app1-apigw.central.arubanetworks.com |
US-2 | apigw-prod2.central.arubanetworks.com |
US-East1 | apigw-us-east-1.central.arubanetworks.com |
US-West4 | apigw-uswest4.central.arubanetworks.com |
EU-1 | eu-apigw.central.arubanetworks.com |
EU-Central2 | apigw-eucentral2.central.arubanetworks.com |
EU-Central3 | apigw-eucentral3.central.arubanetworks.com |
Canada-1 | apigw-ca.central.arubanetworks.com |
China-1 | apigw.central.arubanetworks.com.cn |
APAC-1 | api-ap.central.arubanetworks.com |
APAC-EAST1 | apigw-apaceast.central.arubanetworks.com |
APAC-SOUTH1 | apigw-apacsouth.central.arubanetworks.com |
Obtaining Access Token via OAuth Protocol
Let's look at each step in detail. You can choose a tool of your choice to try this out. Some popular tools that doesn't require programming are cURL and Postman. In this section, cURL examples are provided.
1) Login and Obtain CSRF Token
First step is to perform a login using user credentials (Username and Password).
API Endpoint: /oauth2/authorize/central/api/login
Base URL: https://apigw-prod2.central.arubanetworks.com
(Replace the above part of the URL with correct API Gateway mentioned above)
Request Query Params: “client_id” obtained from the API Gateway
Request Header: Set the “Content-Type” as “application/json”
Request Payload: Username and Password of Aruba Central User in JSON format
Response: The response headers contains the CSRF Token and Session Key.
Response Header Key | Response Header Value | Description |
---|---|---|
Set-Cookie | csrftoken=xxxx; session=xxxx | The API Gateway returns a CSRF token and the user session. |
cURL API Request
Replace , and with respective values. Verbose is enabled for the following command with "-v" option. The response output will contain Set-Cookie key in Response Headers
curl -v --cookie-jar 'central-cookie' --location --request POST 'https://apigw-prod2.central.arubanetworks.com/oauth2/authorize/central/api/login?client_id=<central-API-app-client-id>' \
--header 'Content-Type: application/json' \
--data-raw '{
"username": "<central-user-email-id>",
"password": "<central-user-password>"
}'
Note
Providing --cookie-jar 'central-cookie' is optional. It creates a file with csrf and session token. Copy the CSRF token and session token from either "central-cookie" file created by above cURL command or from the Response headers obtained by enabling verbose "-v".
2) Obtain Authorization Code
In this step, the API request will be made to obtain the authorization code.
API Endpoint: /oauth2/authorize/central/api
Base URL: https://apigw-prod2.central.arubanetworks.com
(Replace the above part of the URL with correct API Gateway mentioned above)
Request Query Params: "client_id", "response_type" as code, "scope" as either read or all
Request Header: Set the “Content-Type” as “application/json”; “Cookie” as “session=xxxx”; “X-CSRF-Token” as "xxxx" (obtained from the first step)
Request Payload: “customer_id” as key with value in JSON format
Note
Setting Scope as read provides read-only access and all provides read-write access.
Response Payload: auth_code is received in the response payload/body.
{
"auth_code": "xxxx"
}
cURL API Request
Replace , and with respective values. Set the scope to read for read-only access or all for read-write access.
curl --request POST 'https://apigw-prod2.central.arubanetworks.com/oauth2/authorize/central/api?client_id=<central-API-app-client-id>&response_type=code&scope=all' \
--header 'Content-Type: application/json' \
--header 'Cookie: session=<session-key>' \
--header 'X-CSRF-Token: <csrf-token>' \
--data-raw '{
"customer_id": "<central_customer_id>"
}'
Note
Once this authorization code is obtained it needs to be exchanged for the access token within 300 seconds
3) Acquire the Access Token
This is the final step in obtaining access token. Once we have the auth_code, it can be exchanged for access token.
API Endpoint: /oauth2/token
Base URL: https://apigw-prod2.central.arubanetworks.com
(Replace the above part of the URL with correct API Gateway mentioned above)
Request Query Params: "client_id", "grant_type" as authorization_code, "client_secret" and "code" as auth_code (obtained in previous step)
Request Header: Set the “Content-Type” as “application/json”
Request Payload: Not required
Response Payload: Contains the access token and refresh token in JSON format. This "access_token" should be passed with every API Request to Central API Gateway.
{
"refresh_token":"xxxx",
"token_type":"bearer",
"access_token":"xxxx",
"expires_in":7200
}
cURL API Request
Replace , and with respective values.
curl --request POST 'https://apigw-prod2.central.arubanetworks.com/oauth2/token?client_id=<central-API-app-client-id>&client_secret=<client-secret>&grant_type=authorization_code&code=<auth-code>' \
--header 'Content-Type: application/json'
Note
All OAuth requests must use the SSL endpoints available at either API Reference of this portal OR The endpoints listed in the Aruba Central API Gateway swagger interface as mentioned in the section(API Swagger Interface).
# Refreshing the Access Token
Access token expires after a certain time. Refresh token API should be used to refresh the tokens before and after they expire. This can be done via a simple REST API call instead of performing all the steps of generating a new access token again.
API Endpoint: oauth2/token
Base URL: https://apigw-prod2.central.arubanetworks.com
(Replace the above part of the URL with correct API Gateway mentioned above)
Request Query Params: "client_id", "grant_type" as refresh_token, "client_secret" and "refresh_token" (obtained in previous step)
Request Header: Set the “Content-Type” as “application/json”
Response Payload: Contains the access token and refresh token in JSON format. This new "access_token" should be used for further requests and "refresh_token" should be used for next token refresh.
{
"refresh_token": "xxxx",
"token_type": "bearer",
"access_token": "xxxx",
"expires_in": 7200
}
cURL API Request
Replace . and with respective values
curl --request POST 'https://apigw-prod2.central.arubanetworks.com/oauth2/token?client_id=<central-API-app-client-id>&client_secret=<central-API-app-client-secret>&grant_type=refresh_token&refresh_token=<refresh-token>' \
--header 'Content-Type: application/json'
Note
For more information check out the Aruba Central Documentation Center .
Updated about 1 year ago