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.

1. Login using user credentials to get valid session and CSRF token from Aruba Central
2. Obtain Authorization code
3. 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

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.

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).

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 .