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 Free trial, Startup plans, or Pro 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 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 (yourcompanyname.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

Upon subscribing to an Enterprise plan, the Tracker Support team can enable SSO for your account. Before we can do that, we’ll need a couple things from you.

  • Please send a copy of your IdP’s metadata to tracker@pivotal.io so we can upload it to your account.
  • Before an account can be enabled for Enterprise features/SAML SSO, at least one company owned email domain must be explicitly associated with the enterprise account. This means that any time someone attempts to login with your organization’s domain(s), they’ll be redirected to your IdP’s sign-in portal. Please let us know what domain(s) we should associate 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 email us at tracker@pivotal.io and we’ll make sure your Enterprise account supports signed requests.

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.

Testing SP- and IdP-initiated login

After all the steps above have been completed, it’s time to test out SP- and IdP-initiated login! By now you would have already provided us with any company owned email domains you’d like associated with your Enterprise account, and we would have “soft-enabled” them. Soft-enabling allows us to perform testing on your Enterprise account without forcing all users with your company domain(s) to be redirected to your IdP sign-in portal.

  • 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) visit your Tracker subdomain (yourcompanyname.pivotaltracker.com) and attempt to sign in. If you’re not sure what your Tracker subdomain is, reach out to us and we’ll let you know.
  • 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 now time for the Tracker Support team to enable SSO for the entire account (if not, we will work with you to troubleshoot any issues). If you prefer that happen on an agreed upon date/time, just let us know.

Previous
Enterprise overview
Next
Configuring ADFS with Tracker for SAML SSO