Integrate Digisign Authorization with airSlate SignNow

Help me with integration e sign use dropbox

From DocuSign, welcome everybody to today's API Office Hours live Q&A webinar. My name is Larry Kluger. I am a developer evangelist here at DocuSign, and I'll be your host for the webinar. I have with us our API team on the call today. That includes Drew Martin, Matt King, and Geoff Pfander. And later on, Matt King will be giving us a demo. So let's get started with our webinar. We're talking today about authentication. And today we're discussing sender authentication, also what I refer to as API authentication, that's used when you are connecting to DocuSign to send envelopes or to use the API for any of the different API methods that are available. Sender authentication is a different subject than signer authentication. Examples of signer authentication include SMS, KBA, which means knowledge base authentication, X509 Signer certificates, and we have many other ways of authenticating the signer as well. Signer authentication has to do with the issue of ensuring that the cosine is who they say they are. We won't be discussing that further today. We're focusing on API authentication for your application. So our focus is OAuth. And if you're wondering why OAuth, well, it's 2019, so your web app does not need to see my password anymore. Also, when your application uses OAuth, your application will then automatically include many other information security features provided by DocuSign or by other third parties connecting in with DocuSign. So that means that if the sender is using two-factor authentication, 2FA, or single sign-on, through a single sign-on supplier, all of that will be incorporated automatically into the authentication flow when your application uses OAuth. And we have many other features in the pipeline as well. Your goal for the authentication phase of your application is to obtain an access token that you will then use for making API requests. DocuSign APIs do not use sessions, which means that every API request must include a valid access token. And that access token is sent as a header value in the API request to DocuSign. DocuSign supports OAuth in three flavors-- authorization [AUDIO OUT] authorization code grant, JWT grant, and implicit grant. Choosing your OAuth flavor. I recommend this flow to understand which you want to use. And in particular, we recommend Authorization Code Grant that you should use it if you can. To use Authorization Code Grant, you need to have the user, the human needs to be present. And there needs to be a server component of your application. So this exactly describes web apps where the user is there, using the browser, and then there's the server side of your application. If you can't use Authorization Code Grant, then the next step is often JSON Web Token Grant. And particularly that's often used for server integrations, also called system integrations, where the user is not present. An example of this type of integration is, let's say an application that's running quietly by itself, no user is present, and the application is watching a database table. And then when a record gets added to the table, or is updated in a particular way, the application then either sends out an envelope via DocuSign, or perhaps looks up information from DocuSign. Another example of this is an application which listens and waits for incoming web hook messages from DocuSign Connect, updating your application about the status of an envelope, and then your application uses a JSON Web Token authentication to use the API from DocuSign to directly gather more information about the envelope, or perhaps manipulate it in some way. If you can't use either of those two grant flows, then an Implicit Grant is the third choice. With Implicit Grant, the user does need to be present, but a server component is not necessary. And Implicit Grant has less capabilities than Authorization Code Grants. So if the user's present and you have a server component, then you would want to use Authorization Code Grant. This flowchart is another way of looking at the same material that we just discussed, and CORS is what's used for single page applications, where there's no server component. And that's where you would use Implicit Grant if that's your situation. We have many code examples that include the example code for how to accomplish the authentication. Both we have examples for Authorization Code Grant and JWT Grant, and we also have an example for Implicit Grant. For Authorization Code Grants, the examples start with eg-03, or -03, to be more precise. And these code examples are on our GitHub organization, that's github.com/docusign. On the right side of the screen, you can see a screenshot from GitHub where I've entered eg-03 in the repository search field, and then that shows as a result, the seven results so it shows our C# code example for Authorization Code Grant, also Java node. And then I'm going to skip curl for a moment, Python and PHP. We also have a set of examples that use the API directly via the curl program. And that's the one you see there, eg-03-curl. It doesn't include the Authorization Code Grant process, but it does include 14, and later there'll be more, workflow code examples. So that's also a useful repository if you decide not to use the SDKs. But we recommend the SDKs. If you're looking for an example of how to do JWT grant flow, then there's a set of those code examples starting with eg-01. So now I want to shift gears a little bit and talk specifically about the OAuth Authorization Code Grant flow. So the benefit is that it's easy to use, it's not so hard to implement. And especially when you use a library, and we'll talk about that next, it provides excellent security and your application will never see the user's password. That's one of the important goals of OAuth. There are many well tested libraries, and code examples are available. And as I discussed, this is the one we recommend when you are able to use it, that this is the one you should use. I'll also say that the Authorization Code Grant flow is the most popular OAuth flow. And it's what I would say 90% or more than 90% of the people mean if you talk to a developer and he or she says yes, I'm using OAuth. What they're talking about most probably will be the OAuth Authorization Code Grant flow, even though the other flows are also certainly under the OAuth umbrella. Authorization Code Grant flow has been around for quite a number of years now. And so it is well understood. There are information security, or InfoSec issues that you want to be aware of. The first one I'll call out to you specifically, which is that you should not embed the authentication dialog in an iFrame. Instead you should do a complete redirect of the user's browser from your application to the identity provider, in this case DocuSign, don't use an iFrame. There's additional InfoSec advice that has been developed, and it's gathered together in RFC6819, and you can look that up and for your reading pleasure. So let's now dive a little deeper into exactly how the OAuth Authorization Code Grant flow works. Many people have asked me about this, because a lot of times, it's not really spelled out. But here I want to show you every detail, and you can follow along. First thing to say is that we are talking here about four different places where software runs. And that's the four different columns of this chart on the left as user's browser, and then your application is running on your server. Then next, the DocuSign authentication server, and finally the servers where the DocuSign APIs are implemented. So let's see what happens here. The first is that on a user's browser, the user is let's say, looking at your application has provided a web page, the user is looking at and that user pushes the send envelope button that you've provided. And that then sends either a get or a post action to your application on your server. What next happens is that your server responds to the user's browser with the redirect command. And the redirect command includes, as all part of the URL, that the browser is going to be redirected to, includes the client ID, that's the same as the Integration key, those two terms are synonyms, the redirect URL, which is a URL hosted by your application, and we'll use that in a little bit, the scopes, which are the permissions that your application wants from DocuSign for this particular user, some various other minor information, and all of this is using the URL of the DocuSign authentication service. Next what happens is the user's browser has received the redirect, and then immediately opens a get request, or makes a get request to the DocuSign occasion server, so you see that's going to the third column here. And this get request is including all that data that it was just sent to the browser by your application. So again, that's the client IP, the redirect URL, scopes and so forth. Next what happens is very often the DocuSign authentication server will respond to the user's browser with the login web page which the first page of that sequence simply says enter your email address. And then later on you get a page for your password and so forth. And that's why I'm showing this arrow as being thicker and having arrowheads on both sides, is at this point the DocuSign authentication server is going back and forth with the user's browser for a number of pages of as I mentioned, the password page is always a second page, but sometimes there can be additional pages supplied by a single sign-on system or provided by DocuSign if a two-factor authentication challenge is being used, this sort of thing. So this can go back and forth. In addition, the little dash box there on the side is telling us that if there is an active login session from the user's browser to DocuSign, maybe that they opened up a DocuSign window on another tab, and if silent login is turned on, which is in fact the default, then this entire log in page and this login back and forth will all be skipped. And you can ask more about silent login during our demo and Q&A time, or we'll also be covering it in depth in our advanced topics session for Authorization Code Grant. In any case, the next step, these two prior steps may have been skipped if we're doing silent login. But this step that I'm showing now always happens, unless things have been canceled. And this step is now another redirect. This one is sent by the DocuSign authentication server, again back to the user's browser. This time the redirect includes the authorization code, hence the name of this flow Authorization Code Grant. So at this point, there's an authorization code. And the address is the redirect URL that was previously supplied. And the redirect URL, remember, is URL hosted by your application. Next the user's browser responds to that redirect by immediately doing a get. And that get has the authorization code. And the address for this get request is your application on your server using the special redirect URL that you've set up. Now at this point, your server, your application is back in control of things. And what it does is it sends a post request essentially at its backdoor, because the user's browser is waiting during this process. And so your application now sends a post request out its backdoor to the DocuSign authentication server. And in this request, the goal is to exchange the authorization code for the access token. And this request includes the client ID. Once again, let's remember the Integration Key from DocuSign. It includes the authorization code that's just received. It includes its secrets, and I think there may be some other minor stuff. But those are the key things. This request goes to the DocuSign authentication server, which then responds back to your server with an access token. Remember that's our goal, right? So now you've got the access token. And along with the access token, you get a refresh token. We'll discuss that in our advanced topics class. And also you get information on when the access token will expire. But I'll tell you right now that it's virtually always the case that DocuSign access tokens last for eight hours. At this point, your application has what it needs. It's got an access token. That means now your application can make any request to DocuSign. And if the original user, remember that a user authenticated herself or himself. If the user has the right privileges, then you will get back the response from DocuSign. I'm not showing that response part right here. I'm proposing in this example that you're doing the create envelope call. And with all API calls to DocuSign, you include the access token. The way you include it, I'm showing in italics, is there's a special header called authorization. That's the name of the header. And the value of the header will be the word bearer and then a space, and then the actual access token that you've received. And if you have questions about this, we can go over it more into question and answer. Now remember, you can ask questions anytime during the webinar. So you've decided that you want to use OAuth Authorization Code Grant. How should you implement it? Well, there's many different client libraries available. And in particular, we want to look for a Authorization Code Grant client library. There are also many Authorization Code Grant server libraries, and you don't need that when you're of course, being the client. Now our code examples that I discussed earlier, each of them uses a commonly used library for the particular software stack of the code example. So for instance, the C# code example is written using .NET Core MVC, which is what's recommended by Microsoft for new Greenfield applications with .NET these days. And the .NET core security module includes support for acting as a OAuth Authorization Code Grant client, so we're using that. With the PHP example, there's a group called the PHP league. And they have software library that they've called OAuth's 2-client, and we've figured that in the example for use with DocuSign. And so forth, you can see the rest of the list here. Now these libraries that we chose to use for the various code examples, you're not limited to these libraries. You can use any OAuth Authorization Code Grant client library. These seem to be popular, currently maintained libraries. And so we decided to make the examples using these particular libraries. A key issue is that we recommend, and the consensus of the experts is that you should not implement a lost Authorization Code Grant yourself, that you should use a library. So that's been an introduction both to OAuth in general and also the OAuth Authorization Code Grant flow. Stay tuned, we're going to have future OAuth webinars where I'm going to discuss each of the OAuth flows in depth, including topics such as silent authentication, token refresh, token strategies, and much more. So I hope you'll join us, and we're going to have that webinar Schedule D. And we'll post that at the end of this webinar, and you will also receive emails. So now it's time for a demo. I want to turn it over now to Matt to take us through a live demo of using Authorization Code Grant. Thank you Larry, that was great. For the record, my name is Matt King. I'm also with the developer programs in evangelism. And for the purposes of this demonstration, we're going to go ahead and do a demo of an Authorization Code Grant using one of our C# libraries. Specifically, we're going to use the eg-03 series that Larry mentioned here just a few minutes ago that's publicly available here on our GitHub. So once you get here, we'll go ahead and download the entire repository. And once we get that opened up here, we are going to need to go through a couple of initial setup phases. And I'll walk you through this here step by step. So part of this repository, we have 14 different common use cases available here. So once you get this up going, you can see how our system works. And after the descriptions, we do have some pretty specific installation instructions. And that's what we're going to go through now. So let's go ahead and get started here. One of the components we are going to require is going to be the redirect URI. So I'm going to go ahead and paste this into a notepad document so we have that ready here in just a sec. And then the other two pieces that we're also going to need are going to be our Integrator Key and our Secret Key, which you can obtain through your developer sandbox. So we'll go ahead and get logged in here. And then once in your sandbox, you will click the silhouette at the top right, and click on go to Admin. And then along the left side towards the bottom, the section we're going to want to go to is going to be API and keys. Now depending on how you're working with this, there are going to be several GUIs that you may care about, specifically your account ID and your username. For the purposes of this demo, we don't really need to worry about that. But what we are going to want is going to be to create a new Integrator Key. So we'll go ahead and add that. And then it's going to ask for a couple of configuration steps. Specifically, we're going to need to add the [AUDIO BREAKING UP] that we should be popping over to Notepad. And we're also going to need to add a Secret Key. Now it's also important to keep in mind that whenever you do create the Secret Key, you are going to want to copy it immediately. But once you hit the Save button here, part of the key is going to be redacted for security purposes. So after you close this window, if you don't have it copied over, you're not going to be able to recover this, and you will need to create a new one. So then, now we have our Secret Key. We'll go ahead and copy the Integrator Key as well. And then let's just go ahead and take a look at that repository we just downloaded. So inside of this folder. And this is just the base folder after you unzip it. You're going to want to go into the Auth Code Grant core folder. And the setup folder we're looking for specifically is going to be this app settings JSON file. Now, we'll go ahead and pretty print that, so it's a little easier to read. Now in this, the section that we need to fill out is going to be the DocuSign portion. As Larry mentioned earlier, your client ID and your Integrator Key are synonymous. So we're going to want to take that Integrator Key and go ahead and paste it in here. And then we're also going to take the Secret Key and put it on the corresponding line directly below the Integrator Key. Now the authorization endpoint and the token endpoints, whenever you're using the demo server, are going to want to be the same. And keep an eye on the app URL, specifically the port. Most developers do utilize systems like IIS, which by default you do use port 8080. So if you're running anything there, you're going to want to turn that off or you're going to run into some complications. And also for demo purposes, we're going to need to fill out the signer name and email address. But don't pay too much attention to the payment information. If you're using payments in the future, you are going to need to fill that out. But for demo purposes, we don't need to worry about that. So we'll go ahead and save this. And then back to our solution. We're going to go ahead and open this up in Visual Studio. So now that we've filled out and saved the JSON file, there's not really any additional configuration that needs to be done. Essentially, this application runs through Visual Studio and then ties into the IIS. So as long as the Configuration Folder is filled out correctly, you can go ahead and hit the Go button, and then it should open the application and in a new browser tab. So the application we're running here is one that's publicly available in all of our primary languages. We refer to it as a launcher, which is a premade application that has several common use cases in it. For these purposes, this launcher does use an Authorization Code Grant. And as soon as you engage any of these, it's going to go ahead and kick off the process. So just for demonstration purposes, we'll go ahead and log out here so I can show you specifically what will happen in any session. So once the Authorization Code Grant flow kicks off, you're going to be redirected this the URL that Larry mentioned earlier. And inside of it is going to be your Integrator Key, also known as your client ID. The second portion of it is going to be the scope, which in this case is going to be the signature. And the response type that we're looking for is your code. Also included in this is going to be your redirect URI, which is URL-encoded. So if you see it up here and it looks a little different, don't worry too much about that. As long as it translates towards the end, everything should be fine. And then at this point, you can go ahead and log in. And this will be the case for anybody that's authorizing themselves during this flow. And once you successfully authenticated, initially you will be required to grant permission for your token to be generated. And once you click that accept button, it's going to send back the code to the launcher which will then finalize the exchange, where it essentially takes the code that's sent back from DocuSign and exchanges it for the bearer token that's then used to authenticate. And once the system picks up that this code is in place, you can go ahead and click on one of the examples. And you can see here we've skipped the OAuth mechanism entirely because we already have our bearer token And then at this point, we can go ahead and get started using the DocuSign API. Now a couple of quick things to mention, this particular launcher does rely on .NET Core 2.1. Specifically, and I can provide this link a little bit later on in the chat, it uses a challenge method included in the ASP .NET Core Authentication namespace. And once I link you to this page, if you have further interest in exploring this a little bit more in depth, essentially what it does is it takes this information that you supply here and uses it against this method built into .NET, and it uses that to do the token exchange on your behalf. Because as Larry mentioned earlier, you really want to use any kind of library, specifically a professional one, for security purposes. OK, well thank you everybody. I would like to thank our terrific panel, Drew and Geoff, and also Matt who provided the demo. Thank you very much. And thank each of you, thank you our attendees for joining us today. [MUSIC PLAYING]