۶Ƶ

DocumentationWorkfrontWorkfront Guide

Create OAuth2 applications for Workfront integrations

Last update: Thu Oct 10 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Admin

As an ۶Ƶ Workfront administrator, you can create OAuth2 applications for your instance of Workfront, which allow other applications to access Workfront. Your users can then give permission to those other applications to access their Workfront data. In this way, you can integrate with applications of your choice, including your own in-house applications.

When you create an OAuth2 application, you generate a Client ID and Client Secret. Your users can then use the Client ID in API calls to integrate with the application you have created.

NOTE
In the context of OAuth2, “creating an app” refers to the process of creating this sort of access link between an app and a server such as Workfront.

Access requirements

Expand to view access requirements for the functionality in this article.

You must have the following access to perform the steps in this article:

table 0-row-2 1-row-2 2-row-2 layout-auto html-authored no-header
۶Ƶ Workfront plan Any
۶Ƶ Workfront license

New: Standard

Or

Current:Plan
Access level configurations You must be a Workfront administrator.

For more detail about the information in this table, see Access requirements in Workfront documentation.

OAuth2 overview

Imagine that an application must pull some specific information from Workfront. An application that requests information is called a client. For this example, the client name is ClientApp. ClientApp needs access to a particular user’s information, and therefore must access Workfront as that user. If your user gives ClientApp their username and password, ClientApp could access all of the data that the user can access. This is a security risk, because ClientApp only needs a small, specific set of information.

When you create an OAuth2 app for ClientApp, you are essentially telling Workfront that ClientApp is allowed to access Workfront, but only if the user whose account ClientApp is accessing gives permission for the access.

Create an OAuth2 application

When creating an OAuth2 application, choose the type of application that best meets the needs of your integration.

Application type
Best for
Authentication method
Machine to Machine Application

Best for CLIs, daemons, or scripts running on your server

Examples:

  • Shell

  • Python

Authentication through JSON Web Token with public/private key-pair encoding.
Single Page Web Application

Best for mobile or single-page web applications

Examples:

  • Javascript

  • Angular

  • React

  • Vue

Authentication through OAuth 2.0 Authorization Code flow with Proof Key for Code Exchange (PKCE).
Web Application

Best for server-side applications that handle credentials and tokens on the server

Examples:

  • Go

  • Java

  • ASP.Net

  • Node.js

  • PHP

Authentication through OAuth 2.0 Authorization Code flow.
NOTE
You can have up to a total of ten OAuth2 Applications at one time.

Create an OAuth2 application using server authentication (JWT flow) create-an-oauth2-application-using-server-authentication-jwt-flow

  1. Click the Main Menu icon Main Menu in the upper-right corner of ۶Ƶ Workfront, or (if available), click the Main Menu icon Main Menu in the upper-left corner, then click Setup Setup icon .

  2. In the left navigation panel, click System, then select OAuth2 Applications.

  3. Click Create app integration.
    The New OAuth2 application box displays.

  4. In the New OAuth2 application box, select Machine to Machine Application.

  5. Enter a name for the new application, such as “Workfront for ClientApp.”

  6. Click Create.

  7. Fill in the fields for the new app.

    table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 layout-auto html-authored no-header
    Client ID This field is automatically generated.
    Client secret

    This field is automatically generated

    IMPORTANT:

    Copy the contents of this field to another secure file before you close this page. You will not be able to see this secret key again.

    If you lose this key, delete it and create a Client Secret.

    1. Click the Delete icon to delete the current Client Secret.

    2. Click Add client secret to generate a new Client Secret.
    Public Keys

    Server to server apps use public and private keys for authentication. Do one of the following:

    • Click Add a public key and enter the public key from the other application.

    • Click Generate a public/private keypair, then share the public key with the other application.
    Name This is the same name that you gave the app. This field cannot be empty.
    Description Enter a description for the integration.

  8. Click Save.

For instructions on configuring and using the OAuth2 application with user credentials (authorization code flow), see Configure and use your organization’s custom OAuth 2 applications using JWT flow.

Create an OAuth2 application using user credentials (Authorization code flow) create-an-oauth2-application-using-user-credentials-authorization-code-flow

NOTE
If you are creating an application to connect to Workfront Fusion, use one of the following redirect URLs:
  • https://app.workfrontfusion.com/oauth/cb/workfront-workfront
  • https://app-eu.workfrontfusion.com/oauth/cb/workfront-workfront (EU Data center)
  • https://app-az.workfrontfusion.com/oauth/cb/workfront-workfront (Azure Data Center)

  1. Click the Main Menu icon Main Menu in the upper-right corner of ۶Ƶ Workfront, or (if available), click the Main Menu icon Main Menu in the upper-left corner, then click Setup Setup icon .

  2. In the left navigation panel, click System, then select OAuth2 Applications.

  3. Click Create app integration.

    The New OAuth2 application displays.

  4. In the New OAuth2 application box, select Web Application.

  5. Enter a name for the new OAuth2 application, such as “Workfront for ClientApp.”

  6. Click Create.

  7. Fill in the fields for the new app.

    table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 7-row-2 8-row-2 9-row-2 layout-auto html-authored no-header
    Client ID This field is automatically generated.
    Client secret

    This field is automatically generated

    IMPORTANT:

    Copy the contents of this field to another secure file before you close this page. You will not be able to see this secret key again.

    If you lose this key, delete it and create a Client Secret.

    1. Click the Delete icon to delete the current Client Secret.

    2. Click Add client secret to generate a new Client Secret.
    Redirect URLs Users will be redirected to this path after they have authenticated with Workfront.
    Refresh token rotation Enable this option to issue a new refresh token whenever the refresh token is used. Your application must store the new refresh token after every refresh.
    Absolute refresh token expiration Select the amount of time that you wish a refresh token to exist before it expires. When it expires, your users must log in to the integration again. Select "No expiration" if you do not want the refresh token to expire.
    Inactivity refresh token expiration

    Select the amount of time after which, if the user has not been active in your system, their refresh token expires.

    For example, if the inactivity refresh token expiration is 6 months, and the user does not log in for six months, the refresh token expires even though the absolute refresh token expiration may be set for longer.
    Logo You can add a logo to make this app more identifiable.
    Name This is the same name that you gave the app. This field cannot be empty.
    Description Enter a description for the integration.
    App Description URL This can be a link to an "About us" page or a page with more information about the integration.

  8. Click Save.

For instructions on configuring and using the OAuth2 application with user credentials (authorization code flow), see Configure and use your organization’s custom OAuth 2 applications using authorization code flow.

Create an OAuth2 single-page web application using PKCE create-an-oauth2-single-page-web-application-using-pkce

  1. Click the Main Menu icon Main Menu in the upper-right corner of ۶Ƶ Workfront, or (if available), click the Main Menu icon Main Menu in the upper-left corner, then click Setup Setup icon .

  2. In the left navigation panel, click System, then select OAuth2 Applications.

  3. Click Create app integration.

    The New OAuth2 application box displays.

  4. In the New OAuth2 application box, select Single Page Web Application.

  5. Enter a name for the new OAuth2 application, such as “Workfront for ClientApp.”

  6. Click Create.

  7. Fill in the fields for the new app.

    table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 7-row-2 8-row-2 9-row-2 10-row-2 layout-auto html-authored no-header
    Client ID This field is automatically generated.
    Redirect URLs Users will be redirected to this path after they have authenticated with Workfront.
    Rotate refresh token every time it is used Enable this option to issue a new refresh token whenever the refresh token is used. Your application must store the new refresh token after every refresh.
    Absolute expiration Select the amount of time you wish a refresh token to exist before it expires. When it expires, your users must log in to the integration again. Select "No expiration" if you do not want the refresh token to expire.
    Inactivity expiration

    Select the amount of time after which, if the user has not been active in your system, their refresh token expires.

    For example, if the inactivity refresh token expiration is 6 months, and the user does not log in for six months, the refresh token expires even though the absolute refresh token expiration may be set for longer.
    Logo You can add a logo to make this app more identifiable.
    Name This is the same name that you gave the app. This field cannot be empty.
    Description Enter a description for the integration.
    Developer name This is the name of the developer who is setting up the OAuth2 application.
    Developer email address This is the email address of the developer who is setting up the OAuth2 application.
    Privacy policy URL This is the link to where your organization stores the privacy policy.

  8. Click Save.

Configure and use the created OAuth2 application

Further configuration and use of the created OAuth2 application requires some technical knowledge, including API calls.

OAuth2 processes for authorization code flow

NOTE
Your users access the OAuth2 application through the API. This section describes the functionality in general terms, and is provided for information only.
For specific instructions on using the OAuth2 application, including specific API calls, see Configure and use your organization’s custom OAuth 2 applications using authorization code flow.

Authorizing with an authorization code and access token authorizing-with-an-authorization-code-and-access-token

  1. ClientApp needs some information from Workfront, so it sends a request to the Workfront API /authorize endpoint. The request includes the response_type code, which indicates that the request should return an authorization code.

  2. This triggers Workfront to send an authentication prompt to the user. The user can enter their credentials into the prompt, which gives Workfront permission to communicate with ClientApp. If the user is already logged into Workfront, this step may be skipped.

  3. The Workfront API sends an authorization code to ClientApp.

  4. ClientApp sends the following information in a request to the Workfront API /token endpoint:

    • The authorization code sent to ClientApp in step 3. This identifies the specific instance of user permission.
    • The Client Secret that was generated when you set up the ClientApp OAuth2 app in Workfront. This allows Workfront to know that the request is coming from ClientApp.

  5. If the authorization code and the client secret are correct, Workfront sends an access token to ClientApp. This access token is sent directly from Workfront to ClientApp, and cannot be viewed, copied, or used by any other user or client application.

  6. ClientApp sends the access token to Workfront along with the specific request for information.

  7. Because the access token is correct, Workfront sends the information to ClientApp.

Refreshing access tokens

For security, access tokens expire after a short amount of time. To get new access tokens without having to enter credentials every time, OAuth2 uses refresh tokens. Refresh tokens are stored by the client.

The process for acquiring a refresh token is the same as the procedure discussed in the section Authorizing with an authorization code and access token. The request for the authorization code includes the scope offline_access, which indicates that the request should return a request token along with the authorization code.

recommendation-more-help
5f00cc6b-2202-40d6-bcd0-3ee0c2316b43