REST authentication

The HP VAN SDN Controller relies on token-based authentication to authenticate its REST APIs. All REST APIs except the /auth and /rsdoc APIs require an authentication token embedded in an X-Auth-Token header to be included with each REST request. The /auth API allows you to obtain a token, while the /rsdoc API provides live REST API documentation information about the controller’s REST API.

OpenStack Keystone used for user and token management

The SDN Controller uses Openstack Keystone as an identity management for managing users, generating tokens, as well as token validation. Upon installation, the SDN Controller creates the following users and roles:

  • User: sdn – This is the primary user that operates different SDN REST and UI operations. The sdn user has roles sdn-user and sdn-admin.

  • User: rsdoc – This is the primary user that is associated with API documentation operations. The rsdoc user has sdn-user role.

  • The Keystone version in use is based on the Folsom release. If a later Keystone version is in use:

Role-Based Access Control (RBAC)

The SDN Controller currently does not enforce role-based permissions (RBAC); however, it might do so in the future. Also, applications installed on the SDN Controller might choose to enforce RBAC per their security requirements.

API access requires authentication

To authenticate, one needs to present username and password to the /auth API as below (using cURL as an example):

curl -sk -H 'Content-Type:application/json' -d '{"login":{"user":"sdn","password":"password","domain":"sdn"}}' https://<controller-ip>:8443/sdn/v2.0/auth

CAUTION: Credential information (user name, password, domain, and authentication tokens) used in cURL commands might be saved in the command history. For security reasons, HP recommends that you disable command history prior to executing commands containing credential information.

The above call returns this example JSON data structure that includes the authentication token, which, by default, expires in 24 hours:

"record": {
"domainId": "62e312edff47413fad7e1d7fa6ac7bc7",
"domainName": "sdn",
"expiration": 1377917359000,
"expirationDate": "2013-08-30 19-49-19 -0700",
"token": "54a6f80a9ae243db89bfa05de4ced51d",
"userId": "bca3dea8a28b457e99e899ae16b79634",
"userName": "sdn"

CAUTION: Please guard this token information, as it can be used as an API key to gain access to your controller REST APIs.

To gain access to the REST API, include the token in the X-Auth-Token header as in the following curl example:

curl -sk -H "X-Auth-Token:54a6f80a9ae243db89bfa05de4ced51d"


One can continue using the same token for different SDN Controller APIs within the default 24-hour period since token creation. If desired, one can change this default 24-hour timeout in the /etc/keystone/keystone.conf file. (See the OpenStack Keystone Administration Guide for more information). The CachedTokenTTL value under the configuration properties com.hp.sdn.adm.auth.impl.AuthenticationManager needs to match the timeout set by Keystone as well to allow efficient caching of tokens.

Service and admin tokens

The Service token is used for internal communication between controllers and is not exposed to the user. The Admin token is used for communication between controller and the Keystone server and is not exposed to the user.

The values for these tokens can be changed using the option Configurations for AuthenticationManagervia the UI. All controllers in a team must have the same Service token to communicate successfully. For the Admin token, both the controller token value and the Openstack Keystone admin_token in the directory /etc/keystone/keystone.conf must match for successful authentication.