GitHub Auth Module

Last modified: 23 September 2024

This authentication module lets users log in to Hub with their GitHub credentials.

Enable GitHub Authentication

To allow users with existing GitHub accounts to log in to Hub, enable the GitHub authentication module.

This procedure is performed by following these steps:

  1. Generate a Callback URL in Hub. When you create an authentication module for GitHub, Hub generates a callback URL to use with this service. This URL identifies the source of each login request to GitHub.

  2. Generate a Client ID and Secret in GitHub. Every login request sent from Hub to GitHub includes a unique identifier. The ID and secret you store in the authentication module tell GitHub that each login request is authorized.

  3. Enable the Auth Module in Hub. When you have generated the information Hub uses to authenticate with GitHub, copy the values into Hub and enable the module.

  4. Authorize the GitHub OAuth Application. This grants the OAuth application access to read the information it needs to authenticate login requests. This step is only required when using an account that belongs to an organization in GitHub or when using the Allowed organizations to restrict logins to users who belong to specific organizations.

note

In this procedure, you generate values in both Hub and GitHub.

The heading for each step tells you which application menu to follow.

Generate a Callback URL in Hub

To get started, open YouTrack and create an authentication module for GitHub accounts. When you create the authentication module, YouTrack generates a callback URL to use with the authorization service.

To generate a callback URL in Hub:

tip

Requires permissions: Low-level Admin Write

  1. In the Access Management section of the Administration menu, select Auth Modules.

  2. From the New module drop-down list, select GitHub.

    • The New GitHub Auth Module dialog opens.

    New GitHub authentication module.

  3. Enter the name for the new auth module and Server URL, then click the Create button.

    • The Auth Modules page displays the settings for a new GitHub authentication module.

    • Hub generates a callback URL for you to use in GitHub.

    The GitHub authorization callback URL.

  4. Copy the Authorization callback URL. If the feature is supported by your browser, use the Copy button to copy the URI to your clipboard.

  5. Click the link to access the Register a new OAuth application page in GitHub.

    note

    This setup requires that you copy values from GitHub into input fields on this page in Hub.

    To simplify setup, open this link in a new browser tab or window.

note

Make sure to update the Redirect URI in the authorization service when you change the base URL of your Hub instance. For example, after changing proxy settings.

Generate a Client ID and Secret in GitHub

  1. Log in to your GitHub account.

  2. Specify the general parameters to register a new OAuth application: Application name, Homepage URL, and optional Application description.

    3. tip

    If you already have any registered GitHub application...

    ...and it's not used to connect with another service, you can use its client ID and client secret:

    In the sidebar, click Applications, then select the application in the Developer applications list.

  3. In the Authorization callback URL, paste the callback URL you copied from the Auth Module page in Hub.

  4. Click the Register application button.

    • GitHub generates the credentials you need to set up the Hub module and displays them at the top of the page.

Enable the Auth Module in Hub

  1. Copy the client ID from GitHub and paste it into the Client ID input field in Hub.

  2. Copy the client secret from GitHub and paste it into the Client Secret input field in Hub.

  3. Configure the optional settings for the authentication module. For more information, see Settings.

  4. Click the Enable module button.

    • The GitHub 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 authenticate with their GitHub accounts.

      GitHubAuthIcon.png

Authorize the GitHub OAuth Application

The first time you attempt to log in using the GitHub authentication module, you are prompted to authorize access to the OAuth application in GitHub.

Prompt to authorize the GitHub OAuth application.

If you are unable to grant the application access at this point in time, access the settings for your organization and grant them there. For specific instructions, please refer to the GitHub documentation.

Settings

Field

Description

Type

Displays the name of the application or 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 GitHub account.

Authorization callback URL

Displays the Authorization callback URL used to register the connection to Hub in GitHub.

Client ID

Stores the identifier GitHub uses to validate a login request. You generate this value in GitHub when you configure the authorization settings for an application and enter a callback URL.

Client Secret

Stores the secret or password used to validate the client ID. You generate this value in GitHub together with the client ID.

Server URL

Displays the URL of the server to which Hub sends a login request when a user logs in with a GitHub account.

Scope

Displays the scope for the access request.

The information displayed below this field helps you configure the authentication module.

Allowed organizations

Restricts logins for this auth module to users who belong to specific organizations in GitHub. Enter a comma-separated list of organizations. If empty, any user with a GitHub account can log in using this auth module.

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

Actions

The following actions are available in the header:

Action

Description

Set default

Designates the authentication module as the default for your installation. Only one authentication module can be set as the default at any time. If another module is currently set as the default, that state is cleared.

This option is only shown when the current authentication module is not designated as the default.

Clear default

Removes the authentication module as the default for your installation.

If none of the available authentication modules are designated as the default, unauthenticated users are always directed to the Hub login page.

This option is only shown when the current authentication module is designated as the default.

Disable module

Disables the authentication module.

This option is only shown when the authentication module is currently enabled.

Enable module

Enables the authentication module.

This option is only shown when the authentication module is currently disabled.

Delete module

Removes the authentication module from Hub. Use only when you have configured additional authentication modules that let users log into your Hub installation.