VMware vRealize Automation - 7.2 Programming Guide
Programming Guide
vRealize Automation 7.2
This document supports the version of each product listed and
supports all subsequent versions until the document is
replaced by a new edition. To check for more recent editions of
this document, see http://www.vmware.com/support/pubs.
EN-002326-00
Programming Guide
You can find the most up-to-date technical documentation on the VMware Web site at:
hp://www.vmware.com/support/
The VMware Web site also provides the latest product updates.
If you have comments about this documentation, submit your feedback to:
docfeedback@vmware.com
Copyright © 2008–2016 VMware, Inc. All rights reserved. Copyright and trademark information.
VMware, Inc.
3401 Hillview Ave.
Palo Alto, CA 94304
www.vmware.com
2 VMware, Inc.
Contents
vRealize Automation Programming Guide 5
Overview of the vRealize Automation REST API 7
1
REST API Authentication 9
2
Using HTTP Bearer Tokens 9
Congure the Duration of an HTTP Bearer Token 9
Request an HTTP Bearer Token 10
Validate an HTTP Bearer Token 12
Delete an HTTP Bearer Token 13
REST API Use Cases 15
3
Create a Tenant 16
Syntax for Displaying Your Current Tenants 18
Syntax for Requesting a New Tenant 20
Syntax for Listing All Tenant Identity Stores 23
Syntax for Linking an Identity Store to the Tenant 25
Syntax for Searching LDAP or Active Directory for a User 29
Syntax for Assigning a User to a Role 30
Syntax for Displaying all Roles Assigned to a User 31
Request a Machine 33
Syntax for Listing Shared and Private Catalog Items 35
Syntax for Geing Information for a Catalog Item 38
Syntax for Geing a Template Request for a Catalog Item 41
Syntax for Requesting a Machine 44
Syntax for Viewing Details of a Machine Request 47
Approve a Machine Request 50
Syntax for Listing Work Items 51
Syntax for Geing Work Item Details 57
Syntax for Constructing a JSON File to Approve a Machine Request 62
Syntax for Approving a Submied Machine Request 65
Syntax for Updating Cost Information 67
List Provisioned Resources 69
Syntax for Displaying Your Provisioned Resources 70
Syntax for Displaying Provisioned Resources by Resource Type 72
Syntax for Displaying All Available Resource Types 75
Syntax for Displaying Provisioned Resources by Business Groups You Manage 76
Syntax for Viewing Machine Details 84
Manage Provisioned Deployments 87
Syntax for Geing Deployment Details 89
Syntax for Navigating to the Children of a Deployed Resource 92
VMware, Inc.
3
Programming Guide
Working with Reservations 101
Working with Reservation Policies 265
Working with Key Pairs 274
Working with Network Proles 287
Get a List of Available IP Ranges for an IPAM Provider 316
Import and Export Content 334
Perform a Day 2 Action: Power O 98
Perform a Day 2 Action: Change Lease 100
Create a Reservation 101
Display a List of Reservations 244
Update a Reservation 254
Delete a Reservation 264
List Reservation Policies 265
Create a Reservation Policy 268
Display a Reservation Policy by ID 270
Update a Reservation Policy 271
Delete a Reservation Policy 273
Get a Key Pair List 274
Create a Key Pair 279
Query a Key Pair 281
Update a Key Pair 283
Delete a Key Pair 285
Get a Network Prole List 287
Create a Network Prole 303
Query a Network Prole 307
Update a Network Prole 313
Delete a Network Prole 315
Syntax for Listing Supported Content Types 335
Syntax for Listing Available Content 339
Syntax for Filtering Content by Content Type 342
Syntax for Creating a Package for Export 343
Syntax for Listing Packages in the Content Service 345
Syntax for Exporting a Package 347
Syntax for Validating a Content Bundle Before Importing 348
Syntax for Importing a Package 350
Understanding Blueprint Schema 351
Manage XaaS Content with Import and Export 353
Related Tools and Documentation 357
4
Using the vRealize Automation API Reference 357
View Reference Information for an API 358
Using vRealize CloudClient 358
Using Third Party Tools 358
Filtering and Formaing REST API
5
Information 361
Index 363
4 VMware, Inc.
vRealize Automation Programming Guide
The Programming Guide provides information about the vRealize Automation REST APIs, including how to
use the REST API services and resources, create HTTP bearer tokens for authentication and authorization,
and construct REST API service calls.
Intended Audience
This information is intended for administrators and programmers who want to congure and manage
vRealize Automation programmatically using the vRealize Automation REST API. The guide focuses on
common use cases. For related information about all available REST API services, see in vRealize Automation
API Reference at hps://www.vmware.com/support/pubs/vcac-pubs.html.
VMware Technical Publications Glossary
VMware Technical Publications provides a glossary of terms that might be unfamiliar to you. For denitions
of terms as they are used in VMware technical documentation, go to
hps://www.vmware.com/support/pubs/vcac-pubs.html.
VMware, Inc.
5
Programming Guide
6 VMware, Inc.
Overview of the vRealize Automation
REST API 1
The vRealize Automation REST API provides consumer, administrator, and provider-level access to the
service catalog with the same services that support the vRealize Automation console user interface. You can
perform vRealize Automation functions programmatically by using REST API service calls.
The vRealize Automation REST API oers the following services and functions.
Table 1‑1. vRealize Automation REST API Services
Service Description
Approval Service Retrieve, create, update, and delete approval policies, policy types,
policy instances, and policy requests.
Branding Service Change the background and text colors, company logo, company
name, product name, tenant name, and other resources in the
console.
Catalog Service Retrieve global and entitled catalog items, and entitlements for a
catalog item and its service that the current user can review. A
consumer can retrieve, edit, and submit a request form for a catalog
item. A provider can retrieve, register, update, and delete catalog
items. Provision and manage systems.
Component Registry Service Access and manage all services and serves as the central view for
all service lookups.
Composition Service Allows vRealize Automation services to register application
components, which the composition service manages so that they
can be used in composite blueprints.
Content Management Service Access and manage the content controller and package controller
for export and import processes. This includes export and import
for blueprints and software.
Endpoint Conguration Service Create, read, update and delete endpoint types, endpoint
categories, and endpoints.
Event Broker Service Provide a central location and a consistent way of recording events
and querying for events.
Forms Service Used internally by the vRealize Automation system to create, read,
update and delete (perform CRUD operations on) request forms for
XaaS components.
IaaS Proxy Provider Service Run a proxy service that acts as a bridge between the service
catalog and the IaaS provider to call other services, such as the
catalog service, composition service, reservation service, and event
broker service.
Identity Service Manage tenants, business groups, SSO and custom groups, users,
and identity stores.
VMware, Inc. 7
Programming Guide
Table 1‑1. vRealize Automation REST API Services (Continued)
Service Description
IP Address Management Service Allocate and deallocate IP addresses from IP address management
Licensing Service Retrieve permissions and post serial keys.
Management Service (Reclamation Service) Retrieve work item forms, callbacks, and tasks. Manage endpoint
Network Service Access and manage application network and security seings for
Notication Service Congure and send notications for several types of events such as
Orchestration Gateway Service Provides a gateway to VMware Realize Orchestrator (vRO) for
Extensibility (Plug-in) Service Retrieve, create, update, and delete a resource. Retrieve an
Portal Service Retrieve, create, update, and delete a portal resource.
Properties Service Manage custom properties, property groups, and property
Reservation Service Retrieve, create, update, and delete a reservation or reservation
Software Services Triggers the execution life cycle of software components using the
vRA Orchestrator Service Manage vRealize Orchestrator actions, tasks, packages, and
Work Item Service Retrieve, create, update, complete, cancel, and delete a work item.
XaaS Service Manages XaaS elements such as forms, endpoints, XaaS blueprints,
(IPAM) providers.
details including tenant, password, user name, and endpoint URL.
Retrieve performance metrics. Retrieve and cancel reclamation
requests.
creating and conguring NAT and routed networks; creating load
balancers; and adding and conguring security groups, security
tags and security policies for application components.
the successful completion of a catalog request or a required
approval.
services running on vRealize Automation. By using the gateway,
consumers of the API can access a vRO instance, and initiate
workows or script actions without having to deal directly with the
vRO APIs.
extension. Retrieve license notications.
denitions. Properties specify items that can be added to blueprints
to trigger vRealize Orchestrator actions.
policy.
software agent, registers software agents, and manages the
creation, modication and deletion of software componentsoftware
component types, software resource requests, and nodes
(machines).
workows. Browse system and plug-in inventories.
Also retrieve form data, metadata, detail forms, and submission
forms from service providers.
tenants, vRealize Orchestrator imports, workows, and work items.
The advanced designer service selection on the vRealize Automation
API Reference landing page selects the documentation for the XaaS
service.
When a service request contains a resource URL, the rst part of the URL identies the service and the last
part identies the resource. For example, the following resource URL identies the catalog service and the
providers resource:
https://$host/component-registry/api/services
For more information about all the vRealize Automation REST API service calls, see “Using the vRealize
Automation API Reference,” on page 357 and the vRealize Automation API Reference in your
vRealize Automation installation.
8 VMware, Inc.
REST API Authentication 2
In the REST API, vRealize Automation requires HTTP bearer tokens in request headers for authentication of
consumer requests. A consumer request applies to tasks that you can perform in the vRealize Automation
console, such as requesting a machine.
To acquire an HTTP bearer token, you authenticate with an identity service that manages the
communication with the SSO server. The identity service returns an HTTP bearer token that you include in
all request headers until the token expires, or you delete it. An HTTP bearer token expires in 24 hours by
default, but you can congure the token with a dierent duration.
Using HTTP Bearer Tokens
You use HTTP bearer tokens for tasks that you can also perform in the vRealize Automation console. You
create a request header with the curl command or with some other utility.
You use HTTP bearer tokens for tasks that you can also perform in the vRealize Automation console. You
create a request header with the curl command or with some other utility.
You use POST, HEAD, and DELETE methods to manage HTTP bearer tokens.
Method URL Description
POST /tokens Authenticate the user with the identity service /tokens and
generate a new token.
HEAD /tokens/tokenID Validate the token tokenID.
DELETE /tokens/tokenID Delete the token tokenID.
Use the following root URL for HTTP bearer calls:
https://$vra_server/identity/api/tokens
Configure the Duration of an HTTP Bearer Token
You set the duration of HTTP bearer tokens in the /etc/vcac/security.properties le on the
vRealize Automation appliance.
The eective duration or lifetime of an HTTP bearer token depends on the duration of its corresponding
SAML token, which the SSO server creates at request time. An HTTP bearer token expires when it reaches
the end of its congured duration, or at the end of the congured duration of the SAML token, whichever
comes rst. For example, if the congured duration is three days for the HTTP bearer token and two days
for the SAML token, the HTTP bearer token expires in two days. A conguration seing on the SSO server
determines the duration of SAML tokens.
VMware, Inc.
9
Programming Guide
Prerequisites
Log in to the vRealize Automation appliance with SSH as root. The password is the one you specied
n
when you deployed the appliance.
The /etc/vcac/security.properties le on the appliance must be editable.
n
Procedure
1 Open the /etc/vcac/security.properties le for editing.
2 Add the following lines to the le, where N is an integer specifying the duration of the token in hours.
identity.basic.token.lifetime.hours=N
#The number is in hours.
3 Save and close the le.
4 Log out of the vRealize Automation appliance.
The new value applies the next time someone requests an HTTP bearer token.
Request an HTTP Bearer Token
You use an HTTP bearer token to authenticate a vRealize Automation REST API consumer request .
A consumer request must specify the correct component registry service and resource. For example, the
URL to obtain an HTTP bearer token must specify the identity service and token resource.
The HTTP bearer token expires in 24 hours by default. See “Congure the Duration of an HTTP Bearer
Token,” on page 9 for information on how to set the duration.
For related information, see “Syntax for Requesting an HTTP Bearer Token,” on page 11.
Prerequisites
Log in to vRealize Automation using the applicable credentials. For example, to assign a user to a role,
n
log in as a tenant administrator.
Verify that the host name and fully qualied domain name of the vRealize Automation instance are
n
available.
Procedure
Enter a curl command in the following format, replacing the variables with the correct values.
u
The variable $vRA used in this example represents the host name.domain name of the
vRealize Automation server, for example, mycompany.mktg.mydomain.com.
curl --insecure -H "Accept: application/json" -H 'Content-Type: application/json'
--data '{"username":"usrname","password":"passwd","tenant":"tenantURLtoken"}'
https://$vRA/identities/api/tokens
For example, enter the following command line:
curl --insecure -H "Accept: application/json" -H 'Content-Type: application/json' --data
'{"username":"TenantAdminUser @example.com","password":"password","tenant":"MYCOMPANY"}'
https://vra.mycompany.com/identities/api/tokens
The command returns a response header with a status code and, if your request is successful, an HTTP
bearer token.
10 VMware, Inc.
Chapter 2 REST API Authentication
For example, the following sample output displays based on the command input:
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Cache-Control: no-cache, no-store
Pragma: no-cache
Expires: Thur, 16 Jul 2015 23:59:59 GMT
Content-Type: application/json;charset=UTF-8
Content-Length: 324
Date: Wed, 15 Jul 2015 13:04:50 GMT
{
"expires":"2015-16-01T13:09:45.619Z",
"id":"MTM5MTI1OTg5MDQwMzozNDQyZWMxZmQ5ZDliODUzMGFiMjp0ZW5hbnQ6cWV1c2VybmFtZTpmcml0ekBjb2tlLmNvb
TplMDViNGU0NGM2ZWU0MWQ1OWEwMTNmZGExNTQwZjNlNGM3YTBlM2I5MDhlYWZjYjY1ZjhiODI2OTg4ODU3M2UwOTUwOWRk
MjlmYWRjNWQ4NjJkOTk1YmE3MTg1MWZhOTc2MjEyYjYxZmU3YTVhZDcwNzM3ZTg3ZDNjNDk2ZDlmNA==",
"tenant":"MYCOMPANY"
}
What to do next
Include the HTTP bearer token in your REST API service calls. You can store the token in a variable such as
$AUTH and then use the variable in your requests.
Syntax for Requesting an HTTP Bearer Token
An HTTP bearer token is required by the REST client to use the vRealize Automation REST API. You can
obtain a bearer token by authenticating to the identity service.
Input
Use the supported input parameters to control the command output.
A consumer request must specify the correct component registry service and resource. For example, the
URL to obtain an HTTP bearer token must contain the identity service and token resource values.
Input Description
host host name.domain name of the vRealize Automation server, for example,
mycompany.mktg.mydomain.com.
usrname Species the tenant administrator user name.
passwd Species the tenant administrator password.
tenantURLtoken Species the tenant URL token determined by the system administrator when
creating the tenant, for example, support.
Output
The following information is displayed as a result of your HTTP bearer token request.
Output Description
expires Contains the ISO 8601 timestamp indicating when the token expires.
id Contains the HTTP bearer token to use in Authorization header in subsequent
requests.
tenant Displays the tenant ID associated with the token.
Response Status Codes
One of the following codes are displayed as a result of your HTTP bearer token request.
VMware, Inc. 11
Programming Guide
Status Code Description
200 OK Your request succeeded and the resource was updated. The
400 BAD REQUEST The data you provided in the POST failed validation.
401 UNAUTHORIZED The request could not authenticate the user or
Example: curl Command
You can enter the following command line format to request an HTTP bearer token.
curl --insecure -H "Accept: application/json" -H 'Content-Type: application/json' --data
'{"username":"usrname",
"password":"passwd","tenant":"tenantURLtoken"}' https://$host/identity/api/tokens
When your request succeeds, the system returns the 200 OK status code, the expiration date and time of the
token, and the HTTP bearer token. After receiving the bearer token, you can include it in your request
headers.
Validate an HTTP Bearer Token
response body contains the full representation of the
resource.
Inspect the response body for details.
authentication credentials required.
You can validate an existing HTTP bearer token.
Prerequisites
“Request an HTTP Bearer Token,” on page 10.
n
Procedure
Create the request to validate the HTTP bearer token, as in the following example.
u
HEAD
/tokens/MTM5MTI1OTg5MDQwMzozNDQyZWMxZmQ5ZDliODUzMGFiMjp0ZW5hbnQ6cWV1c2VybmFtZTjYjY1ZjhiODI2OT
g4O
DU3M2UwOTUwOWRkMjlmYWRjNWQ4NjJkOTk1YmE3MTg1MWZhOTc2MjEyYjYxZmU3YTVhZDcwNzM3ZTg3ZDNjNDk2ZDlmNA
==
Accept: application/json
The system returns one of the following status codes.
Status Code Description
204 NO CONTENT The request succeeded.
401 UNAUTHORIZED You must have authentication credentials to access the resource. All requests must
be authenticated.
403 FORBIDDEN Your authentication credentials do not provide sucient access to the resource.
404 NOT FOUND Could not locate the resource based on the specied URI.
405 METHOD NOT ALLOWED The HEAD method is not supported for the resource.
500 SERVER ERROR Could not create or update the resource because of an internal server error.
12 VMware, Inc.
Chapter 2 REST API Authentication
Delete an HTTP Bearer Token
You can delete an HTTP bearer token.
Prerequisites
“Request an HTTP Bearer Token,” on page 10.
n
Procedure
Create the request to delete the HTTP bearer token, as in the following example.
u
DELETE
/tokens/MTM5MTI1OTg5MDQwMzozNDQyZWMxZmQ5ZDliODUzMGFiMjp0ZW5hbnQ6cWV1c2VybmFtZTjYjY1ZjhiODI2OT
g4O
DU3M2UwOTUwOWRkMjlmYWRjNWQ4NjJkOTk1YmE3MTg1MWZhOTc2MjEyYjYxZmU3YTVhZDcwNzM3ZTg3ZDNjNDk2ZDlmNA
==
Accept: application/json
The system returns one of the following status codes.
Status Code Description
204 NO CONTENT The request succeeded. The resource has been deleted.
401 UNAUTHORIZED You must have authentication credentials to access the resource. All requests must
be authenticated.
403 FORBIDDEN Your authentication credentials do not provide sucient access to the resource.
404 NOT FOUND Could not locate the resource based on the specied URI.
405 METHOD NOT ALLOWED The DELETE method is not supported for the resource.
500 SERVER ERROR Could not create or update the resource because of an internal server error.
VMware, Inc. 13
Programming Guide
14 VMware, Inc.
REST API Use Cases 3
Available use cases provide the prerequisite, command line options and format, and sample results to help
you perform a variety of vRealize Automation functions, such as requesting a machine or creating a
reservation.
You can nd information about all of the available vRealize Automation REST API calls in the vRealize
Automation API Reference zip le located in the vRealize Automation Documentation Center. The use cases
provide samples of calls that you might commonly use and descriptions of example inputs and outputs
relative to those calls.
Create a Tenant on page 16
n
You can use the REST API identity service to create a vRealize Automation tenant and perform related
functions. Perform the tasks required to create a tenant with the REST API in sequence. For
information about creating and working with tenants and roles by using thevRealize Automation
application user interface, see the Tenant Administration and IaaS Conguration documentation.
Request a Machine on page 33
n
You can use REST API catalog service commands to complete a variety of tasks related to requesting a
machine. This procedure provides sample command line syntax for machine request tasks. Supporting
information regarding available input and output parameters, command-line entry samples, and
sample JSON output samples is available in the subsequent topics that explain syntax for the various
tasks.
VMware, Inc.
Approve a Machine Request on page 50
n
You can use a sequence of REST API workitem service commands to approve a machine request.
List Provisioned Resources on page 69
n
You can use the REST API catalog service to log in to vRealize Automation and display a full or
ltered list of your provisioned resources .
Manage Provisioned Deployments on page 87
n
You can use the REST API catalog service to log in to vRealize Automation and view information
about provisioned resources .
Working with Reservations on page 101
n
You can work with the REST API reservation service to perform a variety of functions, such as creating
and updating reservations.
Working with Reservation Policies on page 265
n
You can use the vRealize Automation REST API to work with the reservation service to perform a
variety of functions, such as creating and updating reservation policies.
15
Programming Guide
Working with Key Pairs on page 274
n
You can work with the keyValuePair data element of the REST API workitem service to list, create, and
update key pairs.
Working with Network Proles on page 287
n
You can use the vRealize Automation IaaS proxy provider service and IPAM service REST API to
create, list, and update network proles.
Get a List of Available IP Ranges for an IPAM Provider on page 316
n
You can query a specied IPAM provider endpoint for a list of the available IP address ranges
congured on the IPAM provider device.
Import and Export Content on page 334
n
You can use the REST API content management service to import and export content, such as
blueprints, between vRealize Automation systems.
Create a Tenant
You can use the REST API identity service to create a vRealize Automation tenant and perform related
functions. Perform the tasks required to create a tenant with the REST API in sequence. For information
about creating and working with tenants and roles by using thevRealize Automation application user
interface, see the Tenant Administration and IaaS Conguration documentation.
Prerequisites
Log in to vRealize Automation as a system administrator and a tenant administrator.
n
Verify that there is access to a functional LDAP, Active Directory, or Native Active Directory identity
n
server.
Verify that the identity server details required for the JSON template are available.
n
Verify that the host name and fully qualied domain name of the vRealize Automation instance are
n
available.
Verify that you have a valid HTTP bearer token that matches your login credentials. See Chapter 2,
n
“REST API Authentication,” on page 9.
Syntax for Displaying Your Current Tenants on page 18
n
You can use the REST API identity service to list of all the vRealize Automation tenants in your
system.
Syntax for Requesting a New Tenant on page 20
n
You can use the REST API identity service to submit a request for a tenant. You can specify request
parameters using JSON command line input or by calling an existing JSON le from the command
line.
Syntax for Listing All Tenant Identity Stores on page 23
n
You can use the REST API identity service to list all available identity stores for a named
vRealize Automation tenant, such as the default tenant vsphere.local.
Syntax for Linking an Identity Store to the Tenant on page 25
n
You can use the REST API identity service to link an LDAP, Active Directory, or Native Active
Directory identity store to the vRealize Automation tenant.
Syntax for Searching LDAP or Active Directory for a User on page 29
n
You can use the vRealize Automation REST API identity service to search the congured LDAP
directory, Active Directory, or Native Active Directory for a user.
16 VMware, Inc.
Chapter 3 REST API Use Cases
Syntax for Assigning a User to a Role on page 30
n
You can use the REST API identity service to assign a user to a role.
Syntax for Displaying all Roles Assigned to a User on page 31
n
You can use the REST API identity service to display all of the roles assigned to a user.
Procedure
1 Use the identity service to display all the available tenants.
curl --insecure -H "Accept:text/xml"
-H "Authorization: Bearer $token"
https://$host/identity/api/tenants
2 Submit a request for a new tenant and either call a JSON le that contains tenant request parameters or
specify those parameters using inline text. The rst example uses a JSON le as input. The second
example uses inline text as input.
The rst example calls the following sample newTenant.json le.
{
"@type" : "Tenant",
"id" : "development",
"urlName" : "development",
"name" : "DevelopmentTenant",
"description" : "Tenant for all developers",
"contactEmail" : "admin@mycompany.com",
"defaultTenant" : false
}
Examples Command
Example 1
Call the above newTenant.json file,
which contains parameters for the
tenant request.
Example 2
Specify the parameters for the
tenant request by using inline text.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token"
https://$host/identity/api/tenants/development --data
@C:\Temp\newTenant.json
curl --insecure -H "Accept: application/json" -H "ContentType: application/json"
-H "Authorization: Bearer $token"
--data
'{"@type":"Tenant","id":"development","urlName":"developmen
t","name":
"DevelopmentTenant","description":"Tenant for all
developers","contactEmail":
"admin@mycompany.com","defaultTenant":false}'
3 List all available identity stores for a named tenant, such as the default tenant vsphere.local by using
variables, instead of the full token and host name.domain name.
curl --insecure -H "Accept: application/json" -H 'Content-Type: application/json'
-H "Authorization: Bearer $token” https://$host/identity/api/tenants/MYCOMPANY/directories
4 Link an LDAP, Active Directory, or Native Active Directory identity store to the tenant by using the
identity service.
Call the following sample ldap.json.txt input le from the command line to specify necessary
parameters.
{
"alias": "example.com",
"domain": "example.mycompany.com",
"groupBaseSearchDn": "ou=demo,dc=example,dc=mycompany,dc=com",
VMware, Inc. 17
Programming Guide
"name": "openLDAPDemo",
"password": "password",
"type": "LDAP",
"url": "ldap://10.000.00.000:389",
"userBaseSearchDn": "ou=demo,dc=example,dc=mycompany,dc=com",
"userNameDn": "cn=demoadmin,ou=demo,dc=example,dc=mycompany,dc=com"
}
Use the following command to call the example JSON text le and link an identity store to a tenant. The
command also tests that vRealize Automation can connect to the identity store successfully. If the
command nishes successfully, vRealize Automation succeeded in connecting to the identity store.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token”
https://$host/identity/api/tenants/development/directories/example.mycompany.com
--data @C:\Temp\ldap.json.txt
5 Query the congured LDAP directory, Active Directory, or Native Active Directory for a specic user.
curl --insecure -H "Accept:text/xml"
-H "Authorization: Bearer $token"
https://$host/identity/api/tenants/$tenantId/principals/$userId
6 Assign a user to a role with the REST API identity service.
Use the following command string to submit a request to assign the user tony in the domain
example.mycompany.com to the tenant administrator role. It provides empty braces for the required JSON
payload.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token"
"https://$host/identity/api/authorization/tenants/development/principals/
susan@example.mycompany.com/roles/CSP_TENANT_ADMIN/" --data "{}"
7 Display all of the roles assigned to a user with the identity service.
Use the following command to list all the roles that are assigned to tony@example.mycompany.com.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token"
https://$host/identity/api/authorization/tenants/development/principals/
tony@example.mycompany.com/roles
What to do next
Syntax for Displaying Your Current Tenants
You can use the REST API identity service to list of all the vRealize Automation tenants in your system.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL hps://$host/identity/api/tenants
$host Species the host name and fully qualied domain name or IP address
of the vRealize Automation identity server.
$token Species a valid HTTP bearer token with necessary credentials.
18 VMware, Inc.
Chapter 3 REST API Use Cases
Output
The command output contains property names and values based on the command input parameters.
Parameter Description
Links Species an array of link objects, each of which contains the
following parts:
rel
n
Species the name of the link.
n
Self refers to the object that was returned or
requested. This parameter does not appear when
you query a single prole.
n
First, Previous, Next, and Last refer to
corresponding pages of pageable lists.
Species the application or service that determines
n
the other names.
href
n
Species the URL that produces the result.
Content Species an array of data rows, each of which represents
one of the tenant objects returned in a pageable list. Each
tenant object can contain the following information:
Id:
n
Species the unique tenant identier.
urlName:
n
Species the name of the tenant as it appears in URLs.
Name:
n
Species the name of the tenant for display purposes.
description:
n
Species the long description of the tenant.
contactEmail:
n
Species the primary contact email address.
Password:
n
Unused
defaultTenant:
n
Is set to True if the corresponding tenant is the default
tenant (vsphere.local).
Metadata Species the following paging-related data:
Size: Species the maximum number of rows per page.
n
totalElement: Species the number of rows returned.
n
This parameter is not output when you query for a
single prole.
totalPages: Species the total number of pages of data
n
available.
Number: Species the current page number.
n
Oset: Species the number of rows skipped.
n
VMware, Inc. 19
Programming Guide
Example: curl Command
The following example command displays all available tenants.
curl --insecure -H "Accept:text/xml"
-H "Authorization: Bearer $token"
https://$host/identity/api/tenants
Format the XML output to improve its readability. For information about formaing output, see Chapter 5,
“Filtering and Formaing REST API Information,” on page 361.
Example: JSON Output
The following JSON output is returned based on the command input.
{
"links" : [ ],
"content" : [ {
"@type" : "Tenant",
"id" : "vsphere.local",
"urlName" : "vsphere.local",
"name" : "vsphere.local",
"description" : null,
"contactEmail" : null,
"password" : null,
"defaultTenant" : true
}, {
"@type" : "Tenant",
"id" : "MYCOMPANY",
"urlName" : "MYCOMPANY",
"name" : "QETenant",
"description" : "Test tenant",
"contactEmail" : null,
"password" : "defaultPwd#1",
"defaultTenant" : false
} ],
"metadata" : {
"size" : 19,
"totalElements" : 2,
"totalPages" : 1,
"number" : 1,
"offset" : 0
}
}
Syntax for Requesting a New Tenant
You can use the REST API identity service to submit a request for a tenant. You can specify request
parameters using JSON command line input or by calling an existing JSON le from the command line.
Input
Use the supported input parameters to control the command output.
20 VMware, Inc.
Chapter 3 REST API Use Cases
Parameter Description
URL hps://$host/identity/api/tenants/$tenantId --data @
$inputFileName.json
$token Species a valid HTTP bearer token with necessary credentials.
$host Species the host name and fully qualied domain name or IP
address of the vRealize Automation identity server.
$tenantId Species the ID of the tenant.
$tenantURL Species the URL of the tenant.
$tenantName Species the name of the tenant.
$description Species a description of the tenant.
$emailAddress Species the contact email address for the tenant.
JSON Input File Template
To simplify command line input, create a JSON le and call that le from the command line. To create a
JSON le, copy the following template to a new text le. To maintain formaing, use an XML editor. Replace
the italicized variables in the template with your specic values.
{
"@type" : "Tenant",
"id" : "$tenantId",
"urlName" : "$tenantURL",
"name" : "$tenantName",
"description" : "$description",
"contactEmail" : "$emailAddress",
"defaultTenant" : false
}
Output
The command output contains property names and values based on the command input parameters.
VMware, Inc. 21
Programming Guide
Parameter Description
Links Species an array of link objects, each of which contains the
Content Species an array of data rows, each of which represents
Metadata Species the following paging-related data:
following parts:
rel
n
Species the name of the link.
n
Self refers to the object that was returned or
requested. This parameter does not appear when
you query a single prole.
n
First, Previous, Next, and Last refer to
corresponding pages of pageable lists.
Species the application or service that determines
n
the other names.
href
n
Species the URL that produces the result.
one of the tenant objects returned in a pageable list. Each
tenant object can contain the following information:
Id:
n
Species the unique tenant identier.
urlName:
n
Species the name of the tenant as it appears in URLs.
Name:
n
Species the name of the tenant for display purposes.
description:
n
Species the long description of the tenant.
contactEmail:
n
Species the primary contact email address.
Password:
n
Unused
defaultTenant:
n
Is set to True if the corresponding tenant is the default
tenant (vsphere.local).
Size: Species the maximum number of rows per page.
n
totalElement: Species the number of rows returned.
n
This parameter is not output when you query for a
single prole.
totalPages: Species the total number of pages of data
n
available.
Number: Species the current page number.
n
Oset: Species the number of rows skipped.
n
Example: curl Command
Submit a request for a new tenant and either call a JSON le that contains tenant request parameters or
specify those parameters using inline text. The rst example uses a JSON le as input. The second example
uses inline text as input.
22 VMware, Inc.
Chapter 3 REST API Use Cases
The rst example calls the following sample newTenant.json le.
{
"@type" : "Tenant",
"id" : "development",
"urlName" : "development",
"name" : "DevelopmentTenant",
"description" : "Tenant for all developers",
"contactEmail" : "admin@mycompany.com",
"defaultTenant" : false
}
Example 1: Use the following example to call the above newTenant.json le, which contains parameters for
the tenant request.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token"
https://$host/identity/api/tenants/development --data @C:\Temp\newTenant.json
Example 2: Use the following example to specify parameters for the tenant request by using inline text.
curl --insecure -H "Accept: application/json" -H "Content-Type: application/json"
-H "Authorization: Bearer $token"
--data '{"@type":"Tenant","id":"development","urlName":"development","name":
"DevelopmentTenant","description":"Tenant for all developers","contactEmail":
"admin@mycompany.com","defaultTenant":false}'
Syntax for Listing All Tenant Identity Stores
You can use the REST API identity service to list all available identity stores for a named
vRealize Automation tenant, such as the default tenant vsphere.local.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL hps://$host/identity/api/tenants/$tenantId/directories
$host Species the host name and fully qualied domain name or IP address of the
vRealize Automation identity server.
$token Species a valid HTTP bearer token with necessary credentials.
$tenantId Species the ID of the tenant.
Output
The command output contains property names and values based on the command input parameters.
VMware, Inc. 23
Programming Guide
Parameter Description
Links Species an array of link objects, each of which contains the
Content Species an array of data rows, each of which represents
Metadata Species the following paging-related data:
following parts:
rel
n
Species the name of the link.
n
Self refers to the object that was returned or
requested. This parameter does not appear when
you query a single prole.
n
First, Previous, Next, and Last refer to
corresponding pages of pageable lists.
Species the application or service that determines
n
the other names.
href
n
Species the URL that produces the result.
one of the tenant objects returned in a pageable list. Each
tenant object can contain the following information:
Id:
n
Species the unique tenant identier.
urlName:
n
Species the name of the tenant as it appears in URLs.
Name:
n
Species the name of the tenant for display purposes.
description:
n
Species the long description of the tenant.
contactEmail:
n
Species the primary contact email address.
Password:
n
Unused
defaultTenant:
n
Is set to True if the corresponding tenant is the default
tenant (vsphere.local).
Size: Species the maximum number of rows per page.
n
totalElement: Species the number of rows returned.
n
This parameter is not output when you query for a
single prole.
totalPages: Species the total number of pages of data
n
available.
Number: Species the current page number.
n
Oset: Species the number of rows skipped.
n
Example: curl Command
The following example command lists the identity stores by using variables, instead of the full token and
host name.domain name.
curl --insecure -H "Accept: application/json" -H 'Content-Type: application/json'
-H "Authorization: Bearer $token” https://$host/identity/api/tenants/MYCOMPANY/directories
24 VMware, Inc.
Chapter 3 REST API Use Cases
Example: JSON Output
The following JSON output is returned based on the command input.
HTTP/1.1 200 OK
Server: Apache-Beach/1.1
Cache-Control: no-cache, no-store
Pragma: no-cache
Expires: Wed, 31 Dec 1969 23:59:59 GMT
Content-Type: application/json;charset=UTF-8
Content-Length: 830
Date: Sat, 01 Feb 2014 13:07:54 GMT
{"links":[],
"content":[
{"@type":"IdentityStore",
"domain":"vcac.mycompany.com",
"name":"openLDAPPromocom",
"description":null,
"alias":"promocom.com",
"type":"LDAP",
"userNameDn":"cn=promocomadmin,ou=promocom,dc=vcac,dc=mycompany,dc=com",
"password":null,
"url":"ldap://10.000.00.000:389",
"groupBaseSearchDn":"ou=promocom,dc=vcac,dc=mycompany,dc=com",
"userBaseSearchDn":"ou=promocom,dc=vcac,dc=mycompany,dc=com"
},
{"@type":"IdentityStore",
"domain":"example.mycompany.com",
"name":"openLDAPDemo",
"description":null,
"alias":"example.com",
"type":"LDAP",
"userNameDn":"cn=demoadmin,ou=demo,dc=example,dc=mycompany,dc=com",
"password":null,
"url":"ldap://10.000.00.000:389",
"groupBaseSearchDn":"ou=demo,dc=example,dc=mycompany,dc=com",
"userBaseSearchDn":"ou=demo,dc=example,dc=mycompany,dc=com"
}],
"metadata":{
"size":20,
"totalElements":2,
"totalPages":1,
"number":1,
"offset":0
}
}
Syntax for Linking an Identity Store to the Tenant
You can use the REST API identity service to link an LDAP, Active Directory, or Native Active Directory
identity store to the vRealize Automation tenant.
Input
Use the supported input parameters to control the command output.
VMware, Inc. 25
Programming Guide
Parameter Description
URL hps://$host/identity/api/tenants/$tenantId/directories/$domainName --data
$host Species the host name and fully qualied domain name or IP address of
$token Species a valid HTTP bearer token with necessary credentials.
$tenantId Species the ID of the tenant.
userId Species the ID of the user in the form name@domain.
$domainAlias Species the domain alias.
$domainName Species the domain of the identity store.
$grpBaseSearchDn Species the group search base Distinguished Name.
$identityStoreName Species a description of the new tenant.
$password Species the password.
$identityStoreType Species the identity store type for the tenant. The following values are
$identityServerUrl Species the URL of the identity server.
$usrBaseSearchDn Species the user search base Distinguished Name.
$usrNameDn Species the Distinguished Name for the login user.
@$inputFileName.json
the vRealize Automation identity server.
supported:
LDAP
n
AD
n
NATIVE_AD
n
JSON Input File Template
Use this template to create a JSON input le. Replace the variables in the template with actual values in the
le.
{
"alias": "$domainAlias",
"domain": "$domainName",
"groupBaseSearchDn": "$grpBaseSearchDn",
"name": "$identityStoreName",
"password": "$password",
"type": "$identityStoreType",
"url": "$identityServerUrl",
"userBaseSearchDn": "$usrBaseSearchDn",
"userNameDn": "$usrNameDn"
}
Output
The command output contains property names and values based on the command input parameters.
26 VMware, Inc.
Chapter 3 REST API Use Cases
Parameter Description
Links Species an array of link objects, each of which contains the
following parts:
rel
n
Species the name of the link.
n
Self refers to the object that was returned or
requested. This parameter does not appear when
you query a single prole.
n
First, Previous, Next, and Last refer to
corresponding pages of pageable lists.
Species the application or service that determines
n
the other names.
href
n
Species the URL that produces the result.
Content Species an array of data rows, each of which represents
one of the tenant objects returned in a pageable list. Each
tenant object can contain the following information:
Id:
n
Species the unique tenant identier.
urlName:
n
Species the name of the tenant as it appears in URLs.
Name:
n
Species the name of the tenant for display purposes.
description:
n
Species the long description of the tenant.
contactEmail:
n
Species the primary contact email address.
Password:
n
Unused
defaultTenant:
n
Is set to True if the corresponding tenant is the default
tenant (vsphere.local).
Metadata Species the following paging-related data:
Size: Species the maximum number of rows per page.
n
totalElement: Species the number of rows returned.
n
This parameter is not output when you query for a
single prole.
totalPages: Species the total number of pages of data
n
available.
Number: Species the current page number.
n
Oset: Species the number of rows skipped.
n
Example JSON Input File
Call the following sample ldap.json.txt input le from the command line to specify necessary parameters.
{
"alias": "example.com",
"domain": "example.mycompany.com",
"groupBaseSearchDn": "ou=demo,dc=example,dc=mycompany,dc=com",
"name": "openLDAPDemo",
"password": "password",
"type": "LDAP",
VMware, Inc. 27
Programming Guide
"url": "ldap://10.000.00.000:389",
"userBaseSearchDn": "ou=demo,dc=example,dc=mycompany,dc=com",
"userNameDn": "cn=demoadmin,ou=demo,dc=example,dc=mycompany,dc=com"
}
Example: curl Command
The following example command calls the example JSON text le and links an identity store to a tenant. The
command also tests that vRealize Automation can connect to the identity store successfully. If the command
nishes successfully,vRealize Automation succeeded in connecting to the identity store.
curl --insecure -H "Content-Type: application/json"
-H "Authorization: Bearer $token”
https://$host/identity/api/tenants/development/directories/example.mycompany.com
--data @C:\Temp\ldap.json.txt
Example: JSON Output
This output indicates that an identity store is successfully linked to the specied tenant.
Request Headers
{
Content-Type = application/json
Accept = application/json
Content-Length = 413
Accept-Charset = big5, big5-hkscs, euc-jp, euc-kr, gb18030, gb2312, gbk,
ibm-thai, ibm00858, ibm01140, ibm01141, ibm01142, ibm01143, ibm01144, ibm01145,
ibm01146, ibm01147, ibm01148, ibm01149, ibm037, ibm1026, ibm1047, ibm273, ibm277,
ibm278, ibm280, ibm284, ibm285, ibm290, ibm297, ibm420, ibm424, ibm437, ibm500,
ibm775, ibm850, ibm852, ibm855, ibm857, ibm860, ibm861, ibm862, ibm863, ibm864,
ibm865, ibm866, ibm868, ibm869, ibm870, ibm871, ibm918, iso-2022-cn, iso-2022-jp,
iso-2022-jp-2, iso-2022-kr, iso-8859-1, iso-8859-13, iso-8859-15, iso-8859-2,
iso-8859-3, iso-8859-4, iso-8859-5, iso-8859-6, iso-8859-7, iso-8859-8, iso-8859-9,
jis_x0201, jis_x0212-1990, koi8-r, koi8-u, shift_jis, tis-620, us-ascii, utf-16,
utf-16be, utf-16le, utf-32, utf-32be, utf-32le, utf-8, windows-1250, windows-1251,
windows-1252, windows-1253, windows-1254, windows-1255, windows-1256, windows-1257,
windows-1258, windows-31j, x-big5-hkscs-2001, x-big5-solaris, x-compound_text,
x-euc-jp-linux, x-euc-tw, x-eucjp-open, x-ibm1006, x-ibm1025, x-ibm1046, x-ibm1097,
x-ibm1098, x-ibm1112, x-ibm1122, x-ibm1123, x-ibm1124, x-ibm1364, x-ibm1381,
x-ibm1383, x-ibm300, x-ibm33722, x-ibm737, x-ibm833, x-ibm834, x-ibm856, x-ibm874,
x-ibm875, x-ibm921, x-ibm922, x-ibm930, x-ibm933, x-ibm935, x-ibm937, x-ibm939,
x-ibm942, x-ibm942c, x-ibm943, x-ibm943c, x-ibm948, x-ibm949, x-ibm949c, x-ibm950,
x-ibm964, x-ibm970, x-iscii91, x-iso-2022-cn-cns, x-iso-2022-cn-gb, x-iso-8859-11,
x-jis0208, x-jisautodetect, x-johab, x-macarabic, x-maccentraleurope, x-maccroatian,
x-maccyrillic, x-macdingbat, x-macgreek, x-machebrew, x-maciceland, x-macroman,
x-macromania, x-macsymbol, x-macthai, x-macturkish, x-macukraine, x-ms932_0213,
x-ms950-hkscs, x-ms950-hkscs-xp, x-mswin-936, x-pck, x-sjis_0213, x-utf-16le-bom,
x-utf-32be-bom, x-utf-32le-bom, x-windows-50220, x-windows-50221, x-windows-874,
x-windows-949, x-windows-950, x-windows-iso2022jp
}
Response Headers
{
Date = Wed, 29 Oct 2014 22:41:57 GMT
Content-Type = application/json;charset=UTF-8
Content-Length = 0
Vary = Accept-Encoding,User-Agent
28 VMware, Inc.
Chapter 3 REST API Use Cases
Keep-Alive = timeout=15, max=100
Connection = Keep-Alive
}
Successful
Unlinked Identity Store Error
The following output indicates that an identity store is not linked to the specied tenant. To resolve the
problem, correct the identity store and connection details in the JSON input le and rerun the command.
Command failed [Rest Error]: {Status code: 400}, {Error code: 90027} , {Error
Source: null}, {Error Msg: Cannot connect to the directory service.}, {System
Msg: 90027-Connection to directory service can’t be established}
Syntax for Searching LDAP or Active Directory for a User
You can use the vRealize Automation REST API identity service to search the congured LDAP directory,
Active Directory, or Native Active Directory for a user.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL hps://$host/identity/api/tenants/$tenantId/principals/$userId
$host Species the host name and fully qualied domain name or IP address of the
vRealize Automation identity server.
$token Species a valid HTTP bearer token with necessary credentials.
$tenantId Species the ID of the tenant.
$userId Species the ID of the user in the form name@domain.
Output
The command output contains property names and values based on the command input parameters.
Property Description
Links Species an array of link objects, each of which contains the following parts:
rel
n
Species the name of the link.
n
Self refers to the object that was returned or requested. This parameter does
not appear when you query a single prole.
n
First, Previous, Next, and Last refer to corresponding pages of pageable
lists.
Species the application or service that determines the other names.
n
href
n
Species the URL that produces the result.
@type Species the user name.
rstName Species the rst name of the user.
lastName Species the last name of the user.
description Species the description of the user.
emailAddress Species the email address of the user.
locked Species the Boolean ag indicating if the user is locked out.
VMware, Inc. 29
Programming Guide
Property Description
disabled Species the Boolean ag indicating if the user is disabled.
principalId Species the principal ID of the user in username@domain format.
tenantName Species the name of tenant to which user belongs.
name Species the rst and last name concatenated.
Example: curl Command
The following example command queries the congured LDAP directory for a specic user.
curl --insecure -H "Accept:text/xml"
-H "Authorization: Bearer $token"
https://$host/identity/api/tenants/$tenantId/principals/$userId
Example: JSON Output
The following JSON output is returned based on the command input.
{
"links" : [ ],
"content" : [ {
"@type" : "User",
"firstName" : "Tony",
"lastName" : "Anteater",
"emailAddress" : "tony@example.mycompany.com",
"locked" : false,
"disabled" : false,
"principalId" : {
"domain" : "example.mycompany.com",
"name" : "susan"
},
"tenantName" : "MYCOMPANY1",
"name" : "Tony Anteater"
} ]
}
Syntax for Assigning a User to a Role
You can use the REST API identity service to assign a user to a role.
Input
Use the supported input parameters to control the command output.
Parameter Description
URL hps://$host/identity/api/authorization/tenants/$tenantId/principals/$princi
palId/roles/roleId
$host Species the host name and fully qualied domain name or IP address of
the vRealize Automation identity server.
$token Species a valid HTTP bearer token with necessary credentials.
$tenantId Species the ID of the tenant.
$principalId Species the ID of the user in name@domain format.
$roleId Species the ID of the user role.
30 VMware, Inc.
Loading...