# OAuth 2.0 Auth Module

An OAuth 2.0 authentication module lets users log in to YouTrack and any connected services with credentials that are stored in an external authorization service. YouTrack provides pre-configured authentication modules for [Amazon](amazon-auth-module.html), [Bitbucket Cloud](bitbucket-cloud-auth-module.html), [Facebook](facebook-auth-module.html), [GitLab](gitlab-auth-module.html), [Keycloak](keycloak-auth-module.html), [Microsoft Account](microsoft-live-auth-module.html), [Okta](okta-auth-module.html), and [PayPal](paypal-auth-module.html).

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.

> **Note:**
> When a user created manually in YouTrack logs on with OAuth 2.0 for the first time, YouTrack ties the OAuth 2.0 user to the existing YouTrack user if a matching email address or username is found. If no match is found, a new account for the OAuth 2.0 user is created in YouTrack.

## Enable OAuth 2.0 Authentication

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

Procedure: To create an OAuth 2.0 auth module:

> **Tip:**
> Requires permissions: Low-level Admin Write

1. From the main navigation menu, select ![](https://resources.jetbrains.com.cn/help/img/youtrack/2026.2/settings.svg) `Administration > Access Management > Auth Modules`.

2. Click the New module button.

* The Select an identity provider dialog opens. ![Select an identity provider dialog listing available authentication services.](https://resources.jetbrains.com.cn/help/img/youtrack/2026.2/select-idp.png)

3. In the Select an identity provider dialog, select OAuth 2.0.

* The Configure Login with OAuth 2.0 wizard opens.

4. Enter the Auth module name, Authorization URL, Token URL, and User info URL, then click Next.

![Wizard step for OAuth 2.0 endpoint URLs with the corresponding configuration fields displayed.](https://resources.jetbrains.com.cn/help/img/youtrack/2026.2/oauth2-wizard-1.png)

5. Copy the generated redirect URI.

![Wizard step with the OAuth 2.0 redirect URI.](https://resources.jetbrains.com.cn/help/img/youtrack/2026.2/oauth2-wizard-2.png)

Register the authorized redirect URI for YouTrack in the authorization service. This process varies by service. You can refer to the setup instructions for any of the pre-configured authentication modules, like [Amazon](amazon-auth-module.html), [Bitbucket Cloud](bitbucket-cloud-auth-module.html), [Facebook](facebook-auth-module.html), [GitLab](gitlab-auth-module.html), [Microsoft Entra ID](azure-ad-auth-module.html), [Microsoft Live](microsoft-live-auth-module.html), and [PayPal](paypal-auth-module.html). The procedures for other third-party authorization services are similar.

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

6. Copy the Client ID and Client secret from the authorization services and paste them into the corresponding fields in YouTrack.

![Wizard step for Client ID and Client secret with the corresponding configuration fields displayed.](https://resources.jetbrains.com.cn/help/img/youtrack/2026.2/oauth2-wizard-3.png)

7. Click Finish.

The OAuth 2.0 authentication module is created and its configuration page opens.

Procedure: To enable the OAuth 2.0 auth module:

> **Tip:**
> Requires permissions: Low-level Admin Write

1. Review and configure optional settings for the authentication module. For more information, see [Additional Settings](#oauth-additional-settings).

2. Click Save to apply the settings.

3. Click Enable.

* The OAuth 2.0 authentication module is enabled.

* The auth module icon is added to the login dialog window. Users can click this icon to log in to YouTrack with their credentials.

4. To verify that the authentication module is configured correctly, click the Test login button.

* YouTrack opens the authentication flow with the configured identity provider.

* If you are authenticated successfully, the configuration is correct.

## General Information

In the header of the settings page, you can find the general information about the authentication module.

| Setting | Description |
| --- | --- |
| Name | Stores the name of the authentication module. Use this setting to distinguish this module from other authentication modules in the Auth Modules list.     You can change the name and icon of the authentication module using the Rename action. For more details, see [Actions](#auth-module-actions).   |
| Type | Displays the type of authorization service that is enabled for third-party authentication in YouTrack.  |
| Accounts imported to YouTrack | Displays the number of users that have been imported to YouTrack. |

## Actions

The following actions are available in the header:

| Action | Description |
| --- | --- |
| Enable | Enables the authentication module.     This option is only shown when the authentication module is currently disabled.   |
| Disable | Disables the authentication module.     This option is only shown when the authentication module is currently enabled.   |
| Test login | Lets you test the connection with the authentication service. |
| Rename |    Lets you update the existing authentication module name and change its default icon.     You can find this action in the ![](https://resources.jetbrains.com.cn/help/img/youtrack/2026.2/more-options.svg) More options menu.    |
| Delete | Removes the authentication module from YouTrack. Use only when you have configured additional authentication modules that let users log into your YouTrack installation.     You can find this action in the ![](https://resources.jetbrains.com.cn/help/img/youtrack/2026.2/more-options.svg) More options menu.    |

## General Settings

On the General Settings tab, you find the general settings for the authentication module. This includes the redirect URI used to register YouTrack in the authorization service and the client credentials generated in the authorization service.

| Setting | Description |
| --- | --- |
| 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.     If none of the available authentication modules are designated as the default, unauthenticated users are always directed to the YouTrack login page.   |

### Authentication

The Authentication settings define the core security credentials and parameters required to connect YouTrack with the OAuth 2.0 authorization service. By entering your generated Client ID and Client Secret, and defining the required access Scopes, you enable secure identity verification. This section also displays the unique Redirect URI that must be registered in the authorization service to authorize the connection.

| Setting | Description |
| --- | --- |
| Redirect URI | Displays the authorized redirect URI 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. |
| Scopes | A space-separated list of scopes YouTrack requests from the identity provider. Scopes determine which claim groups the identity provider returns. |

### Authorization Service Endpoints

The settings in this section of the page store the OAuth 2.0 endpoints used by the authorization service.

| Setting | Description |
| --- | --- |
| Authorization URL | Stores the endpoint that YouTrack uses to get authorization from the resource owner via user-agent redirection.  |
| Token URL | Stores the endpoint that YouTrack uses to exchange an authorization grant for an access token.  |
| User info URL | Stores the endpoint used to locate profile data for the authenticated user. |
| Logout URL | The optional endpoint to invalidate the authorization service session on logout |
| Email URL | Stores 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.  |
| Avatar URL | Stores the endpoint used to locate the binary file that is used as the avatar for the authenticated user. Use only when the avatar isn't stored directly in the user profile. |

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

* To specify paths to fields inside nested objects, enter a sequence of segments separated by the slash character (`/`).

* To reference values that may be stored in more than one location, use the "Elvis operator" (`?:`) as a delimiter for multiple paths. With this option, YouTrack uses the first non-empty value it encounters in the specified field.

> **Note: Custom Attributes**
> If you have added custom attributes to user profiles, these attributes can also be mapped to attributes that are stored in the authorization service. Each custom attribute is listed by name with an input field for storing the name of the corresponding field in the authorization service.
>
>
>
> To learn more about custom attributes in user profiles, see [Manage Custom Attributes](manage-custom-attributes.html).

| Field | Description |
| --- | --- |
| User ID | Maps to the field that stores the value to copy to the User ID property in YouTrack.  |
| Username | Maps to the field that stores the value to copy to the Username field in the YouTrack profile.    |
| Full name | Maps to the field that stores the value to copy to the Full name field in the YouTrack profile.  |
| Email | Maps to the field that stores the value to copy to the Email field in the YouTrack profile.  |
| Email verification state | Maps to the field that stores the value to copy to the verified email property in YouTrack. |
| 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.  |
| Groups | Maps to the attribute that stores group membership assignments in the connected authorization service.     When this value is specified, you can map and sync group memberships in the authorization service with corresponding groups in YouTrack. For details, see [Group Mapping](#group-mappings).   |

## Group Mapping

> **Note: Availability**
> The ability to map and sync memberships between groups in a service that supports the OAuth2 protocol and groups in YouTrack is only available with services that return group membership data from the same authorization service endpoint that supplies user data.

On the Group Mappings tab, you can map existing groups in the authorization service to the groups in YouTrack.

> **Note:**
> Group synchronization supports regular user groups only, not customer groups.

If you want to map groups in the OAuth 2.0 service to groups in YouTrack, you need to specify the Groups attribute that stores group memberships from the OAuth 2.0 service in the Attribute Mapping section of the settings for this auth module.

When group mappings are configured, YouTrack checks for group memberships when users log in with accounts that are managed in the directory service. YouTrack performs the following operations for each group from the OAuth 2.0 service that is mapped to a YouTrack group:

* Users who are members of a mapped OAuth 2.0 group and are not members of the mapped YouTrack group are added to the group in YouTrack.

* Users who are not members of a mapped OAuth 2.0 group and are members of the mapped YouTrack group are removed from the group in YouTrack.

Changes to group memberships in the authorization service are only applied in YouTrack when users log in using their accounts from the OAuth 2.0 service.

You can map multiple OAuth 2.0 groups to a single target group in YouTrack. You can't map OAuth 2.0 groups to more than one YouTrack group.

Procedure: To map a group from an OAuth 2.0 authorization service to a group in YouTrack:

> **Tip:**
> Requires permissions: Low-level Admin Write

1. Open your OAuth 2.0 auth module.

2. Select the Group Mappings tab.

3. Click the Add mapping button.

* The Add Mapping dialog opens.

4. Enter the name of the group from OAuth 2.0 in the OAuth group name field.

5. Select a group from the Target group list.

6. Click the Add button.

* The mapping is added to the list.

## SCIM 2.0

The `SCIM 2.0` tab lets you enable System for Cross-domain Identity Management (SCIM) provisioning for the OAuth 2.0 authentication module. When SCIM provisioning is enabled, an external identity provider can create, update, and deactivate Hub user accounts using the SCIM 2.0 protocol.

The OAuth 2.0 authentication module synchronizes user data only during login. When a user signs in, YouTrack reads the user attributes and group memberships returned by the identity provider.

Changes made in the identity provider are not synchronized automatically while the user is inactive. For example, updates to user attributes or group memberships are applied only after the user signs in again.

To keep user accounts and groups synchronized automatically, enable SCIM 2.0 provisioning and create a SCIM 2.0 token for the authentication module.

> **Note:**
> Group synchronization supports regular user groups only, not customer groups.

Procedure: Enable SCIM 2.0 provisioning

To allow an external identity provider to provision users through SCIM:

1. Open your OAuth 2.0 auth module.

2. Select the SCIM 2.0 tab.

3. Enable the Enable SCIM 2.0 provisioning option.

* YouTrack generates a SCIM 2.0 base URI for this authentication module.

4. [Create a SCIM 2.0 token](#create-scim-token) and copy its value.

5. Specify both the SCIM 2.0 base URI and SCIM 2.0 token generated in YouTrack when configuring SCIM provisioning in your identity provider. The base URI identifies the provisioning endpoint, while the token authenticates provisioning requests sent by the identity provider.

Procedure: Create a SCIM 2.0 Token

1. In the SCIM 2.0 Tokens section, click New Token.

2. In the New SCIM 2.0 Token dialog, enter a name for the token.

3. Click Create.

* Hub generates the token and displays its value in the SCIM 2.0 Token Created dialog.

4. Copy the token value and store it in a secure location before closing the dialog. The token value cannot be viewed again after the dialog is closed.

Procedure: Delete a SCIM 2.0 Token

> **Note:**
> After a token is deleted, provisioning requests that use this token are rejected.

1. Select one or more tokens in the SCIM 2.0 Tokens table.

2. Click Delete and confirm the action in the Delete SCIM 2.0 token dialog.

## Additional Settings

The settings on the Additional settings tab let you manage account creation and group membership and reduce the loss of processing resources consumed by idle connections.

| Setting | 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 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.   |
| Authentication | Determines how credentials are passed to the authorization service. When enabled, credentials are passed in the HTTP header. When disabled, credentials are passed in the request body. |
| Email auto-verification | Determines how YouTrack sets the verification status of an email address when the authentication service does not return a value for this attribute. |
| Extension grant type | Saves the value used for the `grant_type` parameter in an OAuth 2.0 Extension Grant flow. This flow lets you exchange a YouTrack access token for an OAuth 2.0 access token.     To learn how to exchange access tokens using the YouTrack REST API, see [Extension Grants](https://www.jetbrains.com.cn/en-us/help/youtrack/devportal/extension-grants.html).   |
| 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). Use 0 for an infinite timeout. |
| 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). Use 0 for an infinite timeout. |
| Changes made to OAuth 2.0 | Links to the Audit Events page in YouTrack. There, you can view changes that were applied to this authentication module. |