An OAuth 2.0 authentication module lets users log in to YouTrack with credentials that are
stored in an external authorization service.
YouTrack provides pre-configured authentication modules for Amazon, Azure AD 2.0, Facebook, Microsoft Live, Facebook, PayPal, and Yandex Passport.
You can also use the generic OAuth 2.0 authentication module to let users log in to YouTrack 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 YouTrack:
Your users log in to YouTrack with the credentials they use in an external service.
Your YouTrack users have fewer accounts and passwords to remember.
New users with accounts in the connected service can create their own accounts in YouTrack.
Enable OAuth 2.0 Authentication
To allow users with existing accounts in an external authorization service to log in to YouTrack, enable an OAuth 2.0 authentication module.
This procedure takes place in three steps:
Generate a Redirect URI in YouTrack. When you create an authentication module,
YouTrack 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 YouTrack 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 YouTrack.
When you have generated the information YouTrack uses to authenticate with the authorization service, copy the values into YouTrack and enable the module.
Generate a Redirect URI in YouTrack
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.
YouTrack 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 YouTrack in the authorization service.
This process varies by service. The instructions in the following table describe how to register YouTrack as an application for pre-configured OAuth 2.0 authorization services.
The procedures for other third-party authorization services are similar.
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 YouTrack 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 YouTrack.
Enable the Auth Module in YouTrack
Copy the client ID from the authorization service and paste it into the Client ID input field in YouTrack.
Copy the client secret from the authorization service and paste it into the Client secret input field in YouTrack.
The icon stored in the Button image setting is added to the login dialog window.
Users can click this icon to log in to YouTrack 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 YouTrack 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 YouTrack.
Name
Stores the name of the authentication module. Use this setting to distinguish this module from other authentication modules in the Auth Modules list.
Button image
Displays the image used for the button that a user clicks to log in to YouTrack 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 YouTrack 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 YouTrack uses to obtain
authorization from the resource owner via user-agent redirection.
Token
Stores the endpoint that YouTrack uses to exchange an authorization
grant for an access token.
User data
Stores the endpoint used to locate profile data for the authenticated user.
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.
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 YouTrack.
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 YouTrack.
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 YouTrack.
Email
Maps to the field that stores the value to copy to the Email field in the YouTrack profile.
Verified email
Maps to the field that stores the value to copy to the verified email property in YouTrack.
Full name
Maps to the field that stores the value to copy to the Full name field in the YouTrack profile.
Avatar
Maps to the field that stores the image to use as the Avatar in the YouTrack 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.
Connection Settings
The settings in this section of the page let you reduce the loss of processing resources consumed by idle connections.
Setting
Description
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).
User Management Options
The following options are located at the bottom of the page.
Use these settings to manage YouTrack account creation and group membership.
Option
Description
User creation
Enables creation of YouTrack accounts for unregistered users who log in with an account that is stored in
the connected authorization service.
YouTrack 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.