OAuth for the Adobe Sign API

‍What is OAuth?

According to Wikipedia, OAuth is an open standard for access delegation, commonly used as a way for Internet users to grant websites or applications access to their information on other websites but without giving them the passwords. When used with the Adobe Sign API, this means automatically obtaining an Access Token and then applying it in each of the API calls.

Some manual setup and configuration steps are performed once by you, the developer, as part of building and collecting development artifacts for your API application. Subsequent steps are performed automatically by your application each time the Adobe Sign API is called. These subsequent steps make use of the artifacts defined in your one-time manual procedure.

OAuth Overview

As mentioned, implementing the OAuth protocol for your Adobe Sign API calls involves two phases:

• the one-time manual development phase in which you build and collect OAuth artifacts
• the execution phase where these artifacts are used for access to the Adobe Sign API

There exists a misconception that using the Adobe Sign OAuth implementation for API calls involves a manual procedure each time an Access Token has expired and is required for access to the Adobe Sign API. In fact, manual procedures are performed only once during the development phase of your application. After that, expiry of an Access Token involves a procedure followed by your application in the execution phase, to obtain new Access Tokens. No manual procedure is performed after the development effort is finished.

Basically, the one-time development phase involves configuring Adobe Sign to define an API application, and manually performing a RESTful call to the API to retrieve an Authorization Code that your application can use to obtain an Access Token for use in authorizing each API call. That Authorization Code never changes, so the manual procedure is never more required.

Terms and Concepts

Before we jump into the manual and automatic procedures that implement the OAuth protocol with the Adobe Sign API, let us review some terms and concepts required for an understanding of the process.

• API Application – A single application that will use the Adobe Sign API. This is defined using the Adobe Sign Web Application. Details from this definition are used in both the manual development procedure and in the automated execution of your API Application.
  
  
• Redirect URL(S) – Any web page that you can use for a one-time manual procedure of obtaining an Auth Code. (eg. https://google.com).
  
  
• Base URL – Each of the Adobe Sign API calls is a RESTful service call. There are several server farms that implement Adobe Sign instances, throughout the world. Your API application should, at the beginning of each API session, ask Adobe Sign for an up-to-date base URL to be used for your Adobe Sign instance because this base URL could possibly change between one session and the next. All subsequent API calls in the session should use this base URL. Failure to get an up-to-date Base URL could result in errors when calling the API.
  
  
• Auth Code – You (manually) and your application (automatically) will use this Auth Code to request OAuth Tokens from Adobe Sign.  An Auth code represents the union of:

1. Your API Application Definition in Adobe Sign, and
2. access permissions for various API calls that your application will be making.
   
   

• Scope Keywords – These are from the Adobe Sign Web Application where your API Application is defined. Examples are: user_login:self, agreement_send:group, agreement_write:group.
  
  
• Client ID and Client Secret – These are also from the Adobe Sign Web Application where your API application is defined. They are used automatically by your API application to obtain a new Access Token or Refresh Token when either have expired.
  
  
• Access Token – A code that you include with each of your Adobe Sign API calls. This Access Token expires after about 5 minutes from its last use. Your application should test the Access Token for validity at the beginning of each API session. If you get a status of 401 (unauthorized) or similar, your application should use the Refresh Token to request a new Access Token.
  
  
• Refresh Token – A code that your application uses for request of a new Access Token in the event that the Access Token has expired. This token expires after 60 days of no-use, that is, 60 days from the last time the token was used. If your application gets a status of 4xx when using this token, then your application can automatically use the Auth Code, Client ID and Client Secret to obtain both a new Access Token and a new Refresh Token. (No manual procedure is used in this.) Your application should record these for use in future API calls.

Configuring OAuth

Storing OAuth Artifacts

Your application needs to be able to store codes and tokens in a secure manner and needs to be able to later on read those codes and tokens automatically as part of the OAuth protocol procedure. You also need to be able to manually enter codes in this machine-readable storage during the development effort. In a demonstration, this secure machine readable and manually editable storage was a Java Properties file stored in the /var directory with permissions such that only the running application may access. The properties file satisfied the three conditions: manually editable, machine read/writable and secure. You might want to do the same or use a database table for the various codes and tokens that must be stored and read.

Setup for OAuth Protocol

As mentioned, there are manual development tasks to be performed for setup of the OAuth protocol, and there are automated tasks to be performed by your API application. Here we detail the manual steps that must be performed as part of the development effort of an Adobe Sign API application.

Step 1: Start a Collection of OAuth Artifacts

As mentioned above, these artifacts should be manually writeable and machine writeable / readable by your application at execution time. In a demonstration a properties file in a secure directory was used.

Step 2: Identify Redirect URL

Pick a website, any website. It doesn’t need to be part of your application. In a demonstration we used https://google.com . Record this URL in your machine readable collection of artifacts.

Step 3: Login to Adobe Sign as System User

Login to Adobe Sign as the user that will be making the API calls (usually a System User who is a Group Admin). The user you login as at this step will be the user that the API calls will be made as (unless overridden by API parameters). This user ID will be embedded in the Auth Code that we will request shortly.

Step 4: Create an API Application in Adobe Sign

Having logged in to Adobe Sign, create an API Application: Go to the Account tab -> Adobe Sign API -> API Applications -> Click the + sign in the circle to make a new API Application.

Step 5: Name and Domain of the API Application

Give your API Application a name, and Choose the Domain: Customer, click Save.

Step 6: Start to Configure OAuth

Having saved your application name, now click once on your API Application: Then click on Configure OAuth for Application that appears.

Step 7: Record Application Details

Copy the Client ID and Client Secret and place them with your machine-readable collection of info.

Step 8: Set the Redirect URL

Enter the Redirect URL(s) (from step 2) - comma separated if more than one - in the space provided.

Step 9: Set the API Scope

Select the scope items your API Application will need. Typically choose Group for a Modifier.

Step 10: Record Scope Keywords

Copy the list of scope keywords shown that you check-marked, to your list of info, along with your chosen modifiers, plus-separated. Eg:

user_login:self+agreement_send:group+agreement_write:group+
agreement_read:group+agreement_retention:group+library_read:group

Step 11: Save the Configured API Application

Click Save.

Note: if the required scope of access for your application changes, login as the same (System) user and restart from Step 9.

Step 12: Build Manual Auth Code Request

Build a request for an Auth Code and place it with your collected info, using this example where the &scope parameter must match that which you configured your API Application in step 10 above:

https://secure.echosign.com/public/oauth
?redirect_uri=[enter your URL here from step 2]
&response_type=code
&client_id=[enter your Client ID here from step 7]
&scope=user_login:self+agreement_send:self+agreement_write:self+
agreement_read:self+agreement_retention:self+library_read:self

Step 13: Use the Auth Code Request in a Browser

NOTE: You may need this request URL later. If your application goes unused for 60 days you'll need to repeat this step. Save the request URL for later use in that case.

NOTE: The code generated by this request expires after 5 minutes. Be sure you're ready to immediately execute the steps listed below, under "Implementing OAuth at Run-Time" before you do this step because those steps use this code and must be executed within 5 minutes of the request described in this step.

Enter the resulting URL in any browser that has access to the public Internet.

Step 14: The Auth Code

You will be taken to the URL you indicated as the redirect_uri. (This is the only time and purpose that the redirect URL is used, except Step E below.) Note the Address Bar in the browser - it has a code parameter. Copy this Auth Code and paste it into your collection of info. This Auth Code represents a combination of your Client ID and your scope and does not change unless you change your scope in the API Application definition.

Step 15: End of Manual Development Tasks

That completes the manual tasks for setup of an API Application, which tasks never need to be performed again, unless you change the scope for the application (which would be part of a further application development effort). Save the info collection as part of the machine readable application development artifacts.

Implementing OAuth At Run-Time

As mentioned, there are manual development tasks to be performed for setup of the OAuth protocol, and there are automated tasks to be performed by your API application. Here we detail the automated, execution-time steps that must be performed by your Adobe Sign API application.

Setup Your Application

Step A: Read OAuth Details

Arrange for your application to programmatically read your collection of info.

Step B: Write OAuth Tokens and Base URL

Arrange for your application to read and record three items: an Access Token and a Refresh Token and a Base URL.

Step C: Test Access Token and Get Base URL

Skip this step if you do not have any Access Token yet. The Access Token expires after about 5 minutes of disuse, so at the beginning of each API session arrange for your application to: test the validity of a previously stored Access Token.

The application should test the validity of an Access Token by using it to get a Base URL:

URL: https://api.echosign.com/api/rest/v6/baseUris (for GET)
Header: "Authorization"
Value: in this format, starting with the word Bearer:
Bearer [insert your Access Token Here] (a space after “Bearer”)

If that call results in 401, then the Access Token has expired so your application should move on to the next step, to get a new Access Token and record it for future reference.

If that call results in 2xx, then the Access Token is good and should be used in future API calls for this session. The returned BaseURL should be recorded by your application for future API calls in this session.

Step D: Use Refresh Token

 (Refresh Tokens expire 60 days after last use) Skip this step if:

• the previous step (the testing step) resulted in 2xx for an existing Access Token, or
  
  
• if you have not yet recorded any Refresh Token.

Here we use the Refresh Token to get a new Access Token: Have your application retrieve the previously recorded Refresh Token and use it to get a new Access Token:

https://secure.echosign.com:443/oauth/refresh  (for POST)
Header: "Content-Type"  Value: "application/x-www-form-urlencoded"
Body:
refresh_token=[insert Refresh Token here]
&client_id=[insert Client ID here]
&client_secret=[insert Client Secret here]
&grant_type=refresh_token

If that call results in 401, then the Refresh Token hasn't been used for 60 days and has expired so your application should move on to the next step.

If that call results in 2xx, then the Refresh Token is good and the JSON payload of the response should be examined for a new Access Token. Get from the JSON response this new Access Token with this keyword: access_token

Store the new Access Token for future reference in making API calls in this session. Go back to Step C to get and record a Base URL for API calls in this session.

Step E: Get New Access Token and New Refresh Token

Skip this step if you have a valid Access Token. This step should be used if by this point you do not have an existing valid Refresh Token or Access Token. Both will be retrieved in this step.

Here we use all of our credentials to get both an Access Token and a Refresh Token:

https://secure.echosign.com:443/oauth/token  (for POST)
Header: "Content-Type"  Value: "application/x-www-form-urlencoded"
Body:
code=[insert Auth Code from step 14 here]
&client_id=[insert Client ID here]
&client_secret=[insert Client Secret here]
&redirect_uri=[insert a URL that was included in step 8, above]
&grant_type=authorization_code

That call will result in a 2xx if everything is OK. If not, you'll have to check all the steps up to this point for accuracy.

Record both the access_token and refresh_token for future API calls.

Go back to step C and continue from there to get a Base URL which you should record for future API calls in this session.

Step F: Use your tested Access Token and Base URL for your API calls

In all your API calls for this session, use the retrieved and recorded Base URL and set the Authorization header to the word Bearer plus a space, plus the Access Token. Eg:

URL: [insert your base URL here]/api/rest/v6/…
Header: "Authorization"
Value: in this format, starting with the word Bearer:
Bearer [insert your Access Token Here] (a space after “Bearer”)

Conclusion

As with most technical instructions, this took more words to explain than to actually perform. Making a distinction between one-time manual development tasks, and run-time execution steps helps to clarify the use of the OAuth protocol for use with Adobe Sign.