Okta Auth Module

The Okta authentication module lets users log in to YouTrack with their Okta credentials.

Okta supports two protocols for handling federated single sign-on, both of which are supported for authentication in YouTrack.

The Okta authentication module supports the OpenID Connect (OIDC) protocol. The settings for this module are preconfigured to support direct connections with the Okta service. With this module, you need to register YouTrack as a client application in Okta.
The SAML 2.0 Auth Module supports the SAML protocol. The settings for this module are preconfigured for generic connections with various SAML providers. Additional configuration for SAML authentication with Okta is required.

Your choice of protocol depends mainly on your use case, but OIDC is generally recommended for new integrations.

Enable Okta Authentication

To let users with existing Okta accounts log in to YouTrack, configure and enable the Okta authentication module.

To create the Okta authentication module:

From the Access Management section of the Administration menu, select Auth Modules.
Click the New module button.
- The Select an identity provider dialog opens.
In the Select an identity provider dialog, select Okta.
- The Configure Login with Okta wizard opens.
Specify the Okta domain of your organization, then click Next.
Copy the generated redirect URI.
Follow the instructions provided in the wizard to create the YouTrack app integration in Okta and register the redirect URI.
For additional information, refer to the Okta Help Center.
Copy the Client ID and Client Secret from Okta and paste them into the Client ID and Client secret fields in YouTrack correspondingly.
Click Finish.
- The Auth Modules page displays the settings for a new Okta authentication module.

To complete the setup:

Configure the optional settings for the authentication module. For more information, see Additional Settings.
Click the Save button to apply the settings.
Click the Enable button.
- The Okta authentication module is enabled.
- The Okta icon is added to the login dialog window. Users can click this icon to log in to YouTrack with their Okta credentials.

Settings

In the header of the settings page, you can find the general information about the authentication module, including its name and Okta domain.

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 of the authentication module using the Rename action. For more details, refer to Actions.
Domain	Displays the web domain of the Okta service.
Accounts imported to YouTrack	Displays the number of users in Okta that have been imported to your YouTrack installation.
User accounts discovered in Okta	Displays the number of user accounts that YouTrack has found in Okta.
Last sync	Displays the last time when YouTrack synchronized user accounts and groups between YouTrack and Okta.

On the General Settings tab, you find the general settings for the authentication module. This includes the redirect URI that you used to register YouTrack in the authorization service and the input fields that store the Client ID and Client Secret.

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.
Default	Sets the current authentication module as the default.
API token	Stores the access token that grants authorized access to the Okta API, which is required for scheduled synchronization of user accounts and groups. Okta API tokens are issued for a specific user, and all requests with the token act on behalf of the user. Therefore, you should only generate an API token for a user account with an appropriate level of access in the directory service. To learn how to create an API token in Okta, refer to the Okta documentation.

Users & Groups

The settings on the Users & Groups tab let you set up synchronization of user account and group data between YouTrack and Okta.

When synchronization is enabled, changes applied to Okta profiles are synchronized with YouTrack on a set schedule. This synchronization is performed in addition to the synchronization requests that are automatically sent when users log in to YouTrack or a connected service using their Okta account credentials.

Scheduled synchronization does not replace the group membership synchronization that is automatically performed when users log in with their Okta accounts. However, these two synchronization schemes use different sources.

Scheduled sync uses the Okta API. This API references attributes that are stored directly in Okta user profiles.
Synchronization performed during login is handled using the OAuth 2.0 application used to connect Okta and YouTrack. Attributes that are made available to the application are mapped from Okta user profiles but can be assigned different names.

This creates a situation where the value for a custom attribute is set when the user logs in to YouTrack, but the value is cleared during the scheduled synchronization.

To ensure that these values remain in sync, the variable names assigned to attributes in Okta profiles must exactly match the attribute names assigned to the user profile in the Okta application that is registered in YouTrack.

If you need more assistance, contact the YouTrack support team.

Setting	Description
Selected groups	Allows you to select user groups from Okta that will be synchronized with YouTrack.
Select all groups	Enables synchronization of all groups found in Okta with YouTrack.
Scheduled sync	Determines the frequency with which user attributes and group memberships are synchronized with Okta. If the setting is enabled, you can choose from one of three predefined intervals: Hourly Every 3 hours Daily at 9 AM You can also launch the synchronization manually at any time by clicking the Sync now button in the header. If the setting is disabled, group memberships are still synchronized on a per-user basis during login. The synchronization feature is only active when the authentication module is Enabled.

Setting

Description

Selected groups

Allows you to select user groups from Okta that will be synchronized with YouTrack.

Select all groups

Enables synchronization of all groups found in Okta with YouTrack.

Scheduled sync

Determines the frequency with which user attributes and group memberships are synchronized with Okta.

If the setting is enabled, you can choose from one of three predefined intervals:

Hourly
Every 3 hours
Daily at 9 AM

You can also launch the synchronization manually at any time by clicking the Sync now button in the header.

If the setting is disabled, group memberships are still synchronized on a per-user basis during login.

The synchronization feature is only active when the authentication module is Enabled.

Group Mappings

In case the API access is not configured in Okta, you can provide the names of Okta groups to use in YouTrack manually.

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

Users who are members of a mapped Okta 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 Okta 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 Okta accounts.

To map a group from Okta to a group in YouTrack:

Open your Okta auth module.
Select the Users & Groups tab.
Click the Add group by name button.
Enter the name of the Okta group in the designated field.
Click the Save button.
- The specified group is added to YouTrack.
- Clicking the group name redirects you to the Groups | <Your Group Name> page
Repeat steps 3 through 5 until you have mapped all the desired groups.

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.

Option	Description
Account status	Determines whether accounts are banned in YouTrack when an account with corresponding credentials is deleted or deactivated in Okta. When set to Ignore, changes to the account status in Okta are not applied to accounts in YouTrack. When set to Forward, accounts that are deleted or deactivated in Okta are banned in YouTrack.
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.
Extension grant type	Saves the value that is used to identify the authentication module when used for extension grants. If a value is provided, YouTrack will process requests to exchange access tokens that are issued by the authorization service for tokens that grant access to YouTrack. To exchange access tokens successfully, the authentication module must be authorized in the third-party authentication service and enabled in YouTrack. To learn how to exchange access tokens using the YouTrack REST API, see Extension Grants.
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).
Changes made to Okta	Links to the Audit Events page in YouTrack. There, you can view a list of changes that were applied to this authentication module.

Field Mapping

When a user profile response object is returned by Okta, values from the specified field paths are copied to the user profile in YouTrack. Use the settings in the Field Mapping section of the page 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 the predefined Okta module, the User ID, Email, Email verification state, Full name, and Groups are synced automatically. The names for these fields are predefined by Okta and cannot be updated, so the mapping to the corresponding fields in YouTrack is hard-coded and the settings are hidden.

Instead, you only see mapping settings for custom attributes that have been added to user profiles in YouTrack. 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, refer to Manage Custom Attributes.

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.

Actions

The following actions are available in the header:

Action	Description
Test login	Lets you enter a username and password to test the connection with the authentication service.
Sync now	Launches the synchronization of users and groups between Okta and YouTrack. You can configure which Okta groups to use in YouTrack on the Users & Groups tab.
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.
Rename	Lets you update the existing authentication module name and change its default icon. You can find this action in the 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 More options (...) menu.

Last modified: 17 January 2025