We are looking at the DocuSign API integration using .NET.
I've managed to send an email from this correctly and added fields to the form programmatically however I could do with knowing how to use the Send On Behalf feature.
It looks like in the APILogin() function I need to add a default header called X-DocuSign-Act-As-User and then the email address (SOB is enabled on the API account). But then it says I need something to do with a token for this user? But not sure where I get this from?
Thanks,
Alex
X-DocuSign-Act-As-User header is only applicable when using OAuth tokens. For non-token usage, add the X-DocuSign-Authentication header.
Example from the GUIDE:
X-DocuSign-Authentication:<DocuSignCredentials><SendOnBehalfOf>bob.smith#gmail.com</SendOnBehalfOf><Username>{name}</Username><Password>{password}</Password><IntegratorKey>{integrator_key}</IntegratorKey></DocuSignCredentials>
Where {name} is the email address of your API Initiator and {password} is the password of your API Initiator. Those credentials are used to authenticate the API call, but the envelope will be created and owned by "bob.smith#gmail.com" as the Sender.
Note 1: "bob.smith#gmail.com", i.e. the on-behalf user, must be an account member with "send envelopes" permissions.
Note 2: API Initiator credentials - recommendation is to use API Name (the User's GUID) rather than email address, and use the "encrypted password" instead of the plain-text password. This is retrievable via the login_information API call. These forms of the credentials are not useful for logging into DocuSign via the Web interface.
Related
We are developing application for e-signature on PDF for different users of oru system, which call many docusign APIs and we try use JWT to authenticate the APIs. I able to get token. But I have doubt on one parameter of JWT request body. I refer link https://developers.docusign.com/esign-rest-api/guides/authentication/oauth2-jsonwebtoken.
What do you mean by "The user ID of the user to be impersonated.", I used API account user id.
Please refer my previous query Signer URL for an envelope - calling docusign API and getting 400 bad request error. I think, this is not correct what I use to pass here. However I am getting token.
Please let me know if you want to know more details.
"The user ID of the user to be impersonated." means exactly this, you can impersonate a user or "act on behalf of the user" by providing his userId in the JWT call.
So the impersonated user will be the sender of the envelope.
If you use your account userId you will be acting as the sender
I need to add DocuSign to my chat app (iOS, Android, Windows) in order to ask to sign documents to all the chat group members.
I want to implement DocuSign signing flow without Server implementation: only Sender and Recipients client side implementation (is it possible?).
Flow that I imagined:
An authenticated Sender create the envelope with Envelopes: create REST call.
Other members must sign the document (no DocuSign account needed)...
...so I need to generate a "recipient url" for every member using the REST call EnvelopeViews: createRecipient (who call this endpoint?)
I tested this flow with Postman and I've some questions:
EnvelopeViews: createRecipient require X-DocuSign-Authentication header, so this request must be called from Sender side, is it?
EnvelopeViews: createRecipient return an url that can be used once, why? The second time I use this url I get 404 as response.
So what I notice is the Recipient can't use the url (provided by the Sender) twice but he can't generate a new url every time because it isn't authenticated (no X-DocuSign-Authentication).
How can I implement this flow properly?
Lots of good questions:
EnvelopeViews: createRecipient require X-DocuSign-Authentication header, so this request must be called from Sender side, is it?
Do not use the X-DocuSign-Authentication header. That's "legacy authentication" and DocuSign does not support it for new REST eSignature apps. Instead, use OAuth. Probably the OAuth JWT grant flow since that flow enables your application to impersonate a DocuSign user (such as the sender), when the user is not present.
You can call EnvelopeViews: createRecipient from your server or from your browser app. If you call from your browser then you'll need to implement a private CORS gateway.
Either way, when the signer is ready to sign, you obtain the signing ceremony URL from the EnvelopeViews: createRecipient API call, then redirect the signer's browser to the URL.
EnvelopeViews: createRecipient return an url that can be used once, why?
For security reasons. That's part of our information security architecture. And not only is the signing ceremony URL only usable once, it is also time limited. It should be used within a minute or two from when you receive it from DocuSign. It will expire 5 minutes after it was created.
The second time I use this url I get 404 as response.
Yes, that's as designed. You get the URL, then you immediately redirect the signer to the URL. Then they sign. Then they're redirected back to your application.
If you want to provide a URL to a signer that the signer can use later on, you can implement that flow yourself. I've described how in other answers.
So what I notice is the Recipient can't use the url (provided by the Sender) twice but he can't generate a new url every time because it isn't authenticated (no X-DocuSign-Authentication).
How can I implement this flow properly?
You're almost there. Implement the JWT grant flow in your application. That way your app can impersonate the sender even when they're not around. When the signer wants to sign, your app gets the signing ceremony URL from DocuSign, and then redirects to enable signing.
An alternative which also works fine is for the sender to sign in to DocuSign by using the standard OAuth Authorization Code grant. This provides your app with an access token and a refresh token.
Your app enables the sender to send the enveloper by using the access token.
Later, when the signer wants to sign, your app uses the refresh token that it stored to generate a new access token. Use the access token with the EnvelopeViews: createRecipient API method to obtain the signing ceremony URL.
X-DocuSign-Authentication header is legacy authentication, please don't use this as it's not as secure as modern OAauth.
Again, security. Every time you want someone to sign your code should generate the URL. Also, note you cannot generate two URLs. Only one is valid at a time. You need your app to have some logic to ensure that only one user is signing and only at that point in time the URL is generated.
I am doing service integration with DocuSign platform using JWT Grant auth type. DocuSign account has multiple users setup.
My service is SendEnvelopService and one of the important request param to the service is user email. SendEnvelopService need to impersonate user with given email-id when calling DocuSign and send envelope in behalf of that user. Note that every request to SendEnvelopService will have different value of email request param.
I have following questions around it -
Question#1) Since I need to impersonate different user every time (based on email id in my request), I assume I need to get new JWT auth token every time, before making actual api call. Is that right? Is it usual and ok to request new JWT auth token so frequently before every api call? Does it raise any integration concerns with DocuSign?
Question#2) In my request, I have email id of the user to impersonate. I don't have user's GUID which I need, to get JWT auth token and impersonate it. Is there any api that I can use to get user GUID by email id? I wonder what kind of authentication will be needed for such api because I don't have JWT auth token yet.
One idea I have is may be I need to setup one admin user in DocuSign and keep admin userId (GUID) in application config. Now I have 2 users, one is admin user and another is request user which I have email from the service request. I can following steps -
Do requestJWTUserToken impersonating admin user. We get
oAuthTokenAdmin
Using oAuthTokenAdmin make
https://developers.docusign.com/esign-rest-api/reference/Users/Users/list
api call to get userId (GUID) of request user email.
Now do another requestJWTUserToken impersonating request userId. We
get oAuthTokenUser
Now make actual api call using oAuthTokenUser and to send envelope
Go to:
https://admindemo.docusign.com/
Log in with your demo (sandbox) credentials.
Then you have two options:
If it is only for you, simple thing is to click "API and Keys" page under Integrations on the left nav.
You will see this:
You can also click on "Users" on the left and select the user you want, any user really, doesn't have to be you.
then you'll see it under this:
For your first question, no, you don't have to do that. You can use the same user for all API calls. Especially if this user is an admin, then you can do all API calls under that context.
I have set up Sandbox account and successfully created integrator keys for my apps REST API calls. I have docusign header (X-DocuSign-Authentication) on my code that requires username/password/integrator key for api connections. I used DocuSign ApiClient & AuthenticationApi to set it up in code. Looks good on sandbox. My question is when we go live, on production, the admin account is an individual user credential (not a generic admin account). So how can we have that set -up in every application for the REST api connections header?
For "User Applications" -- where an individual logs in and later sends envelopes -- it is vastly preferred that you use OAuth to authenticate the users. See the docs. See a recipe example of using OAuth.
If you want to use Legacy Authentication (the X-DocuSign header) for a user application, then your app needs to request (and securely store) the user's DocuSign email and password. These days, this is a not a good plan.
As you know, you must include the username and pw in each call to DocuSign if you use the Legacy Authentication scheme. The data is secure since it is within an https conversation. But requesting and storing the pw from your users is problematic.
These days, Legacy Auth should only be used for "Service Integrations" -- DocuSign integrations where there is no human involved, just an autonomous / batch process that sends out the signing requests.
X-DocuSign-Authentication=[<DocuSignCredentials><SendOnBehalfOf>UserId from CheckAccountMemberResult</SendOnBehalfOf><Username>apiusername</Username><Password>passs</Password><IntegratorKey>apikey</IntegratorKey></DocuSignCredentials>]}
I was testing “Send On Behalf Of” feature and received an error in the subject.
Please let me know what I am missing?
Do I have to take the Auth Token route? If that is the case, do I have to use operating user's password as opposed api user's password. I am confused.
Thanks
N
Update: Another surprise. The authentication was working fine for the API credentials (without the SendOnBehalfOf tag). Now it's not. Hope Docusign is not doing any maintenance.
When using Send On Behalf Of with SOAP, the sending user is identified within the Email element of the authentication header. For example, let's say that my API user name is "apiuser#example.com" and my sending user name is "sender#example.com". If using the DSAPI.asmx endpoint, the authentication header would look like this:
X-DocuSign-Authentication: <DocuSignCredentials><Username>[sender#example.com]apiuser#example.com</Username><Password>mypassword</Password><IntegratorKey>EXPL-00000000-0000-0000-0000-000000000000</IntegratorKey></DocuSignCredentials>
When using WS-Security and the API.asmx endpoint, a similar structure is used:
<SOAP-ENV:Header>
<wsse:Security mustUnderstand="true">
<wsse:UsernameToken>
<wsse:Username>[EXPL-00000000-0000-0000-0000-000000000000][sender#example.com]apiuser#example.com</wsse:Username>
<wsse:Password>mypassword</wsse:Password>
<wsse:Nonce>00000000000000000000000000000000</wsse:Nonce>
<wsu:Created>2013-10-29T20:37:59.241468Z</wsu:Created>
</wsse:UsernameToken>
</wsse:Security>
</SOAP-ENV:Header>
For reference, OAuth2 is not required and is not supported in the SOAP API at this time.
Have you read through the "Send On Behalf Of Functionality in the DocuSign REST API" section (p16-18) of the DocuSign REST API Guide (http://www.docusign.com/sites/default/files/REST_API_Guide_v2.pdf)? This content provides a decent overview of how to use SOBO with the DocuSign REST API, and even includes some examples.