Configure outbound applications with OAuth 2.0 authorization code grants

Outbound applications provide a way for administrators to manage OAuth 2.0 connections to external systems from workflows built in Foundry. Outbound applications are managed at the Organization level in Control Panel.

An outbound application represents a bundle of configurations required for Foundry to behave as an OAuth 2.0 client. The application makes requests to another system that can behave as an OAuth 2.0 server.

Outbound applications in Foundry only support the OAuth 2.0 authorization code grant ↗ type.
To set up an OAuth 2.0 client credentials grant, follow these resources to manually establish the handshake process within a webhook.

Create an outbound application

To create an outbound application, first navigate to the Outbound applications in Control Panel, under Organization settings. If you have access to multiple Organizations, be sure to select the Organization in which you wish to create your outbound application. All users of this Organization with permission to set up sources in Data Connection will be able to select any outbound application as an authorization mechanism for their connection.

To view the Outbound applications page, you need access to the "Manage outbound applications" workflow, which is granted by default to the Organization administrator role in Control Panel.

Learn more about configuring roles.

Select New application and provide the required inputs to set up your outbound application. Detailed configuration options are listed below.

Configuration options

The following configuration options apply to both cloud-based and on-premise OAuth 2.0 servers.

Configuration options for direct cloud connections

We recommend using a direct connection when setting up an outbound connection if the OAuth 2.0 server is reachable over the Internet.

Configuration options for on-premise OAuth servers

On-premise configuration should only be used if the OAuth server is inside a private network and cannot be reached through a direct Internet connection.

Connect to an OAuth 2.0 server inside a private network

Because some OAuth 2.0 servers are not exposed to the open Internet, OAuth 2.0 handshake requests must be routed through a custom REST API source using an agent worker runtime to connect to the server. This method requires you to write your own requests that will be used to perform the OAuth 2.0 handshake.

The first step is to create a REST API source that can connect to your OAuth2 server. For example, you might configure your source with a domain and client secret:

Next, you need to create a webhook on that REST API source that can call the /token endpoint of the OAuth 2.0 server. You can optionally create a second webhook that can refresh the token.

The example below shows an example of an OAuth 2.0 handshake request to a hypothetical OAuth 2.0 server using cURL:

curl -XPOST 'https://<oauth-server>/token'
    -H 'Content-Type: application/json'
    -d '{"client_id":"8b3df622e71449519cd9b0160b9e39f7", \
         "client_secret":"04011f337b984df0ad8c58a50f9e91f5", \
         "code":"a8ec5e83728e480fa6bfda4eb8e122a3"}'

An example response could look like following:

{ "access_token":"1846149cf5774c3d8eaeb18b75f7178d",
  "refresh_token": "1846149cf5774c3d8eaeb18b75f7178d",
  "token_type":"bearer",
  "scope":"<comma-delimited-set-of-scopes>",
  "expires_in": "3600" }

As another example, a typical refresh request could look like the following:

curl -XPOST 'https://<oauth-server>/refresh_token'
    -H 'Content-Type: application/json'
    -d '{"client_id":"8b3df622e71449519cd9b0160b9e39f7", \
         "client_secret":"04011f337b984df0ad8c58a50f9e91f5", \
         "refresh_token":"a8ec5e83728e480fa6bfda4eb8e122a3"}'

The response would be identical to the handshake response above:

{ "access_token":"1846149cf5774c3d8eaeb18b75f7178d",
  "refresh_token": "1846149cf5774c3d8eaeb18b75f7178d",
  "token_type":"bearer",
  "scope":"session",
  "expires_in": "3600" }

Use the instructions in the next section to create the token and refresh token webhooks you will need to implement an OAuth 2.0 handshake in Foundry.

Token webhook

The token webhook should implement a request to the /token endpoint on the OAuth 2.0 server to fetch a valid token given a client_id, redirect_uri, and authorization_code. The token webhook must have the input and output parameters listed below. Learn more about webhook parameters.

Below is an example request configuration showing a standard OAuth 2.0 server token request:

You must also set grant_type=authorization_code as one of the entries in the webhook form body. Review the documentation for your OAuth 2.0 server for additional required configurations.

Refresh token webhook

After creating the token webhook, you must create a second webhook for the refresh token flow using the input and output parameters listed below. The webhook should implement a request to the /token endpoint to fetch a new token given a refresh_token and client_id.

Below is an example request configuration showing a standard OAuth 2.0 server refresh request:

You must also set grant_type=refresh_token as one of the entries in the webhook form body. Review the documentation for your OAuth 2.0 server for additional required configurations.

The available output parameters are the same as the parameters for the token webhook.

Manage outbound applications

Once you create an outbound application, it will be available to all users in that Organization to use as the authorization method for a REST API source in Data Connection. The following options are available for administrators with permisssions to manage outbound applications.

Delete an outbound application

Deleting an outbound application will permanently remove stored tokens and refresh tokens for all users who have authorized the application. The application configuration, including the client secret, will also be permanently deleted. This action cannot be reversed.

Reset an outbound application

Resetting an outbound application will permanently remove stored tokens and refresh tokens for all users who have authorized the application. This effectively returns the application to the state just after initial setup when no user has yet completed the interactive authorization flow. The next time a user attempts to perform a workflow that requires a token from this outbound application, they will be prompted to complete the authorization flow again.

Enable an outbound application

Enabling an outbound application means that users may perform the interactive authorization flow to this external system. Disabling an application will prevent any previously stored tokens and refresh tokens from being used. However, these tokens will not be deleted and may be used again after the application has been re-enabled.

New users who have not previously authorized the application will not be able to perform the interactive authorization flow while the outbound application is disabled.

Newly created applications will be enabled by default and may only be disabled after being created.

Use outbound applications in Data Connection

Once an outbound application is created and enabled, it may be used as the authentication method for a domain in a REST API source. When configuring a domain, select OAuth 2.0 and then select the desired outbound application from the dropdown.

Any webhooks using a domain with OAuth 2.0 configured will result in an interactive prompt for each user the first time they attempt to run it. Webhooks are most often invoked through Actions from Workshop; in this case, when running an Action in Workshop, the user will see a pop-up window showing the authentication page of the OAuth 2.0 server, prompting them to authorize Foundry to interact with this system on their behalf.

If a token refresh workflow is configured, users are unlikely to see this prompt again unless the authorization is revoked in the external system or the outbound application is reset. If no refresh workflow is configured, the end user will see the authentication pop-up anytime the resulting token expires. Tokens often expire within minutes or hours, and we encourage use of the refresh flow for a better user experience.