Authentication for Document Webhooks

Last update: November 7, 2023

CREATED FOR:

  • Developer

Authentication

Adobe Workfront document webhooks supports two different forms of authentication: OAuth2 and ApiKey. In both cases, Workfront passes authentication tokens in the header when making an API call.

OAuth2

OAuth2 allows Workfront to make authorized API calls to a webhook provider on behalf of a user. Before doing so, the user must connect their external document provider account to Workfront and grant Workfront

access to act on their behalf. This handshaking process only happens once for each user. Here’s how it works:

  1. The user begins connecting the webhook integration to their account. Currently, this is done by clicking the “Add Document” dropdown > “Add Service” > Custom integration name.

  2. Workfront navigates the user the Authentication URL, which may prompt the user to login to the external document provider. This page is hosted by the webhook provider or the external document management system. When doing so Workfront adds a “state” parameter to the Authentication URL. This value must be passed back to Workfront by appending the same value to the Workfront Return URI in the step below.

  3. After logging to the external system (or if the user is already logged in), the user is taken to an “Authentication” page, which explains that Workfront is requesting access to perform a set of actions on the user’s behalf.

  4. If the user clicks the “Allow” button, the browser will redirect to the Workfront Redirect URI , adding “code=<code>” to the querystring. Per the OAuth2 spec, this token is short lived. The querystring must also have the following, “state=<sent_by_workfront>”.

  5. Workfront processes this request and makes an API call to the Token Endpoint URL with the authorization code.

  6. The Token Endpoint URL returns a refresh token and access token.

  7. Workfront stores a these tokens and fully provisions the webhook integration for this user.

  8. From this point forward, Workfront will be able to make authorized API calls to the webhook provider. When making these calls, Workfront will send the the access token in the HTTP request header as shown below:

    -------------------------------
Authorization: Bearer [access_token] ­­­­­­­­­­­­­­­­­­­­­­­­­­
-------------------------------

  9. If the access token has expired, Workfront will make a call to the Token Endpoint URL to retrieve a new access token then attempt the authorized API call again with the new access token.

ApiKey

Making authorized API calls to a webhook provider using an ApiKey is much simpler than OAuth2. When making an API call, Workfront will simply pass the ApiKey and Workfront username in the HTTP request header:

-------------------------------

apiKey: 12345

username: johndoe@foo.com

-------------------------------

The Webhook provider can use the username to apply user-specific permissions. This works best when both systems connect to LDAP using Single Sign On (SSO).

Previous pageRegister a Webhook Integration
Next pageGet OAuth2 Tokens

Workfront