After completing the DocuSign's OAuth flow with my Docusign App I would like to add a webhook to the user's account using the Connect APIs.
What I managed to achieve so far is complete the OAuth flow, get the token and create a webhook on my OAuth app but instead I want to create it on the user's one.
I think it should be possibile since it's exactly what the DocuSign API explorer is doing: it first makes me follow the OAuth and then allows me to create a webhook on my account.
Am I missing something?
Your OAuth identity on DocuSign can be associated with one or more accounts. You create an account-wide webhook by specifying the account_id in the ConnectConfigurations: create call to end point POST /v2/accounts/{accountId}/connect
So some choices:
If your login has access to your user's account then you're all set.
When your user logs in to DocuSign you could create the webhook using his credentials.
You can also use Service Application authentication, but in all cases, the login used by your app needs permission for the user's account to add a webhook on that account.
Note: by "user" I am assuming that you mean someone who is sending out envelopes. We call that person the "sender." People who receive or sign envelopes typically don't have accounts. They're "recipients."
If you want to know when someone signed, you should add a webhook on either the sender's account or on the envelope itself when it was sent.
Related
I have an backend API in an Azure Website that I like to protect using Azure AD.
As I understand it I'll first do an App Registration, use information registration as part of the sign in to get a token back to the client.
I can then send that token to the API and validate the token in the backend API to verify it.
But don't that token give access to all resources in the subscription? How to I restrict the App Registration to only be allowed to access that specific API? And not also another API in the subscription?
I also like to have a set of users that are allowed to access the API. If I'll just allow everyone to log in using the App Registration, everyone that's in my AD will receive a token back?
Can I somehow use a Enterprise Application to restrict access to the API only and only allow a set of users?
Or is there another way of doing this?
But don't that token give access to all resources in the subscription? How to I restrict the App Registration to only be allowed to access that specific API? And not also another API in the subscription?
A token only gives access to the API identified by the audience (aud) claim in the token.
Nothing more.
So if your client app asks for an access token to your API, that token is only valid on that API.
I also like to have a set of users that are allowed to access the API. If I'll just allow everyone to log in using the App Registration, everyone that's in my AD will receive a token back?
Can I somehow use a Enterprise Application to restrict access to the API only and only allow a set of users?
Yes.
You can find the enterprise app (service principal) for the API, enable Require user assignment, and then assign the users/groups you want to have access to the API from Users/Groups tab of the enterprise app.
Access token acquisition will then fail for users who are not assigned.
If you are using the same app registration for both the client and API, then you have to remember that you should acquire an access token regardless to call the API.
Don't use the id token.
Also in that case, a user who is not assigned to the app will fail login.
I'm following the React OAuth Implicit example shown here: https://github.com/docusign/eg-02-react-implicit-grant and I'm confused as to how an end user of our React SPA is supposed to be able to create an envelope for themselves without having access to our Admin account password.
As part of our app's sign up process, we have our end users fill out a form which prefills an envelope for them to sign via Docusign. We imagined that our Docusign admin account would authenticate our application on behalf of these users behind the scenes, allowing them to move on immediately to the embedded signing ceremony.
In the linked example, however, an end user is prompted via the Docusign UI to sign into our Admin account in order to continue using Docusign's API methods.
How can we avoid asking the end user to sign in? Or is this not possible when using the implicit grant model?
Thanks in advance.
Excellent question. There are many uses cases for DocuSign-integrated applications:
Use case: The signer is using your app
Signers don't need DocuSign accounts. Only the sender of the signing request needs an account.
Option 1: Use a Powerform
The easiest way to handle this use case is to use a DocuSign PowerForm. A PowerForm is a DocuSign envelope template that is implicitly sent by the DocuSign system. The signer can then fill in the form with their name and other details, and then sign the document(s).
Here's a video that demonstrates the Powerform solution.
You can fill in the form on behalf of the signer via query parameters. See this SO answer. Integrating your app with a PowerForm is easy but there may be some aspects of the envelope that can't be set via the template. See this article for details on how to set the URL the user will be redirected to when they finish signing.
Option 2: Create the envelope yourself, then let your user sign it
A more capable option is for your app to create the envelope yourself. You need an access token for a paid DocuSign user to send the envelope. I wouldn't use a system administrator account, just a regular DocuSign account user.
Something like:
Create a user in your DocuSign account such as "HR#your_company.com"
Set up a backend (server app) to use DocuSign JWT authentication to impersonate the HR#your_company.com "user." See the eg-01 series of code examples available in multiple languages.
Write your SPA to either create the envelope itself (after obtaining the access token from the backend) or use a private API to ask the backend to create the envelope. After the envelope is created, obtain the URL for the Signing Ceremony.
Your SPA now redirects the user to the Signing Ceremony (don't use an iFrame). After the user has signed, she will be redirected back to your SPA along with the event info (that she signed). An example of this is the Embedded Signing Ceremony workflow (the first workflow) in the DocuSign Code Example Launchers, the eg-03 series. Here's the Node.js example.
Notes.
Don't use an iFrame since the Signing Ceremony needs the entire screen. A 100% iFrame is not really needed since the SPA can save state in the session via cookies or local storage.
You can set the DocuSign Signing Ceremony to ping your server (AJAX pings) to keep the session alive, serve as a heartbeat, etc.
If you have your SPA create the envelope then you'll need to setup a CORS gateway to enable the SPA to communicate with the DocuSign cloud. This is detailed in the eg-02 example's write-up.
Creating an envelope for the signer as described above gives you maximum control over the envelope including the potential inclusion of attachment documents, payments, etc.
Use case: Your employee is using your SPA app
In this case, your employee can authenticate with DocuSign via the SPA, and then anything with DocuSign via the SPA and the DocuSign API. Eg:
Sending envelopes
Sending the envelope and then having the signer (in person) sign the envelope. Eg a banking application where the bank employee is enabling the in-person signer to open an account.
Monitoring sent envelopes
Whatever
This is the use case being demonstrated by the eg-02 React example.
Any route requires you to be authenticated as a DocuSign user to use it. With the standard service integration flow, you direct the user through docusign's /oauth/auth flow, use the returned code to get an access token via /oauth/token, then use that token on /oauth/userinfo to get the user's ID which you can then sign and use in a JWT.
Instead of directing users through the oauth UI to get their consent, DocuSign allows organization admins to pre-authorize an application for everyone in the application. No need to send organization members through the oauth flow. Great.
However, once this action has been taken, it's not clear how my application could make requests on behalf of any user, since the /oauth/userinfo route that gives you the user id requires an oauth code that you get by passing the user through DocuSign's oauth browser UI.
More specifically: if the admin of foo.com's DocuSign organization authorizes my app, and bob#foo.com starts using my application, how do I get bob#foo.com's user ID to create a JWT with?
When you say "bob#foo.com starts using my application" what, exactly, does that mean?
Case 1: Bob is interacting with your application. In that case, you should be using a User Application OAuth flow such as Authorization Code Grant to enable him to login.
If your app needs to later act on behalf of Bob when he's not around, then store Bob's user id for later use with the JWT grant.
Case 2: Your app is running in the background (no human interaction). At some point your app needs to starting doing things for Bob by impersonating him. All you have is his email address.
If this time arrives and your app has had no interaction with Bob, then yes, you need prior access as an admin (in Bob's account) so you can look up Bob's user_id from his email.
This second account would be the "admin user account" for your app. The account would need admin privileges to lookup the user's information. Your app would get access to this admin account when your app is installed.
Use the Users:list API call. Remember to encode the email address.
Example:
GET call: /v2/accounts/{accountId}/users?email=larry%2Buser%40foo.com
Re: user_id lifetime I'm reasonably sure that the user_id guid doesn't change for a given accounted user (someone who is a member of an account on DocuSign). I will check to make sure.
I created an app on one twitter account. I would like to authorise that same app on a different account.
FAQ on how to authorise apps says On the website of the application you want to connect, find the button/link asking you to connect your Twitter account. But I haven't built said site/page.
How can I auth this app on the second account?
You have to use the OAuth Authentication Flow process.
To do so, you first need to request an authentication link from your Consumer Key and Consumer Secret using https://api.twitter.com/oauth/request_token (doc : https://dev.twitter.com/oauth/reference/post/oauth/request_token).
When you receive a callback or a code, you can use them to execute a second query that is https://api.twitter.com/oauth/access_token as described at https://dev.twitter.com/oauth/reference/post/oauth/access_token. You will want to use the oauth_verifier parameter.
Remember that authentication in Twitter is not an easy process and you should read more about it on Twitter (https://dev.twitter.com/oauth/3-legged) or use a library that will do that for you.
I have an application that currently integrates into my merchant account using my access token. Early discussion with neighborhood merchants indicates some positive interest. I want to integrate OAuth support so that I can try to get traction with those merchants.
Though https://docs.connect.squareup.com/api/connect/v1/#navsection-oauth has information, I seek some additional clarification.
(i) Access using https redirect-url is denied at Square Connect Authorize has an answer "By default the OAuth flow is disabled for applications which is why you are seeing the "Authorization not allowed" failure. If you wish to enable OAuth flow for your application then you need to contact Square." #SquareConnectSupport: I have sent an email to Developer#Square, please let me know what else do I do.
(ii) Here is how I think it will work - the OAuth integration (Please confirm)
User types in browser say "mysnow.com/square"
The Handler at "mysnow.com/square" allows user to type in an ID this ID is local to mysnow
Then the Handler at "mysnow.com/square" directs the merchant to https://connect.squareup.com/oauth2/authorize along with my application id, permissions and redirect url.
The handler then receives a notification code with AuthZ Code at the redirect URL previously provided.
Next the handler obtains the Access token (using the AuthZ code)
Finally, the handler then saves the ID, the AuthZ code , the relevant Access Token and the date/time stamp (when the token was obtained) as a tuple in a safe data store.
(iii) Using the Access Token
When there is need to access merchant data of given ID, then use the ID to get the Access Token. Use this Access Token to manage the permitted data (based on permission)
Renew the access token periodically.
(iv) For testing purposes, I create few test/dummy merchants? Or do you have dummy merchant accounts that I can use for testing.
You can authorize up to ten merchants through the OAuth flow without approval from Square, which should be enough to get your integration running and tested. If you would like to make it more broadly available, you will need to contact Square about getting the app in the Square App Marketplace.
That looks essentially correct. The best practice for OAuth is something like this:
Merchant visits your landing page (e.g. mysnow.com/square) and clicks an action to start using your square integration.
Merchant's browser is redirected to the OAuth page (https://squareup.com/oauth2/authorize?client_id=YOUR_CLIENT_ID&scope=LIST_OF_OAUTH_SCOPES_YOU_NEED)
Merchant authorizes your application to access their data and is redirected back to your site. In the URL is an authorization code
Your backend makes an API call to Square to exchange the authorization code for an access token. It then uses that access token to look up information about the merchant and pre-populate fields of your signup form (e.g. you can get name, email, etc)
With a partially populated signup form on your site, merchant is prompted to complete their registration with your service.
There isn't really a way to create "dummy" merchants, but you can sign up for multiple merchant accounts with the same identity information, as long as you use a different email for each one. If you have GMail, you can do "you+someword#gmail.com" and the mail will be redirected to "you#gmail.com", so you don't need to create a bunch of email accounts to have unique email addresses.