Authenticate with the ViPR REST API

TOC

BacktoTop

Overview

ViPR uses a token-based authentication system for all its REST API calls. Examples are provided for authentication with the ViPR REST API, with cookies and without cookies.

This article applies to EMC ViPR 2.0.

Once a user is authenticated against ViPR, an authentication token is returned and can be used to authenticate the user in subsequent calls.

Authentication tokens expire after eight hours or after two hours of idle time. Once expired, the token is internally destroyed. If a client makes a request with the expired token:
  • An HTTP 401 code is returned if the client is automatically following redirects, indicating that you need to login and authenticate to obtain a new token.
  • An HTTP 302 code is returned if the client is not automatically following redirects. The 302 code directs the client to where to get re-authenticated.
Note Image
If running a REST API script, you can get a proxy token to run the script. A proxy token does not expire.
You can retrieve and use authentication tokens by:
  • Saving the X-SDS-AUTH-TOKEN cookie from a successful authentication request and sending that cookie along in subsequent requests.
  • Reading the X-SDS-AUTH-TOKEN HTTP header from a successful authentication request and copying that header into any subsequent request.

This article is part of a series

You can authenticate with the ViPR REST API at any time. However, if you are setting up a virtual data center for the first time, then follow the steps.

  1. Authenticate with the ViPR REST API
  2. Add physical assets to ViPR:
  3. Create ViPR virtual assets:
    1. Create and configure a virtual array
    2. Create virtual pools:

BacktoTop

Authenticate with cookies

This example shows how to use authentication tokens by saving the cookie from a successful authentication request, then passing the cookie in a subsequent request. The examples here are written in curl and formatted for readability.

In this example, you specify the ?using-cookies=true parameter to indicate that you want to receive cookies in addition to the normal HTTP header. This curl command saves the authentication token to a file named cookiefile in the current directory.

curl -L --location-trusted -k https://<ViPR_VIP>:4443/login?using-cookies=true -u "root:Password" -c cookiefile -v

The next command passes the cookie with the authentication token through the -b switch, and returns the user's tenant information.

curl -k https://10.247.100.247:4443/tenant -b cookiefile -v <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <tenant_info><name>Provider Tenant</name> <link href="/tenants/urn:storageos:TenantOrg:d61d9fa1-9886-40ef-85d3-c40b6de2c72f:" rel="self"/> <id>urn:storageos:TenantOrg:d61d9fa1-9886-40ef-85d3-c40b6de2c72f:</id> </tenant_info>

BacktoTop

Authenticate without cookies

This example shows how to use authentication tokens by reading the X-SDS-AUTH-TOKEN http header from a successful authentication request and copying that header into a subsequent request. This example does not use cookies. The examples here are written in curl and formatted for readability.

This command executes a GET on the /login resource. The -u option indicates the user of basic authentication header. The user designation must be included in the request. Upon successful authentication, a HTTP 200 code is returned as well as the X-SDS-AUTH-TOKEN header containing the encoded token.

curl -L --location-trusted -k https://10.247.100.247:4443/login -u "root:ChangeMe" -v > GET /login HTTP/1.1 > Authorization: Basic cm9vdDpDaGFuZ2VNZQ== > User-Agent: curl/7.24.0 (i386-pc-win32) libcurl/7.24.0 OpenSSL/0.9.8t zlib/1.2.5 > Host: 10.247.100.247:4443 > Accept: */* > < HTTP/1.1 200 OK < Date: Tue, 26 Nov 2013 22:18:25 GMT < Content-Type: application/xml < Content-Length: 93 < Connection: keep-alive < X-SDS-AUTH-TOKEN: BAAcQ0xOd3g0MjRCUG4zT3NJdnNuMlAvQTFYblNrPQMAUAQADTEzODU0OTQ4NzYzNTICAAEABQA5dXJu OnN0b3JhZ2VvczpUb2tlbjo2MjIxOTcyZS01NGUyLTRmNWQtYWZjOC1kMGE3ZDJmZDU3MmU6AgAC0A8= < <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <loggedIn> <user>root</user> </loggedIn> * Connection #0 to host 10.247.100.247 left intact * Closing connection #0 * SSLv3, TLS alert, Client hello (1):

The token can then be passed back in the next API call. You can copy the X-SDS-AUTH-TOKEN contents and pass it to the next request through curl's -H switch.

curl https://10.247.100.247:4443/tenant -k -H "X-SDS-AUTH-TOKEN: BAAcOHZLaGF4MTl3eFhpY0czZ0tWUGhJV2xreUE4PQMAUAQADTEzODU0OTQ4NzYzNTICAAEABQA5dXJu OnN0b3JhZ2VvczpUb2tlbjpkYzc3ODU3Mi04NWRmLTQ2YjMtYjgwZi05YTdlNDFkY2QwZDg6AgAC0A8="

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <tenant_info> <name>Provider Tenant</name>\ <link href="/tenants/urn:storageos:TenantOrg:d61d9fa1-9886-40ef-85d3-c40b6de2c72f:" rel="self"/> <id>urn:storageos:TenantOrg:d61d9fa1-9886-40ef-85d3-c40b6de2c72f:</id> </tenant_info>

BacktoTop

How to handle an HTTP 302 authentication redirect

If you try to access a ViPR REST resource without a valid token, ViPR will issue an HTTP 302 redirect code.

An HTTP 302 redirect code includes the URL of the authentication resource, appended with a service= parameter that indicates where to be redirected after successful authentication.

BacktoTop

Handle authentication redirects using cookies

Using cookies, you can automatically follow redirects.

The following curl example allows access to the API resource by passing credentials to it, and passing curl's -L option which instructs curl to automatically follow the redirects. The final HTTP response code is 200 OK, although in the full verbose output you can see how curl received the HTTP 302 Found and automatically followed the redirect.

Request

curl -k "<ViPR_VIP>:4443/tenant?using-cookies=true" -u "root:ChangeMe" -c cookie1 -b cookie1 -L -v

Response

HTTP 200 OK

Response Body

GET /tenant?using-cookies=true HTTP/1.1 Authorization: Basic cm9vdDpDaGFuZ2VNZQ== User-Agent: curl/7.24.0 (i386-pc-win32) libcurl/7.24.0 OpenSSL/0.9.8t zlib/1.2.5 Host: 10.247.100.247:4443 Accept: */* Cookie: X-SDS-AUTH-TOKEN=BAAcVlM5TkkwdnRvUFBJbXJkbzVqSzB3azZBQ0VnPQMAUAQADTEzODU0OTQ4NzYzNTICAAEABQA5dXJuOnN0b3JhZ2VvczpUb2tlbjo3OGM4ODljOS1hZTE5LTQ2NTgtODYxNS00ZDk5YTY xNWVmOTU6AgAC0A8= HTTP/1.1 200 OK Date: Wed, 27 Nov 2013 18:57:12 GMT Content-Type: application/xml Content-Length: 276 Connection: keep-alive <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <tenant_info> <name>Provider Tenant</name> <link href="/tenants/urn:storageos:TenantOrg:d61d9fa1-9886-40ef-85d3-c40b6de2c72f:" rel="self"/> <id>urn:storageos:TenantOrg:d61d9fa1-9886-40ef-85d3-c40b6de2c72f:</id> </tenant_info>

BacktoTop

Handle authentication redirects without using cookies

This example shows what to do when you authenticate with an invalid security token or no token. This example does not use cookies. The examples in this section are written in curl.

In this example, the initial request for the current user's tenant returns an HTTP 302 error. Note the following:

  • The X-SDS-AUTH-TOKEN header has to be copied into each request.
  • The X-SDS-AUTH-TOKEN header is a custom HTTP header.
  • If you are not using cookies, HTTP clients that use the automatically follow redirects option need to disable it. Automatically following redirects would mean the client follows all HTTP 302 responses without copying the custom header. This results in an authentication failure.

Procedure

  1. Request the current user's tenant.
    Request

    curl -k "<ViPR_VIP>:4443/tenant" -v

    Response

    GET /tenants HTTP/1.1 User-Agent: curl/7.24.0 (i386-pc-win32) libcurl/7.24.0 OpenSSL/0.9.8t zlib/1.2.5 Host: 10.247.100.247:4443 Accept: */* HTTP/1.1 302 Found Date: Wed, 27 Nov 2013 15:30:13 GMT Content-Length: 0 Connection: keep-alive Location: <ViPR_VIP>/login?service={LocationString}

  2. Perform a GET against the location in the response body.
    Request

    curl -k "<ViPR_VIP>:4443/login?service={LocationString} -v

    Response

    HTTP/1.1 401 Unauthorized WWW-Authenticate: basic realm="ViPR"

  3. Present basic authentication credentials to the URL returned in step 1.
    Request

    curl -k "<ViPR_VIP>:4443/login?service={LocationString} -v -u "root:ChangeMe"

    On successful authentication, you see another 302 code, this time redirecting you to the original service. The authentication token is also in the HTTP header.

    Response

    GET /login?service={LocationString} HTTP/1.1 > Authorization: Basic cm9vdDpDaGFuZ2VNZQ== > User-Agent: curl/7.24.0 (i386-pc-win32) libcurl/7.24.0 OpenSSL/0.9.8t zlib/1.2.5 > Host: 10.247.100.247:4443 > Accept: */* > < HTTP/1.1 302 Found < Date: Wed, 27 Nov 2013 16:53:28 GMT < Content-Type: application/xml < Content-Length: 0 < Connection: keep-alive < Location: https://10.247.100.247:4443/tenant?auth-redirected < X-SDS-AUTH-TOKEN: {Token_String}

  4. Access the location, making sure to supply the X-SDS-AUTH-TOKEN HTTP header.
    Request

    curl -k <ViPR_VIP>:4443/tenant?auth-redirected -H "X-SDS-AUTH-TOKEN:{token_text}"

    Response

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <tenant_info> <name>Provider Tenant</name> <link href="/tenants/urn:storageos:TenantOrg:d61d9fa1-9886-40ef-85d3-c40b6de2c72f:" rel="self"/> <id>urn:storageos:TenantOrg:d61d9fa1-9886-40ef-85d3-c40b6de2c72f:</id> </tenant_info>

BacktoTop

Logout

The logout API ends a session.

A given user is allowed a maximum of 100 concurrent authentication tokens. Past this limit, the system refuses any new connection for this user until tokens free up. They can free up by expiring naturally, or by explicitly calling this URI:

https://<ViPR_VIP>:4443/logout

If you have multiple sessions running simultaneously, this URI forces the termination of all tokens related to the current user.

GET <ViPR_VIP>:4443/logout?force=true

An example logout request follows.

Request

GET: <ViPR_VIP>:4443/logout X-SDS-AUTH-TOKEN:{Auth_Token}

Pass in the header or cookie with the authentication token to logout.

Response

HTTP 200

BacktoTop

A ViPR user can view their own name, tenant associate, and roles using the whoami API call.

Request

GET <ViPR_VIP>:4443/user/whoami Content-Type: application/xml X-SDS-AUTH-TOKEN: <AUTH_TOKEN>

Response

HTTP 200 Content-Type: application/xml <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <user> <common_name>root</common_name> <distinguished_name>root</distinguished_name> <home_tenant_roles> <home_tenant_role>TENANT_ADMIN</home_tenant_role> </home_tenant_roles> <subtenant_roles/> <tenant>urn:storageos:TenantOrg:6c7dde31-ec48-4028-8672-5e74f5754656:global</tenant> <vdc_roles> <vdc_role>SYSTEM_AUDITOR</vdc_role> <vdc_role>SECURITY_ADMIN</vdc_role> <vdc_role>SYSTEM_ADMIN</vdc_role> <vdc_role>SYSTEM_MONITOR</vdc_role> </vdc_roles> </user>

This example shows the whoami output for the Root user. Root is associated with the tenant indicated in the <tenant> field. Root has the tenant roles listed in the <home_tenant_roles> and <subtenant_roles> fields. It also has the virtual data center roles listed in the <vdc_role> field.