Importing authentications

The process of importing authentications can help you create a seamless branded experience and to save End Users who are already registered with your product having to register and authenticate again. It can be used to import authentications for your own product, or from other major token-based services supported by Tray (Zendesk, Marketo,etc.)

The steps involved

Copy

1. In the Tray app UI, when you are creating a solution you should make sure that the authentication option is hidden from the End User when they are configuring their solution instance in your external UI. At this point you should also allocate an External ID to the authentication, as this is required when finally creating a solution instance.

2. In your external app, when registering a new user, creating their access token etc. (as per the Main Process) you should use the createUserAuthentication mutation to create an authentication. When using this API, in order to specify which service you are creating an authentication for, and to supply the correct auth details you will need to specify the serviceId, the serviceEnvironmentId and the auth data (API key, domain, etc.) will need to be passed in the data field. These details can be obtained from the Settings & People section in the Tray UI.

3. The createUserAuthentication mutation will return an authenticationId which can then be passed (along with External ID from step 1) when you are using the createSolutionInstance mutation which is required when you are activating a solution for an End User.

4. Remember that once a Solution Instance has been created, the final step in activating it for an End User is to use the updateSolutionInstance mutation to set the status to 'enabled'.

1 - Set the hidden authentication field in the UI

Copy

First, when creating/editing your Solution, set the Authentication as hidden in the UI, by dragging it to the Not visible to the users section as per the below screenshot:

From this you can pick up the External ID which must be passed when you are creating the Solution Instance in step 3.

2 - Create the authentication

Copy

Before you create the authentication you need to go the Settings section of your dashboard and navigate to Embedded settings.

Scroll down and you will notice Authentication import generator. Enter your service name under connector dropdown and choose your environment to obtain the serviceId, serviceEnvironmentId and auth data for the service you are authenticating with:

Alternatively, you can use the Get User Authentications (with Master Token) graphQL API call to obtain serviceId and serviceEnvironmentId.

Using the Master Token here will return all the auths you have created when testing your source workflows.

The name given to the authentication you are creating is determined by you. This name will be visible in the Tray UI and can help you categorise authentications according to service and owner. You can also display it in your own app UI if it is ever needed.

Note also that, if you are the actual owners of the service and it uses standard password/token-based authentication, it is possible to pass extra custom fields into data in the above mutation. Please contact us if you would like to discuss this.

Note on connector version

Copy

You will also note that each connector contains multiple versions:

The version you choose should correspond to the version the connector is on in the Tray workflow builder. This is found by clicking on Show advanced settings for the Workflow connector step. You can then scroll back up to see the version, as per this SQS example:

Selecting the version is a necessary step to take because authentication details might change from one version of the Tray connector to the next - e.g. the service may ask for an extra key to be passed in the data field, or the type of the authentication may change from token-based to OAuth2.0

In the vast majority of cases authentication does not change from one version to the next, so you will notice that the returned code snippet will most often stay exactly the same when you change versions in the drop-down.

Please also see our documentation on managing connector versions for some basic info on this topic.

Important note on formatting data

Copy

The json values passed in data must be in single line format, with " characters escaped with a slash as per the above example.

If you are importing an auth for your own OAuth-based service, scopes (as a simple list of strings such as scopes: ["pages_show_list", "leads_retrieval"]) can be used to define the exact read/write access an auth has to different components of the service. Your service OAuth documentation should provide the necessary details for scopes.

The payload for this mutation will return an authenticationId.

3 - Create the Solution Instance

Copy

Along with the externalId obtained from step 1, the authenticationId you have just obtained when creating the auth can be passed (as authId) using the authValues argument when using the createSolutionInstance API:

1
mutation {
2
 createSolutionInstance(input: {
3
   solutionId: "0dc02586-xxx-xxx-xxxx-cb98734578ef",
4
   instanceName: "some instance name",
5
   authValues: [{ externalId: "external_sqs_authentication", authId: "aaa67786-xxx-xxx-xxx-97dedd1519b3" }]
6
 }) {
7
  solutionInstance {
8
   id
9
  }
10
 }
11
}

Note that the externalId of both authValues and configValues is case sensitive. For example if, in the UI at step 1 above, you have set the externalId as 'external_sqs_authentication' but then create the Solution Instance with 'External_SQS_Authentication' then the mutation will fail.

4 - Enable the Solution Instance

Copy

Don't forget that once a Solution Instance has been created, the final step in activating it for an End User is to use the updateSolutionInstance mutation to set the status to 'enabled'.