YouTrack Server 2024.3 Help

Keycloak Auth Module

The Keycloak authentication module is a pre-configured OAuth2.0 auth module that lets users log in to YouTrack with their Keycloak credentials.

Enable Keycloak Authentication

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

This procedure takes place in three steps:

  1. Create a Keycloak Auth Module. 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.

  2. Generate a Client ID and Secret in Keycloak. Every login request sent from YouTrack includes a unique identifier. The ID and secret you store in the authentication module tell the Keycloak authorization service that each login request is authorized.

  3. Enable the Auth Module in YouTrack. When you have generated the information that YouTrack uses to authenticate with the Keycloak authorization service, copy the values into YouTrack and enable the module.

Create a Keycloak Auth Module in YouTrack

First, create the Keycloak authentication module. When you perform this action, YouTrack generates a redirect URI to use with the authorization service.

  1. In the Access Management section of the Administration menu, select Auth Modules.

  2. From the New Module drop-down list, select Keycloak.

    • The New Keycloak Auth Module dialog opens.

  3. In the New Keycloak Auth Module dialog, enter values for the following settings:

    Setting

    Description

    Keycloak root URL

    Enter the root URL for your Keycloak server.

    Keycloak realm

    Enter the name of the Keycloak realm where you manage the user accounts that you want to allow access to YouTrack.

  4. Click the Create button.

    • The Auth Modules page displays the settings for a new Keycloak authentication module.

    • YouTrack generates a redirect URI for you to use in the authorization service.

    Keycloak auth redirect uri

Generate a Client ID and Secret

The next step is to get a client ID and secret from Keycloak.

  1. Log in to the admin console with your administrator account.

  2. Select your realm from the list.

  3. From the Configure menu, select Clients.

  4. Click the Create button.

    • The Add Client dialog opens.

  5. Enter values for the following settings:

    • For the Client ID, enter a value that helps you identify the client application.

    • For the Client Protocol, select openid-connect.

    • For the Root URL, enter the base URL for your YouTrack installation.

  6. Click the Save button.

    • The page that stores the settings for your new client application opens.

  7. On the Settings tab for your client app, change the Access Type to confidential.

  8. Click the Save button.

  9. Use the value stored as the Client ID to enable the authentication module in HUb.

  10. Select the Credentials tab, then use the value that is stored as the Secret to enable the authentication module in YouTrack.

For additional information, please refer to the Keycloak documentation.

Enable the Auth Module in YouTrack

To complete the setup, store the client ID and secret from the authorization service in the Keycloak auth module.

  1. Copy the Client ID from the Settings tab in Keycloak and paste it into the Client ID input field in YouTrack.

  2. Copy the Secret from the Credentials tab in Keycloak and paste it into the Client secret input field in YouTrack.

  3. Configure the optional settings for the authentication module. For more information, see Additional Settings.

  4. Click the Save button to apply the settings.

  5. Click the Enable module button.

    • The Keycloak 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 Keycloak credentials.

Test the Connection

To verify that the Keycloak authentication module is set up correctly, test the connection.

Click the Test login button in the header. This verifies the login process in a new browser tab.

  • If the authentication module is set up correctly, a success message is shown.

  • If there are problems with the connection, the authentication service displays an error message. Use the information provided on the error page to investigate the problem.

    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.

    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 YouTrack REST API, see Extension Grants.

    Authorization Service Endpoints

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

    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 get 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.

    Email

    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

    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.

    Field Mapping

    When a user profile response object is returned by Keycloak, 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 Keycloak module, the User ID, Email, Email verification state, Full name, and Groups are set automatically. If you need to modify these values to suit your needs, you can overwrite them.

    • 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.

    Field

    Description

    User ID

    Maps to the field that stores the value to copy to the User ID property in the YouTrack account.

    Username

    Maps to the field that stores the value to copy to the Username field in the YouTrack account.

    This option is available in YouTrack versions 2023.1.65369 and later.

    Full name

    Maps to the field that stores the value to copy to the Full name field in the YouTrack account.

    Email

    Maps to the field that stores the value to copy to the Email field in the YouTrack account.

    Email verification state

    Maps to the field that stores the value to copy to the verified email property in the YouTrack account.

    Avatar

    Maps to the field that stores the image to use as the Avatar in the YouTrack account.

    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 Mappings.

    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 Keycloak 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

    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.

    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.

    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.

    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.

    Group mappings for Keycloak accounts.

    If you want to map groups in Keycloak to groups in YouTrack, you need to specify the Groups attribute that stores Keycloak group memberships in the Field Mapping section of the settings for this auth module. For the predefined Keycloak module, the Groups attribute and Scope are set automatically.

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

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

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

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

    1. Open your Keycloak auth module.

    2. Select the Group Mappings tab.

    3. Click the Add mapping button.

      • The Add Mapping dialog opens.

      Dialog for adding group mappings.
    4. Enter the name of the Keycloak group 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.

    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.

    Test login

    Lets you test the connection with the authentication service.

    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.

    Last modified: 22 August 2024