Introduction
After installing and configuring WatchMe to provide User video demonstrations, the next step is to enable on-demand Debug Logs to every WatchMe, further empowering your support teams to solve issues faster. To enable Debug Logs, we need to set up three security elements. Once these are configured, Debug Logs will start to work auto-magically.
Because most companies prefer to control their own Salesforce security elements, we have decided not to include them directly in the WatchMe managed package. It's a few more clicks to set up, but it keeps your secrets right where they should be...with you.
These configurations may be unfamiliar to many 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 1 - Create a Digital Signature (if one does not exist)
First, we will create and download a Digital Signature file for use in steps 2 and 3. 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. From there, click the "Download Certificate" button and save the certificate to your computer (we will use it again in a moment). Congratulations! Your already done with 1 of the 3 steps!
Step 2 - Add an External Client App
Now, the toughest part. The truth is that there is not much to the External Client Application, 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. Start by going to Setup -> External Client App Manager and click the New External Client App button in the upper right-hand corner. Name the App 'WatchMe' and provide the required email address.
At the bottom of the screen expand the collapsed "API (Enabled OAuth Settings)" section and check "Enable OAuth." When you do this, a few new options will appear.
The Callback URL is not specifically 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 on that page 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 step 1.
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 the cloned Permission set we created in the Configuration article 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).
Copy the Consumer Key (NOT the Consumer Secret) for use in an upcoming step. Whew! We are finally done with the External Client App configuration. That was a lot to take in, but you did it brilliantly! We are almost there. Just one more element to go!
Step 3 - 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 a couple of different ways to work with Named Credentials. If you are more familiar with the modern Named Credentials, then go for it! 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.
Once you've created your new Named Credential, fill out the pieces as shown below. If you'd like to learn more about the details of Named Credentials, consult Salesforce help articles. For now, 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 "WatchMe".
- 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 for production environments and 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!
Summary
Security configuration helps WatchMe access the resources your team needs to be successful. With these security configurations in place, you are ready to start helping your team to help your users! On to the next section!