In my usecase, admin users create documents and send them off to users for signature. All the admin users use a single organization account. I am confused about which OAuth flow to go with here: JWT or AuthCode.
I would think you could choose Auth code Grant, but not 100% sure of all your requirements.
Here is our official guidance:
https://developers.docusign.com/platform/auth/
The users share a "single organizational account" -- you mean a "system" user account such as "sales#example.com"?
Authorization Code grant would mean that the users would be sharing a common password with each other. That's ok but not great. So I'd lean a bit towards JWT where the app handles the authentication to the common user account.
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.
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
My company (C1) has DocuSign implementation feature set up with RestApi and we use oAuth to authenticate users with email and password to create and send envelopes. This functionality works perfect.
One of our clients said they have SSO enabled in their org and would like to SSO directly to DocuSign from my company page instead of providing password option. In our current implementation, users are prompted for email address first and then the password.
If clients have SSO enabled, I assume they go directly to Docusign but to get that functionality, is there anything I need to do regarding changing the existing workflow or implementation for RestAPI.
Do we need to obtain consent for our Client (who has SSO enabled)?
Thanks in advance
You don't need to do anything differently. These clients would be able to authenticate to your integration/app using SSO. If they are already autneticated, a cookie remembers it and they would automatically be redirected back to your app. The first time, the would have to give consent to your app to enable it to do things for them, but after that - smooth sailing, without any need to login or anything.
Feel free to let me know if you run into any issues. Otherwise, you'r good.
As Inbar says, if your application uses either the OAuth Authorization Code or OAuth Implicit grant flow, then your application will automatically support SSO once the user's DocuSign account has been set for SSO.
If your application uses the OAuth JWT grant, then SSO has no bearing on your application since your application is itself authenticating with DocuSign and impersonating a user.
And the above is why Authorization Code grant or Implicit grant is preferred over JWT grant whenever there's an option to not use JWT grant.
If you're using Legacy Header authentication, your application won't be able to authenticate as users who have SSO Login enforced. Until you're able to implement one of the OAuth workflows, users who need to use your API integration will need to have their Login Policy set to allow them to login with a password. More info on Login Policy is available here: https://support.docusign.com/en/articles/How-to-exclude-specific-users-from-SSO-requirements