Introducing OAuth for Partners for Docusign Connect

•

Summary•3 min read

This new security feature enables ISV and SI Docusign partners to apply their own OAuth Connect settings to their customers' Docusign accounts.

Additional resources

Additional resources

Docusign offers five different mechanisms to authenticate Docusign Connect event messages; that is, to make sure that messages are coming only from Docusign and not from someone else.

OAuth authentication
HMAC message signing and authentication
HTTP Basic authentication
Mutual TLS authentication
Digital signature (SOAP only, deprecated)

OAuth for Docusign Connect allows administrators to grant scope-based access to resources to Docusign Connect while ensuring integrity and authenticity. Docusign Connect specifically uses the Client Credentials authentication grant type, which is a server-to-server communication protocol. For an example of how to set up an Authorization Server on Azure, how to obtain an access token, and then how the access token is being supplied in the Connect event message, see Andy Singh’s From the Trenches blog post.

We are excited to announce a new addition to OAuth for Docusign Connect. This feature lets partners and integrators use their OAuth settings for their clients’ event messages. This will enable integrators and partners to manage Connect security for their clients in a more streamlined way. Here’s how the authentication flow for this new Connect security option works:

OAuth for Connect: Partner OAuth workflow

OAuth for Connect must be set up for the account where the integration key is located. This would be the partner’s or integrator’s account. You can then set the integratorManaged parameter to true while creating the Connect configuration on the Client’s account. Connect will then use the partner’s or integrator’s OAuth credentials while sending event notifications. You can use this parameter for account-level and envelope-level configurations.

This functionality is only supported in the API. It is available to all Demo and Production environments.

A sample payload for what the integratorManaged parameter looks like is below:

{
    "configurationType": "custom",
    "urlToPublishTo":"Your Webhook URL",
    "allUsers": "true",
    "name": "Your configuration name",
    "allowEnvelopePublish": "true",
    "enableLog": "true",
    "includeOauth":"true",
    "integratorManaged": "true",
    "deliveryMode": "SIM",
    "events": [
        "envelope-completed"
    ],
    "eventData": {
        "version": "restv2.1",
        "includeData": [
            "tabs",
            "payment_tabs",
            "custom_fields",
            "powerform",
            "recipients",
            "folders",
            "extensions",
            "attachments",
            "prefill_tabs",
            "document_fields"
        ]
    },
    "requiresAcknowledgement": "true"
}

We recommend testing this out in your demo account to ensure everything works as expected.

Additional resources

Karan KaushikDeveloper Support Engineer

Karan Kaushik began his Docusign career in January 2022. As a front-line developer support engineer, Karan enjoys working on complex technical problems. He is passionate about using technology to make people's day-to-day lives easier and simpler, leveraging his array of experience across information technology, cloud operations, and software development.