Using the Scripting API to Configure or Update a REST Host Authentication

You can configure or update the OAuth 2.0 token sending strategy of a REST host by using either the query parameter or authorization header strategy.

Starting with vRealize Orchestrator 8.7, you can now use two different strategies for sending an OAuth 2.0 bearer access token when making an OAuth 2.0 authorized request. The default strategy, used in previous product versions, is to send the token in a oauth_token query parameter when making requests to the host. Using the query parameter strategy can introduce certain vulnerabilities, such as having the REST host server log the incoming requests.

Note: The query parameter will be deprecated in a future vRealize Orchestrator release.

The newly introduced and recommended strategy is to use the Authorization header to send the token when making request to the host.

You can configure either token sending strategy by:

• Using the OAuth 2.0 tab used in built-in REST workflows such as Add a REST Host or Update a REST Host. For an example of using this option when running the Add a REST Host workflow, see Add a REST Host.
• Changing the authorization strategy by adding custom scripting to your workflow.

The scripting approach uses the following methods:

Token sending strategy	Scripting
Authorization header	host.authentication = RESTAuthenticationManager.createAuthentication("OAuth 2.0", ["<token>", "Authorization header"]);
Query parameter	host.authentication = RESTAuthenticationManager.createAuthentication("OAuth 2.0", ["<token>", "Query parameter"]);

Note: The old scripting approach of creating an OAuth 2.0 authentication by passing only the token parameter without a token sending strategy still works, and for backwards compatibility preserves the past behavior of using the query parameter strategy.

host.authentication = RESTAuthenticationManager.createAuthentication("OAuth 2.0", ["<token>"]);

To demonstrate the scripting approach to managing your REST host authorization strategy, the following procedure presents a sample use case of creating a workflow which can be used for switching authorization strategies.

Procedure

1. Log in to the vRealize Orchestrator Client.
2. Navigate to Library > Workflows and select New Workflow.
3. Add a name for the workflow and click Create.
4. Navigate to the Schema tab and add a Scriptable task workflow element.
5. Add the following input and output parameters to the workflow element:

   Input or Output	Name	Type
   Input	host	REST:RESTHost
   Input	token	string
   Output	result	REST:RESTHost

6. Under the Scripting tab, add the following script:

   var oldAuth = host.authentication
   var ouath20type = "OAuth 2.0"
   if (oldAuth.type !== ouath20type) {
       System.log ("REST host isn't using" + ouath20type);
       result = host;
   } else {
       var oldStrategy = oldAuth.rawAuthProperties[1]
       if (oldStrategy === "Query parameter") {
           var newStrategy = "Authorization header";
       } else {
           var newStrategy = "Query parameter"
       }
       var newAuth = RESTAuthenticationManager.createAuthentication ("OAuth 2.0", [token, newStrategy]);
       host.authentication = newAuth;
       result = RESTHostManager.updateHost(host);
   }

   Note: In the preceding code sample, you can also use oldAuth.getRawAuthProperty(1) instead of oldAuth.rawAuthProperties[1]. Both function in the same way.
7. Save the workflow.
8. To change the token sending strategy of your REST host, run the workflow.

What to do next

You can verify what token sending strategy your REST host uses by navigating to Inventory > REST-Host, selecting your host, and checking the Authorization entry.