{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":21491,"path":"integrate-applications/integration-hub/setup-docusign-jwt.md","title":"Set up Docusign eSignature spoke using JWT grant","bundle":null,"doc_type":null,"release":"australia","body":"\n# Set up Docusign eSignature spoke using JWT grant\n\nIntegrate the ServiceNow instance and Docusign by using JWT grant to authenticate ServiceNow requests.\n\n## Before you begin\n\n- Request an Integration Hub subscription.\n- Activate the Docusign eSignature spoke.\n- Role required: admin.\n\n**Important:** If you are setting up Docusign eSignature spoke using JWT grant, you need not set up the spoke using authorization code grant.\n\n## Configure Docusign account\n\nCreate a custom OAuth application from your Docusign account to enable OAuth 2.0 authentication with the Docusign eSignature spoke.\n\n### Before you begin\n\nDocusign requirements:\n\n- Docusign account\n- Docusign app configured to integrate with ServiceNow\n- Role required: Docusign administrator\n\n### About this task\n\nComplete these steps from your Docusign account. See the [Docusign Developer Center](https://developers.docusign.com/) documentation for instructions on creating and configuring custom applications. Docusign uses a scripted webhook to send signed document data to ServiceNow instance. This enables flow designers to pause a flow until a document is signed, and use document data in the flow.\n\n### Procedure\n\n1. From your Docusign account, register your application.\n\n2. Generate an integrator key and secret key.\n\n3. Record the values of integrator key and secret key to register the app as a third-party OAuth provider on your ServiceNow instance.\n\n You need these values when you [Register Docusign as OAuth Provider](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/integrate-applications/integration-hub/setup-docusign-jwt.md)\n\n4. Click **ADD RSA KEYPAIR** and record the **Keypair ID**, **Public Key**, and **Private Key**.\n\n5. Add the ServiceNow OAuth Redirect URL in your Docusign account.\n\n 1. Navigate to **Integrations** > **App and Keys**.\n\n 2. Under **Apps and Integration Keys**,find the required app.\n\n 3. For the required app, click the **Actions** drop-down list and click **Edit**.\n\n 4. Under **Additional settings**, click **Add URI** and add the OAuth callback endpoint in this format: `https://.service-now.com/oauth_redirect.do`.\n\n \\[Omitted image \"docusign-add-redirect-uri.png\"\\] Alt text: Add Redirect URI in Docusign account.\n\n6. Obtain the value of **Account Base URI** from the Docusign account.\n\n 1. Navigate to **Integrations** > **App and Keys**.\n\n 2. Under **My Account Information**, you can find the value of the **Account Base URI**.\n\n \\[Omitted image \"docusign-acct-base-uri.png\"\\] Alt text: Account Base URI.\n\n 3. Copy and record this value for later use.\n\n\n## Generate the JKS certificate\n\nGenerate a JKS certificate for the JWT authentication of the Docusign eSignature spoke.\n\n### Before you begin\n\nRole required: admin\n\n### Procedure\n\n1. Open the text editor for code such as, Sublime Text.\n\n2. Create a new file.\n\n3. Paste the Private Key you had earlier generated from your Docusign integrator app.\n\n For more information, see [Configure Docusign account](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/integrate-applications/integration-hub/setup-docusign-jwt.md).\n\n **Note:** Ensure that you include both beginning and ending of the private key.\n\n4. Save the file with the .key extension, for example, `privatekey.key`.\n\n5. Open terminal and navigate to the directory where you saved the file with the `.key` extension.\n\n6. Create a CA signed certificate using your private key by executing the command:\n\n ```\n openssl req -new -x509 -key .key -out .pem -days 1095\n ```\n\n System prompts you to provide required details such as Country Name, Province Name and so on.\n\n7. Enter the required details.\n\n8. Create PKCS 12 file using your private key and CA signed certificate by executing the command:\n\n ```\n openssl pkcs12 -export -in .pem -inkey .key -certfile .pem -out .p12 \n ```\n\n System prompts you to provide a password.\n\n9. Provide the export password.\n\n10. Create the JKS file by executing this command:\n\n ```\n keytool -importkeystore -srckeystore .p12 -srcstoretype pkcs12 -destkeystore .jks -deststoretype JKS\n ```\n\n System prompts you to provide a password.\n\n11. Provide the destination and source keystore passwords.\n\n\n## Attach a Java Key Store certificate to the Docusign eSignature spoke\n\nEnable the JWT Bearer Grant token authentication by attaching a valid Java KeyStore \\(JKS\\) certificate to the Docusign eSignature spoke.\n\n### Before you begin\n\n- Ensure the availability of a valid Java KeyStore certificate\n- Role required: admin\n\n### Procedure\n\n1. Navigate to **All** > **System Definition** > **Certificates**.\n\n2. Click **New**.\n\n3. Complete the form.\n\n |Field|Description|\n |-----|-----------|\n |Name|Enter a name to uniquely identify the record. For example, `Docusign Certificate`.|\n |Notify on expiration|Define users to be notified when the certificate expires.|\n |Warn in days to expire|Enter the number of days to send a notification before the certificate expires.|\n |Active|Enable|\n |Type|Select **Java Key Store**.|\n |Expires in days|Enter the number of days until the certificate expires.|\n |Key store password|Enter a password associated with the certificate.|\n |Short description|Enter a summary about the certificate.|\n\n4. Click the attachments icon \\(\\[Omitted image \"attachments-icon.png\"\\] Alt text: Attachments icon\\) and attach a JKS certificate.\n\n5. Click **Validate Stores/Certificates**.\n\n\n## Create a JWT signing key for the Docusign eSignature spoke\n\nCreate a JSON Web Token \\(JWT\\) signing key to assign to your Java KeyStore certificate.\n\n### Before you begin\n\nRole required: admin.\n\n### Procedure\n\n1. Navigate to **All** > **System OAuth** > **JWT Keys**.\n\n2. Click **New**.\n\n3. Complete the form.\n\n |Field|Description|\n |-----|-----------|\n |Name|Enter a name to uniquely identify the JWT signing key. For example, `Docusign JWT Keys`.|\n |Signing Keystore|Select the valid JKS certificate attached in the previous task. For example, `Docusign Certificate`.|\n |Key Id|Enter a key Id to identify which key is used when multiple keys are used to sign tokens.|\n |Signing Algorithm|Select an algorithm to sign with the JWT key.|\n |Signing Key Password|Enter a password associated with the signing key.|\n |Active|Enable.|\n\n4. Click **Submit**.\n\n\n## Create a JWT provider for the Docusign eSignature spoke\n\nAdd a JSON Web Token \\(JWT\\) provider to your ServiceNow instance.\n\n### Before you begin\n\nRole required: admin.\n\n### Procedure\n\n1. Navigate to **All** > **System OAuth** > **JWT Providers**.\n\n2. Click **New**.\n\n3. On the form, fill in the fields.\n\n |Field|Description|\n |-----|-----------|\n |Name|Enter a name to uniquely identify the JWT provider. For example, `Docusign JWT Provider`.|\n |Expiry Interval \\(sec\\)|Enter a number in seconds to set the lifespan of JWT provider tokens.|\n |Signing Configuration|Select a JWT signing key. For example, `Docusign JWT Keys`.|\n\n4. Right-click the form header, and click **Save**.\n\n The Standard Claims and Custom Claims related lists display.\n\n5. On the same page of the JWT provider record, enter values for **iss**, **sub**, and **aud** in the **Standard Claims** related list.\n\n |Claim|Value|\n |-----|-----|\n |iss|``|\n |sub|``|\n |aud|`account-d.docusign.com`|\n\n For more information, see [How to get an access token with JWT Grant](https://developers.docusign.com/platform/auth/jwt-get-token/) in [Docusign Developer Center](https://developers.docusign.com/).\n\n6. Insert a record in the **Custom Claims** related list and complete the form.\n\n |Field|Value|\n |-----|-----|\n |Claim Name|scope|\n |Claim Value Type|string|\n |Claim Value|signature impersonation|\n\n7. Click **Update**.\n\n\n## Register Docusign as OAuth Provider\n\nUse the information generated during Docusign account configuration to register Docusign as an OAuth provider and allow the instance to request OAuth 2.0 tokens.\n\n### Before you begin\n\nRole required: admin.\n\n### Procedure\n\n1. Navigate to **All** > **System OAuth** > **Application Registry**.\n\n2. Click **New**.\n\n The system displays the message **What kind of OAuth application?**\n\n3. Select **Connect to a third party OAuth Provider**.\n\n The system displays a blank Application Registries form.\n\n4. Complete the form.\n\n\n
\n\nField\n\n\n\nValue required\n\n
\n\nName\n\n\n\nEnter any name to uniquely identify the record. For example, enter `Docusign OAuth`.\n\n
\n\nClient ID\n\n\n\nEnter the integrator key you generated during the Docusign account configuration.\n\n
\n\nClient Secret\n\n\n\nEnter the client secret you generated during the Docusign account configuration.\n\n
\n\nDefault Grant type\n\n\n\nSelect **JWT Bearer**.\n\n
\n\nAuthorization URL\n\n\n\n- For developer sandbox environment, enter `https://account-d.docusign.com/oauth/auth`.\n- For live production system, enter `https://account.docusign.com/oauth/auth`.\n\n\n
\n\nToken URL\n\n\n\n- For developer sandbox environment, enter `https://account-d.docusign.com/oauth/token`.\n- For live production system, enter `https://account.docusign.com/oauth/token`. For more information see, [Post Go-Live](https://developers.docusign.com/esign-rest-api/guides/post-go-live) and [User Info Endpoint Reference](https://developers.docusign.com/esign-rest-api/guides/authentication/user-info-endpoints) in the [Docusign Developer Center](https://developers.docusign.com/) documentation.\n\n\n
5. Right-click the form header, and click **Save**.\n\n - The system validates the OAuth credentials and populates the **Redirect URL**.\n - The system populates **OAuth Entity Profile** with **Grant Type** as **JWT Bearer**. For example, **OAuth Entity Profile** is created with default **Name**, **Docusign OAuth default\\_profile**\n6. Insert a record in the **OAuth Entity Scopes** related list and fill the values.\n\n |Field|Value|\n |-----|-----|\n |Name|scope|\n |OAuth Scope|signature impersonation|\n\n7. Copy the value from **Redirect URL**.\n\n8. Click **Update**.\n\n9. Login to your Docusign account to edit the configuration of your custom Docusign application.\n\n See the [Docusign Developer Center](https://developers.docusign.com/) for instructions.\n\n10. Paste the Redirect URL value into the Redirect URI for your custom Docusign application.\n\n For example, paste `https://instance.service-now.com/oauth_redirect.do`\n\n\n### Result\n\nThe instance can request OAuth 2.0 tokens for the spoke.\n\n**Note:** When an OAuth token expires, the spoke automatically regenerates a new token in most cases. If a token expires and is not regenerated, an administrator can regenerate the spoke OAuth token.\n\n## Obtain consent\n\nObtain explicit consent for the ServiceNow application from Docusign.\n\nRole required: admin\n\n### Obtain consent for an organization administrator\n\nSee [Docusign Developer documentation \\(Admin consent for internal applications\\)](https://developers.docusign.com/esign-rest-api/guides/authentication/obtaining-consent#admin-consent-for-internal-applications) for instructions to obtain consent for an organization administrator.\n\n## Create Credential records for the Docusign eSignature spoke\n\nCreate Credential records to the Docusign custom OAuth application you created during Docusign account configuration. The Docusign spoke connection and credential alias uses these credentials to authorize actions.\n\n### Before you begin\n\nRole required: admin.\n\n### Procedure\n\n1. Navigate to **All** > **Connections & Credentials** > **Credentials**.\n\n2. Click **New**.\n\n The system displays the message **What type of Credentials would you like to create?**.\n\n3. Select **OAuth 2.0 Credentials**.\n\n The pop-up window displays a blank OAuth 2.0 Credentials form.\n\n4. Fill these values.\n\n |Field|Value required|\n |-----|--------------|\n |Name|Enter any name to uniquely identify the record. For example, enter `Docusign Credentials`.|\n |Active|Enable|\n |OAuth Entity Profile|Select the OAuth profile you created when you registered the custom Docusign application as an OAuth provider. For example, select **Docusign OAuth default\\_profile**.|\n |Applies to|Select the MID Servers that can use this credential. For example, select **All MID Servers**.|\n |Order|Select the order to apply this credential. For example, enter `100`.|\n\n5. Save the record.\n\n6. Click the **Get OAuth Token** related link to generate the OAuth token.\n\n\n## Create Connection records for the Docusign eSignature spoke\n\nCreate Connection records to your Docusign account. The Docusign spoke connection and credential alias uses these connections to perform actions in DocuSsign.\n\n### Before you begin\n\nRole required: admin.\n\n### Procedure\n\n1. Navigate to **All** > **Connections & Credentials** > **Connection & Credential Aliases**.\n\n2. Open for the record for **Docusign**.\n\n3. From the **Connections** tab, click **New**.\n\n The system displays a blank HTTP\\(s\\) Connection form.\n\n4. Enter these values.\n\n\n
\n\nField\n\n\n\nValue required\n\n
\n\nName\n\n\n\nEnter any name to uniquely identify the connection record. For example, enter `Docusign Connection`.\n\n
\n\nCredential\n\n\n\nSelect the Credential record you created for Docusign. For example, select **Docusign Credentials**.\n\n
\n\nConnection URL\n\n\n\n- For demo environment, enter `https://demo.docusign.net`.\n- For live production system, enter the Base URI such as `na2.docusign.net` or `eu.docusign.net`. For instructions on obtaining the base URI, see [Post Go-Live](https://developers.docusign.com/esign-rest-api/guides/post-go-live) and [User Info Endpoint Reference](https://developers.docusign.com/esign-rest-api/guides/authentication/user-info-endpoints) in the [Docusign Developer Center](https://developers.docusign.com/) documentation.\n\n\n
5. Click **Submit**.\n\n\n### What to do next\n\nSynchronize ServiceNow with Docusign to access Docusign accounts, templates, and envelopes from the Docusign spoke. See [Synchronize Docusign with ServiceNow](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/integrate-applications/integration-hub/sync-docusign-servicenow.md).\n\n"}}