EMC ViPR. Controller REST API Developer Guide. Version

Transcription

1 EMC ViPR Version Controller REST API Developer Gide

2 Copyright EMC Corporation. All rights reserved. Pblished in USA. Pblished Febrary, 2014 EMC believes the information in this pblication is accrate as of its pblication date. The information is sbject to change withot notice. The information in this pblication is provided as is. EMC Corporation makes no representations or warranties of any kind with respect to the information in this pblication, and specifically disclaims implied warranties of merchantability or fitness for a particlar prpose. Use, copying, and distribtion of any EMC software described in this pblication reqires an applicable software license. EMC², EMC, and the EMC logo are registered trademarks or trademarks of EMC Corporation in the United States and other contries. All other trademarks sed herein are the property of their respective owners. For the most p-to-date reglatory docment for yor prodct line, go to EMC Online Spport ( For docmentation on EMC Data Domain prodcts, go to the EMC Data Domain Spport Portal ( EMC Corporation Hopkinton, Massachsetts In North America EMC ViPR Controller REST API Developer Gide

3 CONTENTS Chapter 1 Getting Started with the ViPR Controller REST API 7 Welcome to the ViPR Controller REST API... 8 ViPR REST API access...8 API Ports... 8 Identifying resorces...9 Controller API athentication overview... 9 Bilding an API sper ser Athentication and cookies...11 Athentication redirects...12 Logot...15 Whoami Proxyser Using proxyser to rn a controller REST API script Destroying a proxy token...17 Chapter 2 Setting Up a Single Tenant Environment 19 Single Tenancy vs Mltitenancy...20 Adding sers to the provider tenant with athentication providers Adding an athentication provider Changing the ser mapping in the provider tenant Assigning roles to a tenant...23 Chapter 3 Athorization 25 Athorization overview...26 Virtal data center roles Tenant roles ACLs...29 Virtal array and virtal pool ACLs Examples: Virtal array and virtal pool ACL APIs Project ACLs Examples: Project ACL APIs Examples: Changing a project's owner Chapter 4 ViPR REST API Resorces 35 ViPR services overview System resorces...38 System resorces: virtal array System resorces: virtal pool System resorces: networks and network systems API review: storage systems Tenant and project resorces Chapter 5 Setting Up a Mlti-tenant Environment 51 Prereqisites for creating mltiple tenants Example format: XML Configring mltiple tenants with the REST API...52 EMC ViPR Controller REST API Developer Gide 3

4 CONTENTS Chapter 6 Common Operations 59 Blk operations...60 Searching API resorces...61 Tagging API resorces Tracking asynchronos operations Deactivating, or decommissioning, resorces...63 Chapter 7 Setting Up a Virtal Data Center 65 Setting p the virtal data center...66 Example format: JSON Adding a storage system Registering network systems Registering a RecoverPoint protection system...68 Host Registering hosts and assigning initiators and IP interfaces...70 Setting p the virtal array Setting p the virtal pool Creating a project for a tenant Chapter 8 Managing File Systems and Snapshots 91 File system Creating a file system Expanding a file share Exporting a file system Unexporting a file share Deleting a file system export Deleting a file system Snapshot Creating a file system snapshot Exporting a file system snapshot Restoring a file system snapshot Unexporting a file system snapshot Deleting a file system snapshot Chapter 9 Managing Volmes 111 Create block volme Exporting a volme to a host Creating a block volme snapshot Deleting a block volme snapshot Unexporting a volme from a host Deleting a block volme Chapter 10 Managing Hosts 125 Host API Overview Adding and discovering a Windows host Windows clsters Adding and discovering a LINUX host Adding and discovering a vcenter Server Examples: Accessing vcenter resorces EMC ViPR Controller REST API Developer Gide

5 CONTENTS Chapter 11 Discovering Storage Systems 137 Registering and discovering physical storage systems in VNX Block and VMAX Registering and discovering a VPLEX Registering and discovering an Isilon storage system Registering and discovering a NetApp storage system Registering and discovering a VNX File storage system Chapter 12 User Interface Services 145 Catalog, Services, Orders, and Approvals Accessing UI services UI Services response formats Approval reqests Approving or rejecting Retrieving a list of pending approvals URL notification Asset options Upstream vales Execting a service Service catalog Service descriptors Field descriptors Field validation Type field vales Tracking orders Chapter 13 Error Codes and HTML Retrn Codes 161 Error code descriptions HTTP retrn codes EMC ViPR Controller REST API Developer Gide 5

6 CONTENTS 6 EMC ViPR Controller REST API Developer Gide

7 CHAPTER 1 Getting Started with the ViPR Controller REST API This chapter contains the following topics. Welcome to the ViPR Controller REST API... 8 ViPR REST API access...8 Identifying resorces...9 Controller API athentication overview... 9 Logot...15 Whoami Proxyser Getting Started with the ViPR Controller REST API 7

8 Getting Started with the ViPR Controller REST API Welcome to the ViPR Controller REST API ViPR REST API access The ViPR Controller REST API describes the programmatic interfaces that allow yo to create, read, pdate, and delete resorces in a ViPR data center. This gide shold be sed in conjnction with the ViPR REST API Reference, which contains a comprehensive description of all ViPR resorces, and the REST API calls that manage them. This gide assmes that yo have ViPR installed. For information on installing ViPR, refer to the EMC ViPR Installation and Configration Gide. The ViPR REST API is accessible sing any web browser or programming platform that can isse HTTP reqests. For example, after yo log into ViPR, yo cold type the following URL into a browser to retrieve the crrent ser's tenant. Reqest GET HTTP 200 "name": "Provider Tenant", "id": "rn:storageos:tenantorg:d61d9fa ef-85d3- c40b6de2c72f:", "link":, "href": "/tenants/ rn:storageos:tenantorg:d61d9fa ef-85d3-c40b6de2c72f:" <ViPR_VIP> is the IP address or flly qalified domain name (FQDN) of the pblic virtal IP address of yor ViPR vapp. Port 4443 is the HTTP port sed for REST client access to many services on the ViPR virtal appliance. Other REST services are accessed throgh port 443. (See API Ports on page 8.) To isse POST, PUT, and DELETE HTTP reqests from a web browser, yo need browser plgins, sch as Internet Explorer's httpanalyzer. Most major browsers, sch as Firefox and Chrome, have a poster plgin that will allow yo to call HTTP commands directly from yor browser. Yo can also access the REST API sing scripting platforms sch as crl and perl. EMC also provides a Java client that wraps the ViPR Controller REST API calls in a set of Java classes. API Ports The ViPR Controller REST API ses two different ports. The following table show the services available on each of the two ports sed by the ViPR REST API. 8 EMC ViPR Controller REST API Developer Gide

9 Getting Started with the ViPR Controller REST API REST API Service Port Description ViPR API 4443 (HTTPS) Send ViPR REST API calls to port 4443 to manage resorces controlled by the following services: Block services (volmes, consistency grops, snapshots, exports) File services (file systems, snapshots) Compter services (clster, host, host discovery, ip interface, initiators, vcenter data center, vcenter Virtal Data Center services (block virtal pools, file virtal pools, networks, Storage systems, storage pools, and others.) Tenant and Project services ViPR UI Services API 443 (HTTPS) Send ViPR REST API calls to port 443 to manage the following resorces: Approvals Asset options Catalog Exection window Orders Schema Identifying resorces Each ViPR managed storage resorce is niqely identified by an ID that is generated by ViPR when it is created. A URN is a Uniform Resorce Name. The URN for a resorce is a niqe identifier for the resorce and cannot be changed. To find the URN of a particlar resorce, yo can se the GET resorce_url/blk API call, which gives yo a list of all the URNs of a given resorce class. Then yo can se the URNs obtained from this GET call and se them in the payload of the POST resorce_url/blk call to obtain more detailed information abot the specified resorces. See Blk Operations on page 60 for more information on how to retrieve URNs and details associated with a given resorce URN. Controller API athentication overview Before yo call any ViPR Controller REST API, yo mst sccessflly athenticate a ser. Clients pass secrity credentials to ViPR sing Basic HTTP Athentication. All API reqests are delivered over secre sockets (https). ViPR accepts secrity credentials, and ses them to athenticate the ser against LDAP or Active Directory. Yo can login to ViPR by calling this API: Identifying resorces 9

10 Getting Started with the ViPR Controller REST API Reqest GET ViPR challenges the ser with a dialog box. Enter the name of the ser in the User Name field, and the password of the ser in the Password field. The ViPR API is always accessed over secre sockets, so se HTTPS instead of HTTP. ViPR_VIP is the IP address or Flly Qalified Domain Name(FQDN) of the virtal IP of the ViPR vapp. Use port 4443 for logging in to ViPR with the API. With some application development platforms, yo can pass in ser credentials withot interacting with the ViPR login dialog box. For example, this crl command allows yo to log in as the root ser with a password of ChangeThis: crl <ViPR_VIP>:4443/login - "root:changethis" -k where <ViPR_VIP> is Pblic IP Address>. Note Bilding an API sper ser The <ViPR_VIP> token is sed throghot this docmentation. The ser with which yo log in to ViPR mst have access to the ViPR resorces yo want to manage. It may be convenient to bild a general-prpose sper ser with wide access to ViPR to rn yor API scripts. The root ser is a bilt-in ser in ViPR. It is commonly sed for initial ViPR setp, and can be sed by a Controller REST API application as a sper ser. The root ser has the following roles: SECURITY_ADMIN SYSTEM_ADMIN SYSTEM_MONITOR TENANT_ADMIN SYSTEM_AUDITOR In some data centers, the root ser may be rendered navailable by yor data center administrator. Yo can assign the roles sed by root to a standard LDAP ser by calling the following REST calls: PUT <ViPR_VIP>:4443/tenants/id/role-assignments PUT <ViPR_VIP>:4443/vdc/role-assignments To call either of these APIs, yo need to be athenticated as a ser with the SECURITY_ADMIN role. Athorization on page 25 contains a fll description of the ser roles yo can assign in a ViPR environment. Setting p a single tenant environment on page 19 contains a fll description of setting p ViPR sers and tenants, and assigning roles to those sers. 10 EMC ViPR Controller REST API Developer Gide

11 Getting Started with the ViPR Controller REST API Athentication and cookies Athentication with cookies Athentication withot cookies ViPR ses a token-based athentication system for all its pblic API calls. Once a ser is athenticated against ViPR, an athentication token is retrned and can be sed to athenticate the ser in sbseqent calls. Athentication tokens expire after eight hors or after two hors of idle time. Once expired, the token is internally destroyed and any attempt to call an API with that token retrns an HTTP 401 code. This code indicates yo need to login and athenticate again to obtain a new token. Yo can retrieve and se athentication tokens by: Reading the X-SDS-AUTH-TOKEN HTTP header from a sccessfl athentication reqest and copying that header into any sbseqent reqest. Saving the X-SDS-AUTH-TOKEN cookie from a sccessfl athentication reqest and sending that cookie along in sbseqent reqests. This example shows how to se athentication tokens by reading the X-SDS-AUTH-TOKEN http header from a sccessfl athentication reqest, copying that information into a cookie, then passing the cookie in a sbseqent reqest. The examples here are written in crl and formatted for readability. crl -L --location-trsted -k - "root:password" -c cookiefile -v In this example, yo specify the?sing-cookies=tre parameter to indicate that yo want to receive cookies in addition to the normal HTTP header. This crl command saves the athentication token to a file named cookiefile in the crrent directory. The next command passes the cookie with the athentication token throgh the -b switch, and retrns the ser's tenant information. crl -k -b cookiefile -v <?xml version="1.0" encoding="utf-8" standalone="yes"?> <tenant_info><name>provider Tenant</name> <link href="/tenants/ rn:storageos:tenantorg:d61d9fa ef-85d3-c40b6de2c72f:" rel="self"/> <id>rn:storageos:tenantorg:d61d9fa ef-85d3-c40b6de2c72f:</ id> </tenant_info> This example shows how to se athentication tokens by reading the X-SDS-AUTH-TOKEN http header from a sccessfl athentication reqest and copying that header into a sbseqent reqest. This example does not se cookies. The examples here are written in crl and formatted for readability. crl -L --location-trsted -k - "root:changeme" -v > GET /login HTTP/1.1 > Athorization: Basic cm9vddpdagfz2vnzq== > User-Agent: crl/ (i386-pc-win32) libcrl/ OpenSSL/ 0.9.8t zlib/1.2.5 > Host: :4443 > Accept: */* Athentication and cookies 11

12 Getting Started with the ViPR Controller REST API > < HTTP/ OK < Date: Te, 26 Nov :18:25 GMT < Content-Type: application/xml < Content-Length: 93 < Connection: keep-alive < X-SDS-AUTH-TOKEN: BAAcQ0xOd3g0MjRCUG4zT3NJdnNMlAvQTFYblNrPQMAUAQADTEzODU0OTQ4NzYzNTICAA EABQA5dXJ OnN0b3JhZ2VvczpUb2tlbjo2MjIxOTcyZS01NGUyLTRmNWQtYWZjOC1kMGE3ZDJmZDU3Mm U6AgAC0A8= < <?xml version="1.0" encoding="utf-8" standalone="yes"?> <loggedin> <ser>root</ser> </loggedin> * Connection #0 to host left intact * Closing connection #0 * SSLv3, TLS alert, Client hello (1): This exectes a GET on the /login resorce. The - option indicates the ser of basic athentication header. The ser designation mst be inclded in the reqest. Upon sccessfl athentication, a HTTP 200 code is retrned as well as the X-SDS-AUTH-TOKEN header containing the encoded token. The token can then be passed back in the next API call. Yo can copy the X-SDS-AUTH- TOKEN contents and pass it to the next reqest throgh crl's -H switch. crl -k -H "X-SDS-AUTH-TOKEN: BAAcOHZLaGF4MTl3eFhpY0czZ0tWUGhJV2xreUE4PQMAUAQADTEzODU0OTQ4NzYzNTICAA EABQA5dXJ OnN0b3JhZ2VvczpUb2tlbjpkYzc3ODU3Mi04NWRmLTQ2YjMtYjgwZi05YTdlNDFkY2QwZD g6agac0a8=" Athentication redirects <?xml version="1.0" encoding="utf-8" standalone="yes"?> <tenant_info> <name>provider Tenant</name>\ <link href="/tenants/ rn:storageos:tenantorg:d61d9fa ef-85d3-c40b6de2c72f:" rel="self"/> <id>rn:storageos:tenantorg:d61d9fa ef-85d3-c40b6de2c72f:</ id> </tenant_info> If yo try to access a ViPR REST resorce withot a valid token, ViPR will isse an HTTP 302 redirect code. An HTTP 302 redirect code incldes the URL of the athentication resorce, appended with a service= parameter that indicates where to be redirected after sccessfl athentication. It also incldes a signatre parameter to prevent forgery on the service= parameter. 12 EMC ViPR Controller REST API Developer Gide

13 Getting Started with the ViPR Controller REST API Handling athentication redirects withot sing cookies This example shows what to do when yo athenticate with an invalid secrity token or no token. This example does not se cookies. The examples in this section are written in crl. In this example, the initial reqest for the crrent ser's tenant retrns an HTTP 302 error. Note the following: The X-SDS-AUTH-TOKEN header has to be copied into each reqest. The X-SDS-AUTH-TOKEN header is a cstom HTTP header. If yo are not sing cookies, HTTP clients that se the atomatically follow redirects option need to disable it. Atomatically following redirects wold mean the client follows all HTTP 302 responses withot copying the cstom header. This reslts in an athentication failre. Procedre 1. Reqest the crrent ser's tenant. Reqest crl -k "<ViPR_VIP>:4443/tenant" -v GET /tenants HTTP/1.1 User-Agent: crl/ (i386-pc-win32) libcrl/ OpenSSL/ 0.9.8t zlib/1.2.5 Host: :4443 Accept: */* HTTP/ Fond Date: Wed, 27 Nov :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. Reqest crl -k "<ViPR_VIP>:4443/login?service=LocationString -v HTTP/ Unathorized WWW-Athenticate: basic realm="vipr" 3. Present basic athentication credentials to the URL retrned in step 1. Reqest crl -k "<ViPR_VIP>:4443/login?service=LocationString -v - "root:changeme" On sccessfl athentication, yo see another 302 code, this time redirecting yo to the original service. The athentication token is also in the HTTP header or cookie (depending on whether?sing-cookies=tre appeared in the original reqest). GET /login?service=locationstring HTTP/1.1 > Athorization: Basic cm9vddpdagfz2vnzq== > User-Agent: crl/ (i386-pc-win32) libcrl/ OpenSSL/ 0.9.8t zlib/1.2.5 > Host: :4443 > Accept: */* > < HTTP/ Fond Athentication redirects 13

14 Getting Started with the ViPR Controller REST API Athentication redirects sing cookies < Date: Wed, 27 Nov :53:28 GMT < Content-Type: application/xml < Content-Length: 0 < Connection: keep-alive < Location: < X-SDS-AUTH-TOKEN: Token_String 4. Access the location, making sre to spply either the cookie or the http header. Reqest crl -k <ViPR_VIP>:4443/tenant?ath-redirected -H "X-SDS-AUTH-TOKEN:token_text" <?xml version="1.0" encoding="utf-8" standalone="yes"?> <tenant_info> <name>provider Tenant</name> <link href="/tenants/ rn:storageos:tenantorg:d61d9fa ef-85d3-c40b6de2c72f:" rel="self"/> <id>rn:storageos:tenantorg:d61d9fa ef-85d3-c40b6de2c72f:</ id> </tenant_info> Using cookies, yo can atomatically following redirects. The following crl example allows access to the API resorce by passing credentials to it: Reqest crl -k "<ViPR_VIP>:4443/tenant?sing-cookies=tre" - "root:changeme" -c cookie1 -b cookie1 -L -v HTTP 302 In this example, crl's -L option indicates that we want to follow redirects. Body GET /tenant?sing-cookies=tre HTTP/1.1 Athorization: Basic cm9vddpdagfz2vnzq== User-Agent: crl/ (i386-pc-win32) libcrl/ OpenSSL/0.9.8t zlib/1.2.5 Host: :4443 Accept: */* Cookie: X-SDS-AUTH- TOKEN=BAAcVlM5TkkwdnRvUFBJbXJkbzVqSzB3azZBQ0VnPQMAUAQADTEzODU0OTQ4NzYz NTICAAEABQA5dXJOnN0b3JhZ2VvczpUb2tlbjo3OGM4ODljOS1hZTE5LTQ2NTgtODYxNS 00ZDk5YTY xnwvmotu6agac0a8= HTTP/ OK Date: Wed, 27 Nov :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/rn:storageos:tenantorg:d61d9fa ef-85d3- c40b6de2c72f:" rel="self"/> <id>rn:storageos:tenantorg:d61d9fa ef-85d3-c40b6de2c72f:</id> </tenant_info> 14 EMC ViPR Controller REST API Developer Gide

15 Getting Started with the ViPR Controller REST API Logot The logot API ends a session. A given ser is allowed a maximm of 100 concrrent athentication tokens. Past this limit, the system refses any new connection for this ser ntil tokens free p. They can free p by expiring natrally, or by explicitly calling this URI: If yo have mltiple sessions rnning simltaneosly, this URI forces the termination of all tokens related to the crrent ser. GET <ViPR_VIP>:4443/logot?force=tre An example logot reqest follows. Reqest GET: <ViPR_VIP>:4443/logot X-SDS-AUTH-TOKEN:Ath_Token Pass in the header or cookie with the athentication token to logot. HTTP 200 Whoami A ViPR ser can view their own ser name, tenant association, and roles sing the whoami API call. Reqest GET <ViPR_VIP>:4443/ser/whoami HTTP 200 GET /ser/whoami <ser> <common_name>root</common_name> <distingished_name>root</distingished_name> <roles> <role>system_auditor</role> <role>security_admin</role> <role>system_admin</role> <role>system_monitor</role> <role>tenant_admin</role> </roles> <sbtenant_roles/> <tenant> rn:storageos:tenantorg:7985d df-bba1-29d6a873f811: </tenant> </ser> This example shows the whoami otpt for the Root ser. Root is associated with the tenant indicated in the <tenant> field. Root has the roles listed in the <roles> field. Logot 15

16 Getting Started with the ViPR Controller REST API Proxyser Becase standard ViPR secrity tokens expire after 8 hors, ViPR provides a special ser ID that can rn a Controller REST API script on a schedle withot having to repeatedly log in. For example, yo might set p a script to check particlar file services every 12 hors, and take appropriate action in the presence of certain conditions. The proxy token featre allows a ser to retrieve a persistent secrity token from ViPR, then pass that token to a special ser called proxyser, who rns the script. The proxyser is a bilt-in ser in ViPR. This ser has the PROXY_USER role, and is the only ViPR ser that can have that role. The proxyser cannot perform any secrity-related operations. For example, a proxy ser cannot register an athentication provider, or do role assignments for a ser. The proxyser is best sed for monitoring and provisioning operations. Using proxyser to rn a controller REST API script ViPR provides a way to rn a Controller REST API script on a schedle withot having to repeatedly log in. For example, yo might set p a script to check particlar file services every 12 hors, and take appropriate action in the presence of certain conditions. The examples in this section are written in crl, and formatted for readability. Before yo begin Yo mst have a ser from yor LDAP repository mapped to a tenant in ViPR. Note Bilt-in sers, sch as root, can also se proxy tokens. Procedre 16 EMC ViPR Controller REST API Developer Gide 1. Log in to ViPR. crl -k <ViPR_VIP>:4443/login?sing-cookies -c cookie2 - "myuser@mycompany.com:changethis" ViPR delivers a standard ViPR athentication token. (This token has an 8 hor timeot.) 2. Retrieve yor ser s proxy token. Each ViPR ser has one and only one proxy token. crl -k <ViPR_VIP>:4443/proxytoken -b cookie2 -v GET /proxytoken HTTP/1.1 User-Agent: crl/ (i386-pc-win32) libcrl/ OpenSSL/ 0.9.8t zlib/1.2.5 Host: :4443 Accept: */* Cookie: X-SDS-AUTH-TOKEN=Token_Text HTTP/ OK Date: Wed, 27 Nov :05:02 GMT Content-Type: application/xml Content-Length: 0 Connection: keep-alive X-SDS-AUTH-PROXY-TOKEN: Token_Text The ser's proxy token is contained in the header X-SDS-AUTH-PROXY-TOKEN. 3. Schedle yor script to rn say, once every 12 hors. Yo can se standard schedling software provided by yor platform operating system to do this. For example, CRON is available for most LINUX workstations.

17 Getting Started with the ViPR Controller REST API Destroying a proxy token 4. Pass the proxy token - X-SDS-AUTH-PROXY-TOKEN - for yor ser to the proxyser. How yo do this is specific to yor application. One method is to save the token to a file that is accessible by the proxyser. 5. The proxyser logs in, and ses the LDAP ser s proxy token to rn the schedled script as that ser. For example, if vipr_ser passes a proxy token to proxyser, proxyser can rn vipr_ser s script as vipr_ser sing vipr_ser s proxy token. The proxy token does not age ot. The script can rn repeatedly for an indefinite period of time. A proxy token does not expire, bt it can be destroyed by the ser who created it, or by a ViPR SECURITY_ADMIN. The examples in this section are written in crl, and formatted for readability. To destroy yor own proxy token, call: crl -k "<ViPR_VIP>:4443/logot?force=tre&proxytokens=tre" -b cookie1 -v GET /logot?force=tre&proxytokens=tre HTTP/1.1 User-Agent: crl/ (i386-pc-win32) libcrl/ OpenSSL/0.9.8t zlib/1.2.5 Host: :4443 Accept: */* Cookie: X-SDS-AUTH-TOKEN=Token_Text HTTP/ OK Date: Wed, 27 Nov :49:06 GMT Content-Type: application/xml Content-Length: 95 Connection: keep-alive <?xml version="1.0" encoding="utf-8" standalone="yes"?> <LoggedOt> <ser>root</ser> </LoggedOt> To destroy another ser s proxy token, call: crl -k "<ViPR_VIP>:4443/logot? force=tre&proxytokens=tre&sername=vipr_user" -b cookie1 -v Destroying a proxy token 17

18

19 CHAPTER 2 Setting Up a Single Tenant Environment This chapter contains the following topics. Single Tenancy vs Mltitenancy...20 Adding sers to the provider tenant with athentication providers Setting Up a Single Tenant Environment 19

20 Setting Up a Single Tenant Environment Single Tenancy vs Mltitenancy ViPR atomatically incldes a provider tenant. Tenants allow yo to separate grops of sers and give those grops access to different resorces in yor data center. In some environments, a single tenant is all that is reqired to manage yor data center. In other environments, yo may need mltiple tenants. For example, if yo are a service provider, a mlti-tenant environment may be necessary to separate sers and protect their data. This chapter describes how to se athentication providers to map LDAP sers into the ViPR provider tenant. For information on bilding a mlti-tenant environment with the ViPR REST API, see Setting p a Mlti-tenant Environment on page 51. Adding sers to the provider tenant with athentication providers Adding an athentication provider Athentication providers are added to ViPR to allow sers from Active Directory (AD) or Lightweight Directory Access Protocol (LDAP) v3 compliant servers to athenticate sers and allows those sers to participate in ViPR operations. The first athentication provider yo add to ViPR maps sers from Active Directory or LDAP into the provider tenant. Once an athentication provider is registered, tenants can be configred to restrict access to a sbset of sers and grops obtained from the provider. For example, if an athentication provider is created for domain mycompany.com, the provider tenant can be configred to only accept sers from this domain by adding a tenant ser mapping to it. User mappings for a tenant can be as simple as a single domain name, or as complex as a combination of domain names, grop names and specific ser attribtes fond in the LDAP/AD schema. Yo can se athentication providers to create mlti-tenancy environments where yo create two or more grops of sers, and give those grops access to different resorces in yor data center. Setting p a Mlti-tenant Environment on page 51 describes the API calls reqired to set p a mlti-tenant environment. An athentication provider defines a set of LDAP or Active Directory sers who are initially assigned to the provider tenant. Each of those sers has access to ViPR resorces according to the roles and ACLs assigned to the provider tenant. Before yo begin In this example, yo login as the root ser. By defalt, the root ser has the Secrity Administrator (SECURITY_ADMIN) role on the entire virtal data center. The root ser is allowed to add an athentication provider for the mycompany.com domain. Procedre 1. Login to ViPR as the root ser and obtain an athentication token that can then be sed in sbseqent ViPR API calls. Reqest GET <ViPR_VIP>:4443/login?sing-cookies Provide credentials to satisfy the athentication challenge. 20 EMC ViPR Controller REST API Developer Gide

21 Setting Up a Single Tenant Environment HTTP 200 X-SDS-AUTH-TOKEN:Token_Text <loggedin> <ser>root</ser> </loggedin> 2. POST an athentication provider for the mycompany.com domain. Reqest POST <ViPR_VIP>:4443/vdc/admin/athnproviders 'Content-Type': 'application/xml', 'X-SDS-AUTH-TOKEN': 'Token_Text', 'ACCEPT': 'application/xml' <athnprovider_create> <server_rls> <server_rl>ldap:// </server_rl> </server_rls> <domains> <domain>sanity.local</domain> </domains> <grop_whitelist_vales> <grop_whitelist_vale>*admin*</grop_whitelist_vale> <grop_whitelist_vale>*test*</grop_whitelist_vale> </grop_whitelist_vales> <mode>ad</mode> <name>ad configration2</name> <description>ad configration2</description> <disable>no</disable> <manager_dn>cn=administrator,cn=users,dc=mycompany,dc=com</ manager_dn> <manager_password>p@ssw0rd</manager_password> <search_base>cn=users,dc=mycompany,dc=com</search_base> <search_filter>serprincipalname=%</search_filter> <search_scope>subtree</search_scope> <grop_attribte>cn</grop_attribte> </athnprovider_create> The ViPR Installation and Configration Gide has more information abot the meaning of each athentication provider parameter. HTTP 200 <athnprovider> <creation_time> </creation_time> <id>rn:storageos:athnprovider:0555dc65-598f-4dea-951ad9f5b2b61c5e:</id> <inactive>false</inactive> <link href="/vdc/admin/athnproviders/ rn:storageos:athnprovider:0555dc65-598f-4dea-951a-d9f5b2b61c5e:" rel="self"/> <name>ad configration2</name> <tags/> <description>ad configration2</description> <disable>false</disable> <domains> <domain>mycompany.com</domain> </domains> <grop_attribte>cn</grop_attribte> <grop_whitelist_vales> <grop_whitelist_vale>*admin*</grop_whitelist_vale> <grop_whitelist_vale>*test*</grop_whitelist_vale> </grop_whitelist_vales> <manager_dn>cn=administrator,cn=users,dc=mycompany,dc=com</ manager_dn> <mode>ad</mode> Adding an athentication provider 21

22 Setting Up a Single Tenant Environment <search_base>cn=users,dc=mycompany,dc=com</search_base> <search_filter>serprincipalname=%</search_filter> <search_scope>subtree</search_scope> <server_rls> <server_rl>ldap:// </server_rl> </server_rls> </athnprovider> Changing the ser mapping in the provider tenant In this example, yo modify the provider tenant to inclde a sbset of sers from the domain mycompany.com. Before yo begin Follow the instrctions in the topic Adding an athentication provider on page 20 to set p an athentication provider. This example ses the same athentication token as that procedre. Headers are hidden for brevity. In this example, yo modify the provider tenant to only map sers from the grops AdminUsers and TestUsers in the domain mycompany.com. Users in the domain mycompany.com that are not members of the AdminUsers and TestUsers grops will no longer be mapped into the provider tenant. Modify the provider tenant by sending a PUT reqest to the resorce PUT <ViPR_VIP>:4443/tenants/tenant_rn where tenant_rn is the URN ID of the tenant. In this example, yo athenticate as root and are modifying the provider tenant. Procedre 1. Obtain the URN ID of the provider tenant. The following API call retrns the crrent ser's tenant. The crrent ser is root. Reqest GET <ViPR_VIP>:4443/tenant HTTP 200 GET /tenant 22 EMC ViPR Controller REST API Developer Gide <tenant_info> <name>provider Tenant</name> <link href="/tenants/ rn:storageos:tenantorg:d61d9fa ef-85d3-c40b6de2c72f:" rel="self"/> <id>rn:storageos:tenantorg:d61d9fa ef-85d3- c40b6de2c72f:</id> </tenant_info> 2. Use that URN ID to access the provider tenant and modify it, adding the desired ser mapping. Reqest PUT <ViPR_VIP>:4443/tenants/Tenant_URN <tenant_pdate> <name>provider Tenant</name> <ser_mapping_changes> <add> <ser_mapping> <domain>mycompany.com</domain> <grops> <grop>testusers</grop> <grop>adminusers</grop>

23 Setting Up a Single Tenant Environment Assigning roles to a tenant </grops> </ser_mapping> </add> </ser_mapping_changes> </tenant_pdate> HTTP 200 <tenant> <creation_time> </creation_time> <id>rn:storageos:tenantorg:d61d9fa ef-85d3- c40b6de2c72f:</id> <inactive>false</inactive> <link href="/tenants/ rn:storageos:tenantorg:d61d9fa ef-85d3-c40b6de2c72f:" rel="self"/> <name>provider Tenant</name> <tags/> <description>root Provider Tenant</description> <ser_mappings> <ser_mapping> <attribtes/> <domain>mycompany.com</domain> <grops> <grop>testusers</grop> <grop>adminusers</grop> </grops> </ser_mapping> </ser_mappings> </tenant> For the mapping to be valid, AdminUsers and TestUsers need to be available to ViPR throgh the white list parameter of the athentication provider that this tenant ses. The *Admin* and *Test* expressions (see Adding an athentication provider on page 20) make this possible. Once an athentication provider is available and sers can be mapped to a tenant, roles can be assigned to sers and grops. For example, the Tenant Administrator (TENANT_ADMIN) role can be assigned to a ser. This allows that ser to perform administrative tasks on the tenant, sch as looking at the tenant information. It also allows that ser to assign roles to other sers within the tenant. Assigning the Tenant Administrator role to an Active Directory ser By assigning the TENANT_ADMIN role to a ser, yo allow that ser to perform administrative tasks on the tenant, sch as looking at the tenant information. Before yo begin Yo mst be logged in as a ser with the SECURITY_ADMIN role. The tenantadmin@mycompany.com ser is a valid AD ser who is part of a grop called AdminUsers. This ser is eligible to be TENANT_ADMIN becase the tenant lists AdminUsers as one of the acceptable grops for ser mapping. Procedre 1. Call the following API to apply the role assignment to tenantadmin@mycompany.com. Reqest PUT <ViPR_URL>:4443/tenants/tenant_URN/role-assignments.json Assigning roles to a tenant 23

24 Setting Up a Single Tenant Environment "add": ["sbject_id": "tenantadmin@mycompany.com", "role": ["TENANT_ADMIN"]] where tenant_urn is the ID of the ViPR tenant to which yo are applying the role assignment. The following API retrns the URIs of all tenants known to ViPR. GET <ViPR_URL>:4443/tenants/blk HTTP 200 "link":"rel":"self","href":"/tenants/tenant_urn/roleassignments" "role_assignments": [ "role": ["TENANT_ADMIN"],"sbject_id":"tenantadmin@mycompany.com" "role":["tenant_admin"],"sbject_id":"root" ] 2. To test ot that tenantadmin@mycompany.com has TENANT_ADMIN privileges in this tenant, login with that ser and reqest role assignment information for the provider tenant. Reqest GET <ViPR rl>:4443/login.json - tenantadmin@mycompany.com:password HTTP 200 X-SDS-AUTH-TOKEN:Token_text "ser":"tenantadmin@mycompany.com" Reqest GET <ViPR_URL>:4443/tenants/Privider_Tenant_URI/roleassignments.json X-SDS-AUTH-TOKEN:Token_text HTTP 200 "link":"rel":"self","href":"/tenants/ rn:storageos:tenantorg:d082a5b faf-9e62-ae1c989f1995:/roleassignments" "role_assignments": [ "role": ["TENANT_ADMIN"],"sbject_id":"tenantadmin@mycompany.com" "role":["tenant_admin"],"sbject_id":"root" ] 24 EMC ViPR Controller REST API Developer Gide

25 CHAPTER 3 Athorization This chapter contains the following topics. Athorization overview...26 Virtal data center roles Tenant roles ACLs...29 Virtal array and virtal pool ACLs Project ACLs Athorization 25

26 Athorization Athorization overview Virtal data center roles Athorization in ViPR is controlled by roles and Access Control Lists (ACLs). There are two types of roles (virtal data center roles and tenant level roles), and different types of ACLs. Virtal data center roles are scoped to the entire ViPR virtal data center. Note that they can only be assigned to sers and grops that belong to the top level provider tenant. These roles define what the ser can do at the virtal data center level. The virtal data center level roles are: Secrity Administrator System Administrator System Monitor System Aditor A ser with a Secrity Administrator role can assign roles to sers. In the example below, a Secrity Administrator assigns the Secrity Admin role to a ser with a sbject_id of sername@mycompany.com. Reqest: PUT <ViPR_VIP>/vdc/role-assignments Reqest body <role_assignment_change> <add> <role>security_admin</role> <sbject_id>sername@mycompany.com</sbject_id> </add> </role_assignment_change> HTTP 200 <role_assignments_create> <role_assignment> <role>system_admin</role> <sbject_id>sername@mycompany.com</sbject_id> </role_assignment> <role_assignment> <role>system_auditor</role> <role>security_admin</role> <role>system_monitor</role> <role>system_admin</role> <sbject_id>sername@mycompany.com</sbject_id> </role_assignment> <link href="/vdc/role-assignments" rel="self"/> </role_assignments_create> The following table lists the athorized actions for each ViPR virtal data center level role. Virtal Data Center- Athorized Actions Level Role - - Secrity Administrator Manages the athentication provider configration for the ViPR virtal data center to identify and athenticate sers. Athentication 26 EMC ViPR Controller REST API Developer Gide

27 Athorization Virtal Data Center- Athorized Actions Level Role - - providers are configred to add specified sers into ViPR sing existing Active Directory/Lightweight Directory Access Protocol (AD/ LDAP) ser acconts/domains. Assigns roles and project ACLs to sers or grops. Configres ACLs for virtal arrays and virtal pools to control which tenants may se them. Restores access to tenants and projects, if needed. (For example, in the event that the Tenant Administrator locks himself/herself ot, the Secrity Administrator can reset ser roles to restore access.) Changes ViPR virtal data center properties. Shts down/reboots/restarts ViPR services. Manages ViPR virtal data center software and license pdates. System Administrator Sets p the physical storage infrastrctre of the ViPR virtal data center and carves the physical storage into two types of virtal resorces: virtal arrays and virtal pools. Athorized actions inclde: Adding physical storage resorces into ViPR sch as arrays, ports, pools, switches, and networks. Creating virtal pools; defining storage capabilities and assigning physical storage pools to virtal pools. Creating virtal arrays; partitioning storage into discrete pods of compte, network, and storage resorces to control file system/ volme/object pathing throgh SAN/IP networks. Sets p object storage in the ViPR virtal data center; this incldes creating the object virtal pool and data stores, assigning an IP network to the Object Data Service, and assigning an object namespace to the tenant. Configres Access Control Lists (ACLs) for virtal arrays and virtal pools to control which tenants may se them. Manages the ViPR virtal data center resorces that are not managed by tenants. Retrieves ViPR virtal data center stats and health information. Retrieves blk event and statistical records for the ViPR virtal data center. System Monitor Has read-only access to all resorces in the ViPR virtal data center. Retrieves blk event and statistical records for the ViPR virtal data center. Does not have visibility into secrity-related resorces, sch as athentication providers, ACLs, and role assignments. Retrieves ViPR virtal data center stats and health information. System Aditor Has read-only access to the ViPR virtal data center adit logs. Virtal data center roles 27

28 Athorization Tenant roles Tenant roles are scoped to the tenant in which the assignment is made. Tenant Administrator, Tenant Approver, and Project Administrator are tenant-level roles. Tenant roles can be assigned to sers/grops from the corresponding tenant. These roles define what the ser can do at the tenant level. The tenant level roles are: Tenant Administrator Tenant Approver Project Administrator A ser with a Secrity Admin or Tenant Admin role can assign roles to sers within a tenant. The URL indicates the tenant. In the following example, a Secrity or Tenant Administrator with access to the tenant assigns a Tenant Administrator role to a ser with a sbject ID of ser@mycompany.com. PUT: <ViPR rl>:4443/tenants/<tenant rn>/role-assignments.json Reqest body: "add": ["sbject_id": "ser@mycompany.com", "role": ["TENANT_ADMIN"]] : HTTP 200 The following table lists the athorized actions for each ViPR tenant-level role. Tenant-Level Role Athorized Actions - - Tenant Administrator Creates tenants nder the provider tenant (in a mlti-tenant environment). (In a single-tenant enterprise private clod environment, there is jst the provider tenant and the Tenant Administrator(s) has access to all projects.) Maps AD/LDAP sers into their tenant to define who can log into the tenant. Creates, modifies, and deletes projects in their tenant. Manages resorces in the tenant's projects. Configres ACLs for projects and the Service Catalog in their tenant. Assigns roles to tenant sers. (Can assign Tenant Administrator or Project Administrator roles to other sers.) Tenant Approver Approves or rejects Service Catalog orders in their tenant. Views all approval reqests in their tenant. Project Administrator Creates projects in their tenant, getting an OWN ACL on the created project. 28 EMC ViPR Controller REST API Developer Gide

29 Athorization ACLs An Access Control List (ACL) is a list of permissions attached to a ViPR resorce that specifies which tenants are athorized to access that resorce as well as what operations are allowed on that resorce. ACLs can be assigned to the following ViPR resorces: Block virtal pool File virtal pool Projects Virtal arrays Note Only Project ACLs are managed throgh the ViPR ser interface. Other ACLs mst be managed sing the API. For each virtal array, virtal pool, or project resorce, there is a limit of 100 ACLs. In other words, there is a maximm of 100 ser/grop assignments for projects and 100 tenant assignments for a virtal array or virtal pool. Virtal array and virtal pool ACLs At creation time, virtal arrays and virtal pools are pblic. They are accessible to all tenants. A System or Secrity Administrator can assign an ACL to a virtal pool or virtal array to restrict them to be sed by specified tenants. The ACL permission associated with virtal arrays and pools is of the type USE. If a specific tenant has a USE ACL on a virtal pool, this means that all the sers who are mapped to that tenant will be allowed to se that virtal pool in their provisioning operations. All newly created virtal arrays and pools will have an empty ACL. The System or Secrity Administrator is responsible for managing the ACL. If no ACLs are set, the virtal arrays and pools remain accessible to the provider tenant and all other tenants in the ViPR system. For virtal pools and virtal arrays, yo cannot assign an ACL to a ser (sbject ID) or grop. Only tenants can be assigned ACLs for these resorces. The following table shows the APIs that allow a system or secrity administrator to modify ACLs for virtal arrays and virtal pools. Note that there are separate API calls for file and block virtal pools. API Description - - GET /block/vpools/id/acl Show ACL assignment for block store virtal pool. PUT /block/vpools/id/acl GET /file/vpools/id/acl PUT /file/vpools/id/acl GET /vdc/varrays/id/acl Add or remove block store virtal pool ACL entries. Show ACL entries for file store VirtalPool. Add or remove ACL entries from file store VirtalPool. Show VirtalArray ACL Virtal Array. ACLs 29

30 Athorization API Description - - PUT /vdc/varrays/id/acl Add or remove ACL for VirtalArray Virtal Array. Examples: Virtal array and virtal pool ACL APIs The examples in this section show some commonly-sed APIs for managing virtal array and virtal pool ACLs. Virtal array: Assigning the USE ACL to a tenant The following example shows how to give a tenant privileges to se a virtal array. If no ACL exists on the virtal array, all tenants have access to it. Reqest PUT rn:storageos:virtalarray:f49f6e36-0fe d116204d86:/acl <acl_assignment_changes> <add> <privilege>use</privilege> <tenant>rn:storageos:tenantorg:7985d dfbba1-29d6a873f811:</tenant> </add> </acl_assignment_changes> : HTTP 200 <acl_assignments> <acl_assignment> <privilege>use</privilege> <tenant>rn:storageos:tenantorg:7985d dfbba1-29d6a873f811:</tenant> </acl_assignment> </acl_assignments> Virtal array: Removing the USE ACL from a tenant Reqest PUT rn:storageos:virtalarray:f49f6e36-0fe d116204d86:/acl <acl_assignment_changes> <remove> <privilege>use</privilege> <tenant>rn:storageos:tenantorg:7985d dfbba1-29d6a873f811:</tenant> </remove> </acl_assignment_changes> : HTTP 200 <acl_assignments/> Virtal pool: Assigning the USE ACL to a tenant The following example shows how to give a tenant privileges to se a virtal pool. If no ACL exists on the virtal pool, all tenants have access to it. 30 EMC ViPR Controller REST API Developer Gide

31 Athorization Reqest PUT <ViPR_VIP>/file/vpools/rn:storageos:VirtalPool: fcf2e f11-9e8d3e7e7fa9:/acl <acl_assignment_changes> <add> <privilege>use</privilege> <tenant>rn:storageos:tenantorg:d61d9fa ef-85d3- c40b6de2c72f:</tenant> </add> </acl_assignment_changes> : HTTP 200 <acl_assignments> <acl_assignment> <privilege>use</privilege> <tenant>rn:storageos:tenantorg:d61d9fa ef-85d3- c40b6de2c72f:</tenant> </acl_assignment> </acl_assignments> Project ACLs A Tenant Administrator can access all projects for their tenant. Project Administrators can only access projects that they own. The ACL permissions associated with projects are listed in the following table. The project ACLs can be created or modified by a Tenant Administrator, a Secrity Administrator, or a project owner. Project owners are assigned the OWN ACL. The ser that creates the project is the owner of that project nless they, or a tenant administrator, transfers ownership of that project to another ser. The defalt ACL behavior of a project is different from the defalt ACL behavior of a Virtal Array or Virtal Pool. Whereas, the defalt ACL for a Virtal Array or Virtal Pool enables anyone to se them, the defalt ACL for the Project prevents all bt the Tenant Admin, Secrity Admin, or Project owner from sing it. For other sers or grops to se a project, that ser or grop mst be explicitly added to the ACL for that project. Project ACL Description - - ALL The ser can perform create, read, pdate, and delete (CRUD) operations on file systems, volmes, snapshots, exports, and bckets within the project. BACKUP OWN The ser has read-only access to volmes, file systems and bckets in the project. The ser can create, delete, and export snapshots for volmes and file systems in the project. The ser with the OWN ACL is the project owner. A project owner can do all of the following: Perform CRUD operations on project resorces. Set ACLs on the project. Transfer ownership of the project to another ser. Delete the project. Set project properties, sch as the project name and owner. Project ACLs 31

32 Athorization Project ACL Description - - ANY The ANY ACL appears in the EMC ViPR REST API Reference Gide. It means "any ser that has either the BACKUP or ALL ACL". Examples: Project ACL APIs Newly created projects will have an empty ACL. The Tenant Administrator or the project owner is responsible for managing the ACL. The examples in this section show some commonly-sed APIs for managing project ACLs. Get the ACLs for a project Reqest GET /projects/project_urn/acl <acl_assignments> <acl_assignment> <privilege>all</privilege> <sbject_id>jordab@sanity.local</sbject_id> </acl_assignment> <acl_assignment> <privilege>backup</privilege> <sbject_id>jordab2@sanity.local</sbject_id> </acl_assignment> </acl_assignments> Assigning the USE ACL to a ser The following example sets the project ACL sing a ser's sbject_id. A sbject_id or grop can be assigned the ALL or BACKUP permission. Reqest PUT <ViPR_VIP>/projects/<project rn>/acl <acl_assignment_changes> <add> <privilege>all</privilege> <sbject_id>jordab2@sanity.local</sbject_id> </add> </acl_assignment_changes> HTTP 200 <acl_assignments> <acl_assignment> <privilege>all</privilege> <sbject_id>jordab@sanity.local</sbject_id> </acl_assignment> <acl_assignment> <privilege>all</privilege> <privilege>backup</privilege> <sbject_id>jordab2@sanity.local</sbject_id> </acl_assignment> </acl_assignments> 32 EMC ViPR Controller REST API Developer Gide

33 Athorization Examples: Changing a project's owner The example in this section shows how to change the owner of a project. The OWN ACL is assigned to a project's creator, giving that ser ownership rights to that project. A tenant admin, a project admin or the project's owner can reassign the ownership of the project to another ser. Checking the owner of a project The ser that owns the project is displayed in the <owner> field of the project resorce. Here, the ser jordab@sanity.local is displayed as the project owner. GET /projects/project_rn <project> <creation_time> </creation_time> <id>rn:storageos:project:2c4d5503-a d a08e4bd3ee3:</id> <inactive>false</inactive> <link href="/projects/rn:storageos:project:2c4d5503- a d a08e4bd3ee3:" rel="self"/> <name>project1</name> <tags/> <owner>jordab@sanity.local</owner> <tenant> <id>rn:storageos:tenantorg:d61d9fa ef-85d3- c40b6de2c72f:</id> <link href="/tenants/ rn:storageos:tenantorg:d61d9fa ef-85d3-c40b6de2c72f:" rel="self"/> </tenant> </project> Changing the owner of a project This example changes the ownership of the project shown in the previos example to jordab2@sanity.local. Note that this is done by changing the owner attribte of the project, rather than throgh an ACL call. Reqest PUT /projects/project_urn <project_pdate> <owner>jordab2@sanity.local</owner> </project_pdate> HTTP 200 Examples: Changing a project's owner 33