App Registrations page in Jitterbit Management Console

Introduction

The App Registrations page lets Harmony organization administrators register third-party 3-legged OAuth 2.0 (3LO) applications for use with certain Integration Studio connectors. Once the third-party 3LO application is registered in the App Registrations page, you can authenticate a connection using 3-legged OAuth 2.0.

For more information on authenticating a connection with 3LO, see 3LO authentication.

Note

If you are using a cloud (Jitterbit-provided) application, an app registration is not needed to configure a connection.

On the App Registrations page, organization administrators can register private applications with 3LO-enabled connectors, set the details of the OAuth provider, and define the behavior of the refresh tokens. To open it, select Management Console > Customizations > App Registrations from the Harmony portal menu:

You can view, create, edit, or delete registrations, and view and edit advanced options for a registration. A connector can be registered multiple times. Each is considered a unique connector app.

View

With no registrations, the body of the page contains a toolbar and an empty table:

With registrations, the body of the page contains a toolbar and a table listing available registrations:

• Search: Enter text to find matching entries.

• Create New: Create a new registration.

• Actions: Hover on a row to reveal the actions icons:

  • Advanced options: Show advanced options for the registration.

  • Edit: Edit the registration.

  • Delete: Delete the registration.

Click on any column heading (except Actions) to sort the table in ascending order by that column. Click again to reverse the sort order.

Create

To create a new connector app registration, follow these steps:

1. Click Create New. A new row appears in the table:

   

2. Set values for the following fields:

   In the Create new app registration section:

   • Name: A name for the registration that is unique for the connector.

   • Description: A description for the registration.

   • Connector: Click to open the menu, then select one of the supported connectors. Currently, these connectors support 3LO:

     • BMC Helix ITSM
     • HTTP v2
     • Jira
     • Slack

   • Client ID: The client identifier assigned by the OAuth provider.

   • Client Secret: The client secret assigned by the OAuth provider.

   • Scope: One or more space-separated OAuth 2.0 scopes.

   In the Configuration section:

   • Authentication URL: The URL to send an authorization request to.

   • Access token URL: The URL to send an access token request to.

   • Refresh token URL: The URL to request a new access token.

3. Click Save to save the values, or Cancel to cancel:

   

4. When successfully saved, the registration appears as a new entry in the table:

   

Edit

To edit a registration, follow these steps:

1. Hover on a registration in the table to reveal the actions icons, then click Edit. The Edit app registration pane appears:

   

2. In the Edit app registration pane, edit the fields, then click Save to save the changes, or Cancel to cancel.

   Note

   A registration's Connector cannot be changed from its initial value.

3. Read the notification message that appears in the top-right part of the window. To close the notification, click the Close icon.

Delete

To delete a registration, follow these steps:

1. Hover on a registration in the table to reveal the actions icons, then click Delete.

2. A Delete App Registration dialog opens:

   

3. Enter the text DELETE then click Delete, or click Cancel to cancel the action.

Advanced options

The Advanced options drawer contains the default settings provided by the OAuth provider for each registration's token, and for the authentication, token, and refresh requests.

To open it, hover on a registration in the table, then click Advanced options. The drawer appears at the bottom of the page:

The drawer contains these tabs:

• Token policy

• Authentication request

• Token request

• Refresh request

Tip

If a tab has invalid settings, the Save button becomes inactive, and an error symbol appears beside the tab's label.

Token policy

The Token policy tab contains settings for the token:

Important

Enable Token policy tab settings only if they are also enabled in the OAuth provider.

The following settings are available:

• Enable refresh token expiration: When toggled on and used in combination with a connection's Receive Expiration Notification and Days for Expiration Notification settings, you will receive email notifications and a notification banner throughout the Harmony portal reminding you to obtain a new refresh token when the current one is expired or is approaching expiration. When a refresh token expires, all dependent operations will fail at runtime.

  When this setting is enabled, the email notification is sent to the Harmony organization administrators (members of a role with the Admin permission, and the user who last deployed the project).

  To set the expiration period, enter a whole number greater than zero, then click the menu and select one of Seconds, Hours, or Days:

  

  Tip

  The recommended setting for this value should match that used in the OAuth provider itself. For example, if an OAuth provider's refresh token expiration is 1 year, set the Expire after value to 1 year.

• Enable refresh token inactivity expiration: When toggled on, refresh tokens that have been inactive for the specified amount of time are marked as expired in the Harmony platform. Use the Expire after field to specify the interval after which an inactive refresh token is marked as expired.

  Important

  Use this setting in alignment with the OAuth provider's inactivity setting. Enabling this setting when the OAuth provider does not have an inactivity setting defined will cause valid refresh tokens to be incorrectly considered to be expired in the Harmony platform. Conversely, if the OAuth provider does have this setting defined, but it is not enabled and specified here in the Harmony portal, the endpoint might use a stale refresh token, potentially causing issues based on the OAuth provider's refresh token rules.

  • Expire after: To set the expiration period, enter a whole number greater than zero, then click the menu and select one of Seconds, Hours, or Days:

    

  Tip

  The recommended setting for this value should match that used in the OAuth provider itself. For example, if an OAuth provider's refresh token inactivity expiration is 90 days, set the Expire after value to 90 days.

• Enable rotating refresh token: Click to enable token rotation:

  

Click Save to save changes, or Cancel to abandon them.

Authentication request

The Authentication request tab contains settings for the token authentication request:

• Authentication URL: The URL to send an authorization request to.

• Parameters: To add parameters for the request, follow these steps:

  1. Enter values for Key and Value.

  2. To choose the method for sending parameters, click the Send in menu, then select one of Request URL or Request Header.

  3. Click Add. The parameter appears as new row in the table.

  4. Repeat the three previous steps for all parameters.

Click Save to save changes, or Cancel to abandon them.

Token request

The Token request tab contains settings for the token request:

• Access token URL: The URL to send an access token request to.

• Parameters: To add parameters for the request, follow these steps:

  1. Enter values for Key and Value.

  2. To choose the method for sending parameters, click the Send in menu, then select one of Request URL, Request Header, or Request Body.

  3. Click Add. The parameter appears as new row in the table.

  4. Repeat the three previous steps for all parameters.

Click Save to save changes, or Cancel to abandon them.

Refresh request

The Refresh request tab contains settings for the token refresh request:

• Refresh token URL: The URL to request a new access token.

• Parameters: To add parameters for the request, follow these steps:

  1. Enter values for Key and Value.

  2. To choose the method for sending parameters, click the Send in menu, then select one of Request URL, Request Header, or Request Body.

  3. Click Add. The parameter appears as new row in the table.

  4. Repeat the three previous steps for all parameters.

Click Save to save changes, or Cancel to abandon them.