Skip to end of metadata
Go to start of metadata

Introduction

API Manager supports OAuth 2.0 API authentication using Salesforce as the Identity Provider. This page shows how to set up Salesforce as an Identity Provider and obtain the Consumer Key and Consumer Secret needed for creating an OAuth 2.0 security profile. After OAuth 2.0 is configured in both Salesforce and the security profile, members of your Jitterbit org and invited developers will be able to use Salesforce authentication to access and consume your Harmony APIs.

TIPS:

  1. For additional information, see these Salesforce documentation articles:
  2. This process involves copying information between the Salesforce App Manager and the Harmony API Manager. Launching Salesforce App Manager and Harmony API Manager in separate browser windows and leaving each window open will simplify the process.

Creating a Salesforce Domain

NOTE: These instructions are current as of date of publication, but they are subject to change as they are taken from the Salesforce website.

  1. Log in to your Salesforce instance as a Salesforce Admin. The Setup Home page displays as shown in the image below.

  2. Navigate to Settings >Identity >Identity Provider to display the page shown below.
  3. In the section Identity Provider Setup, click on the Configure a Domain Name link.


  4. The My Domain page displays as shown below.
    • Enter your desired Domain Name in the text box.
    • Click on the Check Availability button. "Available" displays in green text if the desired name has not already been registered.
    • Click the Register Domain button.  This could take a few minutes.

  5. You will receive an email when registration is complete as shown in the image below. 

    • Within the registration email, click on your new domain link and log in to your domain.
    • Enter your Phone Number in the popup window. An access code is immediately sent to your mobile phone. Enter the access code into the popup and continue to log in.

  6. The Setup Home page for your new domain opens in a separate browser window.  Navigate to Settings > Company Settings > My Domain.

    • Your Domain is now ready for testing.  Please see Salesforce testing guidelines at Test and Deploy Your New My Domain.
    • When testing is complete, return to Settings > Company Settings > My Domain. In the section My Domain Step 3, click the Deploy to Users button.

  7. A warning message displays as shown below. 
    • Click OK to immediately activate the domain. 
    • If you select Cancel, you will be required to return to this page to enable the new domain later.

Enabling an Identity Provider in Salesforce

  1. While logged into your new domain, navigate to Identity >Identity Provider to display the page shown below.  
  2. In the section Identity Provider Setup, click the Enable Identity Provider button.

  3. A Warning message displays regarding the default certificate that is selected.

    • Select Save if the default certificate is correct.
    • If a different certificate applies, select the certificate in the dropdown list and then click Save.
    • Please see Salesforce documentation regarding certificates at Enable Salesforce as an Identity Provider.

  4. A popup window warns you if the selected certificate will affect existing Service Providers. 

    • Select OK to enable your Identity Provider. 
    • If you select Cancel, you will be required to return to this page to enable the Identity Provider later.

  5. Once the Identity Provider is enabled, the provider details display as shown in the image below.

Creating a Salesforce OAuth Connected APP

  1. Navigate to Platform Tools > Apps >Apps Manager while logged into your domain.
  2. Select New Connected App in the upper right corner of the page.

  3. The New Connected App page displays as shown below.
    • Enter a Connected App Name, API Name and a Contact Email. These required fields are marked with a red bar on the left side of each field.
    • Enter a short description of the Connected App in the Description field to identify the purpose and intent of the App.
    • In the section API (Enable OAuth Settings), click the Enable OAuth Settings checkbox. 

  4. Additional fields display once the API (Enable OAuth Settings) are enabled.
    • Callback URL: Enter the redirect URLs for your region in the Callback URL text box.  See Finding My Region.
      • NA region:
        • Copy these: 
          • https://apps.na-east.jitterbit.com/api-manager/oauthredirect/authcode
          • https://apps.na-east.jitterbit.com/api-manager/swagger-ui/oauthredirect
        • Construct the following URL substituting your Jitterbit org base URL and the name of the security profile you have created for Salesforce OAuth 2.0 authentication:  
          • https://<org base URL>/_oauth/<oauth profile name>

            TIP:

            • Your <org base URL> displays at the top of the My APIs page and is in the format of jitterbittrial#####.jitterbit.net
            • You must enter "jitterbittrial" all in lower case.
      • EMEA region
        • Copy these:
          • https://apps.emea-west.jitterbit.com/api-manager/oauthredirect/authcode
          • https://apps.emea-west.jitterbit.com/api-manager/swagger-ui/oauthredirect 
        • Construct the following URL substituting your Jitterbit org base URL and the name of the security profile you have created for Salesforce OAuth 2.0 authentication: 
          • https://<org base URL>/_oauth/<oauth profile name>

            TIP:

            • Your <org base URL> displays at the top of the My APIs page and is in the format of jitterbittrial#####.jitterbit.eu
            • You must enter "jitterbittrial" all in lower case.
      • APAC region:
        • Copy these:
          • https://apps.apac-southeast.jitterbit.com/api-manager/oauthredirect/authcode
          • https://apps.apac-southeast.jitterbit.com/api-manager/swagger-ui/oauthredirect 
        • Construct the following URL substituting your Jitterbit org base URL and the name of the security profile you have created for Salesforce OAuth 2.0 authentication: 
          • https://<org base URL>/_oauth/<oauth profile name>

            TIP:

            • Your <org base URL> displays at the top of the My APIs page and is in the format of jitterbittrial#####.jitterbit.cc
            • You must enter "jitterbittrial" all in lower case.
    • Selected OAuth Scopes: 
      • Select Full access (full) from the Available OAuth Scopes section and click the Add button to move the scope into the Selected OAuth Scopes section.
      • Select Perform requests on your behalf at any time (refresh_token, offline_access) and click the Add button to move the scope into the Selected OAuth Scopes section.
      • Click the Save button at the bottom of the page to save the App settings.

  5. The API (Enable OAuth Settings) section, as shown below, provides the Consumer Key (equivalent to Client ID in Jitterbit) and Consumer Secret (equivalent to Client Secret in Jitterbit). These two credentials will be required when Creating a Salesforce OAuth 2.0 Security Profile.

    • A note displays indicating to allow 2-10 minutes after saving the App before attempting to authenticate APIs.
    • Click Continue to return to the App page.

      TIP: Leave this page open to facilitate copying information into the security profile.
  6. You can return to your Salesforce domain and view your consumer key and consumer secret at any time. Navigate to Apps > App Manager and select View in the actions dropdown for your Connected App. The consumer key, consumer secret, and all assigned callback URLs display. Additional redirect URIs may be added later as necessary. 

Creating a Salesforce OAuth 2.0 Security Profile

  1. Log in to Harmony, select the API Manager application card and select Security Profile from the dropdown menu.
  2. Click on Create New Profile in the upper right corner of the page.

  3. The View/Edit Security Profile page displays as shown below.

    • Name: Provide a name for the profile.
    • Environment: Select the environment the security profile will be assigned to from the dropdown list.
    • Description: Provide a description of the profile and assigned APIs.

  4. Scroll down the Type field. 
    • Type: Select OAuth 2.0 from the dropdown list.
    • OAuth Provider: Select Salesforce from the dropdown.

  5. Scroll down to OAuth Client ID.

    • OAuth Client ID: The Client ID is generated within your Salesforce Domain as described in Creating a Salesforce OAuth Connected App.
      • Return to the open browser window displaying the Salesforce API (Enable OAuth Settings) page. 
      • Copy the Consumer Key from Salesforce and paste into the OAuth Client ID field in the View/Edit Security Profile page as shown in the image above.
    • OAuth Client Secret: The Client Secret is generated within your Salesforce Domain as described in Creating a Salesforce OAuth Connected App.
      • Return to the open browser window displaying the Salesforce API (Enable OAuth Settings) page. 
      • Copy the Consumer Secret from Salesforce and paste into the OAuth Client Secret field in the View/Edit Security Profile page as shown in the image above.

  6. Scroll down to the OAuth Authorization URL.

    • OAuth Authorization URL: This field is optional and is populated with the standard Salesforce authorization URL.  Replace this URL with your Salesforce custom authorization URL if required.
    • OAuth Token URL: This field is optional and is populated with the standard Salesforce token URL. Replace this URL with your Salesforce custom token URL if required.
    • User Info URL: This field is optional and is populated with the standard Salesforce user information URL.  Replace this URL with your Salesforce custom user information URL if required.
    • Test Client ID + Secret: Click the Test Client ID + Secret button to test communication between Harmony and Salesforce.

  7. A popup window will display asking you to log in to Salesforce. 

    • Click on the x to clear the username field. 
    • Enter your Username and Password.

  8. A popup window displays requesting access to your Salesforce information. 

    • Click the Allow button. 

  9. A separate browser window displays a message in the upper left corner of the page indicating if the Client ID + Secret verified successfully. 
    • If the test fails:
      • Verify the Consumer Key (Client ID in Jitterbit) and Consumer Secret (Client Secret in Jitterbit) are correct in the security profile. 
      • Verify the OAuth Authorization URL, OAuth Token URL, and User Info URL are correct in the security profile if you are using custom Salesforce URLs.
      • Verify the Callback URLs in the Salesforce Connected App are correct for your org base URL, security profile name, and region.
    • If the test is successful, close this page to return to the View/Edit Security Profile page.

  10. Scroll down to Logging.

    • Complete the settings in the Authorized Domains, Logging, Trusted IP Ranges and Rate Limit sections. See Security Profiles and Harmony API Security for additional information about these security settings.
    • Click on the Save button at the bottom of the page when all settings are complete.

Assign the Salesforce OAuth 2.0 Security Profile to an API

  1. Log in to Harmony, select the API Manager application card and select My APIs from the dropdown menu.
  2. Hover over the API card and select View/Edit.


  3. The Publish New API page displays as shown below.
    • Scroll down to the Security Profiles section and click the edit icon .

  4. The Assign Security Profile page displays as shown below. 
    • Select the Salesforce OAuth 2.0 security profile from the dropdown list.
    • Click the Assign Profile button.
    • Click the Save Changes button at the bottom of the page.
    • Click Save Changes in the popup window.
    • Click the Save & Publish button at the bottom of the Publish New API page.

  5. After selecting Save & Publish, the API is live and accessible. Select the Copy URL icon , and paste the link into your browser.


  6. A popup window will display asking you to log in to Salesforce. 

    • Click on the x to clear the username field.
    • Enter your Username and Password.

  7. A popup window displays requesting access to your Salesforce information.

    • Click the Allow button. 

  8. If the authentication is successful, the expected payload will display in your browser.
    • If the API does not run successfully:
      • Verify the Consumer Key (Client ID in Jitterbit) and Consumer Secret (Client Secret in Jitterbit) were copied correctly into the security profile.
      • Verify the OAuth Authorization URL, OAuth Token URL, and User Info URL are correct in the security profile if you are using custom Salesforce URLs.
      • Verify the Callback URLs in the Salesforce Connected App are correct for your org base URL, security profile name, and region.

Additional Salesforce OAuth 2.0 Resources

On This Page

Related Topics

Last updated:  Aug 09, 2019


  • No labels