Salesforce Query authentication guide
Overview
This is a step-by-step guide to creating an OAuth entry, acquiring credentials, and authorizing the Salesforce Query component for use in Matillion ETL.
This guide covers both methods of using Salesforce: Salesforce Lightning and Salesforce Classic.
Please Note
- The Salesforce Query component uses either a username and password or an OAuth for third-party authentication. This guide only explains the OAuth method.
- While component properties may differ between cloud data warehouses, the authentication process remains the same.
- The callback URL, and therefore the Matillion ETL instance, must be HTTPS, not HTTP.
- It is recommended that the callback URL be a fully qualified domain name (FQDN) and not an IP address.
Acquiring Third-Party Credentials
1. In Matillion ETL, click Project, then Manage OAuth.
2. Copy the Callback URL in the field at the top of the window as this will be required later. The URL must be HTTPS format to be accepted by Salesforce.
3. Click in the bottom left of Manage OAuth to open the Add OAuth Entry dialog.
4. Provide a name for the OAuth in the Name field, click the Service drop-down menu, and select Salesforce. Click OK.
5. On returning to the Manage OAuth dialog, check the list of OAuths to ensure your newly created entry is listed.
Please Note
This entry is Not Configured. Configuration of the OAuth entry is discussed in Authorizing for use in Matillion ETL.
Acquiring Third-Party Credentials in Salesforce Lightning
1. Navigate to the Salesforce website, then click Login → Login found in the top-right of the screen. The browser will then redirect to a login screen. Enter valid login credentials to continue.
2. After you have logged in to the Salesforce dashboard, click the ⚙ → Setup, located in the top-right.
3. On the next screen, click Apps → App Manager on the sidebar on the left. Then, click New Connected App on the top-right of the Lightning Experience App Manager dialog.
4. A New Connected App configuration dialog will open. Provide details for the following fields:
- Connected App Name – provide a name for the app.
- API Name – provide a filename for the app (alternatively, use the name automatically generated from the Connected App Name).
- Contact Email – provide an email address to be used as a point of contact for the app.
5. Scroll down to the API (Enable OAuth Settings) section and tick the checkbox next to Enable OAuth Settings. This will reveal a new section. Provide details for the following fields:
- Callback URL – paste the Callback URL (copied from the Manage OAuth dialog in Matillion ETL earlier).
- Selected OAuth Scopes – select Access and manage your data (api), Perform requests on your behalf at any time (refresh_token, offline_access), and Provide access to your data via the Web (web), and click ►, then click Save.
6. If the app is created successfully, the browser will redirect to the newly created app's information page. Then, in the API (Enable OAuth Settings) section, copy the strings next to Consumer Key and Consumer Secret as they will be required in Authorizing for use in Matillion ETL.
Please Note
- To view and copy the Consumer Secret, click Click to reveal.
- Additionally, when copying these strings, some browsers may add a space to the end of the strings. Watch out for this as it will cause the credentials to fail.
Acquiring Third-Party Credentials in Salesforce Classic
1. Navigate to the Salesforce website, then click Login → Login found in the top-right of the screen. The browser will then redirect to a login screen. Enter valid login credentials to continue.
2.After you have logged in to the Salesforce dashboard, click Setup located in the top-right.
3. On the next page, scroll down to the Quick Links section and click Manage Apps.
4. Then, in the Apps window, scroll down to the Connected Apps section and click New above the app list.
5. A New Connected App configuration dialog will open. Provide details for the following fields:
- Connected App Name – provide a name for the app.
- API Name – provide a filename for the app (alternatively, use the name automatically generated from the Connected App Name).
- Contact Email – provide an email address to be used as a point of contact for the app.
6. Scroll down to the API (Enable OAuth Settings) section and tick the checkbox next to Enable OAuth Settings. This will reveal a new section. Provide details for the following fields:
- Callback URL – paste the Callback URL (copied from the Manage OAuth dialog in Matillion ETL earlier).
- Selected OAuth Scopes – select Access and manage your data (api), Perform requests on your behalf at any time (refresh_token, offline_access), and Provide access to your data via the Web (web), and click ►, then click Save.
7. If the app is created successfully, a message will appear stating, "Allow from 2-10 minutes for your changes to take effect on the server before using the connected app". Thereafter, click Continue to be redirected to the newly created app's information window.
In the API (Enable OAuth Settings) section, copy the strings next to Consumer Key and Consumer Secret as they will be required in Authorizing for use in Matillion ETL.
Please Note
- Allow 2-10 minutes before using these credentials in Matillion ETL.
- To view and copy the Consumer Secret, click Click to reveal.
- Additionally, when copying these strings, some browsers may add a space to the end of the string. Watch out for this, as it will cause the credentials to fail.
Authorizing for use in Matillion ETL
1. Return to the Manage OAuth dialog in Matillion ETL and click next to the previously created OAuth entry. This will open the Configure OAuth window.
2. Using the strings copied from the Salesforce website earlier, provide details for the following fields:
- Client ID – enter the Consumer Key.
- Client Secret – enter the Consumer Secret.
- Sandbox – select whether a sandbox will be used, then click Next.
3. The next window will have an Authorization link. Click the link to authorise Matillion ETL to use the acquired credentials.
4. The browser will redirect to a Salesforce page, requesting access to the associated account. Click Allow to confirm.
5. If all is successful, the browser will return to Matillion ETL with a window stating, "Authorization Successful".
