Skip to main content
Matrix42 Self-Service Help Center

Web Services: Authentication types

Authentication types and mechanisms for Matrix42 Web Services integration.

Goal

The SASM application delivers rich REST Services API. And in many cases the existing Web Services need to be requested outside of the UUX application, when OAUTH token is not available. The System provides two alternative approaches for authenticating the Web Service Requests, using Basic Authentication or Web Service API Tokens

Basic Authentication

The approach is very simple to use but highly not recommended, as it is very vulnerable from the Security perspective, because the full login credentials (login name and password) are stored on client side, and could be compromised. 

To authenticate with Basic Authentication the HTTP Request Header has to have property Authorization with value 'Basic username:password'. The following example demonstrates call of Workflow Resume operation using Basic Authentication

var xmlhttp = new XMLHttpRequest();
xmlhttp.open('GET', 'http://localhost/M42Services/api/workflow/resume?objectId=fcfd3ca2-ec21-4846-874c-d6c4f27ffb97', true);
xmlhttp.setRequestHeader('Authorization', 'Basic ' + 'XNtXWTZESvdmlldjpnZmhqS20hMQ=='  /*btoa("username:password)*/);

Use API Token 

The more secure and recommended way to authenticate Web Service call is using API Tokens. The example uses Javascript to demonstrate the flow of Tokens, but absolutely the same ways it can be done with any other programming language

Step 1: Generate API Token

Issue API token in UUX and store it on client. See more details on Web Service API Token.

Step 2: Exchange API token to Access Token

API Token is used only for getting Access Token, which is used for authenticating each Web Service call.

var xmlhttp = new XMLHttpRequest();
xmlhttp.open('POST', 'http://{serverurl}/M42Services/api/ApiToken/GenerateAccessTokenFromApiToken/', true);
xmlhttp.setRequestHeader("Content-Type", "application/json");
xmlhttp.setRequestHeader('Authorization', 'Bearer ' + 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1bmlxdWVfbmFtZSI6ImF0aW50ZXJuYWxcXGF0ZW5kdXNlciIsIm5hbWVpZCI6ImF0aW50ZXJuYWxcXGF0ZW5kdXNlciIsImlzcyI6Imh0dHBzOi8vc3RzLm1hdHJpeDQyLmNvbSIsImF1ZCI6InVybjptYXRyaXg0MkFwaSIsImV4cCI6MTU2MDQ5NzcyMiwibmJmIjoxNTI4OTYxNzIyfQ.KPRlkVooufH0sFVIIHGa38m3kYSNTXrOJdiFB8VSQNM');

 Step 3: Use Access Token for Web Service Call

xmlhttp.onreadystatechange = function() {
  if (this.readyState == 4 && this.status == 200) {
    if(this.responseText!==null){
        var svchttp = new XMLHttpRequest();
        svchttp.open('GET', 'http://{serverurl}/M42Services/api/workflow/resume?objectId=fcfd3ca2-ec21-4846-874c-d6c4f27ffb97', true);
        svchttp.setRequestHeader('Authorization', 'Bearer ' + JSON.parse(this.responseText).RawToken);
    }
    else {
        console.log('Not valid or disabled API token')
    }
  }
};
xmlhttp.send();

Examples

Call Service: Start Workflow

To prepare the web service call to any service, first of all, figure out the contract of the service, which input parameters of the Web Service and how they passed in REST request, as well how the Web Service return data.

You can find this information either in UUX Administration application, management area "Web Services", or find where in standart UUX application this service is activated, and check the contract in the browser Development Tools Network tabulator

StartWorkflow.png

 

The example starts Approval Workflow, which accepts the single input parameter "bookings"

var svchttp = new XMLHttpRequest();
svchttp.open('POST', 'http://{serverurl}/M42Services/api/workflow/start/{workflowId}', true);
svchttp.setRequestHeader('Authorization', 'Bearer ' + {token});
svchttp.send('{bookings:[id1, id2]}');

Where:

workflowId - object ID of the Workflow (can be found in table PLSLXamlComponentType.ID);
token - authentication token (see above how to obtain it);
 

 

  • Was this article helpful?