Introduction
Part 1 Setup and Configuration
Step 1 - Install the Managed Package
Install the package from the AppExchange (not available during beta) or from the installation link provided by the Watch Me team. We recommend installing for Admins Only (and applying appropriate Permission Sets later), but the choice is yours. Follow the prompts until the installation is complete and/or you receive an installation success email from Salesforce.
Step 2 - Clone the Watch Me Permission Set
The External Client App (ECA), which we will create in the next step, must be assigned to Permission Sets (or profiles) to govern which users can use its credentials. However, since the Watch Me Permission Set is part of the managed package, it cannot be selected for the ECA. Therefore, we must clone the Watch Me Permission Set (so the ECA can select it at the appropriate time).
Go to Setup -> Permission Sets and click the 'Clone button' next to the Watch Me Permission Set. Give it a custom name (e.g., "My Watch Me") and save. If it is clear which users will be using Watch Me, you are free to assign the new cloned Permission set to them at this time.
Step 3 - Add the Global Publisher
Users typically access Watch Me through a Global Publisher action, which is included in the managed package. To add it to your org, go to Setup -> Global actions -> Publisher Layouts and click the Edit link next to the Global Layout record.
Select "Mobile & Lightning Actions" and drag the Watch Me action onto the Salesforce mobile and Lightning Experience Actions section. You can now launch the Watch Me application, but it will not work correctly until we configure some additional security-related items.
Part 2 - Security Setup
This next section may be unfamiliar to some admins, but don't worry...we will walk you through each step. If you want to learn more about the purpose of these elements and why we need them in the Watch Me application, please read our article on "How Watch Me uses OAuth 2.0".
Step 4 - Create a Digital Signature (if one does not exist)
In this step, we will create and download a Digital Signature file for use in step 5 and 6. Fortunately, Salesforce handles all the details of generating the certificate, and we only need to make a few clicks.
Go to Setup -> Certificate and Key Management. Click the "CreateSelf-Signed Certificate" button, give your new certificate a name, and click Save. That's it! You can name the certificate anything you like, but remember that you may use this Certificate for other things in Salesforce (in fact, you may find that one already exists).
Once you have created the certificate, click the Label link to view the certificate details screen. On that screen, click the "Download Certificate" button and save the certificate to your computer (we will use it again in a moment).
Step 5 - Add an External Client App
Now, the tricky part. The truth is that there is not much to the External Client App, but because it is new to many people, it can be intimidating. Don't worry! We believe in you and will walk you through every step. Go to Setup -> External Client App Manager and click the New External Client App button in the upper right-hand corner. Name the App 'Watch Me' and provide the required email address.
At the bottom of the screen expand the collapsed "OAuth" section and check "Enable OAuth." When you do this, a bunch of new options will appear.
The Callback URL is not relevant for our purposes (because our security will not rely on browser-based user inputs), but it is required. Typically the Salesforce base URL is entered. OAuth scopes determine which types of activities this External Client App will allow users to perform. For our purposes, select the two options shown above.
Scroll down and select the "Enable JWT Bearer Flow" checkbox. When checked, a file upload component will appear. Click the upload button and select the certificate file you downloaded in the last step.
That's it. Leave everything else to their defaults and click the Create button at the bottom of the screen. You have successfully created an External Client App!
And Now...The Hidden Secrets
The External Client App interface is new to Salesforce and can be a bit confusing. Even though we completed the data entry on the Create screen, there is a little more to do. Click on the link to your newly created app and notice that there are three tabs: Policies, Settings, and Package Defaults. There are just two more things we need to do. On the Policies tab, click the edit button.
In the Plugin Policies section, make sure the "Admin approved users are pre-authorized" policy is selected. Also, select your cloned Permission set to be available for use with this External Client App. When those items are complete, click the Save Button and head over to the Settings tab.
Under the App Settings section, click the Consumer Key and Secret button (Because this is super secret information, Salesforce will want to send you a verification code before proceeding.)
Once you have found these values, copy the Consumer Key (NOT the Consumer Secret) for use in an upcoming step. Whew! That was a lot to take in, but you did brilliantly! We are almost there. Just one more step to go!
Step 6 - Configure a Named Credential
We are at the final step. Go to Setup -> Named Credential to put the final piece in place. As of now, there are couple of different ways to work with Named Credentials. For simplicity's sake, we are going to use what's called a "Legacy Named" credential (there are fewer parts!) Click the New Legacy button.
Please fill out the pieces as shown below. If you have any trouble with the configuration, reach out to us, and we will walk you through everything!
- Name - For the application to work properly, it is critical that the name of this Named Credential be "Watch_Me."
- URL - Enter the mydomain URL for your org. If you are uncertain of your mydomain URL, go to the Developer Console and open the Debug -> Open Execute Anonymous Window. Enter the line System.debug('*****: ' + URL.getOrgDomainUrl()); and click execute. When you open the log, you will see the proper url
- Certificate - Select the certificate you created in earlier steps. (We have noticed that this value has a tendency to be blanked out when other options on this page are set, so you may want to come back and set this last).
- Identity Type - Select Named Principal
- Authentication Protocol - Select JWT Token Exchange. When you select this value, new options will appear on the screen. Don't panic...This is normal.
- Token Endpoint Url - This is the same value you set for the Url property but adds the standardized "/services/oauth2/token" to the end
- Issuer - Remember the Consumer Key you copied from the External Client App? Now's your chance to use it! Paste it here.
- Named Principal Subject - This is the Salesforce username of the User whose credentials will be used for access to back-end elements. Be sure that this user has everything they need to make calls to the tooling API and has been assigned the appropriate Watch Me Permission Set.
- Audiences - This value is always https://login.salesforce.com (or https://test.salesforce.com for sandboxes)
- Token Valid For - Enter a value here
- JWT Signing Certificate - For our purposes in the Watch Me application, this will be the same certificate you selected for the first option.
The very last thing to do is to click the Save button and you are done!
Trouble Shooting Tips
- Unable to exchange JWT Token - There is a problem with how the External Client App and/or the Named Credentials are configured
- Consumer has not approved this User - Permitted Users is set to All users can self-authorize in the External Client App