We are trying to build a DocuSign integration (connector) to our application.
Use Case: We have multiple customer and some customer has multiple account. We intend to use Authorization Code Grant/JWT Grant flow to connect customer account to our application. We would be storing access token, refresh token & expiration date for each connection.
Question:
We notice ISV is the recommended route. We would like to understand more on this:
After creation of an ISV/Partner DocuSign account, how do we integrate it with multiple customers' account?
Can we use the same integration key + client secret in ISV/Partner account to retrieve access token an make calls to eSignature API (i.e to send envelopes and signature) for multiple customers' account?
How would the go-live process occur in this scenario?
Other than the above, are there option other than ISV?
ISV simply means that you build integration to be used by many customers, each with their own account. However, an IK can be used with many different accounts, whether you're an ISV or not.
After creation of an ISV/Partner DocuSign account, how do we integrate
it with multiple customers' account?
You create an IK (integration key which is like a clientId) and that can be used to authenticate with any DocuSign account.
Can we use the same integration key + client secret in ISV/Partner
account to retrieve access token an make calls to eSignature API (i.e
to send envelopes and signature) for multiple customers' account?
Yes, this is called Auth Code Grant. Using this method you must interactively log into DocuSign (like providing a password) whenever you use your application.
How would the go-live process occur in this scenario?
Go-live is the same in all cases. You need to make API calls in the developer environment that comply with the rules (at least 20, no polling, no errors) and then you can start the process. You will need a valid production account to complete the process and promote your IK to production to be used by any customer in production.
Related
We have done one CRM integration where we as an CRM have our own docusign pro account.
We completed the GoLive process successfully and have all required data like Integration key, Account Id, Client Id and Secret Key for App.
Now this CRM integration will be used as an mediator for our clients who will have their own purchased docusign accounts.
So till now we have 2 accounts,
CRM Integration docusign account with GoLive status.
Client account to send their own documents for eSign through our CRM integration.
What we have achieved till now?
We completed the consent flow where we redirect our clients to docusign consent page where they provide consent to our app by login into their docusign account. In this flow we use CRM integration account id in URL which takes our client for consent page. On confirm the client will be redirected back to CRM with auth code attached in redirect URL.
We use this auth code to get access token for this client. We use CRMs account id, Integration App secret key and clients auth code to get the access token. We are successful in this too. We get clients access token. No Issues.
Now when our client is trying to send a document for eSign using the access token received in step 2 above, the docusign throws an error saying INVALID_USER.
I have referred to this post Simillar Issue it kind of approves of what we are trying to achieve but it is failing with error.
Let me try to explain and make sure it's clear.
The IK (Integration Key) is global for the entire environment. By environment I mean either the developer environment, or the production environment. When you went live and completed the process using a production environment - you made your IK available for any account and any user in the production environment.
Now, when you get an access token to make API calls, this token is for a specific userId. The userId can be a member of one ore more accounts as showed in this diagram:
The userId is provided by the user logging in when given the option to consent. So when you doing your consent flow, there's a web browser and user that logs in, that is the userId that consent.
Separately, when you request a token using JWT grant, you provide a userId, that userId is a GUID for a unique user in the system.
This GUID must be for the same exact production user that gave consent. That's first thing to confirm.
Now, if you already have an access token to make API calls, when you make a specific API call, you need to provide an accountID. That's another GUID representing an account, not a user. The userId that was provided to the JWT Grant flow must represent a user that has a membership (it is a member of) in the account for which you provided a GUID (a user can be a member of more than one account). That is the second thing to check.
Lastly, there's a baseURI that is used to make API calls and it can be different for different accounts. You need to also confirm you are using the correct one.
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
So if I have an app with many users on board, all from different companies/places, I'm thinking that an individual 'connect to docusign' with OAuth is the right flow.
I think I could have an admin connect their account and impersonate the entire company, but it doesn't sound great from a security perspective.
I also see some places asking people for their docusign admin username/password which I assume is highly discouraged.
Question: I am planning on using just one 'integration' for my app to manage all this, should I be aiming to use one integration per docusign account I interact with? i.e. Should I ask the companies to each make an integration and give me the id/secret?
Several questions here:
OAuth flow
Yes, if your DocuSign users will have their own DocuSign user IDs then you can add a "Connect to DocuSign" button and use the OAuth Authorization Code grant flow. Include the extended scope so you can use the refresh token on an ongoing basis. Remember to use secure non-volatile storage for the refresh tokens since they can be used to obtain access tokens.
See Authentication for ISVs
I think I could have an admin connect their account and impersonate the entire company, but it doesn't sound great from a security perspective.
Correct. It is best to use JWT grant (impersonation) only if the end users can't use the Authorization Code grant flow. For example, if your app is a back-end app or doesn't have a web interface.
JWT (impersonation) flow is fine when needed, but it incurs significant customer confusion and work to provide consent. So Authorization Code grant is preferred if it fits your needs as an ISV.
One DocuSign client_id (integration key) or one per end-customer?
Best is to use one DocuSign client_id (integration key) for your application, not one per customer. See ISV docs
Should I ask customers to give me an integration key and secret that they created?
Please no. Your customers are not developers. Asking them to become DocuSign developers and create a client id (integration key) is a lot of work for them. There's no need to go down this path. Just use the same OAuth Authorization Code grant redirect_uri for all of your customers. Remember that you can use the state parameter as needed to handle the OAuth redirect from DocuSign.
Use your free partner account to manage your application's client id and its settings.
asking for a DocuSign administrator name/pw from your customers
Correct: don't do that!
you want your customers to set up their DocuSign accounts in a specific way
Your app can do that for them by having including a "Setup DocuSign account" button. That button (when used by an authenticated DocuSign admin) would update the account settings as your app needs. For example, setting up a Connect
users have multiple accounts
Extra: remember that it is common for DocuSign customers to have access to multiple DocuSign accounts. Eg, a general account, an account for HR, etc. They may or may not set up a special account for your application, depending on the use case.
After a user authenticates, your app can either use the user's default account, or if your application uses a dedicated account, check that the user has a access to it.
I'm experimenting with building an integration between my app and any DocuSign account.
If I create an integration key in my developer sandbox, go through the "go live" process will I be able to use that same integration key to authenticate on behalf of users of different DocuSign accounts?
That's right.
The Integration Key's account is the account that creates and manages it.
Any account in DocuSign (production accounts only after you go live) can use the IK.
Of course, users have to consent the first time they use a new IK in their account, but that's part of the OAuth process.
So no, nothing to worry about, the IK is global in the same environment and can be used by any account.
I am wanting to use the DocuSign REST API to create an envelope for our clients. We are wanting to just create the envelope for our clients to simplify the DocuSign process. Each of our clients will have their own DocuSign account that would be separate from our API Integrator Key Account and they will share the API integrator account. How can I achieve this.
Docusign supports various authentication options to support multiple scenarios.
Based on your problem statement it looks like you are building a User Application.
See the Documentation to build user applications over the DocuSign api.