My app is using JWT with individual consent. When, as a customer, I go to the Connected Apps screen at https://account-d.docusign.com/me/appconsent and revoke access to my app, the app still keeps working fine. No Docusign API calls fail, I can still create envelopes. Why? Is there another way to revoke?
The documentation page at https://developers.docusign.com/platform/auth/consent/ says "In cases where user consent was provided by an organization administrator (such as the JWT Grant), this consent can be revoked with the DocuSign Admin tool." But there is no link with more if about this "Admin tool" and I can't find it, and I don't think this applies in my case since I'm using individual consent.
I believe that the next time the app tries to use JWT to obtain an access token, it will fail.
But the already in use access token will continue to work until it expires at the end of its one hour lifetime.
If your experimentation doesn't support the above, please update your question.
Related
I'm using authentication code mechanism through Docusign's API for integration and works as expected.
Have a question regarding the documentation about implementation best practises, described in this page
Questions are related to the diagram at the end:
Question1
In Get the user's account ID, base URL and name (1st square) how do you recommend fetching the user/account information as before consent we don't know who is giving consent?
If it is related to users that may have given consent before, is it even necessary? If tokens already exist for the user, what is the purpose of verifying this scenario?
In the documentation it seems this is reinforced further with what is stated next:
How will we know what is the account/user information before the user gives consent?
Question2 (Similar to above)
In Collect the account ID (GUID) and name of the user, when no access token is found, I'm assuming we should redirect the user immediately so that the use gives consent again. Similar to the question above, in the diagram it indicates we should do this action "Collect account/user info" somehow before redirect for consent? We only know it afterwards as well, so is it needed?
It would be great if it would be possible to clarify the above!
As Inbar commented, that diagram needs some work. I'm sorry for the confusion.
Here's my recommendations for user present (Authorization Code and Implicit grant flows) and user absent (JWT grant flow).
All authorization flows
Determine if your users will typically use your application with a particular eSignature account or with any of their accounts. (It is common for customers to have access to more than one DocuSign eSignature account.)
If a particular account will be used, then provide an installation screen for your app where the admin can enter the account ID (use the guid format).
Your installation screen should also enable the installer to set
the DocuSign OAuth service provider, either production account.docusign.com or demo account-d.docusign.com
User present: Authorization Code and Implicit grant flows
Your app may or may not have its own login sequence for users. Your app needs a DocuSign access token for making API calls to DocuSign APIs.
When your user wants to authenticate with DocuSign:
Start the Authorization Code or Implicit grant flow.
When the flow is done, your app has an access token.
If the Authorization Code grant flow was used then you also have a refresh token.
Use the oauth/userinfo API call to obtain information about the user:
Their name and email
The eSignature accounts they have access too, and which of those accounts is the user's default account
For each account, the name of the account and the baseUrl for making API calls to the account.
If your app's users use a preferred account, then check that the user has access to the preferred account. Else, note the account id of the user's default account. (Also be prepared to handle the cases where there is either no userinfo response, no account or no default account for the user. These are infrequent DocuSign errors and can be fixed by contacting DocuSign Customer Support and referencing this article.
Use the expires_in OAuth response attribute to calculate your expires datetime. Then subtract 10 minutes so you have a buffer between the time you'll last use the access token and when it actually expires. You now have the last_use time.
Store the user's information, including the account id, base url for the account, access token, and last_use datetime.
If you have a refresh token, store it (and the user's information) in non-volatile storage.
When your application wants to make an API call
If you have a current access token for the user (last_use datetime is after the current datetime) then use it.
If the last_use time has passed, then use the refresh token if you have it. When refreshing the toke, you'll receive a new refresh token. Store it in non-volatile storage, overwriting the prior refresh token.
If no refresh token, then your app will need to ask the user to authenticate again.
Do not use oauth/userinfo again after either the token was refreshed or the user authenticated again. Keep and use the userinfo obtained after the person first logged in.
When your user wants to use a different account
Provide a "Switch accounts" feature to enable users to choose which of their accounts should be used. (Only applies if any account can be used with the application.)
User not-present: JWT grant
Your app's configuration screen will also need the user id in guid form. You can either store these values or look them up from DocuSign.
Decide whether a specific account is needed or not (see above).
Decide how the user will grant consent. See this video for more info.
First time your app needs an access token after a reboot
Use the JWT user grant to obtain an access token
As above, calculate the last_use datetime including a 10 minute buffer.
Use oauth/userinfo as above to determine if the user has access
the account or what the user's default account is. Also obtain the account's base_url.
Store the information.
Use the access token to make the API call.
Subsequent API calls
Check the last_use datetime. If it hasn't yet occurred then use the stored access token. If it has occured, then redo the JWT user grant flow but do not make another oauth/userinfo call--use the prior information.
Question 1 - You do not need to remember which user gave consent. That is not something you should do anyway, because users can revoke consent and then your information will be inaccurate. The system will ask for consent if needed (and if you ask for additional scopes it may be needed even if consent was given for example).
Question 2 - You should redirect immediately, whether consent is needed or not is unclear, but the user will either have to login, or just redirected if they have a cookie and consent is also based on their circumstances.
I'll consent (no pun intended) that we can improve this diagram and make it easier to understand. I would suggest implementing a simple scenario first and seeing how it work before moving on to the more advanced scenario (by simple I mean every time a user need to log in as if it was their first time).
I am building an application that will be used by end users in multiple organizations to create and send envelopes for signatures. I am trying to figure out the correct authorization workflow. For this example, say I am manish#example.com.
My understanding of JWT is that JWT will impersonate manish#example.com when any of these 1000's of end users in different organizations send envelopes. Is that correct? But if so, won't they need to authorize the app to impersonate me when they first try to create an envelope? How will these users get my credentials? Would I have to share my credentials with all these end users of my application? Can they log in with their own credentials instead? But if my application is impersonating my own credentials to send envelopes on behalf of these end users, why do I need permission from these users to use my own credentials? After all, in the JWT workflow, the redirect URL does not return any information about the identity of these users of my application.
So, if my app impersonates me, how do end users get my credentials? And, if my app impersonates me, why can't I give this permission to the app once and for all at the time of creating the app? Why do end users have to permit me to impersonate myself?
On a related note, JWT is working great when I use my own personal DocuSign API credentials to authorize my app in testing. But when I try to use my own organization credentials to authorize the app, I get the following error. I also get this error when I try the AWT workflow. How can I fix this error:
Sorry, but we’re having trouble signing you in.
AADSTS50105: The signed in user 'manish#test.edu' is not assigned to a role for the application '225d2ddd-e3a3-4bed-a310-8a9b8786363e'(Docusign Test).
Help in setting up the correct authorization workflow would be great.
JWT enables developers to request a token on behalf of some user without that user having to log in.
That means that except for the first time when the user have to consent - there's no web UI required to obtain a token.
JWT tokens are for a specific user in a specific account and it's the GUID of that userID that is used to uniquely identify a user. If you have multiple accounts - you will have to ensure you use the right userID for the right user for the right account.
Note also that users in DocuSign have different permissions profiles and may or may not have the access required to do what the API is trying to do.
Finally, clarifying one last thing, you wrote :
when any of these 1000's of end users in different organizations send
If you have thousands of end users that will be sending envelope (not just signing them) then JWT is probably not the best choice for you. You can still use it, but you will need some way to know the userId of the user which means you'll need some uber-auth JWT user that is used first or keep tables of users (I assume users can be added/removed etc.) it's not an ideal way to do things.
I have a vuejs SPA. Users have their own accounts with a dashboard. On the dashboard, is a section for PDF signing. All users should have the same PDF displayed, but with their name pre-filled on the PDF, and then 4 spots to sign.
Right now I am stuck on the first part for using the API....which is the auth code.
Why does it seem that the tutorial I followed, requires the owner of the DocuSign account to login and grant rights? I had to do something similar to https://account-d.docusign.com/oauth/auth?response_type=code&scope=signature&client_id=5665656-3506-46fa-b46d-f6acf3b59268&redirect_uri=https://www.google.com and I got a code in return....but how am I even suppose to implement this for my web app?
How do I get the auth code in the background....meaning...I cant have all users go to this URL...am I supposed to do it via ajax GET? I was able to use a correctly formatted URL, but I got the response by visiting the URL in my browser...how can I do this programmatically?
I dont get the granting rights part....because there is no way this would be practical where all the users would have to know my private DocuSign account info?
Of the (3) oauth methods, which is best for my scenario? Authorization Code Grant, Implicit Grant, or JWT Grant
Auth Code Grant was meant for interactive scenarios. It requires UI and a web interface. It cannot be used without UI. Once you have the initial access token, there's a refresh token to be able to obtain a new one without UI, but the initial call requires UI.
The users don't have to know your account info, your account info may not be relevant. The user grant a right to your app/integration to make API calls. That is not your account, it is different. It's a clientId/integration key that you use your account to create, but it can be used with any DocuSign user/account.
JWT would allow for what you asked in #1 but only after a one-time consent was provided (What you asked in #2) by the end-user. You have to do that for users to enable DocuSign to make API calls on their behalf.
Final word, signers do not need an account in DocuSign. I don't know what you're building, but if your end-user just signs - they don't need an account and a lot of 1-3 is moot.
I searched through previous questions but I haven't found a clear answer. My work flow is as follows:
I have a front end web app that talks to a node back end.
The node backend create a PDF and we would like for the user to sign it.
We use Authorization Code Grant
The user is redirected to the Obtain Consent screen
Once consent is granted they are redirected back to our app with a code that is swapped for an access token
We then use that access token to create our envelope and redirect our user to docusign for signing.
I would like to REMOVE the NEED for the user to provide consent. I have seen other companies leverage docusign without needing it.
My questions are:
- Is Authorization Code Grant the right authentication approach or should I be using JWT Grant?
- How can I get an access token for the user without obtaining consent? This seems like a necessary step?
- If I switch to the "Organizational Admin" approach, does my work flow change where I no longer re-direct the user to obtain consent? IF this is the case, how do I get an access token?
The users who are signing the document are not part of our company and do not share the same 'company email domain'.
I'd really welcome all feedback on this. Thank you.
If you just need users to sign, they do not need to log in to DocuSign at all. They don't even need to have a DocuSign account to sign.
Consent is only needed once per user/app. It cannot be avoided, as the user must agree to the app doing things for them.
If you use JWT - there's no need to login except once.
Hope this helps.
We have a case where we have 'clients'. Every client is an different Azure tenant but we keep their tenant id in the database. So we have Angular application where we want to have like a dropdown with all the clients and based on the selected client to query their tenant users so we can add him to our database and give them permissions and stuff to all other applications. As per my readings this in not achievable,
Because this permission application will be used from like 3-4 guys which are part of our tenant only.
Is there a way we can achieve that?
You would need to use the User.Read.All Application permissions and authenticate using the Client Credentials grant. You would then need to retrieve a token from each tenant prior to calling /v1.0/users.
Note that this will require receiving Admin Consent from each tenant you need to query.
Rohit's comment below is an excellent point. If your app is a SPA, meaning the authorization is happening entirely in the browser via Javascript, you're really limited to the OAuth's Implicit Grant.
To use Client Credentials or Authorization Code grants, you need some kind of backend API to handle the authentication and calls to authenticated APIs. I would argue that you should be doing this anyway, if for no other reason than forcing your user to reauthenticate every hour isn't a great user experience.
If you don't mind requiring each user in the tenant to authenticate, you could use the Authorization Code grant. This is a bit more complex of a set up because it requires you to keep track of separate Refresh Tokens for each user. Your backend would need to retrieve the Refresh Token, Exchange it for a set of new tokens (access_token and refresh_token), Store the new Refresh Token, and then call the API using the new Access Token.
Since there is a 1:1 relationship between the Token and the User so, at scale, you're looking at a lot of tokens. You'll also need a bunch of maintenance workflows to handle issues that may come up (refreshing the token fails, new scope requirements, etc.).
It really comes down to the depth of the relationship between your app and the tenant. If you're providing security and analysis to the entire organization, then asking for global Mail.Read is certainly reasonable. If you're providing a service to just part of an organization, it can be hard to get IT to sign off on such a broad permission scope.