OAuth 2.0 Auth Module

An OAuth 2.0 authentication module lets users log in to Hub and any connected services with credentials that are stored in an external authorization service. Hub provides pre-configured authentication modules for Amazon, Azure AD 2.0, Bitbucket Cloud, Facebook, GitLab, Microsoft Live, PayPal, and Yandex Passport.

Use the generic OAuth 2.0 authentication module to let users log in to Hub with accounts from other third-party services that support OAuth 2.0, like Basecamp, Stack Exchange, and Zendesk.

When you enable an OAuth 2.0 authentication module in Hub:

Your users log in to Hub with the credentials they use in an external service.
Your Hub users have fewer accounts and passwords to remember.
New users with accounts in the connected service can create their own accounts in Hub.

Enable OAuth 2.0 Authentication

To allow users with existing accounts in an external authorization service to log in to Hub, enable an OAuth 2.0 authentication module.

This procedure takes place in three steps:

Generate a Redirect URI in Hub. When you create an authentication module, Hub generates a redirect URI to use with the authorization service. This URI identifies the source of each login request.
Generate a Client ID and Secret in the authorization service. Every login request sent from Hub includes a unique identifier. The ID and secret you store in the authentication module tell the authorization service that each login request is authorized.
Enable the Auth Module in Hub. When you have generated the information Hub uses to authenticate with the authorization service, copy the values into Hub and enable the module.

Generate a Redirect URI in Hub

When you create an OAuth 2.0 authentication module, Hub generates a redirect URI to use with the authorization service. If you want to create an Azure AD 2.0 module for an application inside a custom tenant, you need to provide the directory ID of the custom tenant upon creation. In this case, skip directly to Generate a Client ID and Secret in the Authorization Service and follow the instructions for the Azure AD 2.0 (custom tenant) setup.

In the Access Management section of the Administration menu, select Auth Modules.
From the New Module drop-down list, select one of the pre-configured OAuth 2.0 authentication modules, for example, Facebook. To connect another third-party authorization service, select OAuth 2.0, enter the Name and Authorization URL in the sidebar, then click the Create button.
- The Auth Modules page displays the settings for a new OAuth 2.0 authentication module.
- Hub generates a redirect URI for you to use in the authorization service.
If the feature is supported by your browser, use the Copy button to copy the redirect URI to your clipboard.

Generate a Client ID and Secret in the Authorization Service

The next step is to register the authorized redirect URI for Hub in the authorization service. This process varies by service. The instructions in the following table describe how to register Hub as an application for pre-configured OAuth 2.0 authorization services. The procedures for other third-party authorization services are similar.

Authorization Service	Setup Instructions
Amazon	Access Login with Amazon. From the Applications menu, click the Register new application button. Fill in the Application Information form and click the Save button. Expand the Web Settings section and click the Edit button. Paste the redirect URI from Hub into the Allowed Return URLs input field and click the Save button. Use the values that are stored as the Client ID and Client Secret to enable the authentication module in Hub.
Azure AD 2.0 (common tenant)	Access the Microsoft Application Console. You can also access this page from the current version of the Microsoft Azure Portal (select App registrations in the Manage section of the Azure Active Directory menu, then click the Microsoft Application Console link). On the My applications page, click the Add an app button. Enter a name and click the Create button. Copy the value that is stored as the Application Id in the Properties section of the app registration page and paste it into the Client ID input field in the Hub auth module. In the Application Secrets section of the app registration page, click the Generate New Password button. Copy the generated value and paste it into the Client secret input field in the Hub auth module. Click the Save button in the Hub auth module. In the Platforms section of the app registration page, click the Add Platform button and select the Web option from the dialog. Paste the redirect URI from the Hub auth module into the Redirect URLs input field and click the Save button. In the Microsoft Graph Permissions section of the registration page, verify that the `User.Read` permission is included in the Delegated Permissions list. If not, click the Add button and select this permission from the list in the Select Permission dialog. Click the Save button at the bottom of the app registration page.
Azure AD 2.0 (custom tenant)	Access the Microsoft Azure Portal and create a directory. In the sidebar, select Azure Active Directory. In the Manage section of the Azure Active Directory menu, select Properties. Copy the value that is stored as the Directory ID and paste it into the Tenant input field in the New Azure AD 2.0 Module dialog in Hub, then click the Create button. In the Manage section of the Azure Active Directory menu, select App registrations. Click the New application registration button in the header. Enter a name for the application in the Name field. For the Application type, leave Web app / API. For the Sign-on URL, enter the base URL of your Hub installation. Click the Create button. Copy the Application ID and paste it into the Client ID input field in the Hub auth module. Click the Settings button in the toolbar, then select Keys in the API Access section of the Settings menu. Generate a password in the Keys blade: In the Description field, enter an arbitrary value. Select a duration from the Expires drop-down list. Click the Save button in the header. Copy the key value and paste it into the Client secret input field in the Hub auth module, then click the Save button. In the General section of the Settings menu, select Reply URLs. Delete the base URL for your Hub installation. Copy the Redirect URI from the Hub auth module, paste it into the input field on the Reply URLs blade, then click the Save button in the header.
Bitbucket Cloud	Log in to your Bitbucket instance, and access the Bitbucket Settings administrative section. Select OAuth in the left navigation sidebar. Then, click the Add consumer button. In the displayed form, provide a name for your Hub service in Bitbucket and optional description. In the Callback URL field copy the generated URL from the Redirect URI field in Hub. In the Permissions options, select Email and Read check boxes in the Account section. Click Save to generate the Client ID and Secret of your Bitbucket Cloud instance.
Facebook	Access the Facebook for Developers service. Click the Add a new app button. Fill in the Create a New App ID form and click the Create App ID button. From the Products menu, select Add Product and choose Facebook Login. Paste the redirect URI from Hub into the Valid OAuth redirect URIs input field and click the Save Changes button. Open the Settings page and use the values that are stored as the App ID and App Secret to enable the authentication module in Hub.
GitLab	Log in to your GitLab instance, and access the Applications administrative section. In the Add new application form, enter a name for the Hub service, and copy the generated redirect URL to the Redirect URI field. In the Scopes options, select api and read_user options. Click Save application to generate the Client ID and Secret of your GitLab instance.
Microsoft Live	Access the Microsoft Application Registration Portal. On the My applications page, click the Add an app button. Enter a name and click the Create application button. In the Platforms section, click the Add Platform button and select the Web option. Paste the redirect URI from Hub into the Redirect URIs input field and click the Save button. Use the value that is stored as the Application Id for the Client ID setting in Hub. Use the Generate New Password option to generate a value for the Client secret setting in Hub.
PayPal	Access the PayPal Developer service. Open the Dashboard and select My Apps & Credentials. In the REST API apps section, click the Create app button. Fill in the Application Details form and click the Create App button. In the App Settings section, click Show to display the Return URL input field. Paste the redirect URI from Hub into the Return URL input field and click the Save button. Use the values that are stored as the Client ID and Secret to enable the authentication module in Hub.
Yandex Passport	Access Yandex OAuth. Click the Create new client button. Fill in the New Client form. In the Scopes section, select Yandex.Passport API, then enable the Access to email address, Access to user avatar, and Access to username, first name and surname, gender options. Expand the Web Settings section and click the Edit button. Paste the redirect URI from Hub into the Callback URL input field and click the Submit button. Use the values that are stored as the ID and Password to enable the authentication module in Hub.

Enable the Auth Module in Hub

Copy the client ID from the authorization service and paste it into the Client ID input field in Hub.
Copy the client secret from the authorization service and paste it into the Client secret input field in Hub.
Configure the optional settings for the authentication module. For more information, see Additional Settings.
Click the Enable module button.
- The OAuth 2.0 authentication module is enabled.
- The icon stored in the Button image setting is added to the login dialog window. Users can click this icon to log in to Hub with an account from the connected authorization service.

Settings

The first section of the settings page displays the general settings for the authentication module. Here, you also find the redirect URI that you use to register Hub in the authorization service and the input fields that store the Client ID and Client Secret that are generated in the authorization service.

Setting	Description
Type	Displays the type of authorization service that is enabled for third-party authentication in Hub.
Name	Stores the name of the authentication module. Use this setting to distinguish this module from other authentication modules in the Auth Modules list. The name is also shown in the tooltip for the third-party service icon on the login form.
Button image	Displays the image used for the button that a user clicks to log in to Hub with a their account in the connected authorization service. You can upload a JPG, GIF or PNG file. The image is resized to 48 x 48 pixels automatically.
Redirect URI	Displays the authorized redirect URI that is used to register the connection to Hub in the authorization service.
Client ID	Stores the identifier that the authorization service uses to validate a login request. You generate this value in the authorization service when you configure the authorization settings for a web application and enter an authorized redirect URI.
Client Secret	Stores the secret or password used to validate the client ID. You generate this value in the authorization service together with the client ID.

Authorization Service Endpoints

The settings in this section of the page store the OAuth 2.0 endpoints used by the authorization service. Additional settings let you define the request scope, and choose how to authenticate with the service.

For pre-configured OAuth 2.0 modules, the values that are used by the selected authorization service are set automatically.

Setting	Description
Authorization	Stores the endpoint that Hub uses to obtain authorization from the resource owner via user-agent redirection.
Token	Stores the endpoint that Hub uses to exchange an authorization grant for an access token.
User data	Stores the endpoint used to locate profile data for the authenticated user.
Email	The endpoint used to locate the email address of the authenticated user Use only when the email address is not stored in the user profile
Default email verification state	Determines which state should be set for an email address in Hub, when the authentication service does not return the verification status for an email address.

Field Mapping

When a user profile response object is returned by the authorization service, values from the specified field paths are copied to the user profile in Hub. Use the following settings to define the endpoint that locates profile data for the authenticated user and map fields that are stored in the authorization service to user accounts in Hub.

For pre-configured OAuth 2.0 modules, the values that are used by the selected authorization service are set automatically.

Use a sequence of path segments separated by slashes (/) to specify a path to a field inside a nested object.

Field	Description
User ID	Maps to the field that stores the value to copy to the User ID property in Hub.
Email	Maps to the field that stores the value to copy to the Email field in the Hub profile.
Verified email	Maps to the field that stores the value to copy to the verified email property in Hub.
Full name	Maps to the field that stores the value to copy to the Full name field in the Hub profile.
Avatar	Maps to the field that stores the image to use as the Avatar in the Hub profile.
Image URL pattern	Generates an image URL for avatars that are referenced by an ID. Use the <picture-id> placeholder to reference the field that stores the avatar.
Scope	Sets the scope for the access request. Enter a list of scopes, separated by spaces.
Authentication	Determines how credentials are passed to the authorization service.

Additional Settings

The following options are located at the bottom of the page. Use these settings to manage Hub account creation and group membership, and to reduce the loss of processing resources consumed by idle connections.

Option	Description
User creation	Enables creation of Hub accounts for unregistered users who log in with an account that is stored in the connected authorization service. Hub uses the email address to determine whether the user has an existing account.
Auto-join groups	Adds users to a group when they log in with an account that is stored in the connected authorization service. You can select one or more groups. New users that auto-join a group inherit all of the permissions assigned to this group. We recommend that you add users to at least one group. Otherwise, a new user is only granted the permissions that are currently assigned to the All Users group.
Connection timeout	Sets the period of time to wait to establish a connection to the authorization service. The default setting is 5000 milliseconds (5 seconds).
Read timeout	Sets the period of time to wait to read and retrieve user profile data from the authorization service. The default setting is 5000 milliseconds (5 seconds).
Audit	Links to the Audit Events page in Hub. There, you can view a list of changes that were applied to this authentication module.

Last modified: 27 September 2018