Using SAML SSO with Tracker

If your organization uses a SAML-based Single Sign On (SSO) service to manage access to applications, Tracker can integrate with your identity provider (IdP) so that access is explicitly managed via your IdP.

Tracker currently offers SAML SSO to customers who subscribe to an Enterprise plan. SSO and other Enterprise features are not currently available as part of the 30 Day Trial, Free, Startup, or Standard plans at this time.

Important notes about Tracker SSO

Before an account can be enabled for Enterprise features/SAML SSO, at least one company owned email domain must be explicitly associated (“allow-listed”) with the enterprise account. This ensures that when a user with your company domain visits https://www.pivotaltracker.com/signin, Tracker will know to forward them to your IdP’s single-sign-on portal. Users can also visit your Tracker subdomain (https://YOUR_COMPANY_DOMAIN.pivotaltracker.com) which will automatically forward them to your IdP’s single-sign-on portal.
Users with the company domain(s) will not be able to own or have admin rights on any other accounts besides the Enterprise account. Because of this, any Tracker accounts (and their associated projects) owned by your users will need to be merged with the main Enterprise account before SSO can be enabled (Tracker will take care of the merging). Projects associated with any accounts that need to be merged will be moved over to the main enterprise account, and will not be affected.
Once the company domain(s) are associated with your enterprise account, anyone that does not have the company domain(s) will be considered an “external guest.” External guests will still be able to access projects they are already members of, and will only have access to projects they’re explicitly invited to. External guests cannot search/find/self-join projects in the Enterprise account, and will always sign in using their regular Tracker credentials, not SSO.
By default, external guests can be invited to projects by account owners, account admins and project owners. However, you can choose to restrict guest invites to only be allowed by account owners and admins from your Account Settings page.
Tracker supports JIT provisioning. This means that once SSO is enabled and the company domain(s) are associated with your enterprise account, if a member of your organization (who has that domain) doesn’t already have a Tracker login, when they attempt to sign in at https://www.pivotaltracker.com/signin, we will automatically create a user for them. This will also work when the user visits your Tracker subdomain (yourcompanyname.pivotaltracker.com), and you’re also passing along the account_id attribute in your SAML response (see Custom User Attributes).

What Tracker needs from you

Your company owned email domain(s). Before an account can be enabled for Enterprise features/SAML SSO, at least one company owned email domain must be explicitly associated (“allow-listed”) with the enterprise account. This ensures that anytime someone attempts to login with your organization’s domain(s), they’ll be redirected to your IdP’s sign-in portal. Please email us at support@pivotaltracker.com to let us know what domain(s) we should allow-list with your enterprise account.

Configuring your IdP for SAML SSO

Using Tracker’s metadata endpoint

If your IdP supports using a metadata endpoint, you can skip the Service Providers (SP) details section below in favor of using https://www.pivotaltracker.com/auth/saml/metadata.

The metadata endpoint will always transmit the public key to our signing certificate, which some IdPs can use to check our signature on signed SAML AuthNRequests. However, by default we do not sign our AuthNRequests. If you require for yours to be signed, please follow the steps in the Signed SAML AuthNRequests section below.

Service Provider (SP) details

If your IdP does not support using a metadata endpoint/URL, please configure an application within your IdP with the following SP details:

Assertion consumer service (ACS)/Single Sign-On URL: https://www.pivotaltracker.com/auth/saml/callback
Audience URI/SP Entity ID: https://www.pivotaltracker.com
Default RelayState: {"account_id":your_Tracker_account_id} Your account ID can be found on your Account Settings page.
Name ID format: id We prefer to have a unique, unchanging user ID here, however we can also except an EmailAddress.
Application username: Email If field is not present in your IdP interface, OK to skip.

Custom user attributes

Tracker requires certain basic user attributes to be sent in the SAML response. After configuring an application for Pivotal Tracker within your IdP, the following basic user attributes will need to be defined:

email: The user’s email
first_name: The user’s first name
last_name: The user’s last name
id: The user’s ID (any unique identifier for the user that never changes)
account_id: Your Tracker account ID.

Upload your SAML Provider Metadata

After all the steps above have been completed, it’s time to upload your SAML Provider Metadata to your account by following the steps below. Please note, only the account owner or an admin may perform this action.

Click Accounts under your username at the top right of Tracker.
Select Manage Account for the account you wish to manage membership for, then click the Settings tab located above the listed plans.
Scroll down to the ENTERPRISE SETTINGS section, and select Choose File next to SAML Provider Metadata to upload your metadata file (in XML format).
Enable the Place metadata in testing mode setting. This ensures that your metadata is explicitly pointed at your subdomain (https://YOUR_COMPANY_DOMAIN.pivotaltracker.com) for testing purposes. See the Subdomain field under ENTERPRISE SETTINGS for your specific testing URL.
Select Save Changes

Signed SAML AuthNRequests

By default we do not sign our AuthNRequests. The metadata endpoint will always transmit the public key to our signing certificate, which IdPs can commonly use to check our signature on signed SAML AuthNRequests. If your IdP requires signed SAML AuthNRequests, follow the steps below to enable this setting.

Click Accounts under your username at the top right of Tracker.
Select Manage Account for the account you wish to manage membership for, then click the Settings tab located above the listed plans.
Scroll down to the ENTERPRISE SETTINGS section.
If your SP metadata has been uploaded (see steps above), you will see a setting for Sign AuthNRequests.
Enable the setting and select Save Changes.

Exchanging existing Metadata

Sometimes customers need to swap out the existing Metadata in Tracker with a new file, typically because the signing certificate is expiring and needs to be updated. To update your existing metadata, please follow the steps below.

Click Accounts under your username at the top right of Tracker.
Select Manage Account for the account you wish to manage membership for, then click the Settings tab located above the listed plans.
Scroll down to the ENTERPRISE SETTINGS section, and select Choose File next to SAML Provider Metadata to upload your metadata file (in XML format). You will also notice a red X to the right of your existing metadata - don’t click this as it will remove your existing metadata immediately. We recommend continuing with the steps below to ensure a smooth swap of the file.
If you prefer to test the new metadata before fully promoting it, we recommend selecting the Place metadata in testing mode setting before saving your changes. This ensures that your metadata is explicitly pointed at your subdomain (https://YOUR_COMPANY_DOMAIN.pivotaltracker.com) for testing purposes. While in testing mode, users will still be able to access Tracker with their standard Tracker credentials. See the Subdomain field under ENTERPRISE SETTINGS for your specific testing URL.
Select Save Changes.
After you’ve successfully tested the connection, disable the Place metadata in testing mode setting to fully promote the change.

Testing SP and IdP initiated logins

Now that you’ve uploaded your metadata and placed it in testing mode, it’s time to test your SSO connection!

To test SP initiated sign in: Please have someone on your end (who shares your company domain and is an active user within your IdP who’s been assigned the Pivotal Tracker application) visit your Tracker subdomain (https://YOUR_COMPANY_DOMAIN.pivotaltracker.com/signin) and attempt to sign in. See the Subdomain field under ENTERPRISE SETTINGS for your specific testing URL.
To test IdP-initiated sign in: Please have someone from your end (who’s been assigned the Pivotal Tracker application you previously created) attempt to access Tracker through your IdP user portal.

If both sign-in attempts are successful, it’s time to fully enable SSO by following the steps below.

Click Accounts under your username at the top right of Tracker.
Select Manage Account for the account you wish to manage membership for, then click the Settings tab located above the listed plans.
Scroll down to the ENTERPRISE SETTINGS section, and deselect the Place metadata in testing mode setting.
Select Save Changes