Skip to Content

App Registrations

Introduction

The App Registrations page lets Harmony organization administrators register third-party 3-legged OAuth 2.0 (3LO) applications for use with certain Cloud 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:

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:

Empty page

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

Added page

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:

    create

  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, the Jira connector supports 3LO.

    • 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:

    create

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

    saved

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:

    edit

  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:

    delete

  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:

Advanced options

The drawer contains these tabs:

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:

Token policy

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: Click to enable expiration of the refresh token generated on this page. When used in combination with a connection's Receive Expiration Notification setting, the value configured in the connection's corresponding Days for Expiration Notification field is used to notify you the configured number of days prior to the refresh token expiration configured here. If enabled, you are notified, with an application banner and email, when tokens are due to expire, or if they have already expired. Both forms of notification tell you what to do in each case.

    When this setting is enabled, the email notification is sent to the Harmony organization administrators (members of a role with the Admin organization 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:

    Refresh token expiration

    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: Click to enable token inactivity expiry. To set the expiration period, enter a whole number greater than zero, then click the menu and select one of Seconds, Hours, or Days:

    Refresh token inactivity expiration

    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:

    Rotating refresh token

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

Authentication request

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

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:

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