JWT Grant OAuth Flow Setup
v1 - 1.36 of fmESignature Link (DocuSign Edition) used the JWT Grant OAuth Flow authentication method for authenticating with the DocuSign API. In v1.4 of fmESignature Link we have changed to using the Authorization Code Grant method - this removes the requirement to use a FileMaker Web Viewer to run a JavaScript function to generate the JWT Token and in turn call a FileMaker script using an fmp url.
The use of the Web Viewer and the associated call to run an fmp url script whilst other FileMaker scripts were running was causing some challenges for certain integrations by our customers, so we have moved to the Authorization Code Grant which does require the user to initially authenticate the use of the DocuSign app by FileMaker. Once that has been approved the Access Token is generated and stored and can be refreshed without requiring the user to authenticate again.
If you are using v1 - 1.36 of fmESignature Link with the JWT Grant authentication method you can follow these instructions to setup your Sandbox app and fmESignature Link (DocuSign Edition):
DocuSign Sandbox Setup
Setting up your DocuSign Sandbox account to allow you to send test document signing requests from the fmESignature Link file only takes a few minutes – you need to complete the following steps:
- create your DocuSign Sandbox account
- create a new API and Integration Keys in the Sandbox
- copy/paste the keys into the fmESignature Link (DocuSign Edition) Setup screen
We have a short video demonstrating the setup of the DocuSign Sandbox and creating a new API integration – check out the videos page to view this video. The DocuSign Getting Started guide also has details on creating your first API integration.
Once you’ve created your free Developer Sandbox Account you need to first create the Integration Key that you will use with the fmESignature Link file. We recommend having the fmESignature Link file open at the same time on the Setup screen so you can copy/paste keys from your Sandbox account directly to FileMaker:
After you have logged in to your Sandbox account select Settings from the navigation menu across the top:
On the lower left side of the Admin Console select API and Keys to view your existing API apps and create a new set of API keys.
Your API Username can be found under the My Account Information section. Copy and paste this into the API Username field in the Sandbox Preferences.
The API Account ID will be generated automatically by DocuSign. Copy and paste this into the API Account ID field in the Sandbox Preferences
Click the ADD APP & INTEGRATION KEY button to create a new Sandbox App:
First enter an App Name to use for your integration and click the Add button to see the rest of your integration settings:
You will need to record information from this page – for some of the information you will only get one chance to record this (you can always delete the integration and create a new one if this happens) so be careful as you record the information.
Integration Key: this is generated automatically by DocuSign. Copy and paste this into the Integrator Key field in the Sandbox Preferences
Authentication: select Authorization Code Grant (should already be set as the default)
RSA Keypairs: click the Add RSA Keypair button to generate a Public and Private Key. Record these somewhere safe as they are only visible once upon creation. Copy and paste the Private Key into the Private Key field in the Sandbox Preferences
Additional Settings: Redirect URIs: add the following URI: https://docusign.com
Click Save when you have finished. We now need to perform a one time
Once you’ve created your API keys and entered these into the Setup screen in the fmESignature Link file you need to then get consent to allow the fmESignature Link file to make API calls on behalf of a user. To allow fmESignature Link to impersonate a user via API calls click the Request Application Consent button – it will open your web browser and redirect you to a page like this where you can grant consent:
Once permission has been granted you are then able to use fmESignature Link to send document signing requests automatically without requiring the user to login and authorise each request.
When you make a request to the DocuSign API (e.g. to send a signing request) the fmESignature Link file will then perform the authentication with the DocuSign API and you will see the following screen appear:
Here the Web Viewer is loading a blank html page which contains a JavaScript function to generate the JWT Token and then, using the fmp url protocol, call the processSignatureRequest FileMaker script passing in the JWT Token as a script parameter.
If you are having issues with the Web Viewer and the the processSignatureRequest FileMaker script not running when called using the fmp url protocol check out the following support articles: