Overview

In this article, you will learn how to set up a connected system with the OAuth 2.0 Authorization Code grant. Additionally, you will learn how to use the connected system in an Integration. Finally, you will see how to create an interface to give individual users a link to authorize the connection.

• To learn about connected systems and their configuration options, see Connected System Object.
• To learn more about the Authorization Code Grant, see OAuth 2.0: Authorization Code Grant

Because configuring OAuth differs so much between systems and scenarios, this article only discusses the setup at a high-level. Use this information as a general guide rather than specific steps to complete a particular solution.

Set up the third-party app

Appian is the OAuth client in this scenario, which means that it needs to obtain client credentials from the resource's authorization server. Typically, this requires registration with the third-party system though an application or project built within the third-party system. Refer to the third-party's documentation for guidance on OAuth registration for their system.

Create the connected system

Once you have set up the necessary pieces in the other system, it's now time to create the connected system.

Basic setup

1. Open the destination application for the new connected system.
2. Click New > Connected System, then select HTTP.
3. Give the Connected System a name, description, and a logo.
4. For Authentication, select OAuth 2.0: Authorization Code Grant. The Configure Authorization box appears.

Configure OAuth

The Authorization Code grant requires that you enter values both Appian and the other system in order to implement successfully.

In the other system

1. From the connected system, copy the redirect URI provided in the configuration box and add it to the other system.
   • This can also referred to as the callback url.
2. In the other system, note the Client ID and Client Secret values.

In the connected system

1. Enter the other system's Client ID and Client Secret into the appropriate fields.
2. Locate the Authorization endpoint for the other system and enter it into the Authorization Endpoint field.
   • The authorization endpoint can be found in the other system's API documentation.
3. Locate the Token Endpoint for the other system and enter it into the Token Request Endpoint field.
   • The token request endpoint can be found in the other system's API documentation.

Test the connection

Before a user can get data from an integration that authenticates with the Authorization Code grant, they must first authorize the connection. Before creating the connected system, you should verify that the configuration is valid and will enable a user to authorize the connection.

1. Click Authorize. A new dialog should appear from the other system.

   

2. Approve the authorization.

3. In the connected system, verify that you've completed authorization by clicking Done Authorizing.

   

4. Click Save to create the connected system.

If the connection fails verify the settings entered in either system and try again. See the troubleshooting section below for more details.

Use the connected system in an integration

Once the connected system is configured, it can be used in an integration.

Using an OAuth connected system is no different than calling any other connected system in an integration.

1. In the integration object, select Use an existing connected system.
2. Choose your connected system in the Connected System field.
3. Set up the necessary integration's parameters as directed by the third party documentation.

Create an authorization link on an interface

Because access tokens are per user, you need to consider how users will grant access to a protected resource.

Any user needs to grant Appian access to the other system so that Appian can obtain an access token. To achieve this, use an a!authorizationLink().

1. Create an interface that will generate the authorization link and any needed amplifying information to alert the user of the access issue.
   • This interface will act as a reusable object for any relevant integrations.
2. Add an Rule Input with a data type of Any Type to pass in the HTTP response.
3. Enter an interface expression that will show the authorization link.

This interface can be conditionally shown on any integrations that query data from another system. This will provide users that need to authorize access a method to get to the other system's authorization UI.

Troubleshooting

If for some reason your connection is not working, you'll need to take corrective action. This section offers some general guidelines when trying to determine the cause of the failed connection. It is not meant to be a comprehensive list of all possible error scenarios. Be sure to read the error messages from the connected system and integrations, as the often provide specific details about the issue and suggestive corrective action.

Missing authorization page from other system

If the Authorization Endpoint or Scope is misconfigured in the connected system, it can impact the ability to make a successful connection to the authorization server. Users may see no pop-up or a 401 error from the other system.

Verify that the appropriate values are entered in the connected system.

Other system's authorization page appears but can't grant permission

If the Client Secret is not entered properly, the other system will not know what resources should be authorized. Typically, this is seen in the other system's authorization pop-up as an error message.

In addition to the client secret the callback url could have been incorrectly entered in the other system. Ensure the callback url entered in the other system matches what was provided by the connected system.

Integration using the connected system with authorization code is getting an error

If the user has not previously authorized the resource, the Integration will throw an error until the user has allowed the data to be requested.

Additionally, if the Token Request Endpoint or the Client Secret is not configured correctly, the authorization server cannot return a valid token to the client. Verify that this endpoint's value has been properly entered.