Tray Embedded / Core Topics / Whitelabelling / The Config Wizard (custom auth apps)
The Config Wizard (custom auth apps)
Overview
To fully whitelabel the Config Wizard there are two things to address:
Config Wizard and auth dialog URLs by default use the
embedded.tray.io
domain:
When authenticating with a service, the dialog will display Tray.io branding:
For OAuth2 services, you can address both of these by creating a custom auth app in the service admin UI.
The rest of this document will talk you through setting up custom domains and creating a custom auth app.
Custom url domains
It is possible to overwrite the default embedded.tray.io
domain by using the wildcarded domains:
*.integration-configuration.com
*.integration-authentication.com
These domains can be prefixed with your company name e.g.
acme.integration-configuration.com
acme.integration-authentication.com
You will then be able open the Config Wizard with https://acme.integration-configuration.com/external/solutions/${embeddedId}/configure/${solutionInstanceId}?code=${authorizationCode}
Instead of: https://embedded.tray.io/external/solutions/${embeddedId}/configure/${solutionInstanceId}?code=${authorizationCode}
And you will be able to use http://acme.integration-authentication.com/oauth2/token
as a second redirect url when people are authenticating with the services involved in your integration.
If the service does not support the entry of multiple redirect urls for custom apps, it will be more difficult to use custom whitelabelled url domains
This is because Tray.io will only authorize apps which use the default https://auth.tray.io/oauth2/token redirect url.
Please see the workaround section below for how to deal with this
Setting up a Custom auth app
In order for a solution to leverage your Oauth app, we will create an environment for the service on our end. You will then need to create an authentication that uses the environment (see the 3 - Using custom OAuth apps in your Solutions step below).
The basic steps for setting up a custom auth app are:
Create the Oauth app (in e.g. Zendesk, Salesforce etc.):
Give it a name
Include your company logo
Set the main redirect / callback url to the default
https://auth.tray.io/oauth2/token
Set a second redirect / callback url as e.g.
http://acme.integration-authentication.com/oauth2/token
(if you are whitelabelling the urls, and the service supports entering multiple urls)
Submit your app details to Tray, as per the example below
Wait for Tray to create the custom Oauth environment (for e.g. Zendesk, Salesforce etc.) in your account
Create an authentication attached to the service environment in your solution's workflow (see 'Create auth and select environment' example below)
Publish the solution
The last step is crucial in ensurlng that your Oauth app is used in the config wizard for your solution.
Using custom URLs
If you are also using a custom public url for the Config Wizard you will need to add two redirect urls in the app details screen in the third-party service admin UI:
A first one for the default
https://auth.tray.io/oauth2/token
A second one for your custom
https://acme.integration-authentication.com
For some Oauth services such as Salesforce (see below), you are allowed to specify multiple redirect urls which means you can set both URLs durlng the app creation.
Redirect URL workaround
However a lot of Oauth services, such as Zendesk, only allow you to specify a single redirect url.
Workaround 1
There is a workaround for this:
Define the custom app settings to use the default tray.io redirect URL
Create an auth for the service in your Tray workflow
Change the authorized redirect URL to your custom one before publishing the solution
This approach does raise an issue with maintenance - if for any reason you need to reauthenticate, you will need to revert the authorized redirect URL setting back to the default one while you reauth and then revert to the whitelabelled one.
Workaround 2
If this presents a problem, an alternative (but not 100% whitelabelled workaround) is to use the authBaseUrl
query parameter, e.g.:
https://acme.integration-configuration.com/solutions/configure….?code=${authorizationCode}&authBaseUrl=auth.tray.io
This will then instruct the config wizard / auth dialog to request a redirect from the third party service back to the address https://auth.tray.io/oauth2/token
.
You will only need to authorise the default redirect URI in their OAuth app settings.
Creating a Custom auth app example (OAuth2)
1 - Create app in third-party service
2 - Send the app details to Tray.io
In order for your app to be usable with Tray.io, you can use our secure form to send us key app details such as:
Client Id
Client Secret
Service (Connector)
A Tray.io Login email to enable the service for
Please contact your customer success representative when you need access to the form:
The form is managed via a Tray workflow and encrypts credentials via PGP to be imported into Tray's password manager (if they need to be securely shared with other engineers).Workflow execution logs are disabled to prevent form submissions being stored in clear text and accessible via the workflow debug view.
3 - Using custom OAuth apps in your Solutions
Once we have configured the environment for you, you can make use of it in your Solutions.