(Internal) SAML identity authentication

🔍 Articles in This Section

Please use the following list to see additional internal articles regarding the SAML Identity Authentication:

• (Internal) SAML identity authentication (📍you are here)

📖 Customer-facing Resources

• SAML configurations in Gem

In addition to OAuth 2 (our primary authentication method), we also support SAML which notably enables us to integrate with Okta’s access management system. We have successfully used SAML to integrate with the following identity providers:

• Okta
• GSuite
• OneLogin
• Ping Identity PingFederate

Enabling SAML-based authentication requires configuration setup on our end and the customer’s end. Also, local development and testing isn’t as plug-and-play as other parts of our codebase.

Our SAML integration supports the following functionality out of the box:

• SP-initiated SSO
• IdP-initiated SSO
• JIT (Just-in-time) account provisioning
• HTTP Binding Redirect and HTTP Binding POST SP-initiated login

Setting up SAML for a Customer

Setting up SAML for a customer is a multi-step process. As an overview, the process entails:

1. Swap configuration data with the customer
2. Test the end-to-end login flow
3. Enforce SAML login for the team

This works very well for Okta. If the customer is using another identity provider, see below for tips.

Swap Configuration Data with the Customer

We need to both 1) get the customer’s configuration data and 2) send the customer our configuration data. The configuration data also needs to be handed off to the eng oncall. When getting the customer’s configuration, we should also ask if they want to test the login flow with specific users.

Requesting the Customer’s Configuration Data

Generally, we can just ask the customer to provide their IDP metadata XML file. This is something that is provided by most identity providers, like Okta. However, sometimes the customer won’t provide the XML file, so we need to request specific pieces of information instead. In that case, we need to request the Single Sign-On URL, Identity Provider Issuer, and X.509 Certificate. The last item is a public key.

At this time, you should also ask the customer if they’d like to have specific users test the end-to-end login flow before enforcing it for the whole team.

Here’s a sample email template that you can use.

Sending the Customer Gem’s Configuration Data

First, pick the team domain the customer is using. For example, Nextdoor might use nextdoor.com. Anywhere you see below, paste in the team domain you’ve picked. This is somewhat specific to Okta… but the concepts carry over to other Identity Providers.

Standard Template:

• Single Sign On URL: https://www.gem.com/api/saml/sso/
• Audience URI (SPEntity ID): https://www.gem.com/api/saml/sso/
• Application username: email
• NameID Format: email (urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress)
• Attribute Statements:
• first_name (Name Format: Basic) should map to the user’s first name
• last_name (Name Format: Basic) should map to the user’s last name
• Name ID format: Default (for Okta) otherwise Email Address

The following fields should be left in their default states:

• Default RelayState

ID-based Option Template:

Our more sophisticated Enterprise customers would like to use a persistent primary identifier instead of a user’s email address. We support this configuration, but the template for configuration data is a bit different:

• Single Sign On URL: https://www.gem.com/api/saml/sso/
• Audience URI (SPEntity ID): https://www.gem.com/api/saml/sso/
• Application username: <unique-persistent-id-of-customer’s-choosing>
• NameID Format: persistent (urn:oasis:names:tc:SAML:2.0:nameid-format:persistent)
• Attribute Statements:
• email (Name Format: Basic) should map the user’s primary email address
• first_name (Name Format: Basic) should map to the user’s first name
• last_name (Name Format: Basic) should map to the user’s last name

The following fields should be left in their default states:

• Default RelayState

IDP-Specific Configuration Data Details

• Microsoft Azure AD (Active Directory)
• first_name: user.givenname
• last_name: user.surname
• The azure attribute values are a little unclear, so teams may find themselves blocked if they’re not familiar with configuring SAML-SSO for other apps. User/IT will need to create two additional attributes with names/values as follows:

Setting up SAML Configuration

There is a dashboard on the Team Admin Settings Page that now allows SAML configuration to be self serve. Please refer to the associated help article that walks customers through the process of getting setup with SAML.

Note: If the team does not have any existing user accounts when you’re setting up SAML, they can’t go into the team admin page to set it up themselves. So you will have to configure it in the SAML tab in the support dashboard.

At this stage, you should have all of the following required information:

• The team domain you chose for the customer
• The configuration that the customer sent to you (generally the XML metadata file)
• The list of users (if any) that the customer wants to test the end-to-end login flow with

With the above information acquired, you can now point the customer to the help article on getting setup with SAML or guide them through it yourself. The one stipulation is that the customer must be a team admin for their team so that they can access the Team Admin Settings Page.

Test the End-to-End Login Flow

If the customer specified that specific users test the login flow, simply ask those specific users to try to log in to Gem. Otherwise, ask anyone to try logging in. They should be able to log in, connect to their email, and being using Gem. If there are any issues, please debug with the eng oncall.

Enforce SAML Login for the Team

Once we’ve verified the end-to-end login flow works, we want to turn on SAML login for the entire team.

If the customer didn’t specify specific users for testing, then we’re done, congrats!

However, if the customer did specify test users, you will need to edit that specific configuration so that it is enforced globally:

1. Click Edit for the specific configuration.
2. Check the Enforced box.
3. Save your changes.

Helpful Tips

• Missing first_name/last_name when configuring SAML
• Make sure the customer has set the first_name and last_name attribute statements. Also make sure that their test user has a first name and last name set in their identity provider.

Setting upan“namespacedteam”SAMLloginfor a Customer

We now support multiple Gem teams/instances for a single domain via multiple SAML configs. This feature comes with the caveat that a user can be a member of only one team. The team they first sign in with will be the team that they’re assigned to.

This implementation is appropriate for a team that has requested an isolated gem team for one of their teams. This team, like any other Gem team, will not be able to see their “parent” teams’ data at all, and the data will not be able to be migrated between the two gem teams.

This feature is only supported via SAML auth – it will not work for OAuth-based customers.

Step 1: Create a “namespaced****team”

To create a namespaced team, create a team using the naming convention _. For example, if we wanted to create an exec team for gem.com, the team’s name that we’d create in the support dashboard would be exec_gem.com.

Step 2: Create a SAML login config for the team

The SAML config for an alternative team must be set up by us – it cannot be created during our self-service flow. To install, follow the above documented process. The will be the namspaced name created above (e.g. exec_gem.com).

Step 3: Instruct users to register via the SSO initiated login

To register for a “namespaced” team, the user must use the SSO-initiated login (e.g. clicking the tile in their SSO provider), rather than logging in with their email address on gem.com. After initial registration and log in, they will be able to log in via both their SSO tile and our gem.com login box.

Note: The greenhouse webhook url created for these type of teams by the extension will be wrong – they should use the namespaced team name (e.g. exec_gem.com) in the url. Seethis thread for an example.

• Setting up SAML for a Customer
• Swap Configuration Data with the Customer
• Requesting the Customer’s Configuration Data
• Test the End-to-End Login Flow
• Enforce SAML Login for the Team
• Helpful Tips
• Setting upan“namespacedteam”SAMLloginfor a Customer