Setting Up an OAuth Connected System

Introduction

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.

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.

Setup 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.

images:oauth_registration_third_party.png

Because you will need to enter values both in Appian and the third-party system, it's a good idea to keep the third-party's application settings open in another tab or window while configuring the connected 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, then choose Connected System from the dropdown menu

    images:connectedSystem:new_menu_connected_system.png

  3. Give the Connected System a name, description, and a logo

    images:setting_up_oauth_step_3.png

Configure OAuth

The Authentication dropdown has the option OAuth 2.0: Authorization Code. Select this option to reveal the OAuth configuration box. The Authorization Code grant requires that you enter values both Appian and the other system in order to implement successfully.

/authorization code connected system

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 the 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 the 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 pop-up should appear from the other system images:oath_section_of _connected_system.png
  2. Approve the authorization
  3. In the Connected System, verify that you've completed authorization by clicking Done Authorizing images:oath_section_of _connected_system2.png
  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.

If you are testing the integration as the same user to test the authorization, you will already have authorized the connection (this testing can also occur from the integration. If you're using a different user account, than you'll need to authorize before the integration will return a token and data.

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. Setup the necessary Integration's parameters as directed by the third party documentation. images:setting_up_oauth_integration.png

Because access tokens are per user, Designers 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, Designers must use an a!authorizationLink().

images:auth_link_read.png

  1. Create an interface that will generate the authorization link and any needed amplifying information to alert the user of the access issue.
    • This 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.
  4. 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.

It's important to note that write-based errors that warrant authorization links have a much lower likelihood of occurring. Because interfaces that write data to another system typically query data as well, the initial integration call would pick up the authorization issue first. However, it's still useful to create write-based authorization link to ensure the data submitted by the user makes it to the other system.

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.

Depending on the reason for the missing pop-up, the Connected System will return the error in a red message box. These error boxes contain useful information about the cause of the error.

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.

FEEDBACK