Welcome to Developing with DocuSign.
I'm Karissa Jacobsen, a member of the developer center team.
This video is a continuation of our multipart instructional
series on how to migrate your application to OAuth 2.0.
In this video, I'll walk through how
to tell if you're using non-OAuth 2.0 authentication
and how to set up one of the recommended OAuth 2.0 flows,
specifically JWT authentication using
the DocuSign e-signature Ruby SDK.
Migrating to use OAuth 2.0 has the following benefits,
you'll remove the potential impact
of not complying with privacy laws and policies,
as well as the legal liability of data loss
if somebody hacks your app.
You'll eliminate the possibility of your app breaking
when users change their login credentials.
When you implement OAuth 2.0 authentication,
you'll be able to manage your app through Single Sign-on.
And because we've deprecated legacy authentication,
we no longer document it.
When you move to use OAuth, you'll
be able to take advantage of our documentation,
including how-to guides, best practice guidelines,
and troubleshooting.
Now let's take a look at what legacy authentication looks
like in a Ruby project and how to set up your integration
to use OAuth 2.0 instead.
If your app uses the x DocuSign authentication or WS
security username token header, it
is using legacy authentication and must
be updated to use OAuth 2.0.
Legacy authentication requires DocuSign credentials,
including account email, password, and an integration
key.
That information is passed as the value of the x DocuSign
authentication header.
Now I'll recreate this code using the OAuth methods
provided by the DocuSign e-signature Ruby SDK.
But first, I'll need to gather some information from my admin
dashboard.
To set up JWT authentication, I'll
need my app's integration key, RSA private key, redirect URI,
and an impersonated user GUID.
I can find these OAuth elements on the Apps and Keys page.
Under My Account Information, I can
find my user ID, which I'll use as my impersonated user GUID.
Next to my app name, I can find my integration key.
And to find the rest of the information,
I'll select the Actions button, then choose Edit.
Under Authentication Service Integration RSA Key Pairs,
I'll select Generate RSA.
Make sure to save your public and private keys
in a secure location, as they will not
be accessible after closing this window.
Then, under Additional Settings, Redirect URIs,
I'll select Add URI to add a Redirect URI for my app.
Here I've set up variables to store
my integration key, Redirect URI, and impersonated user
GUID.
I've pasted my RSA private key into a text file named
docusign_private_key.txt and set a variable to point to that
file's location.
I've also defined a variable to store the scopes I'll
need for my API calls.
Scopes represent the OAuth permissions
that are being requested.
For e-signature REST API methods,
use the signature scope.
Additionally, JWT grant authentication
must obtain permission to impersonate a specific user
on a long-term basis and uses the impersonation scope.
However, in the e-signature Ruby SDK,
the impersonation scope is assumed
and is not needed in the JWT grant request.
If the access token will be used for other DocuSign APIs,
additional scopes may be required.
Expires In defines how long the token
will be valid for, after which, I'll need to get a new token.
I also need to set a base path for the authentication service.
This path differs depending on whether your app is
in the development environment or in production.
I'll use account-d.docusign.com.
Since this is the first time I'm authenticating
my app with this specific set of scopes,
I'll need to grant permission for the app to perform actions
under those scopes.
To get this consent, construct a URI value matching the syntax
shown that includes the authentication base
path, your integration key, scopes,
redirect URI, and a response type value of code.
For JWT, be sure to include the impersonation
scope in your consent URL.
After redirecting your app to the consent URL
and choosing Accept, the authentication server
will redirect the user to the URI provided.
Since I'm using an arbitrary redirect URI for this video,
the error message shown in my browser is expected.
You'll also see a code in the URL.
In this authentication flow, you can safely
ignore this and close the tab.
Now that I've granted consent, I can obtain the access token
from the API client, request JWT user token method.
Now, I'm ready to start making API calls.
I can create an API client as before.
But this time, I will add a default header
with Authorization as the key and Bearer access
token as the value.
The rest of my code can remain intact.
Now I can run this simple code example, which successfully
lists the envelopes in my developer account
that have had status changes in the last 30 days.
You can use the same token to make all API
calls while the token is valid.
You don't need to get a new token for every API call.
That's it.
Thanks for tuning in.
If you have any questions about how
to develop your integration with DocuSign,
here are some resources.
I recommend checking out the following links
for more details, OAuth 2.0 requirements in migration,
how to get an access token with JWT grant authentication,
and recommended OAuth 2.0 flows.
If you're watching from our YouTube channel,
please post questions and comments below the video,
or email us developers@docusign.com.