From DocuSign this is developing with
DocuSign. This episode is an introduction
to OAuth for DocuSign developers. I'm
Larry Kluger
a member of the DocuSign Dev Center Team.
In this screencast I'll be focusing on
API authentication. The same
authentication techniques are used for
virtually all of the DocuSign APIs.
Signer authentication is also important
for DocuSign applications. Signer
authentication assures the sender that
the signer or signers of your documents
are who they say they are. DocuSign
offers many types of built-in signer
authentication that you can request for
your envelopes either via the DocuSign
web tool or via API requests. Sign
authentication options include the list
shown on the screen and more. Our newest
type of sign earth indication is ID
verification. With this feature DocuSign
will read and verify a scan of the
signers government-issued ID, such as a
passport or driver's license. Please take
a moment to subscribe to the DocuSign
for a Developers YouTube channel and
please also click the bell icon so
you'll receive an email as we release
new videos, thank you. Let's focus in on
API authentication. DocuSign's standard is
OAuth, the open authentication standard.
OAuth enables your application to
securely authenticate the user with
DocuSign even though your application
will not see the user's password during
the process. I'll show you how this works
with a demo later on in the video. In
addition to password security oAuth
provides the additional benefit that the
authentication step is controlled by the
DocuSign authentication server. This
means, for example, that if a customer
integrates a single sign-on system with
the DocuSign authentication server your
application will also automatically
support your customers single sign-on
system. In the same way, if a customer
enables two-factor authentication your
application will support it
automatically. Your goal for your app's authentication
process is to obtain a DocuSign access token. Your
application needs a token for every API
call it makes to a DocuSign API provided
by our cloud platforms. Please note that
your application should be written
defensively. There are multiple reasons
why an access token can be refused by
DocuSign. For example, a user withdrawing
consent from your integration key. While
it's possible for
DocuSign to cancel an access token
that would only happen in an
extraordinary circumstance. If a token is
refused then your application should
discard it and create a new one.
DocuSign supports 3 OAuth flows:
authorization code grant, JWT grant and
implicit grants. The best OAuth flow to
use is authorization code grant. It is
the easiest for the user and provides
the best information security and
security options. ISVs should especially
try to use the authorization code grant
flow if they can. To use it you will need
the user to be present when your
application is used or configured. Your
application will also need a secure
server component to protect the
integration key's secret. If you can't use
the authorization code grant flow then
often the JWT flow, that is the JSON web
token flow, is the next best one to use
especially for system integrations where
the user is not present. For single-page
web applications or mobile applications
where the user is present, but there is
no secure server component use the
implicit grant flow. We have code
examples for multiple software languages
for the different OAuth flows. They're
available on GitHub and also discussed
on the Dev Center. Before you can use
your integration key to obtain an access
token you must obtain consent from the
user. The authorization code and implicit
grant flows will obtain consent from the
user for your application the first time
the user authenticates with your
application. These flows provide a smooth
user experience. Obtaining consent for
JWT application is a bit more
complicated and I'll discuss the options
in the forthcoming JWT Grant screencast.
Now it's time for a quick demonstration
of an application which uses the OAuth
authentication code flow. Here's the web
application. When I start the login
process my web browser is redirected to
the DocuSign authentication server. First
I authenticate with the service via my name
and password. Next I'm asked to grant
consent to the application and now I'm
returned to the application. Note that if
my account starts to use two-factor
authentication, single sign-on or other
authentication options my application
wouldn't need any changes to support the new
security features.
For our next demo let's use the DocuSign
web tool to see which applications I've
granted consent to. We start with the
DocuSign web tool, not with the
administration tool. Note that I do not
need to be a system administrator to use
an externally-provided application. Next
I open the profile screen and then
choose the connected apps tab. Now I can
see all the apps I've granted consent to
and I can revoke consent from here as
well. After your application has obtained
an access token there are a couple of
additional steps before you're ready to
make an API call. To make an API call you
also need the users account ID and base
URL. Use the OAuth user info API call to
obtain this information. The user's
account or accounts and base URLs change
very infrequently so your application
should cache the results for at least a
day or until the user signs in again.
Many OAuth authorization code grant
libraries can automatically download the
user's information. See the code examples
on GitHub for more information. That's a
wrap. Please subscribe to the channel and
click the notification bell icon so
you'll receive an email as we release
new videos. Thanks for tuning in and
we'll see you on the next episode of
Developing with DocuSign.