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).
Related
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 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
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
Me and my team are facing an identity and management project where DocuSign should be integrated with IdentityIQ to manager its user accounts and permissions.
As you all know, DocuSign works as follows:
An organization
One or more accounts that belong to the organization
Users that belongs to organization
Our client needs users being able to request account permissions, but also organization admin role.
We are using the API to integrate DocuSign with IdentityIQ and handle its requirements, but we do not know, because it is not in the documentation, how Organization permissions can be assigned to users through API. Do you have any experience on this?
Thank you in advance,
Regards
At this time, Organization Admin functionality is not exposed in the DocuSign API.
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.