YouTrack Standalone 2018.3 Help

SAML 2.0 Auth Module

A SAML 2.0 authentication module lets you configure YouTrack as a SAML Service Provider (SAML SP). SAML supports single sign-on (SSO) across multiple domains.

When you enable an SAML 2.0 authentication module in YouTrack:

  • Your users log in to YouTrack with the credentials that are managed in a specified third-party identity provider (SAML IdP).

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

YouTrack can also be set up as a SAML IdP, however, the instructions for the identity provider setup are not described here. To learn how to use YouTrack as a SAML IdP, see SAML 2.0.

Add a New SAML2.0 Authentication Module

To add a SAML2.0 Authentication module:

  1. In a service that you plan to use as a SAML identity provider for YouTrack Standalone, retrieve its parameters as the IdP:

  2. If the IdP service does not provide a fingerprint of their certificate, create it applying SHA256. For example, you can use SAML Tool

  3. In YouTrack Standalone, open admin menu > Auth modules page. Click the Add auth module button and select SAML 2.0 in the drop-down list.

  4. In the displayed dialog, specify parameters of the IdP service.

  5. Configure created auth module: Provide the names of the SAML attributes of the user accounts.

Sample Configurations

Use Okta as SAML Identity Provider in YouTrack

Configuring Okta as a SAML IdP in YouTrack is an easy but not a straight forward process. The trick is that to create an Auth module in YouTrack, you need to provide a unique URL for the IdP. However, in Okta, the IdP URL is specific for an application, and is generated when you create the application for the SAML SP. And to create an application for YouTrack as a SAML service provider in Okta, you need the unique URL that is generated in YouTrack only when you create the Auth module for Okta. This "URLs loop" results in the loop in the configuration procedure: You create an application in Okta with a fake URL for YouTrack to generate the IdP URL, then you create an auth module in YouTrack to generate the SP URL, and after that you can provide the actual SP URL from YouTrack in the Okta application.

To use Okta as IdP for YouTrack Standalone:

  1. In Okta, create a new application for YouTrack Standalone service. Use any URLs for YouTrack Standalone as the SP. You need to correct it later. See the Okta documentation for setting up SAML application.

  2. When you created the application, click the View Setup Instructions button to open a page with the parameters of your Okta IdP:

    Parameters for Okta IdP

  3. Download the certificate of your Okta IdP.

  4. Create a fingerprint for the Okta certificate applying SHA256. For example, you can use SAML Developer Tools.

  5. In YouTrack Standalone, open Auth Modules page.

  6. Click the New module button, then select SAML 2.0 in the drop-down list.
    • A New Module dialog is displayed in the right side-panel.

  7. In the displayed dialog, specify the parameters of your Okta IdP. Click Create.

    Yt okta idp create new auth module

  8. Configure the new module: Set up the SAML attributes.

    Okta idp configure auth module

  9. Switch back to Okta. In Okta, edit the YouTrack application: Provide URLs that are generated during the creation of the new auth module.

  10. Assign the YouTrack application to groups and users that should be able to log in to YouTrack with Okta credentials.

That's it. Now the users can log in to YouTrack and connected services with their Okta credentials.

Use YouTrack as SAML Identity Provider in YouTrack

If you have two YouTrack services, you can use one of them as a SAML Identity Provider and another one — as the service provider.

  1. In the YouTrack Standalone that you use as SAML IdP, open admin menu > SAML 2.0 page. For details about YouTrack as a SAML 2.0 Identity Provide, see Parameters of YouTrack as SAML 2.0 Identity Provider.

  2. In YouTrack that you use as SAML service provider, open Auth Modules page.

  3. Click New module, then, select SAML 2.0....
    • A New Module dialog is displayed in the right side-panel.

  4. In the displayed dialog, provide parameters of the YouTrack service that you use as IdP: Click Create.
    • The new module is created. You are navigated to the settings page the created module:

  5. Configure SAML attributes:

  6. In the IdP, open Admin menu > SAML 2.0 > Registered services tab. Register the YouTrack SAML service provider: As SAML Attributes, provide the same values that you have set up in the Attributes section of the auth module settings page. For more details, see Register a Service Provider.

You are all set! Now your users can log into the YouTrack SP with the credentials from the YouTrack service that you use as SAML IdP.

Last modified: 30 November 2018