(v22) Trusted Access

Trusted Access

Composer provides its own security methodology that allows for machine-to-machine authorization of Composer resources when embedded in your application (the “parent” application). This is a form of “delegated” authorization where the parent application can determine, on demand, how and when to authorize any given embedded Composer component to an end-user logged into the parent application. This methodology is called Trusted Access.

insightsoftware recommends using Trusted Access for all embed-related workflows.

Similar to "single sign-on," this arrangement allows users to log in once to the parent application and yet have their security information propagated to Composer, creating a seamless and secure user experience. This, of course, means that users can't be allowed to "go around" the parent application and directly access Composer. In the stateless world of web applications, this requires some special mechanisms to ensure security that are provided for Logi applications through our SecureKey technology.

On request from the parent application, Trusted Access provides a user access token with defined authorization rules that account for user privileges, object permissions, security filters and any specific user attributes used in interpolation. This user access token can then be used in the parent application to serve any Composer specific embedded components such as dashboards for the respective user. For information on how tokens are initiated and requested in your applications, see Embed Composer Components Using JavaScript and Trusted Access.

Trusted Access tokens are encrypted when stored in Composer metadata. The encryption mode used can be set as described in Change the Encryption Mode.

This topic also describes:

• Trusted Access Prerequisites
• Trusted Access Recommendations
• Register a Client
• Generate a User's Access Token

The following additional topics provide reference information:

• Trusted Access API Endpoints
• Trusted Access Client Properties

Trusted Access Prerequisites

• Every end user must have Composer user account defined, unless you are using LDAP autoprovisioning with Composer. See Manage User Definitions.

• Trusted Access is enabled by default in Composer. If it is disabled, enable Trusted Access by selecting the Trusted Access option on the Security page of the Supervisor UI. See Enable Trusted Access.

Trusted Access Recommendations

For security reasons, we recommend that you use short-lived tokens. Tokens that are valid for less than 10 minutes are recommended. The validity time of a user access token is defined when you register a client with Composer.

Register a Client

To start using Trusted Access, you first need to register your application, as Composer refers to it, as a client.

Registering a client will generate a client ID and client secret. These credentials can then be used to generate user access tokens for any user in the Composer platform, as needed.

To register your application as a client, POST the /api/trusted-access/clients API endpoint. You can also patch, delete, and list Trusted Access clients using the /api/trusted-access/clients API endpoint. See Trusted Access API Endpoints.

Generate a User's Access Token

To generate a user's access token, pass the client ID and client secret to HTTP BasicAuth. To obtain the client ID and client secret, use the /api/trusted-access/clients API endpoint. See Trusted Access API Endpoints.

Generate a User's Access Token for Existing Composer Users

/********REQUEST TRUSTED ACCESS TOKEN ********/
const AccessToken = (ComposerUrl, Username, callback) => { 
	var Client = GetClient();
	if(typeof Client === 'undefined' ||  Client === null)
		callback({ErrorMessage: 'Client Not Found', status : 500});
	else {
		var BasicAuth = Buffer.from(`${Client.client_id}:${Client.client_secret}`).toString('base64');
		Post(BasicAuth, `${ComposerUrl}/api/trusted-access/pull/tokens`, { "username": Username }).then((result) => {
			if(JSON.stringify(result).indexOf('error')>-1)
				callback(result, null);
			else  
				callback(null, result);
		});
	}
};

You cannot generate a token for supervisors. You can only generate them for regular users and for administrators.

Generate a User's Access Token for New Composer Users

/********REQUEST TRUSTED ACCESS TOKEN ********/
const UserContext = {
	"username": "joe",
	"account": "company",
	"fullname": "Example Inc",
	"email": "[e-mail]",
	"groups": ["Store Manager", "Cashier"],
	"attributes": [{"key": "city", "values": ["London"]}]
};
const AccessToken = (ComposerUrl, UserContext, callback) => {
	var Client = GetClient();
	if (typeof Client === 'undefined' || Client === null)
		callback({ErrorMessage: 'Client Not Found', status: 500});
	else {
		var BasicAuth = Buffer.from(`${Client.client_id}:${Client.client_secret}`).toString('base64');
		Post(BasicAuth, `${ComposerUrl}/api/trusted-access/push/tokens`, UserContext).then((result) => {
			if (JSON.stringify(result).indexOf('error') > -1)
				callback(result, null);
			else
				callback(null, result);
		});
	}
};

You cannot generate a token for supervisors. You can only generate them for regular users and for administrators.