We have employed a third party developer to create a small web site that creates embedded envelopes on our behalf to be signed by users. They are currently using their own sandbox account with API id.
We would prefer for them to not have to use our login credentials to make the rest calls when we move to production. Is there a way to create an application service account with the permissions to call the API with our integrator id that would allow them to make the calls on our behalf and only store the service account credentials instead of our admin credentials?
Admin account is not required to send an envelopes, you can create a DS Sender user in your account to send envelopes from your DS Account. Also, system is not required to save the DS Sender user's login credentials in the database, instead they should use Service Integration Authentication to generate the AccessToken of the sender user, and call DS APIs with the help of AccessToken.
Related
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
Some of my application's users have access to more than one DocuSign account. My app is designed to be used with a specific DocuSign account.
Can I specify the DocuSign account during login?
No. With DocuSign, a person authenticates themself as a user, not as a user for a specific account.
However, once the person has completed authentication, your software should use the /oauth/userinfo API call to learn which accounts the user has access to. This API call is also used to learn the user's name and email.
The /oauth/userinfo results will include an array of the accounts that the user is a member of (has access to). The array includes:
the account guid
the account name
the base URL for API calls to the account
whether the account is the user's default account or not
If your application is designed to work with a specific DocuSign account, then your software should check that the user has access to that account and give a clear error message if there's an issue.
If your application can work with any of a user's accounts, then the best pattern is to:
use the user's default account
enable the user to change which of their accounts your application will use
Notes
The /oauth/userinfo API call is available from the DocuSign OAuth service providers:
https://account.docusign.com (production)
https://account-d.docusign.com (development)
The /oauth/userinfo API supports CORS, so it can be used directly from browser-based apps
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've developed an invokable Apex method that leverages the DocuSign Apex Toolkit for preparing and sending an envelope via a Salesforce flow.
The only issue I'm having is when it is invoked by a Salesforce user, that has been added as a DocuSign user, but has not yet gone through the OAuth flow to connect Salesforce to DocuSign for their user account.
A workaround is that I have that new user click a standard "Send with DocuSign" button an any record, which then shows the "Before you can use DocuSign, you must grant consent for this application to make requests on your behalf." message and a button to start and complete the OAuth flow. Once this is done I can go back to my flow and it will successfully complete as that user.
Any ideas how I can "pre-authorize" users, or check for authorization as part of the flow (is this data stored in Salesforce), or at least find a way to get to this "Authorize" screen in Salesforce without needing to begin the process of sending an envelope?
Thanks
Matt
Yes, the administrator for the account can grant "blanket" consent, known as administrative consent, for the relevant integration key (client id) and scope(s) needed by your application.
To do so:
The account needs the Admin feature Access Management with SSO You can have this feature enabled for your developer sandbox account by email request to go-live#docusign.com. Contact your DocuSign account manager for adding the feature to a production account.
You need to claim the email domain for your users.
Use the Admin tool's Connected Apps tile to grant administrative consent to your users in the claimed to domain to the application.
The above assumes that you are supplying the integration key to your Apex application.
If you're using an integration key supplied by DocuSign, then you also need to use the Admin consent for external applications API.
If you're using an integration key supplied by DocuSign as part of a DocuSign for Salesforce product, then I would first ensure that the product is enabled for everyone in your account; that may take care of your app's consent issue.
Re: detecting if consent is required
DocuSign responds with a specific consent_required error if consent is needed. So check the error response of your call. See APIError
I am a developer who is creating DocuSign integration. I want to authenticate other production account using this integration. I have worked with other third party integration(like salesforce, mailchimp, etc.), usually it works fine for other integrations. I just want to confirm that it is the same case here in docusign.
About pricing, If I push my integration to production and authenticate other DocuSign account (if possible) using that integration, then when ever other production account uses this integration to send envelope requests for signing then who will get charged for it? my account or authenticated user's account?
Yes, you can authenticate other DocuSign users' accounts and can send envelopes for signature on behalf of them, DocuSign call this type of Integration a Partner App Integration, where you application will be a Partner App and your users will authenticate your App to call DocuSign API on their behalf. You can check Service Integration of how to accomplish this, you need to check User Consent section in your scenario. Now answer to your 2nd qs, Authenticate User's account will be charged for any envelope sent from the authenticated User's account.