I am running a POC for a Service-based DocuSign integration with JWT Authentication. We would like to leverage embedded sending, enabling multiple customers to send documents for signatures. I am trying to understand how we will manage users and consent in this scenario.
To grant consent for multiple clients, do we need to have a user created in or organization for each of our customers? Do these users need to be admins? Are we able to grant consent to a DocuSign user outside our organization?
Thank you
So, JWT requires consent of the user, but only once. This process is the same as Auth Code Grant, requires the user has a membership in a DocuSign account, log in (not in an iframe) by either entering their password or using IDP for SSO and then they are asked to allow the integration to access specific resources (eSignature in your case) as well as allow it to impersonate them. That is critical for JWT.
If you want to make it a bit easier, you'll have to become an ISV. As an ISV there are ways to consent to an app for an organization and you can also have some level of control over your customers' accounts.
Partner Integration Guide for ISVs
Related
Currently doing a POC for one of our customer requirement. We will have a single admin user for the organization so JWT authentication suits our requirement. Since my developer account has not got admin feature enabled I cant grant administrative consent to my application, so we are blocked. Can you please give admin access to my account.
Just trying to follow through the steps in the video.
https://www.youtube.com/watch?v=WAejcu-O1oE
While Karan's recommendation to contact Support to have the Admin module enabled in your sandbox is accurate, I would also remind you that Individual Consent is available for all account plans to grant permission to use JWT Auth
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 have a DocuSign app that uses 'Auth Code Grant' for individual users to create and send envelopes, and uses 'JWT Grant' for polling and downloading signed documents (i.e., automated operations as described by the documention).
All the examples and documentation I've encounter seem focused on using an admin/system account for JWT Grant, and specifically for impersonating users. I don't need user impersonation functionality in general.
I am currently using a regular (non-admin) user that is assigned a custom permission profile. The profile is simple with only the 'Allow view and manage envelope rights through API' checked. This works in the dev sandbox. I have no problems polling or pulling documents with this user and JWT Grant.
Is it acceptable to use a non-admin user for JWT Grant as in this instance?
Can anyone possibly point me documentation surrounding using JWT Grant for automated processes that do not require heavy integration or admin-level access?
Yes, it is acceptable, I'm not aware of any reason it won't be.
This JWT Best Practices Guide on the DocuSign Developer center. Not sure what else you may need, but feel free to ask specific questions.
Yes, you can use the JWT Grant flow to impersonate account users who are not administrators. This is a common use case for JWT Grant.
We are working on an integration to offer embedded document signing through customer websites we host. We want this to be a comprehensive solution, so envelopes should count against our quota, but will need to be under the user account provisioned through Docusign. We are using the JWT authentication method to impersonate the provisioned accounts and want to make sure we understand any requirements to gain consent.
When we request and provision accounts for our customers, is our integration key automatically granted consent on that account? Will we need to set up a service user account that can be impersonated on each customer account and grant consent individually? Thank you for any help you are able to provide.
If you (as an ISV) intend to purchase and provide the envelopes on behalf of your clients, you will need to be under an ISV License agreement with DocuSign. Architecturally, you would not be adding your clients are users in the accounts owned and managed by you. You would instead use a "system user" to represent each client organization. This works especially well for embedded signing integrations. As for consent, it would be a one-time consent that your configuration team would accomplish when onboarding the new client.
At this time we don't have these capabilities for ISVs.
Consent has to be given in the organization/account level (admin consent).
Which means if your customers are not in your organization, each of them would have to consent once.
Using administrator consent, your customers would only have to go through this process 1 time for your application.
Please free to send a feature request to partners#docusign.com or contact your partner account manager (make sure you're a DocuSign Partner).
I'm developing an integration that needs admin consent, without the interaction of a user. I see that in order to give consent to an application I need to do that from the organization dashboard.
The problem is that the demo account doesn't have organization features nor the organization dashboard.
When using JWT Token auth with DocuSign you need to grant consent one-time as you have mentioned, there are two ways to accomplish this:
Using Organizations Interface (which is an Enterprise level feature).
Initiate the request through the API
When going through API the user still needs to interactively grant consent through a browser however the request is initiated through DocuSign's Authentication Service.
See here for steps to take to grant consent through the API:
https://docs.docusign.com/esign/guide/authentication/oa2_jwt.html#granting-consent
In terms of the User Consent vs. Admin consent part of your question, they are actually the same thing the only difference is that the admin consent is done through the admin console and can apply to all users, the user consent is on a per user basis.
If you don't want the individual users to grant consent then you must use the organization admin panel to give consent.
To have organization administration added to your demo/developer sandbox account, please ask your DocuSign sales or technical contact to have it added.