# Custom OAuth apps How to fully whitelabel the Config Wizard ## 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 (US region) * the `embedded.eu1.tray.io` domain (EU region): ![config-wizard-url-2](https://tray.ai/documentation/images/platform/embedded/advanced-features/whitelabelling/custom-oauth-apps/3r7XCeeIPK2xQ3CKcr3OUN_config-wizard-url-2.png) * When authenticating with a service, the dialog will display Tray branding: ![tray-branded-auth-2](https://tray.ai/documentation/images/platform/embedded/advanced-features/whitelabelling/custom-oauth-apps/45qCJKB0nlMDzfBnemG4zD_tray-branded-auth-2.png) For OAuth2 services, you can address both of these by creating a **custom OAuth 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 #### US Region In the US region, 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 to 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. > **Warning:** If the service does not support the entry of multiple redirect urls for custom apps in the US, it will be more difficult to use custom whitelabelled url domains > This is because Tray will only authorize apps which use the default redirect url. > Please see the 'Single Redirect URL issue' section below for how to deal with this #### EU Region Likewise in the EU region, you can overwrite the default `embedded.eu1.tray.io` domain: * `*.eu1.integration-configuration.com` * `*.eu1.integration-authentication.com ` These domains can be prefixed with your company name e.g. * `acme.eu1.integration-configuration.com` * `acme.eu1.integration-authentication.com ` You will then be able to open the Config Wizard with `https://acme.eu1.integration-configuration.com/external/solutions/${embeddedId}/configure/${solutionInstanceId}?code=${authorizationCode}` Instead of: `https://embedded.eu1.tray.io/external/solutions/${embeddedId}/configure/${solutionInstanceId}?code=${authorizationCode}` And you will be able to use `http://acme.eu1.integration-authentication.com/oauth2/token` as a second redirect url when people are authenticating with the services involved in your integration. > **Warning:** If the service does not support the entry of multiple redirect urls for custom apps in the EU, it will be more difficult to use custom white-labelled url domains > This is because Tray will only authorize apps which use the default redirect url. > Please see the 'Single Redirect URL issue' section below for how to deal with this ## Setting up a Custom auth app > **Warning:** Please note that the examples below show urls for the US region. > If you are in the EU please adjust the urls as explained above 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 'Using custom OAuth apps in your Solutions' step below). The basic steps for setting up a custom auth app are: 1. 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. `https://acme.integration-authentication.com/oauth2/token` (if you are whitelabelling the urls, and the service supports entering multiple urls) 2. When creating an auth in your source workflow click 'Use own OAuth app' and enter your app details, as per the example below 3. Publish the solution The last step is crucial in ensuring 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: * The first one for the default `https://auth.tray.io/oauth2/token` * A second one for your custom URL `https://acme.integration-authentication.com/oauth2/token` For some Oauth services such as Salesforce (see below), you are allowed to specify multiple redirect URLs which means you can set both URLs during the app creation. ### Single Redirect URL issue However a lot of Oauth services, such as Zendesk, only allow you to specify a single redirect url. #### Solution 1 One solution for this: 1. Define the custom app settings to use the default Tray redirect URL 2. Create an auth for the service in your Tray workflow 3. 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. #### Solution 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 authorize the default redirect URI in their OAuth app settings. ## Creating a Custom auth app example (OAuth2) ### 1 - Create an app in third-party service ### 1 - Create new app This will need to be done in the admin UI for the service you are working with. For example in Salesforce, you will want to navigate to Setup, and then in the Quick Find, search for "App Manager". Then click on "New Connected App", which will load a form for entering the information for your new app. Note: When creating an app with a third-party service there may be a delay of e.g. 10 minutes before it is ready and usable. ![salesforce-oauth-app](https://tray.ai/documentation/images/platform/embedded/advanced-features/whitelabelling/custom-oauth-apps/064589bc-208d2150_salesforce-oauth-app-2.png) ### 2 - Enter app details **The exact details required will vary by service**, but for Salesforce we recommend the following set up: > **Warning:** The following table is specific to Salesforce, but it acts as a rough guide to the settings a thrid party service might have | **Setting** | **Value** | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Connected App Name** | The name you want to appear to customers durlng the login consent screen, e.g. Acme | | **API Name** | This will usually default to the same as the Connected App Name | | **Contact Email** | The email address of your support team to handle issues that may arise | | **Logo Image URL** | The image to show to your customers durlng the consent screen | | **Enable OAuth Settings** | Ticked | | **Callback URL** | You will want to enter the following URL in this field: `https://auth.tray.io/oauth2/token`. This will ensure that you are able to create an authentication inside a Tray.io workflow. In addition, if you are using a whitelabelled domain you will need to include e.g. `https://acme.integration-authentication.com/oauth2/token` as a second callback URL. This is important for ensurlng that your config wizard auth dialog works with your app | | **Selected OAuth Scopes** | Select the required scopes for your integration. For a reference of the scopes used by Tray.io's app, when you create an authentication in the workflow builder you can look at what scopes are being asked for | All other settings in **Basic Information** can be filled out to further customize your application, other settings can be left as-is. ### 2 - Using custom OAuth apps in your Solutions When you add e.g. a Salesforce connector to a workflow, you **must create an authentication (as you usually do when configuring and testing the workflow)**  When doing so you can add your OAuth app details by clicking on 'Use own OAuth app': ![customOauthApp](https://tray.ai/documentation/images/platform/embedded/advanced-features/whitelabelling/custom-oauth-apps/1IUGXldMsF8LCE6EY7i8yr_customOauthApp.png) Then add the app details as per the following: ### 1 - add name and description You can then add a name e.g. 'Salesforce custom OAuth app 1' and description: ![customOauth hubspot TraySettings1](https://tray.ai/documentation/images/platform/embedded/advanced-features/whitelabelling/custom-oauth-apps/23SnLp0MKQ6RYgDhFepr8B_customOauth_hubspot_TraySettings1.png) ### 2 - add app details And then you can add key details such as Client ID and Secret. Exactly what details are required here will vary according to the service: ![customOauth hubspot TraySettings2](https://tray.ai/documentation/images/platform/embedded/advanced-features/whitelabelling/custom-oauth-apps/269d5UyniYNEc8Ns75ZODy_customOauth_hubspot_TraySettings2.png) Then go ahead and **create an authentication** with your new OAuth app selected, including the appropriate scopes you wish to be available to your End Users. Once this is done **don't forget to publish your solution!** ### 3 - Final re-branded Config Wizard The key outcome here is that, when End Users are creating an authentication for this service they will automatically be logging into the correct environment and therefore **the Tray branding will be removed**: ![customOauthApp Output](https://tray.ai/documentation/images/platform/embedded/advanced-features/whitelabelling/custom-oauth-apps/2gR759lUUnaujnzLTAyoBR_customOauthApp_Hubspot_Output.png)