How to Create an Azure Custom Extension App for Docusign IAM

Creating an Azure Custom Extension App for Docusign IAM requires three things: a data store, a secured Functions App, and a working connection between them.

Most real-world agreement workflows need to connect to systems your org already runs on. Docusign IAM makes that possible by letting developers build Custom Extension Apps that plug into existing infrastructure. On Azure, that means Cosmos DB and Azure Functions doing the heavy lifting.

By the end of this guide, you'll have a fully configured Azure Source System, OAuth locked down, and connectivity to Cosmos DB confirmed and ready for app manifest configuration and deployment.

This guide covers:

• Setting up a Cosmos DB resource group and container as the data repository

• Creating an Azure Functions App to host your application logic

• Securing the Functions App with OAuth and capturing credentials for the app manifest

• Configuring redirect URIs for Demo and Production environments

• Adding API permissions to enable secure data access

• Adding environment variables to connect the Functions App to Cosmos DB

• Deploying and testing the function code to confirm connectivity

What are Azure custom extensions for Docusign IAM?

Azure Custom Extensions enable developers to extend Docusign Intelligent Agreement Management (IAM) capabilities by connecting external applications and services. The setup involves provisioning key Azure resources: a Cosmos DB for NoSQL to serve as the data repository, and an Azure Functions App to host application logic.

A critical step is securing the Functions App using OAuth. This requires creating an App Registration, setting up secrets, and configuring API permissions and Docusign redirect URIs. By the end of this guide, you will have deployed your function code and confirmed connectivity to Cosmos DB, fully preparing the Azure Source System for app configuration and deployment.

Use cases

Azure Custom Extensions for Docusign IAM support a range of integration scenarios:

• HR Onboarding: Automatically trigger document signing workflows when new employees are added to Azure Active Directory.

• Contract Management: Extend Navigator capabilities to pull contract data from external CRM systems.

• Compliance Workflows: Add custom validation steps to Maestro workflows that verify data against external compliance databases.

Key terms defined

• OAuth2: An authorization framework that enables secure, limited access to user accounts on third-party services.

• Maestro: Docusign's workflow orchestration tool that coordinates agreement processes.

• Navigator: Docusign's AI-assisted agreement management interface.

• Docusign IAM: Docusign Intelligent Agreement Management (IAM) is an AI-assisted, cloud-based platform that transforms how organizations create, sign, and manage agreements.

Prerequisites

Before starting, complete the following:

• Download Azure CLI

• Download and install VSCode (used in this guide. If you prefer not to use VSCode, all steps can be completed via Azure Functions Core Tools and a command prompt or terminal)

• Login to Azure CLI: open your terminal and run az login. If unsuccessful, try az login --use-device-code. Follow the prompts to authenticate.

Step 1: Create a Cosmos DB Resource Group

Cosmos DB serves as the data repository for your extension app. This step provisions the database, container, and a sample data record that you will use to verify connectivity when testing the deployment.

1. Under Azure Services, select Azure Cosmos DB

   

2. Select Azure Cosmos DB for NoSQL

   

3. Configure as needed. Note down the Account name and save. Below is an example of the configuration for this example.

   

4. Navigate to the created resource.

5. Add a new Database named: Accounts-DB

   

6. Add a new Container named: Accounts with Primary Key: account_holder_email

   

7. Add a new item under the Accounts container using the data model below. Paste it in and save (test values can be modified):

{
  "account_type": "business",
  "account_holder_name": "Catherine Client",
  "account_holder_email": "catherine.client@mailinator.com",
  "phone": "0411222333",
  "date_of_birth": "01/01/1990",
  "secondary_card_holder_name": "James Client",
  "secondary_card_holder_email": "james.client@mailinator.com",
  "secondary_card_holder_date_of_birth": "01/01/1990",
  "employment_status": "Employed",
  "employer": "Mayfair",
  "occupation": "Consultant",
  "annual_income": "$100,000.00"
}

Step 2: Create an Azure Functions App

The Azure Functions App hosts the logic that connects Docusign IAM to your Cosmos DB data source. This step creates the app and links it to your resource group.

1. Navigate to Azure Home > Function App > Create

2. Enter a name for your Function App.

3. Add the resource group and other relevant information.

4. Select Review + create, then Create

For more information, see Microsoft's Azure Functions documentation.

Step 3: Set up OAuth for the Functions App

Securing the Functions App with OAuth ensures that only authorized requests can access your application logic. This step creates an App Registration and captures the credentials (client ID, client secret, authorization URL, and token URL) that you will need when configuring the app manifest.

1. Navigate to Settings > Authentication in the Function App.

   

2. Select Add identity provider and choose Microsoft

3. Select Create New App Registration

4. Set Unauthenticated requests to HTTP 401

5. Set the client secret expiration date and click Add

   
   

Save the following values to a notepad, you will need them for the app manifest:

• Select Edit on the newly created identity provider.

• Copy the Application (client) ID → this goes in the manifest clientId attribute.

• Copy the MICROSOFT_PROVIDER_AUTHENTICATION_SECRET → this goes in the manifest clientSecret attribute.

  

• Navigate to the Identity Provider page by selecting the provider name, then select Endpoints

• Copy the OAuth 2.0 authorization endpoint (v2) → this goes in the manifest authorizationUrl attribute.

• Copy the OAuth 2.0 token endpoint (v2) → this goes in the manifest tokenUrl attribute.

  

  Important: Your notepad should look like the following.

Step 4: Configure redirect URIs

Redirect URIs tell Azure where to send users after authentication. This step adds the Docusign-specific callback URLs required for both Demo and Production environments.

Select Redirect URIs and add the appropriate URIs for your environment:

Click Save.

Note: You can use the demo redirect URL irrespective of your region.

Step 5: Add API permissions

API permissions allow the Functions App to access Cosmos DB on behalf of authenticated users. This step grants the user_impersonation permission required for secure data access.

1. Add the user_impersonation permission: select Azure Cosmos DB > user_impersonation

2. Search for your function app name, select user_impersonation, and click Add

Step 6: Add environment variables

Environment variables allow the Functions App to connect to your Cosmos DB instance without hardcoding credentials in the application code. This step adds the Cosmos DB endpoint and primary key as configuration values in the Functions App.

The Functions App needs your Cosmos DB credentials as environment variables.

1. Go to Cosmos DB > Data Explorer > Connect

2. Copy the URI → save as COSMOSDB_ENDPOINT

3. Copy the PRIMARY KEY → save as COSMOSDB_PRIMARY_KEY

   

4. Go to Function App > Settings > Environment Variables, click + Add, and enter:

   • Name: COSMOSDB_ENDPOINT / Value: (your URI)

   • Name: COSMOSDB_PRIMARY_KEY / Value: (your PRIMARY KEY)

     

5. Click Apply and confirm

Step 7: Deploy and test function code

With all resources configured, this step deploys the function code to Azure and runs a test query to confirm that the Functions App can successfully read data from Cosmos DB.

1. Download and unzip the function code folder.

2. Open the unzipped folder in VSCode.

   

3. Install the Azure Functions extension for VSCode.

   

4. Sign into your Azure account via the Azure Functions panel (left sidebar).

5. Select the thunder icon next to WORKSPACE, then select Deploy to Azure

   

6. Select Deploy. You will see a "Completed" message when finished.

   

7. Confirm deployment by verifying that 5 functions appear in the Azure Function App with status Enabled.

   

8. Test the deployment by selecting the SearchRecords function, clicking Test/Run, and pasting the following into the Body:

{
    "query": {
        "$class": "com.docusign.connected.data.queries@1.0.0.Query",
        "attributesToSelect": [
            "account_type",
            "account_holder_name",
            "account_holder_email",
            "phone",
            "date_of_birth"
        ],
        "from": "Accounts",
        "queryFilter": {
            "$class": "com.docusign.connected.data.queries@1.0.0.QueryFilter",
            "operation": {
                "$class": "com.docusign.connected.data.queries@1.0.0.ComparisonOperation",
                "leftOperand": {
                    "$class": "com.docusign.connected.data.queries@1.0.0.Operand",
                    "name": "account_holder_email",
                    "type": "STRING",
                    "isLiteral": false
                },
                "operator": "EQUALS",
                "rightOperand": {
                    "$class": "com.docusign.connected.data.queries@1.0.0.Operand",
                    "name": "catherine.client@mailinator.com",
                    "type": "STRING",
                    "isLiteral": true
                }
            }
        }
    },
    "pagination": {
        "limit": 10,
        "skip": 0
    }
}

Click Run to verify the expected result.

Alternative option (without VSCode): Go into terminal or command prompt and type: func azure functionapp publish [FUNCTION_APP_NAME]

Where FUNCTION_APP_NAME is your function app name (e.g., "presales-appcenter").

Next steps

At this point, your Azure Source System is fully configured and ready to support a Docusign IAM Custom Extension App. You have provisioned a Cosmos DB database and container, secured an Azure Functions App with OAuth, and confirmed that your function code can successfully query your data.

With the Azure Source System in place, the next step is configuring the app manifest and deploying your Custom Extension App within the Docusign IAM platform.

Troubleshooting tips

My Azure Function App isn't connecting to Cosmos DB. Double-check that COSMOSDB_ENDPOINT and COSMOSDB_PRIMARY_KEY are correctly added as environment variables. Verify there are no typos, and that values were copied from the correct locations in the Cosmos DB Data Explorer/Connect blade.

I receive an HTTP 401 Unauthorized error when testing the function. This is typically an OAuth or authentication configuration issue. Verify that:

• Unauthenticated requests is set to HTTP 401 in the Function App's Authentication settings.

• Redirect URIs are correctly added in the App Registration, including the Demo URL and any relevant Production URLs for your region.

• API permissions (including user_impersonation for Cosmos DB and the Function App) were correctly added and saved.

The function deployment via VSCode or CLI fails.

• Confirm you have run az login and are authenticated with the correct Azure account.

• If using VSCode, verify you are signed into the Azure Functions extension.

• For the CLI method, confirm the func azure functionapp publish [FUNCTION_APP_NAME] command uses the correct Function App name.

FAQs

Which versions of Azure CLI and VSCode should I use? Use the latest stable versions of both tools for the best experience.

What if I don't want to use VSCode? You can complete all steps using Azure Functions Core Tools and a command prompt or terminal. For deployment, use: func azure functionapp publish [FUNCTION_APP_NAME].