REST authentication

The SDN Controller uses Openstack Keystone as an identity management for managing users, generating tokens, as well as token validation.

The controller supports Keystone releases supporting the 2.0 REST API from Folsom up to the Juno release. It supports the following token authentication providers:

The controller is configured by default to auto-detect the token provider. It can also be forced to use a specific provider. 

The auto detection logic determines that any token longer than 32 characters is PKI or PKIZ. Distinguishing between PKI and PKIZ is accomplished by detecting the PKIZ prefix which is prepended to PKIZ compressed tokens.

The UUID authentication follows this process:

This design requires every API request to call in to Keystone for validation. This approach does not scale well as the number of API calls increases. The PKI authentication mechanism addresses this issue by using a private/public key pair to produce a CMS message which can be verified by an endpoint without checking with Keystone for every API request.

The PKI authentication provider was introduced in the Grizzly release of Keystone. To use PKI tokens, keys and certificates need to be generated. In Grizzly, this is done by using the keystone-manage pki_setup command. Keystone becomes a (CA) by signing user tokens.

The authentication process is as follows:

By default the keystone server is assumed to be installed on the same machine (localhost) as the controller.A remote Keystone server can be specified using the ServerVIP configuration item in the AuthenticationManager configuration set.

The following Keystone controller configuration is set in the controller UI Configurations screen under the com.hp.sdn/adm/auth.impl.AuthenticationManager component. The keys are described as follows:

AdminToken – Keystone admin token.

ConnPoolEvictPeriod – Keystone idle connection clean-up cycle in milliseconds. Minimum is 100.

ConnPoolMaxActive – Keystone maximum active connections. Minimum is 1.

ConnPoolMaxIdle – Keystone maximum idle connections. Minimum is 1.

ConnPoolMinIdleTime – Keystone minimum idle connection time in milliseconds. Minimum is 1000.

ConnSSLClientAuth – Keystone mutual authentication using TLS.

ConnTimeout – Keystone connection timeout in milliseconds. Minimum is 0.

Keystore – Keystone keystore location.

KeystorePass – Keystone keystore password.

MaxCachedTokens – Maximum number of cached tokens. Minimum is 0.

PKICertsDownloadHour – Hour in a 24 hour day (0-23) when PKI certificates download form the Keystore server occur.

PKICertsPath – Keystone PKI (signing and CA) certificates location.

RevListPollPeriod – Keystone PKI revocation list poll interval in seconds.

ServerPort – Keystone server port.

ServerVIP – Keystone server virtual IP.

ServiceRole – Role for shared secret.

ServiceTenant – Tenant (project) for shared secret.

ServiceToken – Shared secret for internal requests.

ServiceTokenTimeout – Timeout for shared secret, 0 for never. Minimum is 1.

ServiceUser – User for shared secret.

Tenant – Keystone tenant (only a single tenant is supported).

TokenProvider – Keystone token provider (Auto-Detect | PKI | PKIZ | UUID)

Truststore – Keystone truststore location.

TruststorePass – Keystone truststore password.

UserRole – Keystone user role (only a single role is supported. Only a user having this role is allowed access to the controller.

For information on Keystone, see the OpenStack Keystone documentation at http://docs.openstack.org/developer/keystone/.

Since tokens for either providers (UUID, PKI, or PKIZ) are bearer tokens, they should be protected by using mutually authenticated TLS. This can be accomplished by using valid PKI transport configuration as described in Changing the default controller keystore and truststore to use CA signed certificates:

The controller must have:

Keystone should be configured to:

HPE VAN SDN Controller 2.6 supports limited RBAC (Role Based Access Control). The SDN Controller currently enforces a single role which has access to all controller features. By default, the single role is sdn-admin. The authenticated user must have this role in order to be granted access to the controller. You must ensure that Keystone is configured to grant this role.

The applications installed on the SDN Controller can enforce RBAC to meet their security requirements.

root@sdnctl1:/var# curl -H "X-Auth-Token:ADMIN" http://192.168.4.61:35357/v2.0/tenants | python -mjson.tool
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   243  100   243    0     0  38786      0 --:--:-- --:--:-- --:--:-- 40500
{
    "tenants": [
        {
            "description": "",
            "enabled": true,
            "id": "575d62cc28bc403c97409072ba6536d3",
            "name": "sdn"
        },
        {
            "description": "Test Tenant",
            "enabled": true,
            "id": "fb2f0c68d410440baf67ba134733dbdb",
            "name": "test-tenant"
        }
    ],
    "tenants_links": []
}

root@sdnctl1:/var# curl -H "X-Auth-Token:ADMIN" -H "Content-Type: application/json" 
-d '{"user": {"email":"tester@test.rose.hp.com", "password": "somepass", "enabled": true, 
"name": "test-user", "tenantId":"575d62cc28bc403c97409072ba6536d3"}}' http://192.168.4.61:35357/v2.0/users
{"user": {"username": "test-user", "name": "test-user", "id": "867e7e2e88644e73a4eee25e4b80c303", 
"enabled": true, "email": "tester@test.rose.hp.com", "tenantId": "575d62cc28bc403c97409072ba6536d3"}}
root@sdnctl1:/var# curl -H "X-Auth-Token:ADMIN" http://192.168.4.61:35357/v2.0/users | python -mjson.tool
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   297  100   297    0     0  36232      0 --:--:-- --:--:-- --:--:-- 37125
{
    "users": [
        {
            "enabled": true,
            "id": "4a4a30ce53b743798dd79d98f5ab7daf",
            "name": "sdn",
            "username": "sdn"
        },
        {
            "email": "tester@test.rose.hp.com",
            "enabled": true,
            "id": "867e7e2e88644e73a4eee25e4b80c303",
            "name": "test-user",
            "tenantId": "575d62cc28bc403c97409072ba6536d3",
            "username": "test-user"
        }
    ]
}

root@sdnctl1:/var# curl -H "X-Auth-Token:ADMIN" http://192.168.4.61:35357/v2.0/OS-KSADM/roles | python -mjson.tool
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   342  100   342    0     0  58481      0 --:--:-- --:--:-- --:--:-- 68400
{
    "roles": [
        {
            "description": "Default role for project membership",
            "enabled": "True",
            "id": "9fe2ff9ee4384b1894a90878d3e92bab",
            "name": "_member_"
        },
        {
            "id": "1719c0d3b647488da8ca7ff6a1d0288b",
            "name": "sdn-user"
        },
        {
            "id": "c105e3dc4a484f5582563e28f7483edc",
            "name": "sdn-admin"
        },
        {
            "id": "67eb2907e94d43f7b3e2518485e20bbc",
            "name": "test-role"
        }
    ]
}

root@sdnctl1:/var# curl -X PUT -H "X-Auth-Token:ADMIN" 
http://192.168.4.61:35357/v2.0/tenants/575d62cc28bc403c97409072ba6536d3/users/
867e7e2e88644e73a4eee25e4b80c303/roles/OS-KSADM/c105e3dc4a484f5582563e28f7483edc
{"role": {"id": "c105e3dc4a484f5582563e28f7483edc", "name": "sdn-admin"}}

root@sdnctl1:/var# curl -X GET -H "X-Auth-Token:ADMIN" http://192.168.4.61:35357/v2.0/tenants/575d62cc28bc403c97409072ba6536d3/users/867e7e2e88644e73a4eee25e4b80c303/roles | python -mjson.tool
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   213  100   213    0     0  11715      0 --:--:-- --:--:-- --:--:-- 12529
{
    "roles": [
        {
            "description": "Default role for project membership",
            "enabled": "True",
            "id": "9fe2ff9ee4384b1894a90878d3e92bab",
            "name": "_member_"
        },
        {
            "id": "c105e3dc4a484f5582563e28f7483edc",
            "name": "sdn-admin"
        }
    ]
}

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":"skyline","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, Hewlett Packard Enterprise 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"
       "roles":["sdn-user","sdn-admin"],
    }
}

	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" https://<controller-ip>:8443/sdn/v2.0/systems

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 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 seen in the controller UI in the Configurations screen under the com.hp.sdn/adm/auth.impl.AuthenticationManager component. 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.