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.

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

   

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

Token policy¶

The Token policy tab contains settings for the token:

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

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

  

  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.