Salesforce Query Authentication Guide

Salesforce Query Authentication Guide


Overview

This is a step-by-step guide to creating an OAuth entry, acquiring credentials and authorising the Salesforce Query component for use in Matillion ETL.

Important Information

  • 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 recommendeded that the callback URL be a fully qualified domain name (FQDN) and not an IP address.

Acquiring Third-Party Credentials

  1. In Matillion ETL, on the top left of the screen, click ProjectManage OAuth.

    Please Note

    If a Salesforce Query component has already been added to an Orchestration Job, the Manage OAuth window may also be accessed using the following method:

    1. Click the component icon to open the Properties panel at the bottom of the screen.
    2. Then, click ... next to the Authentication Method input.
    3. Select OAuth from the dropdown menu in the pop-up window and click OK.
    4. The Authentication input will now appear on the list of properties. Click ... next to it, and finally click Manage in the pop-up window.
    Project dropdown menu

    Project dropdown menu

  2. Copy the Callback URL in the field at the top of the window as this will be required in Acquiring Third-Party Credentials.

  3. Click + in the bottom left of the window to open the Create OAuth Entry window.

    New OAuth entry

    New OAuth entry

  4. Click the Service dropdown menu and select Salesforce. Then, provide a name for the OAuth in the Name field and click OK.

    Create OAuth Entry window

    Create OAuth Entry window

  5. On returning to the Manage OAuth window, check the list of OAuths to ensure the new entry is listed.

    Please Note

    This entry is Not Configured. Configuration of the OAuth entry will be discussed in Authorising for use in Matillion ETL.

    New Entry listed on Manage OAuth window

    New Entry listed on Manage OAuth window


Acquiring Third-Party Credentials in Salesforce Classic

  1. Navigate to the Salesforce website, then click LoginLogin found on the top right of the screen. The browser will then redirect to a login screen. Enter valid login credentials to continue.

    Log in to Salesforce

    Log in to Salesforce

  2. Once logged in, the browser will open the Salesforce dashboard. Then at the top right of the screen, click the <Profile Name>Setup.

    Salesforce homepage

    Salesforce homepage

  3. On the next screen, scroll down to the Quick Links section and click Manage Apps.

    Setup dashboard

    Setup dashboard

  4. Then, in the Apps window, scrolled down to the Connected Apps section and click New above the app list.

    Apps dashboard

    Apps dashboard

  5. A New Connected App configuration window 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

    New Connected App configuration window

    New Connected App configuration window

  6. Next, 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 window 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

    OAuth Settings

    OAuth Settings

  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 then be redirected to the newly created app's information window. Then, in the API (Enable OAuth Settings) section, copy the codes next to Consumer Key and Consumer Secret as they will be required in Authorising for use in Matillion ETL.

    Please Note

    • Allow 2-10 minutes before using these credentials in Matillion ETL.
    • In order to copy the Consumer Secret, Click to reveal must first be clicked to make it visible.
    • Additionally, when copying the codes, some browsers may add a space to the end of the code. Watch out for this as it will cause the credentials to fail.
    Copy the Consumer Key and Secret

    Copy the Consumer Key and Secret


Acquiring Third-Party Credentials in Salesforce Lightning

  1. Navigate to the Salesforce website, then click LoginLogin found on the top right of the screen. The browser will then redirect to a login screen. Enter valid login credentials to continue.

    Log in to Salesforce

    Log in to Salesforce

  2. Once logged in, the browser will open the Salesforce dashboard. Then at the top right of the screen, click the Setup.

    Salesforce homepage

    Salesforce homepage

  3. On the next screen, click AppsApp Manager on the sidebar on the left. Then, click New Connected App on the top right of the Lightning Experience App Maanager window.

    Lightining Experience App Manager

    Lightining Experience App Manager

  4. A New Connected App configuration window 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

    New Connected App configuration window

    New Connected App configuration window

  5. Next, 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 window 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

    OAuth Settings

    OAuth Settings

  6. If the app is created successfully, the browser will redirect to the newly created app's information window. Then, in the API (Enable OAuth Settings) section, copy the codes next to Consumer Key and Consumer Secret as they will be required in Authorising for use in Matillion ETL.

    Please Note

    • In order to copy the Consumer Secret, Click to reveal must first be clicked to make it visible.
    • Additionally, when copying the codes, some browsers may add a space to the end of the code. Watch out for this as it will cause the credentials to fail.
    Copy the Consumer Key and Secret

    Copy the Consumer Key and Secret


Authorising for Use in Matillion ETL

  1. Return to the Manage OAuth window in Matillion ETL and click next to the previously created OAuth entry. This will open the Configure OAuth window.

    Configure OAuth settings

    Configure OAuth settings

  2. Using the codes 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

    Configure OAuth settings

    Configure OAuth settings

  3. The next window will have an Authorization link. Click the link to authorise Matillion ETL to use the acquired credentials.

    Authorization link

    Authorization link

  4. The browser will then redirect to a Salesforce screen requesting access to the associated account. Click Allow to confirm.

    Allow access to Salesforce account

    Allow access to Salesforce account

  5. If all is successful, the browser will return to Matillion ETL with a window stating, "Authorization Successful".

    OAuth Authorization successful

    OAuth Authorization successful