OAuth is a simple and secure authorization framework. For secure access to the APIs, the HPE Aruba Networking Central API Framework plug-in supports OAuth protocol for authentication and authorization. It allows applications to acquire an access token for HPE Aruba Networking 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 HPE Aruba Networking 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

• HPE Aruba Networking Central Customer ID
• Client id and client secret from API Gateway by creating an application.
• Username and Password for the user in your HPE Aruba Networking Central account.
• Domain Base URL for HPE Aruba Networking 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 API

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.

🚧

OAuth API Limit

• The rate limit to generate a new access token for a client ID is restricted to 1 access token per 30 minutes. This is applicable for below steps:
  • Authenticate a User and Create a User Session
  • Generate Authorization Code
• It is recommended to use Refresh Token API to refresh an invalid access token instead of creating new tokens each time for a user.

1. Authenticate a User and Create a User Session

First step is to login using user credentials (Username and Password) and obtaining the CSRF and Session tokens.

API Request

API Endpoint: /oauth2/authorize/central/api/login
API Method: POST
Base URL: https://apigw-prod2.central.arubanetworks.com (Replace the Base URL with correct API Gateway)
Request Query Params: “client_id” obtained from the API Gateway
Request Header: Set the “Content-Type” & "Accept" as “application/json”
Request Payload: Username and Password of HPE Aruba Networking Central User in JSON format

cURL API Request
Replace central-API-Gateway-base-URL, central-user-email-id, central-user-password and central-API-app-client-id with respective values.

curl -v --cookie-jar --location --request POST '<central-API-Gateway-base-URL>/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

• Verbose is enabled for the following command with "-v" option. The response output will contain Set-Cookie key in Response Headers
• 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".

API Response

The response headers contains the CSRF Token and Session Key.

2. Generate Authorization Code

After the user is authenticated and has a valid session, this API is used to get the authorization code.

API Request

API Endpoint: /oauth2/authorize/central/api
API Method: POST
Base URL: https://apigw-prod2.central.arubanetworks.com (Replace the Base URL with correct API Gateway)
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

cURL API Request
Replace central-API-app-client-id, session-key, csrf-token, and central-customer-id with respective values.

📘

Note

Setting Scope as read provides read-only access and all provides read-write access.

curl --request POST '<central-API-Gateway-base-URL>/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>"
}'

API Response

The auth_code is received in the response payload/body.

{
  "auth_code": "xxxx"
}

📘

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 Request

API Endpoint: /oauth2/token
API Method: POST
Base URL: https://apigw-prod2.central.arubanetworks.com (Replace the Base URL with correct API Gateway)
Request Header: Set the “Content-Type” as “application/json”
Request Payload: "client_id", "grant_type" as authorization_code, "client_secret", and "code" (auth code obtained in previous step)
Request Query Params: Not required

cURL API Request
Replace central-API-Gateway-base-URL, central-API-app-client-id, central-API-app-client-secret, and with respective values.

curl --request POST '<central-API-Gateway-base-URL>/oauth2/token' \
--header 'Content-Type: application/json' \
--data '{
    "client_id": "<central-API-app-client-id>",
    "client_secret": "<central-API-app-client-secret>",
    "grant_type": "authorization_code",
    "code": "<auth-code>"         
}'

API Response

The API 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
}

🚧

Note

All OAuth requests must use the SSL endpoints available at either API Reference of this portal OR The endpoints listed in the HPE Aruba Networking 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 Request

API Endpoint: oauth2/token
API Method: POST
Base URL: https://apigw-prod2.central.arubanetworks.com (Replace the Base URL with correct API Gateway)
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”

cURL API Request
Replace central-API-Gateway-base-URL, central-API-app-client-id, central-API-app-client-secret, and central-refresh-token with respective values

curl --request POST '<central-API-Gateway-base-URL>/oauth2/token?client_id=<central-API-app-client-id>&client_secret=<central-API-app-client-secret>&grant_type=refresh_token&refresh_token=<central-refresh-token>'

API Response

The 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
}

📘

Note

For more information check out the HPE Aruba Networking Central Documentation Center .