Trusted Access

This applies to: Visual Data Discovery

Symphony provides its own security methodology that allows for machine-to-machine authorization of Symphony 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 Symphony component to an end-user logged into the parent application. This methodology is called Trusted Access.

Note: 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 Symphony, 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 Symphony. In the stateless world of web applications, this requires some special mechanisms to ensure security that are provided for 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 Symphony specific embedded components such as dashboards for the respective user. For information on how tokens are initiated and requested in your applications, see Embed Symphony Components Using JavaScript and Trusted Access.

Note: In environments where you use Typescript for your client side code, you can use Embed Manager as an npm package. See https://www.npmjs.com/package/logi-embed.

Trusted Access tokens are encrypted when stored in Symphony 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 Prerequisites

Every end user must have Symphony user account defined, unless you are using LDAP autoprovisioning with Symphony. See Manage Users in Symphony.
Trusted Access is enabled by default. If it is disabled, enable Trusted Access by selecting the Trusted Access option on the Security page. 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 Symphony.

Important: If you disable Trusted Access in a multi-tenancy environment, data retrieved through the Data Discovery connector you created is fetched using the tenant admin's credentials instead of each user's credentials. Effectively, all row level security settings are removed on the data retrieved.

Register a Client

To start using Trusted Access, you first need to register your application, as Symphony 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 Symphony 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 Symphony 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);
		});
	}
};

Note: You can only generate tokens for regular users and for administrators.

Generate a User's Access Token for New Symphony Users

/********REQUEST TRUSTED ACCESS TOKEN ********/
const UserContext = {
	"username": "joe",
	"account": "company",
	"fullname": "Example Inc",
	"email": "joe@example.inc",
	"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);
		});
	}
};