Using vCenter Single Sign-On Authentication with the vRealize Orchestrator REST API

If vRealize Orchestrator is configured with the vCenter Single Sign-On Server by using the vSphere Authentication mode, you need a principal holder-of-key token to access system objects in vRealize Orchestrator through the vRealize Orchestrator REST API. To access vCenter Server, or third-party systems that use the vCenter Single Sign-On Server through the vRealize Orchestrator server, you need a delegate holder-of-key token for vRealize Orchestrator and your principal token.

If vRealize Orchestrator is configured with the vCenter Single Sign-On Server, you must authenticate by using valid credentials and vRealize Orchestrator manages the holder-of-key token.

Accessing System Objects in Orchestrator

You can access system objects in vRealize Orchestrator at the URLs of the Inventory and the Catalog services of the REST API.

  • https://{orchestrator_fqdn}/vco/api/inventory/System/
  • https://{orchestrator_fqdn}/vco/api/catalog/System/

When you access system objects in vRealize Orchestrator, you pass your principal holder-of-key token in the Authorization header of HTTP requests that you make to the Inventory or the Catalog service.

For example, to retrieve all system objects of the type Workflow, you make a GET request at https://{orchestrator_fqdn}/vco/api/catalog/System/Workflow/. To authenticate against vRealize Orchestrator, you need to pass your principal holder-of-key token in the Authorization header of the request.

Accessing Objects in Third-Party Systems

To perform operations in third-party systems that are registered with the vCenter Single Sign-On Server through the vRealize Orchestrator REST API, you must authenticate against vRealize Orchestrator and the third-party system. You include two headers in the HTTP calls that you make through the vRealize Orchestrator REST API.

  • Authorization. You must pass your principal holder-of-key token in this header.
  • VCOAuthorization. You must pass a delegate holder-of-key token for vRealize Orchestrator in this header. You must acquire the delegate token for vRealize Orchestrator from the vCenter Single Sign-On Server. vRealize Orchestrator uses the delegate token to authenticate against the third-party system on your behalf.

For example, to run a workflow that uses a virtual machine through the vRealize Orchestrator REST API, you access resources both in vRealize Orchestrator and in vCenter Server. To authenticate against vRealize Orchestrator and vCenter Server, you must pass your principal holder-of-key token in the Authorization header of the request that you make, and the delegate token in the VCOAuthorization header. In this way, you authenticate against vRealize Orchestrator with your principal token and vRealize Orchestrator authenticates on your behalf against vCenter Server with the delegate token.

The vCenter Single Sign-On Server treats vRealize Orchestrator as a solution, and every solution is registered with a unique user name with the vCenter Single Sign-On Server. You request a delegate token for vRealize Orchestrator by passing the solution user name of vRealize Orchestrator and a principal holder-of-key token to the vCenter Single Sign-On Server. The token that the vCenter Single Sign-On Server issues is a delegate holder-of-key token for vRealize Orchestrator to authenticate on your behalf against third-party systems.

Obtain a Session in vCenter Single Sign-On Mode

The following example code obtains a session in vCenter Single Sign-On mode. 

URI uri = URI.create("https://{orchestrator_fqdn}:443/vco/api");
VcoSessionFactory sessionFactory = new DefaultVcoSessionFactory(uri);

//provide the address of the vCenter Single Sign-On server
URI ssoUri = URI.create("https://sso-server:7444/ims/STSService?wsdl");

//set the tokens to be valid for an hour
long lifeTimeSeconds = 60 * 60;

//create a factory for vCenter Single Sign-On tokens
SsoAuthenticator sso = new SsoAuthenticator(URI ssoUri, URI adminUri, VcoSessionFactory vcoSessionFactory, long lifeTimeSeconds);

//provide vCenter Single Sign-On credentials
SsoAuthentication authentication = sso.createSsoAuthentication("username", "password");

VcoSession session = sessionFactory.newSession(authentication);
//use session here