YouTrack Standalone 2017.1 Help

Introduction to YouTrackGoogle Authentication Module

GitHub Authentication Module

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

Enable GitHub Authentication

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

This procedure takes place in three steps:

  1. Generate a Callback URL in YouTrack. When you create an authentication module for GitHub, YouTrack 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 YouTrack 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 YouTrack. When you have generated the information YouTrack uses to authenticate with GitHub, copy the values into YouTrack and enable the module.

Prerequisites

Before you start, verify the following requirements:

  • You have Create Auth Module and Update Auth Module permissions in YouTrack.
  • You have a registered GitHub OAuth application.

Generate a Callback URL in YouTrack

  1. In the Access Management section of the Administration menu, select Auth Modules.
  2. From the Add Module drop-down list, select GitHub.
    • The Auth Modules page displays the settings for a new GitHub authentication module.
    • YouTrack generates a callback URL for you to use in GitHub.
    /help/img/youtrack/2017.1/authModulesGithub_thumbnail.png
  3. Copy the callback URL as instructed on the page.
  4. Click the link to access the New OAth Application page inGitHub.

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: Name, Homepage URL, and optional Application Description.
  3. In the Authorization callback URL, paste the callback URL you copied from the Auth Module page in YouTrack.
  4. Click the Register application button.
    • GitHub generates the credentials you need to set up the YouTrack module and displays them at the top of the page.

Enable the Auth Module in YouTrack

  1. Copy the client ID from GitHub and paste it into the Client ID input field in YouTrack.
  2. Copy the client secret from GitHub and paste it into the Client Secret input field in YouTrack.
  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

Settings

FieldDescription
TypeDisplays the name of the application or service that is enabled for third-party authentication in YouTrack.
NameStores the name of the authentication module. Use this setting to distinguish this module from other authentication modules in the Auth Modules list.
AuthenticationDisplays the current status of the module. This status indicates whether the module is currently enabled or disabled.
AuditLinks to the Audit Events page in YouTrack. There, you can view a list of changes that were applied to this authentication module.
Server URLDisplays the URL of the server to which YouTrack sends a login request when a user logs in with a GitHub account.
The information displayed below this field helps you configure the authentication module.
Client IDStores 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 SecretStores the secret or password used to validate the client ID. You generate this value in GitHub together with the client ID.
Button ImageDisplays the image used for the button that a user clicks to log in to YouTrack with a GitHub account.
Create UsersEnables creation of YouTrack accounts for unregistered users who log in with a GitHub account. YouTrack uses the email address to determine whether the user has an existing account.
Auto-join GroupsAdds users to a group when they log in with their GitHub accounts. 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.
Last modified: 18 April 2017