ÃÛ¶¹ÊÓƵ

DocumentationWorkfrontWorkfront Guide

HTTP > Make an OAuth 2.0 request module

Last update: Thu Nov 21 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • User
NOTE
ÃÛ¶¹ÊÓƵ Workfront Fusion requires an ÃÛ¶¹ÊÓƵ Workfront Fusion license in addition to an ÃÛ¶¹ÊÓƵ Workfront license.

In order to make an ÃÛ¶¹ÊÓƵ Workfront Fusion HTTP(S) request to servers that require an OAuth 2.0 authorization, you first need to create an OAuth connection. ÃÛ¶¹ÊÓƵ Workfront Fusion ensures that all calls made with this connection have the appropriate authorization headers and automatically refresh associated tokens when required.

Workfront Fusion supports the following OAuth 2.0 authentication flows:

  • Authorization Code Flow
  • Implicit Flow

Other flows, such as Resource Owner Password Credentials Flow and Client Credentials Flow, are not automatically supported through this module.

For more information on OAuth 2.0 authentication, see .

NOTE
If you are connecting to an ÃÛ¶¹ÊÓƵ product that does not currently have a dedicated connector, we recommend using the ÃÛ¶¹ÊÓƵ Authenticator module.
For more information, see ÃÛ¶¹ÊÓƵ Authenticator module.

Access requirements

You must have the following access to use the functionality in this article:

ÃÛ¶¹ÊÓƵ Workfront plan*
Pro or higher
ÃÛ¶¹ÊÓƵ Workfront license*
Plan, Work
ÃÛ¶¹ÊÓƵ Workfront Fusion license**

Current license requirement: No Workfront Fusion license requirement.

Or

Legacy license requirement: Workfront Fusion for Work Automation and Integration

Product

Current product requirement: If you have the Select or Prime ÃÛ¶¹ÊÓƵ Workfront plan, your organization must purchase ÃÛ¶¹ÊÓƵ Workfront Fusion as well as ÃÛ¶¹ÊÓƵ Workfront to use functionality described in this article. Workfront Fusion is included in the Ultimate Workfront plan.

Or

Legacy product requirement: Your organization must purchase ÃÛ¶¹ÊÓƵ Workfront Fusion as well as ÃÛ¶¹ÊÓƵ Workfront to use functionality described in this article.

To find out what plan, license type, or access you have, contact your Workfront administrator.

For information on ÃÛ¶¹ÊÓƵ Workfront Fusion licenses, see ÃÛ¶¹ÊÓƵ Workfront Fusion licenses

Creating a connection for an OAuth request

General instructions for creating a connection in the HTTP > Make an OAuth 2.0 request module

  1. Create an OAuth client in the target service with which you want ÃÛ¶¹ÊÓƵ Workfront Fusion to communicate. This option is most likely found in the Developer section of the given service.

    1. When creating a client, enter the appropriate URL in the Redirect URL or Callback URL field:

      table 0-row-2 1-row-2
      Americas / APAC https://app.workfrontfusion.com/oauth/cb/oauth2
      EMEA https://app-eu.workfrontfusion.com/oauth/cb/oauth2

    2. After you create the client, the given service displays 2 keys: Client ID and Client Secret. Some services call these App Key and App Secret . Save the key and secret in a secure location, so you can provide them when creating the connection in Workfront Fusion.

  2. Find the Authorize URI and Token URI in the API documentation of the given service. These are URL addresses through which Workfront Fusion communicates with the target service. The addresses serve for OAuth authorization.

    note note
    NOTE
    If the service uses Implicit flow, you will need only the Authorize URI.
    note info
    INFO
    Example: Yahoo addresses:
    • Authorize URI:
    https://api.login.yahoo.com/oauth2/request_auth
    • Token URI:
    https://api.login.yahoo.com/oauth2/get_token

  3. (Conditional) If the target service uses scopes (access rights), check how the service separates individual scopes and make sure you set the separator in the advanced settings accordingly. If the separator is not set correctly, Workfront Fusion fails to create the connection, and you receive an invalid scope error.

  4. After you complete the steps above, you can start to create the OAuth connection in Workfront Fusion. Add the OAuth 2.0 HTTP(S) request and response processing module to your scenario.

  5. In the module’s Connection field, click Add.

  6. Fill in the following fields to create a connection:

    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 11-row-2 12-row-2 13-row-2 14-row-2 15-row-2 16-row-2 layout-auto html-authored no-header
    Connection name Enter the name of the connection.
    Flow type

    Select the flow for obtaining tokens.

    • Authorization Code: Enter the Authorize URI and Token URI from the service's API documentation.
    • Implicit: Enter the Authorize URI from the service's API documentation.
    Scope Add individual scopes. You can find this information in the given service's developer (API) documentation.
    Scope separator

    Select what the scopes entered above should be separated by. You can find this information in the given service's developer (API) documentation.

    Warning: If the separator is not set correctly, Workfront Fusion fails to create the connection and you receive an invalid scope error.
    Client ID Enter the Client ID. You obtained the Client ID when you created an OAuth client in the service you want to connect.
    Client Secret Enter the Client Secret. You obtained the Client Secret when you created an OAuth client in the service you want to connect.
    Authorize parameters

    Add any parameters that you want to include in the authorization call. The following standard parameters are always automatically included and do not need to be added.

    Standard parameters:

    • response_type

      code for Authorization Code flow and token for Implicit flow

    • redirect_uri

      table 0-row-2 1-row-2 layout-auto html-authored no-header
      Americas / APAC https://app.workfrontfusion.com/oauth/cb/oauth2
      EMEA https://app-eu.workfrontfusion.com/oauth/cb/oauth2

    • client_id

      The Client ID you received when creating the account
    Access token parameters

    Add any parameters that you want to include in the token call. The following standard parameters are always automatically included and do not need to be added.

    Standard parameters:

    • grant_type: authorization_code

    • redirect_uri:

      table 0-row-2 1-row-2 layout-auto html-authored no-header
      Americas / APAC https://app.workfrontfusion.com/oauth/cb/oauth2
      EMEA https://app-eu.workfrontfusion.com/oauth/cb/oauth2

    • client_id: The Client ID you received when creating the account is automatically included in the request body

    • client_secret: The Client Secret you received when creating the account is automatically included in the request body

    • code: The code returned by the authorization request

    Note:

    The OAuth 2.0 standard supports at least 2 methods of client authentication during this step (client_secret_basic and client_secret_post). Workfront Fusion automatically sends the specified client ID and secret through the client_secret_post method. Therefore, these parameters are included as part of the token request body automatically.

    For more information on OAuth 2.0 authentication, see .
    Refresh token parameters

    Add any parameters that you want to include in the token call. The following standard parameters are always automatically included and do not need to be added.

    Standard parameters:

    • grant_type: refresh_token

    • refresh_token: The most recent refresh token obtained by the service you are connecting to

    • client_id: The Client ID you received when creating the account is automatically included in the request body

    • client_secret: The Client Secret you received when creating the account is automatically included in the request body

    Note:

    The OAuth 2.0 standard supports at least 2 methods of client authentication during this step (client_secret_basic and client_secret_post). Workfront Fusion automatically sends the specified client ID and secret through the client_secret_post method. Therefore, these parameters are included as part of the token request body automatically.

    For more information on OAuth 2.0 authentication, see .
    Custom Headers

    Specify any additional keys and values to include in the header of Token and Refresh Token steps.

    Note:

    The OAuth 2.0 standard supports at least 2 methods of client authentication during this step (client_secret_basic and client_secret_post). Workfront Fusion does not automatically support the client_secret_basic method. If the service that you are connecting to expects the Client ID and Client Secret to be combined into a single string and then base64 encoded into the Authorization header, then you should add that header and key value here.

    For more information on OAuth 2.0 authentication, see .
    Token placement

    Select whether to send the token in the header, query string, or in both when connecting to the specified URL.

    Tokens are most commonly sent in the request header.
    Header token name Enter the name of the authorization token in the header. Default: Bearer.
    Query string parameter name Enter the name of the authorization token in the query string. Default: access_token.

  7. Click Continue to save connection settings.

  8. Continue to OAuth 2.0 request module setup.

Instructions for creating a connection to Google in the HTTP >Make an OAuth 2.0 request module

The following example shows how to use the HTTP > Make an OAuth 2.0 request module to connect to Google.

  1. Ensure that you have created a project, configured OAuth settings, and generated your credentials as described in Connect ÃÛ¶¹ÊÓƵ Workfront Fusion to Google Services using a custom OAuth client.

  2. Open the HTTP >Make an OAuth 2.0 request module.

  3. Click Add next to the connection box.

  4. Enter the following values:

    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 layout-auto html-authored no-header
    Connection name Enter the name of the connection.
    Flow type Authorization Code
    Authorize URI https://accounts.google.com/o/oauth2/v2/auth
    Token URI https://www.googleapis.com/oauth2/v4/token
    Scope Add individual scopes. For more information on scopes, see in the Google documentation.
    Scope separator SPACE
    Client ID

    Enter your Google Client ID.

    To create a client ID, see Create OAuth Credentials in Connect ÃÛ¶¹ÊÓƵ Workfront Fusion to Google Services using a custom OAuth client.
    Client Secret

    Enter your Google Client Secret.

    To create a client secret, see Create OAuth Credentials in Connect ÃÛ¶¹ÊÓƵ Workfront Fusion to Google Services using a custom OAuth client.
    Authorize parameters

    Add access_type - offline key-value pair.

    Note: If you experience authentication issues, for example with token refreshing, try adding the prompt - consent key-value pair.

  5. Click Continue to save connection settings.

  6. Continue to OAuth 2.0 request module setup.

Instructions for connecting to Microsoft Graph API via the HTTP > Make an OAuth 2.0 request module

For instructions regarding Microsoft Graph API, see Call the MS Graph REST API via the ÃÛ¶¹ÊÓƵ Workfront Fusion HTTP > Make an OAuth 2.0 request module.

OAuth 2.0 request module setup

When you have established an Oauth 2.0 connection as described in Creating a connection for an OAuth request, continue setting up the module as desired. All authorization tokens are automatically included in this request, and in any other request that uses the same connection.

When you configure the HTTP >Make an OAuth 2.0 request module, Workfront Fusion displays the fields listed below. A bolded title in a module indicates a required field.

If you see the map button above a field or function, you can use it to set variables and functions for that field. For more information, see Map information from one module to another in ÃÛ¶¹ÊÓƵ Workfront Fusion.

Connection
For information on setting up a connection, see Creating a connection for an OAuth request in this article.
Evaluate all states as errors (except for 2xx and 3xx)

Use this option to set up error handling.

For more information, see Error handling in ÃÛ¶¹ÊÓƵ Workfront Fusion.

URL
Enter the URL you want to send a request to, such as an API endpoint, website, etc.
Method
Select the HTTP request method you need to configure the API call. For more information, see HTTP request methods in ÃÛ¶¹ÊÓƵ Workfront Fusion.
Headers
Add the headers of the request in the form of a standard JSON object. For example, {"Content-type":"application/json"}
Query String
Enter the desired query key-value pairs.
Body type

The HTTP Body is the data bytes transmitted in an HTTP transaction message immediately following the headers if there are any to be used.

  • Raw

    The Raw body type is generally suitable for most HTTP body requests even in situations where developer documentation does not specify data to send.

    Specify a form of parsing the data in the Content type field.

    Despite the content type selected, data is entered in any format that is stipulated or required by the developer documentation.

  • Application/x-www-form-urlencoded

    This body type is to POST data using application/x-www-form-urlencoded.

    For application/x-www-form-urlencoded, the body of the HTTP message sent to the server is essentially one query string. The keys and values are encoded in key-value pairs separated by & and with an = between the key and the value.

    For binary data, use multipart/form-data instead.

    Example:

    Example of the resulting HTTP request format:

    field1=value1&field2=value2

  • Multipart/form-data

    The Multipart/form-data is an HTTP multipart request used to send files and data. It is commonly used to upload files to the server.

    Add fields to be sent in the request. Each field must contain a key-value pair.

    • Text

      Enter the key and value to be sent within the request body.

    • File

      Enter the key and specify the source file you want to send in the request body.

      Map the file you want to upload from the previous module (such as HTTP >Get a File or Google Drive >Download a File), or enter the file name and file data manually.

Parse response

Enable this option to automatically parse responses and convert JSON and XML responses so you don't need to use JSON > Parse JSON or XML > Parse XML modules.

Before you can use parsed JSON or XML content, run the module once manually so that the module can recognize the response content and allow you to map it in subsequent modules.

Timeout
Enter the request timeout in seconds (1-300). The default is 40 seconds.
Share cookies with other HTTP modules
Enable this option to share cookies from the server with all HTTP modules in your scenario.
Self-signed certificate
Upload your certificate if you want to use TLS using your self-signed certificate.
Reject connections that are using unverified (self-signed) certificates
Enable this option to reject connections that are using unverified TLS certificates.
Follow redirect
Enable this option to follow the URL redirects with 3xx responses.
Follow all redirects
Enable this option to follow the URL redirects with all response codes.
Disable serialization of multiple same query string keys as arrays
By default, Workfront Fusion handles multiple values for the same URL query string parameter key as arrays. For example, www.test.com?foo=bar&foo=baz will be converted to www.test.com?foo[0]=bar&foo[1]=baz. Activate this option to disable this feature.
Request compressed content

Enable this option to request a compressed version of the website.

This adds an Accept-Encoding header to request compressed content.

Use Mutual TLS

Enable this option to use Mutual TLS in the HTTP request.

For more information on Mutual TLS, see Use Mutual TLS in HTTP modules in ÃÛ¶¹ÊÓƵ Workfront Fusion.

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