I'm building an API to support user provisioning for other application teams around my company. I have a decent understanding of custom policies and have reviewed the invitation flow in WingTipGames, however the sample app is at times hard to follow given the sheer amount of functionality it offers. I would appreciate some clarification around what features I can ignore, vs what is required to support my use case.
Use Case:
My API's CreateUser method creates the user in B2C with ADGraph, then should generate an invitation link that includes a signed JWT with the user's email address, and finally email the link to the recipient. The new user will click the link, which should redirect them directly to the Invitation policy to reset their password.
Clarification Needed:
I'm struggling with simple generation of the Invitation link. What's shown in the sample seems overly complex for my API. In general I'm confused about the OIDC setup given that my API itself (while separately requiring callers to authenticate) will not be involved at all when the recipient clicks the invite link. And as this is an API not an MVC app, I wonder if the process can be stripped down vs the invitation flow in WingTipGames.
Why is ChallengeAsync called in the Invitation\Create method? Presumably this is why we then land in the OnRedirectToIdentityProvider event. Is the challenge what is somehow intercepted and translated into the invitation link?
Are the classes in WingTipCommon relevant here? Namely the AspnetCore.Authentication.OpenIdConnect extensions, handler, and middleware. Asking because users should never arrive at the API in response to clicking the invite link so perhaps the extra plumbing is unnecessary.
Users will always be in a new browser and session when the click the redeem the invitation link, and will redirect directly to the policy (if I understand correctly). Do I still need to worry about the skipCorrelation and XSRF handling?
Any other general suggestions around what to pull out of the sample and what to ignore to support my use case are appreciated.
Thanks
Mark
The Wingtip Games application implements the following flows for invitations:
An invitation link to an application endpoint. This invitation link contains the e-mail address of the invited user, an invitation expiration, and a HMAC-based signature. When the invitation link is opened, the application endpoint validates the HMAC-based signature and the invitation expiration and, if they are valid, then it redirects the invited user to the policy endpoint. This policy redirection contains a signed JWT with the email address of the invited user.
An invitation link to the policy endpoint. This invitation links contains a signed JWT with the email address of the invited user.
I prefer and recommend the first flow for invitations because the application endpoint can implement the invitation logic before the invitation policy is run (e.g. the application endpoint can validate the invitation expiration and, if it isn't valid, then it can display an error message) as well as after the invitation policy has run (e.g. the application endpoint can display a success message).
To answer your specific questions:
Why is ChallengeAsync called in the Invitation\Create method?
This is called for the second flow for invitations. It is called so that the authentication middleware can generate the invitation link and send the invitation message. It is implemented like this so that the application logic doesn't have to be aware of the application identifier, the policy identifier, or the redirection URIs that are required for the invitation link.
Are the classes in WingTipCommon relevant here?
They are used to support the second flow for invitations. See the next answer.
Do I still need to worry about the skipCorrelation and XSRF handling?
This is implemented for the second flow for invitations. As result of the invitation policy, Azure AD B2C issues an authentication response to the client application, where this authentication response is processed by the authentication middleware. Because the authentication middleware doesn't invoke the invitation policy (i.e. it is invoked by the invitation link), then the authentication middleware must be configured to disable the built-in checks for correlation of an authentication request with an authentication response.
Related
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 need to add DocuSign to my chat app (iOS, Android, Windows) in order to ask to sign documents to all the chat group members.
I want to implement DocuSign signing flow without Server implementation: only Sender and Recipients client side implementation (is it possible?).
Flow that I imagined:
An authenticated Sender create the envelope with Envelopes: create REST call.
Other members must sign the document (no DocuSign account needed)...
...so I need to generate a "recipient url" for every member using the REST call EnvelopeViews: createRecipient (who call this endpoint?)
I tested this flow with Postman and I've some questions:
EnvelopeViews: createRecipient require X-DocuSign-Authentication header, so this request must be called from Sender side, is it?
EnvelopeViews: createRecipient return an url that can be used once, why? The second time I use this url I get 404 as response.
So what I notice is the Recipient can't use the url (provided by the Sender) twice but he can't generate a new url every time because it isn't authenticated (no X-DocuSign-Authentication).
How can I implement this flow properly?
Lots of good questions:
EnvelopeViews: createRecipient require X-DocuSign-Authentication header, so this request must be called from Sender side, is it?
Do not use the X-DocuSign-Authentication header. That's "legacy authentication" and DocuSign does not support it for new REST eSignature apps. Instead, use OAuth. Probably the OAuth JWT grant flow since that flow enables your application to impersonate a DocuSign user (such as the sender), when the user is not present.
You can call EnvelopeViews: createRecipient from your server or from your browser app. If you call from your browser then you'll need to implement a private CORS gateway.
Either way, when the signer is ready to sign, you obtain the signing ceremony URL from the EnvelopeViews: createRecipient API call, then redirect the signer's browser to the URL.
EnvelopeViews: createRecipient return an url that can be used once, why?
For security reasons. That's part of our information security architecture. And not only is the signing ceremony URL only usable once, it is also time limited. It should be used within a minute or two from when you receive it from DocuSign. It will expire 5 minutes after it was created.
The second time I use this url I get 404 as response.
Yes, that's as designed. You get the URL, then you immediately redirect the signer to the URL. Then they sign. Then they're redirected back to your application.
If you want to provide a URL to a signer that the signer can use later on, you can implement that flow yourself. I've described how in other answers.
So what I notice is the Recipient can't use the url (provided by the Sender) twice but he can't generate a new url every time because it isn't authenticated (no X-DocuSign-Authentication).
How can I implement this flow properly?
You're almost there. Implement the JWT grant flow in your application. That way your app can impersonate the sender even when they're not around. When the signer wants to sign, your app gets the signing ceremony URL from DocuSign, and then redirects to enable signing.
An alternative which also works fine is for the sender to sign in to DocuSign by using the standard OAuth Authorization Code grant. This provides your app with an access token and a refresh token.
Your app enables the sender to send the enveloper by using the access token.
Later, when the signer wants to sign, your app uses the refresh token that it stored to generate a new access token. Use the access token with the EnvelopeViews: createRecipient API method to obtain the signing ceremony URL.
X-DocuSign-Authentication header is legacy authentication, please don't use this as it's not as secure as modern OAauth.
Again, security. Every time you want someone to sign your code should generate the URL. Also, note you cannot generate two URLs. Only one is valid at a time. You need your app to have some logic to ensure that only one user is signing and only at that point in time the URL is generated.
I am doing service integration with DocuSign platform using JWT Grant auth type. DocuSign account has multiple users setup.
My service is SendEnvelopService and one of the important request param to the service is user email. SendEnvelopService need to impersonate user with given email-id when calling DocuSign and send envelope in behalf of that user. Note that every request to SendEnvelopService will have different value of email request param.
I have following questions around it -
Question#1) Since I need to impersonate different user every time (based on email id in my request), I assume I need to get new JWT auth token every time, before making actual api call. Is that right? Is it usual and ok to request new JWT auth token so frequently before every api call? Does it raise any integration concerns with DocuSign?
Question#2) In my request, I have email id of the user to impersonate. I don't have user's GUID which I need, to get JWT auth token and impersonate it. Is there any api that I can use to get user GUID by email id? I wonder what kind of authentication will be needed for such api because I don't have JWT auth token yet.
One idea I have is may be I need to setup one admin user in DocuSign and keep admin userId (GUID) in application config. Now I have 2 users, one is admin user and another is request user which I have email from the service request. I can following steps -
Do requestJWTUserToken impersonating admin user. We get
oAuthTokenAdmin
Using oAuthTokenAdmin make
https://developers.docusign.com/esign-rest-api/reference/Users/Users/list
api call to get userId (GUID) of request user email.
Now do another requestJWTUserToken impersonating request userId. We
get oAuthTokenUser
Now make actual api call using oAuthTokenUser and to send envelope
Go to:
https://admindemo.docusign.com/
Log in with your demo (sandbox) credentials.
Then you have two options:
If it is only for you, simple thing is to click "API and Keys" page under Integrations on the left nav.
You will see this:
You can also click on "Users" on the left and select the user you want, any user really, doesn't have to be you.
then you'll see it under this:
For your first question, no, you don't have to do that. You can use the same user for all API calls. Especially if this user is an admin, then you can do all API calls under that context.
I have the following flow for sign in / sign up, when using sign-up:
Present user with sign up screen, allow them to enter email/password/name
Validate input, then send email (rest api) and set verification attributes in b2c custom extension properties
User then receives email with verification link
User clicks link from email and gets sent to a new user journey for the return trip
New user journey gets parameters from the querystring (email + verif code)
B2C validates the verif code + expiry
IF user is verified, they're set as verified via custom extension attributes, then sent to the (ASP.NET MVC) application.
Here's where I'm stuck - B2C is sending the jwt token back to the app, but the user doesn't get 'signed-in'.
Am I missing something at step 7? I don't have the "state" variable in my querystring, am I expected to build and include it somehow so that B2C and the app can communicate? I'm lost at this point. I'd post some of the b2c policy xml but not sure what would even help...
EDIT: reply to Jas:
Is that the only way (make an app call b2c for an auth request)? We have multiple apps that a user can use to sign up through b2c, so I was hoping to avoid having to make changes to each of them. Instead I was hoping that B2C could tell the app after account verification that "this user is ok".
I did previous look at https://github.com/azure-ad-b2c/samples/tree/master/policies/sign-in-with-magic-link (written by you!), but again, was hoping I could avoid having to do that work inside of each of our apps.
Here's an example of the jwt 'id_token' I'm trying to pass to the app:
id_token
Side note: Is 'id_token' the same as 'id_token_hint'? I couldn't find whether they're the same or different when googling it.
What you need to do is send the invite link in the email as a link to the app, eg https://myapp.com?id_token_hint=value.
Then have your apps account controller make an auth request to the policy to complete the account redemption along with an extra query parameter “id_token_hint=value”. Now a proper auth can happen with your applications openId middleware initialised.
When performing authorization code grant authentication, Docusign asks for consent. Far as I understand documentation, it's user's consent implied. When first asked for consent, the user is required to enter his credentials. When asked next time, the same user is implied.
However consider this: I have 3 users listed in my demo account wowproj.dev#gmail.com: the wowproj.dev#gmail.com himself, and Mary#inbox.ru, and Mike#inbox.ru.
I need to know two things:
1) whether I can statically specify the user when doing code authorization (say, by his "api username"), so that the user only has to press some "OK" button (maybe enter his password as well, but not username) - is that possible? Otherwise it may be possible that I have users "Mike" and "Mary" in my app, and I have those users in my Docusign account as well; then "Mike" user of my application starts some action, but when asked for consent, "Mary" enters her Docusign credentials and gives her consent. I want the consent to be Mike's! For example, I could store Mike's api username in his account in my app, and use it in grant authorization. But, far as I can see, neither user's login nor his api username are sent to Docusign in authorization code request, so I don't see how to achieve what I want.
2) When asked next time, the same user is implied - that may be a problem. What if my "Mike" from former paragraph, when asked by Docusign, enters his credentials and gives his consent, then he logs out from MY application and Mary logs in instead and starts some action involving Docusign; will Docusign assume it's still Mike's session? How do I make sure this does not happen?
I don't understand your question's use of "implied." Here's how it works. If you have further questions, please update (edit) your original question.
When using authorization code grant, the user first authenticates himself to DocuSign.
Then, if he hasn't previously done so, he is asked to grant consent to the integration. The permissions requested by the integration are the integration's scopes. The usual scope is signature, there can be others.
After he grants consent, the DocuSign authorization service will redirect the user's browser back to the integration, and and an authorization code will be included as a query parameter.
Your integration then makes an oauth call to DocuSign to exchange the authorization code for an access token.
Next (typically), your integration uses the OAuth::getUserInfo method to obtain the user's name, email, authorized DocuSign accounts, and more from DocuSign.
Ensuring that your app's user is the DocuSign user
You can't force who will be authenticating with DocuSign. But you can check that the right person authenticated. For example:
Mike logs into your app. You know Mike's email.
Your app wants its user to authenticate with DocuSign. Your app initiates the OAuth Authorization Code Grant flow with DocuSign.
Your app's user now sees the DocuSign login screen.
(The problem) is that Mike asks Mary to authenticate with DocuSign for him. Mary does so.
But when your app learns the email address of the DocuSign authenticated user, it will be Mary's email address, not Mike's. So your app can reject the DocuSign authentication by posting a message to the user saying that Mike must re-authenticate with DocuSign.
By implementing the above, your app can guarantee that when Mike is logged into your app, the matching authentication with DocuSign will be Mike's DocuSign user account, never someone else's.
Instead of comparing email addresses, you can also use the DocuSign user id. But doing so requires that you go through a step of loading your app with a table that associates Mike's account and his DocuSign User ID. Email addresses are probably easier.
Re: other people logging in after a prior session
There are two cases:
Same browser on the same machine
This is the "public computer problem."
Mike uses browser "G" to login into your app and also into DocuSign. Later Mary slides into his seat and uses the same browser and same application.
By default, DocuSign's OAuth Auth Code Grant enables Silent Authentication. This means that the DocuSign auth flow will silently enable Mary to use Mike's DocuSign session (if it is still active). For a public machine scenario, this is obviously not good. Solutions:
Always require DocuSign to actively authenticate the person (no Silent Authentication allowed). To do so, include prompt=login in the initial URL sent to DocuSign. See docs.
Clear the browser's cookies between users. The standard methods for handling public computers will include this.
Different users on the same app
Your app should use sessions. Each user of the app (in parallel or sequentially) will get their own session. Each session should maintain its own authentication information for DocuSign including the current user's access token, account id, and base url.
All of that information is determined as part of the authentication-with-DocuSign process.
These days, all modern web app frameworks provide easy to use session interfaces.
We also have code examples you can use. See this repository list. (With more on the way.)