Authentication

This section talks about the authentication aspect of the REST API on the controllers. It covers the Login and Logout process and details related to those endpoints.

LOGIN

To access any configuration element -- whether it is through a GET or POST request, the user first has to login to the Mobility Conductor and get authenticated. This is done for securing access to interact with the system using the REST API interface.

Once authenticated, the user will be presented with a UIDARUBA token in the JSON response, which can be used to authenticate further GET or POST API requests.

Syntax for Login request using cURL:

curl --insecure -c "aruba-cookie" -d "username=<username>&password=<password>"
https://<mcr-ip>:4343/v1/api/login

📘

Note

--insecure or -k option is used with the cURL command if the certificate of the Mobility Conductor cannot be validated
-c is used to store the cookie to "aruba-cookie" file and will be used in subsequent API calls through cURL
-d is used to send the data consisting of user credentials

Description of user-specific values used in the cURL example

Login API Request

Request URL:
https://:4343/v1/api/login

Request Method:
GET

Request Header:
Content-Type: application/x-www-form-urlencoded

Request Parameters:
username =
password =

Sample Response for successful login:

{
    "_global_result": {
        "status": "0",
        "status_str": "You've logged in successfully.",
        "UIDARUBA": "06f1758f-bb66-4678-91c5-ee847c87a939"
    }
}

📘

Note:

UIDARUBA is the authentication token, which is a required query parameter for any API call.
Once a user is successfully authenticated and has a valid UIDARUBA token, it is a good practice to reuse the same token for subsequent API calls till the token expires. This will not only avoid creating multiple sessions, but it will also avoid doing a login for every API endpoint.

The following is a response for failed login:

{
  "_global_result": {
    "status":"1", 
    "status_str": "Unauthorized request, authentication failed"
  }
}

👍

Session Timeout

The UIDARUBA token is valid for the duration of the session timeout that is configured on the Controller.
Session timeout can be configured on the Controller to specify the time of inactivity after which the session times out and requires a login for continued access. This can be changed in the web-server profile(changing this timeout will also change the WebUI timeout ). Default timeout is 900 seconds.

👍

Session Limit

Logout should be used to avoid exceeding the maximum number of concurrent sessions, which is limited to 64 (it includes all CLI sessions + WebUI sessions + API sessions).

LOGOUT

To end a session, logout endpoint is used. Once the desired API endpoints are used to interact with the system it is important to close a session. Successful logout can help avoid exceeding the session limit on the Mobility Conductor.

Values required for LOGOUT

The following is an example of Logout request in cURL:

curl -c "aruba-cookie" https://<mcr-ip>:4343/v1/api/logout

📘

Note:

You can use the --insecure or -k option with the cURL command if the certificate of the Mobility Conductor cannot be validated.

Logout API Request

Request URL:
https://:4343/v1/api/logout

Request Method:
GET/POST

Request Header:
Content-Type: application/json
Cookie: SESSION=

Request Parameters:
None

 
Sample Response for logout:

{
    "_global_result": {
        "status": "0",
        "status_str": "You've been logged out successfully.",
        "UIDARUBA": "(null)"
    }
}

🚧

Note

Logout should be used in order to not exceed the maximum number of concurrent sessions, which is limited at 64 (it included combined CLI sessions + WebUI sessions + API sessions)

 
Check out the API guide to learn more about the APIs available, how to interpret the output of an API call and samples in curl.