One topic that doesn’t seem to be explored in detailed is the use of vRealize Orchestrator API and there is some confusion about which one to use (vco/api and vco-controlcenter/api) and how to authenticate, specially when using vRealize Orchestrator as part of the Cloud Extensibility Proxy for vRealize Automation Cloud or with the embedded vRealize Orchestrator in vRealize Automation 8.X, plus, anyway I hope this text could help to clarify.
For starters, there is two sets of APIs with each vRealize Orchestrator Release:
vRealize Orchestrator Server API – They are the APIs you would use for triggering a Workflow, find an Action, import a package, etc. Documentation and Swagger reference can be found at https://[vRO-IP or FQDN]/vco/api/docs/index.html
vRealize Orchestrator Control Center API – They are all the APIs you could use for managing the plug-ins install, server status or working with your Licenses or Certificates, etc. Documentation and Swagger reference can be found at https://[vRO-IP or FQDN]/vco-controlcenter/docs/
Obviously, every request to any of the vRealize Orchestrator REST APIs must be authorized by an authenticated user.
Depending on what you set up as your authentication provider: LDAP, vCenter Single Sign-On or oauth2.0 (what you get with vIDM when using vRA), for your vRealize Orchestrator the authentication scheme for the vRealize Orchestrator Server REST API is different.
BTW, the vRealize Orchestrator License is also affected by the authentication provider integration, after authentication, your vRealize Orchestrator instance is assigned a license based on the authentication provider (mentioned some lines above). Licenses control access to the following vRealize Orchestrator features:
Git integration
Role management
Multi-language support (Python, Node.js, and PowerShell)You can change the license of the vRealize Orchestrator server from the Licenses page of the Control Center (you could use an API for that…see what I did there). Learn more about it at vRealize Orchestrator Feature Enablement with Licenses
Also, in terms of roles, there are a few differences when using vRealize Orchestrator as part of the Cloud Extensibility Proxy in vRealize Automation Cloud , you can learn more about it here: vRealize Orchestrator 8.3 Integration in vRealize Automation Cloud. This topic is relevant for our discussion because when working with this specific vRealize Orchestrator flavor, API-wise, you will need to generate a Refresh Token for a user having the Cloud Assembly service roles (I’ll show you an example later in the blog).
Ok, Let’s take a look how you can authenticate for Realize Orchestrator Server API when having vRealize Orchestrator 8.X depending on the Authentication Provider:
LDAP Authentication
When vRealize Orchestrator is configured with LDAP, you must apply the Basic HTTP authentication scheme.
The Basic HTTP authentication scheme allows you to authenticate against vRealize Orchestrator or a third-party systems by including an Authorization header in every HTTP request. You provide a base64 encoded user name and password in the Authorization header. For details about the Basic HTTP authentication, see RFC 2617.
Single Sign-On Authentication
If Orchestrator is configured with the vCenter Single Sign-On (SSO) server, you need a principal holder-of-key (HoK) token to access system objects in vRealize Orchestrator through the REST API.
The HoK token is passed as a request Authorization header element. The value must be gzip, base64 encoded string.
Oauth2.0 Authentication
If vRealize Orchestrator is configured with vIDM (this is default authentication provider for vRealize Orchestrator when embedded in vRealize Automation 8.X you need an oauth bearer access token to access system objects in vRealize Orchestrator through the REST API.
The oauth bearer token is passed as request Authorization header element. The value must be Bearer {token}.
The very same authentication mechanism applies for Cloud Extensibility Proxy’s vRealize Orchestrator that you integrate with vRealize Automation Cloud with the difference that you obtain your Refresh Token from the Cloud Services Platform.
Ok so what about the vRealize Orchestrator Control Center API ?
This one is very straight forward, the authentication provider is the same vRealize Orchestrator, simply put, you use the same vRealize Orchestrator Appliance Linux Credentials via the Basic HTTP authentication scheme as described above under LDAP Authentication.
Ok how about some examples?
In the embedded vRealize Orchestrator 8.4 you need an oauth bearer access token to access system objects in vRealize Orchestrator through the REST API.
- Get Your Refresh Token with your Basic Credentials
2. Login with your Refresh Token and Obtain a “Bearer” Token
3. From this point use the “Bearer” Token in the Authorization header element for all the vco/api calls, example, I am querying my vRealize Orchestrator for the installed packages:
Ok how about if I want to see the details of an existing Workflow in my Cloud Extensibility Proxy’s vRealize Orchestrator that you integrate with vRealize Automation Cloud
1. Same oauth bearer access token approach, however instead of using vIDM, you rely on the Cloud Services Platform. which makes it simpler to generate your Refresh Token (please note that I selected all the roles since I am using this token for other activities but if it is only for vRealize Orchestrator use, it is enough to assign the Cloud Assembly roles).
2. I can now login with the generated Refresh Token and Obtain a “Bearer” Token (please note the URL, I am using the Cloud Services Platform to login into vRealize Automation Cloud which will be my authorization provider for my Cloud Extensibility Proxy’s vRealize Orchestrator)
3. with this in place, let’s inspect the contents of an existing Workflow, please note that at this point I am now using the specific Cloud Extensibility Proxy’s vRealize Orchestrator URL.
Ok, and now for vRealize Orchestrator Control Center API, no matter if it is vRealize Orchestrator embedded in vRealize Automation 8.X or Cloud Extensibility Proxy’s vRealize Orchestrator, accessing Control Center API uses the same Basic Authentication (as described before)
So if I want to list the installed plug-Ins it would be as simple as following
or if I wanted to very the current vRealize Orchestrator Services status, it would be:
Conclusion:
vRealize Orchestrator allows you to interface with it for accessing its features and/or to perform Configuration via its Server API and Control Center API, however API Authentication varies depending of the Authentication Provider selected and the specific flavor, e.g. Cloud Extensibility Proxy’s vRealize Orchestrator.
Related Links:
- What is vRealize Orchestrator (vRO)? | IT Automation Platform |
- vRealize Orchestrator 8.3 Integration in vRealize Automation Cloud.
- VMware vRealize Orchestrator 8.3 Integration in vRealize Automation
- Cloud. Announcing VMware vRealize Orchestrator 8.4
- New vRealize Orchestrator Plug-In for vRealize Automation
