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.
Related
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.
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.
We are integrating our application with Docusign API using JWT service authentication method. Per the current docs, using the integrator key we need to generate new RSA key pair for each integrator key. Our multitenant integration to Docusign then requires us to generate RSA key pairs for each tenant and load them into our application.
In most public/private key/cert integration with other vendors we have seen that they allow using our own certs/keys. This is very convenient and simple since we only have deal with our own cert and not deal with storing many certs. Is there an option in Docusign to use/upload our own cert instead of creating new keys for every integrator id?
Unfortunately there is not an option for you to upload a public key to DocuSign for JWT authentication.
However, your question implies an incorrect understanding of DocuSign Integration Keys (client_ids). Generally speaking, one application should have one integration key.
An Integration Key can be used by any number of DocuSign users, associated with any number of DocuSign accounts.
So your application can use the same integration key for all of its clients.
Added
While a DocuSign Integration Key (client id) can be used by any user, on any account, there is often confusion about the DocuSign account that manages the Integration Key:
When an Integration Key completes the Go Live process, a DocuSign paid account is set during the process to manage the Integration Key. That account's administrators have the ability to add/change/delete the Integration Key's settings including:
The valid redirect URIs
The valid private/public key pair(s) (for JWT apps)
The key's secret(s) for Authorization Code Grant apps
For a partner / ISV, they should create the Integration Key's Management Account DocuSign account as a minimal paid account that is only used to manage the Integration Key. When their customer uses the application with the customer's DocuSign user/account, the end user will be charged for sending envelopes, not the partner.
For DocuSign Partners in the partner program, a no charge partner account on the production platform is available. It only has the ability to manage the key. Partners should request a partner production account from their DocuSign partner representative.
It's usually better is for partners to purchase the smallest size of production account from DocuSign since it will enable testing on the production system.
Note that the Integration Key management account is any DocuSign account on the production system: the account can manage multiple IKs if needed and can also be used for the ISVs own production uses.
As an update since this is 4 years old, you can import your own public key to use your own generate rsa keypair now.
As an ISV, I want to provide multiple customers of mine (and Google's) the ability to collect data from the Directory API. Since our app is headless, it seems that Domain-Wide Delegation is needed for customers to authorize our app, however it seems to me that it creates a security hole. If our app (again, headless) is authorized to customer A's account, and also to customer B's, what would prevent customer A seeing (collecting) customer B's data and vice versa?
Since the only authentication in this case is our app to the API, what is the recommended approach to prevent this situation from occurring? A different client ID for each customer? Wouldn't that mean that each customer also has to have a Google Developer account? Or, are we faced with having to manually create a separate service account for each customer?
(My app is working fine, BTW, just seems insecure to me)
To answer my own question, after testing this on another customer's GfW account, this is just as insecure as I thought it was. I had no problem collecting data using the same service account creds from two different accounts, the sole "secret" being the admin e-mail address for each account.
This is a missing piece in Google's documentation: Domain-Wide Delegation should not be used using the same service account credentials on multiple accounts, or those accounts will be able to access each other's data. So, if you plan on delivering an app to customers that needs headless API access, either use something like the OAuth web server flow, or create a separate set of service account credentials for each customer.
Left unclear in Google's docs are what limits, if any, exist on the number of credentials or apps a developer can create, so if you plan on having a lot of customers, service accounts and DWD may not be an option.
I just signed up with Docusign for a enterprise account. When I view my API information, I see my Account ID, password and username. From there I went to demo.docusign.com and created a completely separate account to get an integrator key. However, the account ID, password and username for the demo account are completely different from my enterprise account. Should I use my enterprise credentials with the demo integrator key? Or use demo credentials with the demo integrator key?
I've already created several templates and document brands in my enterprise account- I would like to avoid replicating them in the demo account to test them in my application.
You need to setup your workflow in Demo and then go through API Certification to get your Integrator Key promoted to Production.
See the Go Live section for information regarding API Certification: Here
Your DocuSign Account Manager is the correct person to talk to for additional information about this.