VMware vRealize Automation - 6.2 Programming Guide
Programming Guide
vRealize Automation 6.2
Programming Guide
You can find the most up-to-date technical documentation on the VMware website at:
https://docs.vmware.com/
If you have comments about this documentation, submit your feedback to
docfeedback@vmware.com
VMware, Inc.
3401 Hillview Ave.
Palo Alto, CA 94304
www.vmware.com
Copyright © 2008–2016 VMware, Inc. All rights reserved. Copyright and trademark information.
VMware, Inc. 2
Contents
vRealize Automation Programming Guide 5
Updated Information 6
Overview of the vRealize Automation REST API 7
1
REST API Authentication 9
2
Using HTTP Bearer Tokens 9
Configure the Duration of an HTTP Bearer Token 9
Request an HTTP Bearer Token 10
Validate an HTTP Bearer Token 13
Delete an HTTP Bearer Token 13
REST API Use Cases 15
3
Create a Tenant 15
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 26
Syntax for Searching LDAP or Active Directory for a User 30
Syntax for Assigning a User to a Role 32
Syntax for Displaying all Roles Assigned to a User 32
Requesting a Machine By Type 35
Request a Machine 35
Request a vCloud Air Machine 59
Request an Amazon Machine 75
Approve a Machine Request 91
Syntax for Listing Work Items 92
Syntax for Getting Work Item Details 98
Syntax for Constructing a JSON File to Approve a Machine Request 103
Syntax for Approving a Submitted Machine Request 106
List Provisioned Resources 108
Syntax for Displaying Your Provisioned Resources 109
Syntax for Displaying Provisioned Resources by Resource Type 111
Syntax for Displaying All Available Resource Types 114
Syntax for Displaying Provisioned Resources by Business Groups You Manage 116
Syntax for Viewing Machine Details 123
VMware, Inc.
3
Programming Guide
Reprovision a Machine Resource 127
Working with Reservations 130
Working with Reservation Policies 303
Working with Key Pairs 314
Working with Network Profiles 328
Syntax for Viewing Available Actions for a Provisioned Machine 127
Syntax for Reprovisioning a Provisioned Machine 129
Create a Reservation 131
Display a List of Reservations 281
Update a Reservation 292
Delete a Reservation 302
List Reservation Policies 303
Create a Reservation Policy 306
Display a Reservation Policy by ID 308
Update a Reservation Policy 310
Delete a Reservation Policy 312
Get a Key Pair List 314
Create a Key Pair 319
Query a Key Pair 322
Update a Key Pair 323
Delete a Key Pair 326
Get a Network Profile List 328
Create a Network Profile 367
Query a Network Profile 370
Update a Network Profile 392
Delete a Network Profile 395
Filtering and Formatting REST API Information 397
4
Related Tools and Documentation 398
5
Using the vRealize Automation REST API Reference 398
Using vRealize CloudClient 399
Using the API Explorer 399
Install the API Explorer 399
Choosing Your Mode of Operation 400
Log in with the API Explorer 403
Suppress Log Files 405
Creating an API Explorer Command Using Supplied curl Examples 405
Using Third Party Tools 406
VMware, Inc. 4
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 configure 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 REST API
Reference at https://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
definitions of terms as they are used in VMware technical documentation, go to
https://www.vmware.com/support/pubs/vcac-pubs.html.
VMware, Inc.
5
Updated Information
This Programming Guide is updated with each release of the product or when necessary.
This table provides the update history of the Programming Guide.
Revision Description
EN-001636-04 Updated the input URL in Syntax for Displaying All Available Resource Types.
EN-001636-03
EN-001636-02
n
Removed the section titled Logging in Programmatically.
n
Minor reorganization of Using the API Explorer.
n
Updated the format of the Use Cases section topics.
n
Updated the order of topics in the Authentication, Filtering, and Related Tools sections.
EN-001636-01 Updated the documentation to include the following changes:
n
Added new topic section Working with Key Pairs.
n
Added new topic section Working with Network Profiles.
n
Added new topic Syntax for Creating a vCloud Reservation.
n
Added new topic Syntax for Creating an Amazon Reservation.
n
Added new topic Get Resources Schema for an Amazon EC2 Reservation Syntax.
n
Added new topic Get Resources Schema for a vCloud Reservation Syntax.
n
Added new topic Syntax for Displaying a Schema Definition for an Amazon Reservation.
n
Added new topic Syntax for Displaying a Schema Definition for a vCloud Reservation.
n
Added new topic Creating an API Explorer Command Using Supplied curl Examples.
n
Added Amazon EC2 and vCloud information to Syntax for Getting a Compute Resource for a Reservation.
n
Updated Syntax for Constructing a JSON File For a Machine Request and Syntax for Requesting a Machine.
n
Updated Syntax for Constructing a JSON File for a vCloud Air Machine Request and Syntax for Requesting a
vCloud Air Machine.
n
Updated Syntax for Constructing a JSON File for an Amazon Machine Request and Syntax for Requesting an
Amazon Machine.
n
Revised topic flow and content formatting throughout the guide.
EN-001636-00 Initial 6.2 release.
VMware, Inc. 6
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 offers the following services and functions.
Table 1‑1. vRealize Automation REST API Services
Service Description
Advanced Designer Service Manage Advanced Service Designer elements such as forms, endpoints
vRealize Orchestrator workflows, and work items through the Advanced
Designer Service.
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 Access and manage all services and serves as the central view for all
service lookups.
Event Log Service Provide a central location and a consistent way of recording events and
querying for events.
File Service Unused.
Identity Service Manage tenants, business groups, SSO and custom groups, users, and
identity stores.
Licensing Service Retrieve permissions and post serial keys.
Management Service Retrieve work item forms, callbacks, and tasks. Manage endpoint details
including tenant, password, user name, and endpoint URL. Retrieve
performance metrics. Retrieve and cancel reclamation requests.
Notification Service Configure and send notifications for several types of events such as the
successful completion of a catalog request or a required approval.
Plug-in Service Retrieve, create, update, and delete a resource. Retrieve an extension.
Retrieve license notifications.
VMware, Inc. 7
Programming Guide
Table 1‑1. vRealize Automation REST API Services (Continued)
Service Description
Portal Service Retrieve, create, update, and delete a portal resource.
Reservation Service Retrieve, create, update, and delete a reservation or reservation policy.
vCO Service Manage vRealize Orchestrator actions, tasks, packages, and workflows.
Browse system and plug-in inventories.
WorkItem Service Retrieve, create, update, complete, cancel, and delete a work item. Also
retrieve form data, metadata, detail forms, and submission forms from
service providers.
When a service request contains a resource URL, the first part of the URL identifies the service and the
last part identifies the resource. For example, the following resource URL identifies 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 REST API Reference and the REST API Reference in the vRealize Automation
Documentation Center at https://www.vmware.com/support/pubs/vcac-pubs.html.
VMware, Inc. 8
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 configure the token with a different 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.
For information about requesting a bearer token, see the Identity option on the REST API Reference
landing page.
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.
The root URL for HTTP bearer calls is 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 file on the
vRealize Automation appliance.
VMware, Inc.
9
Programming Guide
The effective 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 configured duration, or at the end of the configured duration of the SAML token,
whichever comes first. For example, if the configured 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 configuration setting on
the SSO server determines the duration of SAML tokens.
Prerequisites
n
Log in to the vRealize Automation appliance with SSH as root. The password is the one you specified
when you deployed the appliance.
n
The /etc/vcac/security.properties file on the appliance must be editable.
Procedure
1 Open the /etc/vcac/security.properties file for editing.
2 Add the following lines to the file, 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 file.
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 Configure the Duration of an HTTP Bearer
Token for information on how to set the duration.
For related information, see Syntax for Requesting an HTTP Bearer Token.
Prerequisites
n
Log in to vRealize Automation using the applicable credentials. For example, to assign a user to a
role, log in as a tenant administrator.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
VMware, Inc. 10
Programming Guide
Procedure
u
Enter a curl command in the following format, replacing the variables with the correct values.
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.
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.
VMware, Inc. 11
Programming Guide
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 Specifies the tenant administrator user name.
passwd Specifies the tenant administrator password.
tenantURLtoken Specifies 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.
Status Code Description
200 OK Your request succeeded and the resource was updated. The
response body contains the full representation of the resource.
400 BAD REQUEST The data you provided in the POST failed validation. Inspect the
response body for details.
401 UNAUTHORIZED The request could not authenticate the user or authentication
credentials required.
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.
VMware, Inc. 12
Programming Guide
Validate an HTTP Bearer Token
You can validate an existing HTTP bearer token.
Prerequisites
n
Request an HTTP Bearer Token.
Procedure
u
Create the request to validate the HTTP bearer token, as in the following example.
HEAD
/tokens/MTM5MTI1OTg5MDQwMzozNDQyZWMxZmQ5ZDliODUzMGFiMjp0ZW5hbnQ6cWV1c2VybmFtZTjYjY1ZjhiODI2OTg4O
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 sufficient access to the resource.
404 NOT FOUND Could not locate the resource based on the specified 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.
Delete an HTTP Bearer Token
You can delete an HTTP bearer token.
Prerequisites
n
Request an HTTP Bearer Token.
Procedure
u
Create the request to delete the HTTP bearer token, as in the following example.
DELETE
/tokens/MTM5MTI1OTg5MDQwMzozNDQyZWMxZmQ5ZDliODUzMGFiMjp0ZW5hbnQ6cWV1c2VybmFtZTjYjY1ZjhiODI2OTg4O
DU3M2UwOTUwOWRkMjlmYWRjNWQ4NjJkOTk1YmE3MTg1MWZhOTc2MjEyYjYxZmU3YTVhZDcwNzM3ZTg3ZDNjNDk2ZDlmNA==
Accept: application/json
The system returns one of the following status codes.
VMware, Inc. 13
Programming Guide
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 sufficient access to the resource.
404 NOT FOUND Could not locate the resource based on the specified 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. 14
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 find information about all of the available vRealize Automation REST API calls in the REST API
Reference zip file 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.
This chapter includes the following topics:
n
Create a Tenant
n
Requesting a Machine By Type
n
Approve a Machine Request
n
List Provisioned Resources
n
Reprovision a Machine Resource
n
Working with Reservations
n
Working with Reservation Policies
n
Working with Key Pairs
n
Working with Network Profiles
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 Configuration documentation.
Prerequisites
n
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
server.
VMware, Inc.
15
Programming Guide
n
Verify that the identity server details required for the JSON template are available.
n
Verify that the host name and fully qualified domain name of the vRealize Automation instance are
available.
n
If you are not using the API Explorer, verify that you have a valid HTTP bearer token that matches
your login credentials. See Chapter 2 REST API Authentication.
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 file that contains tenant request parameters
or specify those parameters using inline text. The first example uses a JSON file as input. The
second example uses inline text as input.
The first example calls the following sample newTenant.json file.
{
"@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":"development","
name":
"DevelopmentTenant","description":"Tenant for all
developers","contactEmail":
"admin@mycompany.com","defaultTenant":false}'
VMware, Inc. 16
Programming Guide
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 file 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",
"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 file 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 finishes 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 configured LDAP directory, Active Directory, or Native Active Directory for a specific 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 "{}"
VMware, Inc. 17
Programming Guide
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 https://$host/identity/api/tenants
$host Specifies the host name and fully qualified domain name or IP address of the
vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
Output
The command output contains property names and values based on the command input parameters.
VMware, Inc. 18
Programming Guide
Parameter Description
Links Specifies an array of link objects, each of which contains the
following parts:
n
rel
Specifies the name of the link.
n
Self refers to the object that was returned or requested.
n
First, Previous, Next, and Last refer to
corresponding pages of pageable lists.
n
Specifies the application or service that determines the
other names.
n
href
Specifies the URL that produces the result.
Content Specifies 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:
n
Id:
Specifies the unique tenant identifier.
n
urlName:
Specifies the name of the tenant as it appears in URLs.
n
Name:
Specifies the name of the tenant for display purposes.
n
description:
Specifies the long description of the tenant.
n
contactEmail:
Specifies the primary contact email address.
n
Password:
Unused
n
defaultTenant:
Is set to True if the corresponding tenant is the default
tenant (vsphere.local).
Metadata Specifies the following paging-related data:
n
Size: Specifies the maximum number of rows per page.
n
totalElement: Specifies the number of rows returned.
n
totalPages: Specifies the total number of pages of data
available.
n
Number: Specifies the current page number.
n
Offset: Specifies the number of rows skipped.
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 formatting output, see Chapter 4
Filtering and Formatting REST API Information.
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 file from the command line.
VMware, Inc. 20
Programming Guide
Input
Use the supported input parameters to control the command output.
Parameter Description
URL https://$host/identity/api/tenants/$tenantId --data @
$inputFileName.json
$token Specifies a valid HTTP bearer token with necessary credentials.
$host Specifies the host name and fully qualified domain name or IP address
of the vRealize Automation identity server.
$tenantId Specifies the ID of the tenant.
$tenantURL Specifies the URL of the tenant.
$enantName Specifies the name of the tenant.
$description Specifies a description of the tenant.
$emailAddress Specifies the contact email address for the tenant.
JSON Input File Template
To simplify command line input, create a JSON file and call that file from the command line. To create a
JSON file, copy the following template to a new text file. To maintain formatting, use an XML editor.
Replace the italicized variables in the template with your specific 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 Specifies an array of link objects, each of which contains the
following parts:
n
rel
Specifies the name of the link.
n
Self refers to the object that was returned or requested.
n
First, Previous, Next, and Last refer to
corresponding pages of pageable lists.
n
Specifies the application or service that determines the
other names.
n
href
Specifies the URL that produces the result.
Content Specifies 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:
n
Id:
Specifies the unique tenant identifier.
n
urlName:
Specifies the name of the tenant as it appears in URLs.
n
Name:
Specifies the name of the tenant for display purposes.
n
description:
Specifies the long description of the tenant.
n
contactEmail:
Specifies the primary contact email address.
n
Password:
Unused
n
defaultTenant:
Is set to True if the corresponding tenant is the default
tenant (vsphere.local).
Metadata Specifies the following paging-related data:
n
Size: Specifies the maximum number of rows per page.
n
totalElement: Specifies the number of rows returned.
n
totalPages: Specifies the total number of pages of data
available.
n
Number: Specifies the current page number.
n
Offset: Specifies the number of rows skipped.
Example: curl Command
Submit a request for a new tenant and either call a JSON file that contains tenant request parameters or
specify those parameters using inline text. The first example uses a JSON file as input. The second
example uses inline text as input.
VMware, Inc. 22
Programming Guide
The first example calls the following sample newTenant.json file.
{
"@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 file, 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 https://$host/identity/api/tenants/$tenantId/directories
$host Specifies the host name and fully qualified domain name or IP address of the
vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
$tenantId Specifies 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 Specifies an array of link objects, each of which contains the
following parts:
n
rel
Specifies the name of the link.
n
Self refers to the object that was returned or requested.
n
First, Previous, Next, and Last refer to
corresponding pages of pageable lists.
n
Specifies the application or service that determines the
other names.
n
href
Specifies the URL that produces the result.
Content Specifies 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:
n
Id:
Specifies the unique tenant identifier.
n
urlName:
Specifies the name of the tenant as it appears in URLs.
n
Name:
Specifies the name of the tenant for display purposes.
n
description:
Specifies the long description of the tenant.
n
contactEmail:
Specifies the primary contact email address.
n
Password:
Unused
n
defaultTenant:
Is set to True if the corresponding tenant is the default
tenant (vsphere.local).
Metadata Specifies the following paging-related data:
n
Size: Specifies the maximum number of rows per page.
n
totalElement: Specifies the number of rows returned.
n
totalPages: Specifies the total number of pages of data
available.
n
Number: Specifies the current page number.
n
Offset: Specifies the number of rows skipped.
VMware, Inc. 24
Programming Guide
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
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,
VMware, Inc. 25
Programming Guide
"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.
Parameter Description
URL https://$host/identity/api/tenants/$tenantId/directories/$domainName --data @
$inputFileName.json
$host Specifies the host name and fully qualified domain name or IP address of the
vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
$tenantId Specifies the ID of the tenant.
userId Specifies the ID of the user in the form name@domain.
$domainAlias Specifies the domain alias.
$domainName Specifies the domain of the identity store.
$grpBaseSearchDn Specifies the group search base Distinguished Name.
$identityStoreName Specifies a description of the new tenant.
$password Specifies the password.
$identityStoreType Specifies the identity store type for the tenant. The following values are
supported:
n
LDAP
n
AD
n
NATIVE_AD
$identityServerUrl Specifies the URL of the identity server.
$usrBaseSearchDn Specifies the user search base Distinguished Name.
$usrNameDn Specifies the Distinguished Name for the login user.
JSON Input File Template
Use this template to create a JSON input file. Replace the variables in the template with actual values in
the file.
{
"alias": "$domainAlias",
"domain": "$domainName",
"groupBaseSearchDn": "$grpBaseSearchDn",
VMware, Inc. 26
Programming Guide
"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.
VMware, Inc. 27
Programming Guide
Parameter Description
Links Specifies an array of link objects, each of which contains the
following parts:
n
rel
Specifies the name of the link.
n
Self refers to the object that was returned or requested.
n
First, Previous, Next, and Last refer to
corresponding pages of pageable lists.
n
Specifies the application or service that determines the
other names.
n
href
Specifies the URL that produces the result.
Content Specifies 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:
n
Id:
Specifies the unique tenant identifier.
n
urlName:
Specifies the name of the tenant as it appears in URLs.
n
Name:
Specifies the name of the tenant for display purposes.
n
description:
Specifies the long description of the tenant.
n
contactEmail:
Specifies the primary contact email address.
n
Password:
Unused
n
defaultTenant:
Is set to True if the corresponding tenant is the default
tenant (vsphere.local).
Metadata Specifies the following paging-related data:
n
Size: Specifies the maximum number of rows per page.
n
totalElement: Specifies the number of rows returned.
n
totalPages: Specifies the total number of pages of data
available.
n
Number: Specifies the current page number.
n
Offset: Specifies the number of rows skipped.
VMware, Inc. 28
Programming Guide
Example JSON Input File
Call the following sample ldap.json.txt input file 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",
"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 file 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 finishes 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 specified 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,
VMware, Inc. 29
Programming Guide
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
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 specified tenant. To resolve the
problem, correct the identity store and connection details in the JSON input file 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 configured 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 https://$host/identity/api/tenants/$tenantId/principals/$userId
$host Specifies the host name and fully qualified domain name or IP address of the
vRealize Automation identity server.
$token Specifies a valid HTTP bearer token with necessary credentials.
$tenantId Specifies the ID of the tenant.
$userId Specifies the ID of the user in the form name@domain.
VMware, Inc. 30
Loading...