Introduction
This article will detail the 3 steps needed to create an S-Docs Connected App to use with S-Sign e-signatures. Note that these steps can also be found in the S-Sign Installation & Configuration articles for Lightning and Classic.
Step 1: Create a Self-Signed Certificate
From the setup menu, type "Certificate" into the Quick Find bar, then click Certificate and Key Management in the dropdown menu. Click Create Self-Signed Certificate.
Name your certificate SDocsCert. Click Save.
Click Download Certificate, and keep track of where the file is stored. We will use this in the next step.
Step 2: Create A New Connected App
Navigating to the Connected App creation page is a bit different in Classic and Lightning. In Lightning, type "App Manager" into the Quick Find bar in the setup menu, then click App Manager in the dropdown menu. Click New Connected App in the top right.
In Classic, type "Apps" into the Quick Find bar in the setup menu, then click Apps in the dropdown menu (under Build > Create). Scroll down to the Connected Apps section and click New.
In the Basic Information section, fill in the following fields:
Connected App Name: Sdocs Connected Apps
API Name: Sdocs_Connected_Apps
Contact Email: support@sdocs.com
Scroll down to the API (Enable OAuth Settings) section and check Enable OAuth Settings. Then, enter one of the following URLs into the Callback URL field, depending on if you're working in a sandbox or production environment:
Production: https://login.salesforce.com/services/oauth2/callback
Sandbox: https://test.salesforce.com/services/oauth2/callback
Next, check the Use Digital Signatures checkbox and upload the self-signed certificate that you downloaded in step 1.
Then, scroll down to the Selected OAuth Scopes field. Add the following scopes to your selected scopes:
- Access Connect REST API resources (chatter_api)
- Manage user data via APIs (api)
- Perform requests at any time (refresh_token, offline_access)
This section should look similar to the following image when you are finished:
Leave the rest of the fields at their default settings, and click Save. You will be redirected to the Connected App detail page. Scroll down to the API (Enable OAuth Settings) section and click Copy next to the Consumer Key field. Paste this somewhere you can access later. You will use this key in Step 3. Then, click Manage at the top of the page.
On the next page, click Edit Policies.
Scroll down to the OAuth Policies section. Set the Permitted Users field to Admin approved users are pre-authorized. Set the IP Relaxation field in accordance with your organization's policies. Keep the Refresh Token Policy set to Refresh token is valid until revoked. Then, click Save.
Next, scroll down to the Profiles section and click Manage Profiles.
Add the profile assigned to the S-Sign Internal User. As a reminder, we recommend choosing a generic Salesforce Administrator User as the S-Sign Internal User. All S-Sign operations will be conducted through this user and the secure S-Docs Connected App.
Click Save.
Step 3: Create A New Custom Setting Entry
From the setup menu, type "Custom Settings" into the Quick Find bar, then click Custom Settings in the dropdown menu. Find SDocsSettings and click Manage.
If you've created an S-DocsSettings entry in the past, you can click the Edit link next to its name to edit it now. Otherwise, click New to create a new SDocsSettings entry.
Fill in the following values:
Name: SDocsSettings
ConnectedAppCertificateName: SDocsCert
ConnectedAppConsumerKey: Paste the consumer key that you copied in step 2
ConnectedAppLoginURL:
[Production]: https://login.salesforce.com
[Sandbox]: https://test.salesforce.com
ConnectedAppTokenURL: Enter your Salesforce domain URL.
To find your domain in Lightning, click your user profile in the upper right corner and copy it from under your username. Make sure to add "https://" at the beginning.
To find your domain in Classic, navigate to the Home screen and copy it from your browser's URL bar up to the first forward slash.
ConnectedAppUserName: Enter the username that you want to use as the S-Sign Internal User. As a reminder, we recommend choosing a generic Salesforce Administrator User as the S-Sign Internal User. All S-Sign operations will be conducted through this user and the secure S-Docs Connected App.
Your SDocsSettings entry should look similar to the following:
Click Save.
You've now successfully configured your S-Docs Connected App.
Troubleshooting
My Self-Signed Certificate is Expiring Soon!
Several months after setting this up, you may get an email from Salesforce informing you that your self-signed certificate expired. If that is the case, you can follow the steps below to renew your certificate. We recommend doing this after hours.
Navigate to the Certificate and Key Management page (Setup > Security > Certificate and Key Management) and find SDocsCert. Click Del next to its name to delete it.
Then, click Create Self-Signed Certificate (the button above where your previous certificate was listed).
Name your certificate SDocsCert. Click Save.
Click Download Certificate.
Next, you need to update your Connected App with your new Self-Signed Certificate.
Navigating to the Connected App page is a bit different in Classic and Lightning. In Lightning, type "App Manager" into the Quick Find bar in the setup menu, then click App Manager in the dropdown menu. Find Sdocs Connected Apps, click the dropdown arrow on the right, and click Edit.
In Classic, type "Apps" into the Quick Find bar in the setup menu, then click Apps in the dropdown menu (under Build > Create). Scroll down to the Connected Apps section, find Sdocs Connected Apps, and click Edit.
Once you've navigated to the Connected App Edit page, scroll down to the API (Enable OAuth Settings) section and find the Use digital signatures field. Click Choose File to upload your new Self-Signed Certificate.
Click Save. Note that it may take several minutes for the new certificate to take effect.
Take the update time to double check that your connected app's Consumer Key has not changed:
- From the Sdocs Connected Apps "View" page, click "Manage Consumer Details" in the middle of the page and re-authenticate
- Click the "Copy" button for the Consumer Key
- Compare this Key against the ConnectedAppConsumerKey in your SDocsSettings record
- If the keys do not match, replace the old Key with the new value and Save
General Troubleshooting
If you performed this setup but are receiving errors, please try the following:
- Navigate to Setup > Connected Apps > SDocs Connected Apps > Profiles, and verify that the profiles of the following users are added to the app's permitted profiles list:
- The S-Sign Internal User
- Go to Setup > Remote Site Settings and verify that there are entries for the appropriate Salesforce production/sandbox URL and the customer’s home URL (Salesforce Classic). Additionally, verify that these entries are active.
- Make sure the user's profile has the Apex REST Services permission checked.