Auth Modules
Authentication modules are used to verify the identity of users before granting them access to resources in YouTrack.
The Auth Modules page in Hub displays a list of available authentication modules. To access this page, select Auth Modules from the 
menu.
Available Actions
The following actions are available on the Auth Modules page:
Action | Description |
|---|---|
New module | Opens a list where you can select an authentication service provider or protocol and create a new auth module. |
Disable | Disables the selected authentication modules. Use in situations where you no longer want users to be able to log in with accounts from a specific identity provider. In situations where disabling all the selected authentication modules would leave users without a means of logging in to your Hub installation, this action is blocked. |
Enable | Enables the selected authentication modules. |
Set default | Sets the selected authentication module as the default for your Hub installation. Only one authentication module can be set as the default at any time. To learn more about this feature, see Default Authentication. |
Clear default | Clears the selected authentication module as the default for your Hub installation. When none of the available authentication modules are designated as the default, unauthenticated users are always directed to the Hub login page. |
Delete | Deletes the selected authentication modules from your Hub installation. Any login options supported by deleted modules are immediately removed from the login form. Related settings and configurations are erased and must be set up from scratch. |
Common settings | Navigates to a page that lets you configure settings that apply to all authentication modules. To learn more, see Common Settings for Auth Modules. |
Details | Expands and collapses the Details sidebar. Here, you can view additional information about each auth module that isn't available in the list. |
Drag to reorder | Lets you rearrange the list of authentication modules. This also affects the order of secondary options presented on the YouTrack login form. |
Hub Authentication
User authentication and authorization in YouTrack are managed by Hub. When you first install YouTrack, the Hub authentication module is already preconfigured and active. This authentication module is used to verify the identity of the system administrator who provided credentials for the default administrator account during installation.
If you don't want to configure single sign-on using accounts from a third-party authentication service, you can just use the Hub authentication module.
With user registration enabled for the Hub authentication module, all you have to do is send your users a link to the Hub installation. Anyone with access to the site will be able to create their own account.
When registration is disabled, an administrator must create accounts for each user or send invitations to register using email.
The Hub authentication module is built to support additional features, including account restoration, password strength requirements, and CAPTCHA challenges. The availability of these features in third-party authentication providers varies from service to service. To learn more, see Hub Auth Module.
Third-party Authentication Providers
In addition to the built-in authentication service provided out of the box, YouTrack lets you connect to one or more third-party authentication services.
One of the advantages of third-party authentication is that it leverages accounts for services that may already be in use by your organization. By allowing users to sign in with a single set of credentials across multiple applications, they are less likely to experience the frustration that comes with remembering multiple usernames and passwords.
YouTrack provides pre-configured authentication modules for services that work with various protocols like OAuth 2.0, SAML, LDAP, and OpenID. It also provides generic modules for each protocol that you can use to let users log in to YouTrack with accounts from other third-party services. To learn how to set up an authentication module for a specific service provider, select a topic from this section in the documentation.
Default Authentication
Hub lets you designate a specific authentication module as the system default. When used, unauthenticated users who open a URL that belongs to YouTrack are automatically redirected to the default authentication provider, skipping the standard YouTrack login page. Once authenticated, users are redirected to the originally requested page.
Users who are already authenticated in the default authentication service can navigate directly to the target page.
In situations where there are problems with the default authentication service, users are redirected to an error page. This page contains a link that lets users try using another login option to access YouTrack. When clicked, users are directed to the YouTrack login page. Here, they can select any available authentication providers to log in.
Use this feature when you want users to log in with accounts from a specific identity provider while still providing secondary login options when there's an outage or another connection problem.
If none of the available authentication modules are designated as the default, unauthenticated users are always directed to the YouTrack login page. The same is true when the built-in Hub authentication module is set as the default.
Two-factor Authentication
Two-factor authentication (2FA) is a security mechanism that enhances the protection of user accounts by requiring two distinct forms of verification before granting access. Users can set up 2FA for their own accounts at any time. This requires that they verify their identity using a second factor when they log in with their Hub account credentials.
If you're working with the Hub authentication module and want to require 2FA, you can configure this requirement at the group level. For example, if you want to require that everyone in your organization adds 2FA to their Hub account, you can configure this requirement for the All Users group. To learn more about this feature, see Require Two-factor Authentication.
If you're working with authentication modules supported by third-party services, the configuration and enrolment in two-factor authentication is also managed in the external service, not YouTrack.
Troubleshooting
The /logs/hub-export.log file contains a log of events related to user-management upgrades. Check this file to detect problems related to users who were not imported or are unable to log in using credentials from a third-party service.
Additional topics in this section of the documentation provide instructions for the setup and configuration of supported authentication modules.
- Common Settings for Auth Modules
- Hub Auth Module
- Active Directory Auth Module
- Amazon Auth Module
- Atlassian Jira Auth Module
- Bitbucket Cloud Auth Module
- Facebook Auth Module
- GitHub Auth Module
- GitLab Auth Module
- Google Auth Module
- JetBrains Account Auth Module
- Keycloak Auth Module
- LDAP Auth Module
- Microsoft Account Auth Module
- Microsoft Entra ID Auth Module
- OAuth 2.0 Auth Module
- Okta Auth Module
- OpenID 2.0 Auth Module
- OpenLDAP Auth Module
- PayPal Auth Module
- SAML 2.0 Auth Module
- Yandex Passport Auth Module
Changes Required for Migrating to the New Cloud Domain
After the upgrade to the version 2021.4, YouTrack Cloud instances may migrate to instancename.youtrack.cloud. Auth modules based on OAuth 2.0 and OpenID may require reconfiguration.
To update auth modules:
On the side of the IdP, proceed to update the Authorized redirect URI field or its analogue.
For each redirect URI on the list starting with
https://instancename.myjetbrains.com/youtrack, add one more URI starting withhttps://instancename.youtrack.cloud.Don't remove any URIs from the list, as they may come in handy if you decide to roll the base URL back.
Apply your changes.
In your browser, navigate to
https://instancename.youtrack.cloudand try to log in with the updated auth module.Repeat the procedure for all auth modules that require reconfiguration.