I am trying to integrate Docusign within my web app where users will be able to generate the documents to sign with some information from the web app integrated into Docusign document.
For JWT or Auth Code Grant workflows, Docusign needs the user to sign in to Docusign account to be able to generate an access token.
Now each user cannot really sign into Docusign to generate a document. What's he best way to create Docusign envelops without the end user logging into Docusign account?
If your app's users have DocuSign user accounts, then use Authorization Code grant flow: the user authenticates with DocuSign and then your app uses the user's access_token.
If your app's users do not have DocuSign user accounts (eg the users are your end customers), then:
Create a "system user" in your DocuSign account such as "finance#yourcompany.com"
Authenticate to DocuSign as the system user and grant consent to the application. See this blog post for more.
The above steps are one time only!
Then, when your app is used in production:
When a user starts to use your application, your application uses the JWT grant flow to impersonate the system user.
Via the JWT grant flow, your app now has an access_token that it can use with the DocuSign APIs. Your app can use the access_token to create an envelope, then create a recipient view (embedded signing ceremony)
The app's user can sign via the embedded signing ceremony.
Remember to cache the access_token for the system user. Continue to re-use the access_token until it is about to expire.
See this SO answer for info on caching the access_token
Related
I'm working on an integration with the DocuSign API. I want the users to log in to my app and then initiate the signing process from there. The users must not have a DocuSign account, they should be able to sign without log in to DocuSign. As I understand the JWT Grant flow is the best choice for this scenario by impersonating a system user and create envelopes and recipient view requests for the users who will sign. Please, correct me if I'm doing this wrong.
Many companies who offer electronic signature services also offer authentication services. For example OTP via email, SMS or some other eID. I would like that if the user could authenticate with DocuSign first before accessing my application. I haven't find a service like that at DocuSign. Is there a way to authenticate users without DocuSign accounts for my application with their service?
You first write:
The users must not have a DocuSign account
You later write:
I would like that if the user could authenticate with DocuSign first
before accessing my application
These two statement conflict. You can only authenticate if you have an account.
However, if what you mean is just get an SMS text there are two features you can use:
Send with SMS - sending the SMS as the means of obtaining a signature from user. User doesn't have to have an account with DocuSign.
SMS authentication - envelope is sent via email, SMS is used as a second factor auth. User doesn't have to have an account with DocuSign.
JWT or Auth Code Grant can either be used for the one user/account that does have the ability to send envelopes from DocuSign. Either one would work.
For context, we are currently developing a DocuSign integration on our DMS web app product. So far what we have done is that the web app's admin (we assume this would be someone like our customer's IT) can set up the integration by entering API Account ID, Integration Key, Secret Key, Access Token & Refresh Token. All these information was taken/generated using a DocuSign admin account. With this, we see that any user using the DMS can send out signing requests (via API) without logging in to their own DocuSign account.
However, we realised this means that all signing requests will be sent using the common DocuSign admin account, i.e. the envelopes originate from the admin account and all signed documents also stored in the DocuSign admin account. This is not what we want as the DocuSign admin can see confidential signed documents.
I'm quite confused and would like to seek advise on how should we go about this? Ideally, it is that User A of the DMS can associate his DocuSign account with his DMS account. So that when User A sends out the signing request from our DMS, the signer receives the email from DocuSign showing it is from that user instead of the common admin account.
Also, it looks like the go-live process would have to take place for each customer that is using our DMS? Does it mean like each customer need to have their DocuSign developer account so that the integration key can get promoted to production environment? Or am I in the wrong direction & should look at Partner Integration as ISV?
If your DMS system is a SAAS system, then you can have 1 integration key (client id) for your integration with DocuSign. In other words, your individual customers would NOT have their own integration keys, secrets, etc.
One integration key is the best, if your application's architecture can support it. To do so, you'll want to have one or just a few Redirect URIs to enable your users (who also have DocuSign accounts) to authenticate with DocuSign.
Your app then stores the resulting access token, refresh token, and expiration date for each of your users who have authenticated with DocuSign.
This way, as you say, when your users send out an envelope for signing, it will belong to their own DocuSign account, and will show them as the sender.
When your customer wants to send via DocuSign, your app checks the expiration date for the person's access token. If the access token has expired, then use the refresh token to get a new access token and a new refresh token.
The refresh token is stored in your app's non-volatile storage (encrypted is best) so you can use it days or weeks later for the user. That way they don't have to re-authenticate with DocuSign. For this case, use scopes signature%20extended
For the account_id info, use the user's default account and enable them to switch to another account if they wish.
More information:
Getting started for ISVs
API integration guidelines
I'm trying to access DocuSign account and app.
How to pass to docusign login without client_id, once login successful it will ask for app and send Integration Keys with Secret Keys of that app in callback?
Step1- User redirect to DocuSign login page with url somethings like this
Response.Redirect(WebUtilities.AddQueryString(Options.AuthorizationEndpoint, new Dictionary<string, string>{
{ "scope", "signature extended" },
{ "response_type", "code" },
{ "state", stateString },
{ "redirect_uri", Options.AppUrl + Options.CallbackPath.ToString() } })
);
and after successful login.
Step2. User should have screen with apps which are in setting and from there after selected any app, it will send Integration key/ Secret key of selected app to call back url. By which I want make calls are per my requirements.
Basic point is user from my web site click on docsign link- it will redirect to login of DocuSign - user will select app on successful login - select app which user want - After selection it will redirect to callback with with IntegrationKey and Secret key.
Hope I am clear now.
Unfortunately your question is not clear. Maybe you can edit it.
To make an API call to DocuSign, you need an access_token. Your application obtains an access_token by using an OAuth authentication flow such as Authorization Code grant or JWT grant.
To receive a webhook notification from DocuSign, you set up your Connect/webhook subscription by using the eSignature Administration tool. You do not need a client_id for this action.
Added
The OP has added to their question:
Basic point is user from my web site click on docsign link- it will redirect to login of DocuSign - user will select app on successful login - select app which user want - After selection it will redirect to callback with with IntegrationKey and Secret key.
I think the question is about authenticating an application's user with DocuSign, then returning to the application.
Answer
The OAuth security standards for the Authorization Code grant require that the user login via the OAuth service provider. In this case account.docusign.com or account-d.docusign.com.
There are two ways to do this:
The application redirects the user's browser to the OAuth service provider. After the first step in the Authorization Code grant flow, the user will be redirected back to the application. The application then makes the call to exchange the authorization code for an access token. The app needs a way to recover its state when the user is redirected back to it. There are several ways to do this.
The application can open a new browser tab to the OAuth service provider. The application continues to run in its original browser tab. The app can programmatically close the tab that it created once the user is authenticated.
Once your app has an access token for DocuSign, it can make API calls to DocuSign. Generally speaking, apps should make API calls to DocuSign on behalf of the user. It is less common for apps to show the DocuSign application to users.
The exception is the DocuSign Signing Ceremony, used for actually signing a document. But signers rarely have a login to DocuSign--they don't need a login to sign.
If you're going to show the DocuSign signing ceremony to your application's users then your application will usually obtain an access token for a system user such as "finance#example.com" (via OAuth JWT impersonation grant) not for the signer since the signer does not have a DocuSign login.
I implemented Authorisation Code Grant like the example code provided using passport and it is working fine.
One thing that is confusing me is that when obtaining a new token, passport required authentication.
Are these supposed to be the credentials of our admin account? or, once we go live, is it the credentials of our user who is trying to sign a document (using embedded signing).
Thanks!
When you say
our user who is trying to sign a document (using embedded signing)
note that signers do not need a DocuSign account. They can have one, but they don't need one.
If you want to use embedded signing for a signer who does not have a DocuSign account, use a system account (and JWT Grant) to obtain the Signing Ceremony URL. (A system account can also be used to create the envelope, if necessary.)
Added
A "system account" is a user account in your DocuSign account that represents a generic, system, sender. For example, create a user account "Sales department." Then use JWT Grant (on your backend web server) to impersonate the Sales department user. The result is an access token that your application can use to create envelopes and then have them signed by your website visitors.
The "Sales department" user will be created and controlled by your system administrator. But there is no need for the system administrator to login every morning -- once the system administrator gives consent for the application to impersonate the Sales department user, your application can create new access tokens as needed that impersonate the Sales Department user.
The latter. When using Auth Code Grant, every user of your application will have to log into DocuSign and their credentials will be used.
Read more over here - https://developers.docusign.com/esign-rest-api/guides/authentication/oauth2-code-grant
Help me please. There are several users in the docusign account. How to send an envelope from their name? What would an envelope be sent not on behalf of the administrator, but on behalf of the user.
You need to use DocuSign's OAUTH user Application or Service Integration to implement the same. DocuSign Authentication Overview has details about each integration type.
OAuth Authorization Code Grant and OAuth Implicit Grant are suitable only for user applications because it requires an end user to authenticate with DocuSign.
Service Integration Authentication uses JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants (RFC 7523) to create an access token. It is ideal for service integrations that do not involve a user agent like a browser or web view control. The result is an access token that represents the application or an impersonated user.
Implementing either User Application or Service Integration, you need to get consent of the user for whom you want to send the envelope and envelope will be sent from that user's account and that user will become the sender of the envelope.