Use a proxyuser to run a ViPR Controller REST API script

Table of Contents

Overview

Because standard ViPR Controller security tokens expire after 8 hours, ViPR Controller provides a special user ID that can run a Controller REST API script on a schedule without having to repeatedly log in. For example, you might set up a script to check particular file services every 12 hours, and take appropriate action in the presence of certain conditions.

The proxy token feature allows a user to retrieve a persistent security token from ViPR Controller, then pass that token to a special user called proxyuser, who runs the script. The proxyuser is a built-in user in ViPR Controller. This user has the PROXY_USER role, and is the only ViPR Controller user that can have that role.

The proxyuser cannot perform any security-related operations. For example, a proxy user cannot register an authentication provider, or do role assignments for a user. The proxyuser is best used for monitoring and provisioning operations.

Back to Top

Use a proxyuser to run a ViPR Controller REST API script

You can use the proxyuser and a proxy token to run a REST API script on a schedule without having to repeatedly authenticate with the REST API. For example, you might set up a script to check particular file services every twelve hours, and take appropriate action in the presence of certain conditions. The proxy token automatically refreshes itself every eight hours when ViPR Controller re-validates that the user who owns the proxy token still exists (either as a built-in user or in your authentication provider repository). If the user no longer exists, then ViPR Controller deletes the proxy token.

Before you begin

You can use a proxy token from a built-in user, such as root, or a user from your authentication provider repository who is mapped to a tenant in ViPR Controller

The EMC ViPR Controller REST API Reference on the ViPR Controller Product Documentation Index provides a description and complete list of parameters for the REST API methods used in this article.

The examples in this section are written in curl, and formatted for readability.

This example uses cookies to authenticate with the ViPR Controller REST API. The ViPR Controller REST API Virtual Data Center Configuration Guide on the ViPR Controller Product Documentation Index provides examples of authentication without cookies and additional information concerning authentication with cookies.

Procedure

  1. Authenticate with the ViPR Controller REST API.
    curl -L --location-trusted -k -c cookie2 -v  <ViPR_Controller_VIP>:4443/login?using-cookies=true -u "bbrown@corp.sean.com:Password1"
    ViPR Controller delivers a standard ViPR Controller authentication token. (This token has an 8 hour timeout.)
  2. Retrieve your user’s proxy token. Each ViPR Controller user has one – and only one – proxy token.
    curl -k <ViPR_Controller_VIP>:4443/proxytoken -b cookie2 -i -v
    
    GET /proxytoken HTTP/1.1
    > User-Agent: curl/7.31.0
    > Host: 10.247.97.127:4443
    > Accept: */*
    > Cookie: X-SDS-AUTH-TOKEN=BAAcSEMrcldVNkJld29GMGZ4cG05UUY5UFZZMjFrPQMAVAQADTEzO
    Tk1MzYxNzYwNTECAAEABQA9dXJuOnN0b3JhZ2VvczpUb2tlbjoyMzgxNGEzNy0yZjhjLTRhYTgtOWVjZ
    i1lNmU5NDVkMmVkZWQ6dmRjMQIAAtAP
    >
    < HTTP/1.1 200 OK
    Date: Fri, 09 May 2014 20:27:29 GMT
    Content-Type: application/xml
    Content-Length: 0
    Connection: keep-alive
    X-SDS-AUTH-PROXY-TOKEN: BAAcc2xpMDVQaXRFUjhVZ1h1YlY2dG1FM2haSWpVPQMAZwQAG3Byb3h5VG9rZW5TaWduYXR1cmVLZXlFbnRyeQIAAQEFAEJ1cm46c3RvcmFnZW9zOlByb3h5VG9rZW46OWQ3MWFmMmUtM2JlMy00ODgyLTkyMmYtODgxNTljMTViMWZiOnZkYzECAALQDw==
    
    The user's proxy token is contained in the header X-SDS-AUTH-PROXY-TOKEN.
  3. Schedule your script to run - say, once every 12 hours. You can use standard scheduling software provided by your platform operating system to do this. For example, CRON is available for most LINUX workstations.
  4. Pass the proxy token - X-SDS-AUTH-PROXY-TOKEN - for your user to the proxyuser. How you do this is specific to your application. One method is to save the token to a file that is accessible by the proxyuser.
  5. Authenticate the proxyuser with the ViPR Controller REST API.
    curl -L --location-trusted -k -i -v <ViPR_Controller_VIP>:4443/login -u "proxyuser:ChangeMe"
    HTTP/1.1 200 OK
    Date: Fri, 09 May 2014 20:27:30 GMT
    Content-Type: application/xml
    Content-Length: 98
    Connection: keep-alive
    X-SDS-AUTH-TOKEN: BAAcZGhOV254WWlTbTlWVVU2bWR3clVVeXZGYkpBPQMAVAQADTEzOTk2MjI5NTg4NTACAAEABQA9dXJuOnN0b3JhZ2VvczpUb2tlbjo5OTVkNjkzNS03ZGUzLTQwODMtYmRhOC0wZDJjMzc2NWE5NDY6dmRjMQIAAtAP
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <loggedIn>
       <user>proxyuser</user>
    </loggedIn>
    
    
    
    The authentication token for the proxyuser is contained in the header X-SDS-AUTH-TOKEN.
  6. Run the REST calls in the script using the X-SDS-AUTH-TOKEN for the proxyuser, and your user's proxy token. In this example, a GET /user/whoami request is sent.
    curl -i -v -k <ViPR_Controller_VIP>:4443/user/whoami -H "X-SDS-AUTH-TOKEN: BAAcZGhOV254WWlTbTlWVVU2bWR3clVVeXZGYkpBPQMAVAQADTEzOTk2MjI5NTg4NTACAAEABQA9dXJuOnN0b3JhZ2VvczpUb2tlbjo5OTVkNjkzNS03ZGUzLTQwODMtYmRhOC0wZDJjMzc2NWE5NDY6dmRjMQIAAtAP" -H "X-SDS-AUTH-PROXY-TOKEN: BAAcc2xpMDVQaXRFUjhVZ1h1YlY2dG1FM2haSWpVPQMAZwQAG3Byb3h5VG9rZW5TaWduYXR1cmVLZXlFbnRyeQIAAQEFAEJ1cm46c3RvcmFnZW9zOlByb3h5VG9rZW46OWQ3MWFmMmUtM2JlMy00ODgyLTkyMmYtODgxNTljMTViMWZiOnZkYzECAALQDw=="
    
    HTTP/1.1 200 OK
    Date: Fri, 09 May 2014 20:27:32 GMT
    Content-Type: application/xml
    Content-Length: 354
    Connection: keep-alive
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <user>
       <common_name>bbrown@corp.sean.com</common_name>
       <distinguished_name>bbrown@corp.sean.com</distinguished_name>
       <home_tenant_roles/>
       <subtenant_roles/>
       <tenant>urn:storageos:TenantOrg:bc782b0a-61d8-48ea-b572-8b765918d880:global</tenant>
       <vdc_roles>
          <vdc_role>SYSTEM_ADMIN</vdc_role>
       </vdc_roles>
    </user>
    As this example shows, even though the authentication token for the proxyuser was passed with the REST call, the script is actually being run as the user whose proxy token was passed in with the request, bbrown@corp.sean.com. The proxy token does not age out. The script can run repeatedly for an indefinite amount of time.
Back to Top

Destroy a proxy token

A proxy token does not expire, and is automatically re-validated every eight hours. A proxy token can be destroyed by the user who created it, or by a ViPR Controller SECURITY_ADMIN. The examples in this section are written in curl, and formatted for readability.

Note Image
If a non built-in user no longer exists in the authentication provider repository when ViPR Controller is re-validating their proxy token, then that proxy token is automatically deleted by ViPR Controller.

To destroy your own proxy token, call:
curl -k "<ViPR_Controller_VIP>:4443/logout?force=true&proxytokens=true" -b cookie1 -v

GET /logout?force=true&proxytokens=true 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: */*
Cookie: X-SDS-AUTH-TOKEN={Token_Text}

HTTP/1.1 200 OK
Date: Wed, 27 Nov 2013 20:49:06 GMT
Content-Type: application/xml
Content-Length: 95
Connection: keep-alive

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<LoggedOut>
   <user>root</user>
</LoggedOut>
To destroy another user’s proxy token, call:
curl -k "<ViPR_Controller_VIP>:4443/logout?force=true&proxytokens=true&username={ViPR_User}" -b cookie1 -v
Back to Top