Okta Auth Module
The Okta authentication module is a pre-configured OAuth2.0 auth module that 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 with 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 Hub as a client application in Okta, but everything else is relatively easy to set up.
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, enable the 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 Okta. Every login request sent from YouTrack includes a unique identifier. The ID and secret you store in the authentication module tell the Okta authorization service that each login request is authorized.
Enable the Auth Module in YouTrack. When you have generated the information that YouTrack uses to authenticate with the Okta authorization service, copy the values into YouTrack and enable the module.
Generate a Redirect URI in YouTrack
First, create the Okta authentication module. When you perform this action, YouTrack generates a redirect URI to use with the authorization service.
To generate a redirect URI in YouTrack:
In the Access Management section of the
Administration menu, select .From the New Module drop-down list, select Okta.
The New Okta Auth Module dialog opens.
Enter the name for the new auth module and the Okta domain, then click the Create button.
The Auth Modules page displays the settings for a new Okta 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
The next step is to register the authorized redirect URI for YouTrack in Okta.
Sign in to your Okta organization with your administrator account.
In the Admin Console go to > .
Click the Create App Integration button.
The Create a new app integration settings are displayed.
For the Sign-in method, select OIDC - OpenID Connect.
For the Application type, select Web Application.
Enter a name for your new web app integration.
Paste the redirect URI from YouTrack into the Sign-in redirect URIs input field.
If you want to allow access to everyone in your organization or limit access to members of specific groups, select the corresponding option in the Assignments section. You can also choose the option to skip group assignment for now and set it up later.
Click the Save button.
Switch to the General tab
Use the values that are stored as the Client ID and Client secret to enable the authentication module in YouTrack.
For additional information, please refer to the Okta Help Center.
Enable the Auth Module in YouTrack
To complete the setup, store the client ID and secret from the authorization service in the Okta auth module.
Copy the Client ID from Okta and paste it into the Client ID input field in YouTrack.
Copy the Client secret from Okta and paste it into the Client secret input field in YouTrack.
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 module button.
The Okta 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 log in to YouTrack with their Okta credentials.
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 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. |
Domain | Displays the web domain of the Okta service. Click the icon to the right of this field to copy the domain URL to your clipboard. |
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. |
Extension grant | 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 REST API, see Extension Grants. |
Synchronization Settings
The settings in this section let you set up synchronization of user account 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 using their Okta account credentials.
Values for the Full Name, Username, and Email that are stored in the YouTrack profile are populated when the user account is first created, which is usually when a new user logs in to YouTrack using their Okta account. Later changes to these attributes in Okta profiles are not synced with the YouTrack profile. These changes are synced with the corresponding attributes that are associated with their Okta credentials. This information is displayed in the Credentials section of the Account Security tab in the YouTrack profile.
This synchronization applies to the attributes that are configured in the Field Mapping settings and group memberships as configured on the Group Mappings tab. For details, see Field Mapping and Group Mappings.
Setting | Description |
|---|---|
Schedule | Determines the frequency with which user attributes and group memberships are synchronized with the directory service. You can choose from one of three predefined intervals:
You can also manually synchronize the Hub database at any time by clicking the Synchronize now button. When synchronization is Off, group memberships are still synchronized on a per-user basis during login. To learn more about this feature, see Group Mappings. The synchronization feature is only active when the authentication module is Enabled. |
API token | Stores the API token that grants authorized access to Okta. 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, please refer to the Okta documentation. |
Field Mapping
When Okta returns a user profile as a response object, 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 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 Hub 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 Hub. 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.
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.
Additional Settings
The following options are located at the bottom of the page. These settings let you define the request scope and choose how to authenticate with the service.
For the predefined Okta module, the Scope is set automatically. If you need to modify this value to suit your needs, you can overwrite it.
Other options in this section let you manage YouTrack account creation and group membership and reduce the loss of processing resources consumed by idle connections.
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 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). |
Audit | Links to the Audit Events page in YouTrack. There, you can view a list of changes that were applied to this authentication module. |
Group Mappings
On the Group Mappings tab, you can map existing groups in the authorization service to the groups in YouTrack.
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.
You can map multiple Okta groups to a single target group in YouTrack. You can't map Okta groups to more than one YouTrack group.
To map group from Okta to a group in YouTrack:
Open your Okta auth module.
Select the Group Mappings tab.
Click the Add mapping button.
The Add Mapping dialog opens.
Enter the name of the Okta group in the OAuth group name field.
Select a group from the Target group list.
Click the Add button.
The mapping is added to the list.
Actions
The following actions are available in the header:
Action | Description |
|---|---|
Set default | Designates the authentication module as the default for your YouTrack site. 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. This option is only shown when the current authentication module is not designated as the default. |
Clear default | Removes the authentication module as the default for your YouTrack site. If none of the available authentication modules are designated as the default, unauthenticated users are always directed to the Hub login page. This option is only shown when the current authentication module is designated as the default. |
Disable module | Disables the authentication module. This option is only shown when the authentication module is currently enabled. |
Enable module | Enables the authentication module. This option is only shown when the authentication module is currently disabled. |
Delete module | Removes the authentication module from YouTrack. Use only when you have configured additional authentication modules that let users log into your YouTrack site. |