Integrating your SAML Identity Provider

Parsec for Teams provides a generic authentication provider for SAML based authentication, which allows owners of a team on Parsec to manually configure any SAML-enabled Identity Provider (IDP) system. Parsec supports Service Provider initiated SSO (Single Sign-On) and the Identity Provider initiated SLO (Single Logout). Parsec does not support Identity Provider initiated SSO.

Table of contents

Important notes
Setting up SAML
    Okta
    Azure AD
    Google SSO
    Other
SAML alias, enforcement and session settings

 

Important notes

• SAML-enabled users cannot change their password, use their old Parsec password, or set up MFA within Parsec. The Identity Provider will handle these operations instead.
• Administrators can choose an alias for their team's SAML authentication in the Teams admin portal, to be used instead of your Team ID in order to login. Each member of your team will need to know this alias to log in via SAML.
• Once a user sets up SAML login, they will need to use SAML as long as they're a member of your team.
• Default settings force users to re-authenticate every 8 hours on their client devices. However, active users automatically refresh their session based on activity. Team administrators can increase the re-authentication period to up to 720 hours in the Teams admin portal.
• IDP administrators can remove login access to Parsec via their Identity Provider. This will not invalidate a user's current session, but it will prevent them from logging in again after the session refreshes.
• To remove someone from a Team, an Administrator will have to remove them from the Team on the Teams admin portal.
• You cannot initiate SAML authentication via your Identity Provider. You will receive a Relay State Error. Parsec only allows for logins to initiate from the Parsec login page or from within our app.

Reference Architecture

Setting up SAML

You will want to first register Parsec on your Identity Provider (IdP) and add the following SAML endpoints to it. The full endpoints are shown in the Teams administration portal where you can copy and paste them in to your IdP configuration for Parsec.

• ACS: ACS means Assertion Consumer Service, and is used for establishing a session based on rules made between your IdP and the service provider it is integrating with.

• Metadata: Metadata, alternatively referred to as the entityID in some systems, refers to the configuration data for an IDP or an SP. In this case, the Metadata endpoint in Parsec refers to your Parsec Team’s metadata on the Service Provider end.

In addition to these endpoints, you must use the email format for the name ID field in your identity provider when setting up SAML for Parsec to associate your accounts. The next step is to add metadata provided by your IdP into the Teams panel.

Common SAML providers directions are shown below. Remember that Parsec does not need to provide a signing certificate for the integration to work.

 

Okta

Configure SAML App

• Visit the Applications section in Okta, and click Create App Integration

• In the new window, select SAML 2.0 as the method for sign on and click Next

• When you get to step 2. Configure SAML, use the ACS and Metadata endpoints provided earlier. Make sure to set the name ID format to EmailAddress and the Application username to Email

Configure Default Groups (Optional)

If you are not using SCIM to manage users and groups in Parsec, SAML users will not be assigned to a group in Parsec automatically. However, it is possible to configure default groups by sending additional claims in the SAML response. This will only apply to new users and will not retroactively assign existing users to the default group(s). The group(s) must exist in Parsec and have a matching name, a new group will not be created automatically. If you're using SCIM or don't want to assign people to a group by default you can skip ahead to the next section, this step is optional.

• Add a new claim using the name DefaultGroups and provide a comma delimited list of group name(s). If there are commas in the group name, surround the name with double quotes ("). The list may be with or without spaces after the separator (,).
  • <group_name>, <group2_name>, "<group3_name, location>", ...
  • <group_name>,<group2_name>,"<group3_name, location>", ...

OR

Upload Metadata To Parsec

Now, you just need to provide some IdP metadata to Parsec. In the SAML setup section at the Teams administration portal, you can either upload a metadata XML file, paste the raw contents of the metadata XML, or enter the IdP metadata manually, which your IdP will provide. The most convenient method for Okta is to just use the metadata XML, demonstrated below.

• Download the metadata XML from the link below in the settings page of the application you made

• Go into the SAML section in the Teams administration portal
• In the "Register IdP with Parsec" section, select XML
• Click Choose File and select the metadata XML you downloaded
• Click Parse Metadata

 

Azure AD

Configure SAML App

• Visit the Enterprise Apps area and create your own application for Parsec

• In the Parsec application you made, go into the Single sign-on section

• Select SAML

• Edit 1. Basic SAML Configuration and add the ACS and Metadata endpoints from earlier. Make sure that it's set as the default and then save

• Back in the main SAML page, edit 2. User Attributes & Claims making sure that you use the email field that your team uses to log in to Active Directory. Please note, your company might use user.mail or user.otheremail Make sure you're using the right email attribute for your organization for the NameID

Configure Default Groups (Optional)

If you are not using SCIM to manage users and groups in Parsec, SAML users will not be assigned to a group in Parsec automatically. However, it is possible to configure default groups by sending additional claims in the SAML response. Automatic assignment to default groups can only be assigned during initial provisioning and cannot be updated for existing users. The group(s) must exist in Parsec and have a matching name, a new group will not be created automatically. If you're using SCIM or don't want to assign people to a group by default you can skip ahead to the next section, these steps are optional.

• Add a new claim using the name DefaultGroups and provide the comma delimited list of group name(s). If there are commas in the group name, surround the name with double quotes ("). The list may be with or without spaces after the separator (,).
  • <group_name>, <group2_name>, "<group3_name, location>", ...
  • <group_name>,<group2_name>,"<group3_name, location>", ...

OR

• Your claims should look like this

OR

Upload Metadata To Parsec

Now, you just need to provide some IdP metadata to Parsec. In the SAML setup section at the Teams administration portal, you can either upload a metadata XML file, paste the raw contents of the metadata XML, or enter the IdP metadata manually, which your IdP will provide. Below are some instructions for some of the common providers.

• In 3. SAML Signing Certificate at the main SAML page, download the metadata XML

• Go into the SAML section in the Teams administration portal
• In the "Register IdP with Parsec" section, select XML
• Click Choose File and select the metadata XML you downloaded
• Click Parse Metadata

 

Google SSO

Configure SAML App

• Visit the Google Admin panel and go to Apps > Web and Mobile Apps > Add app > Add custom SAML app

• Complete the steps below:
  1. Provide a name for the SAML app
  2. Download the IdP metadata. You can also do this later.
  3. Use the ACS and Metadata endpoints specified earlier, demonstrated below. Also make sure to set the name ID to Basic Information, Primary Email, and Name ID Format as EMAIL
  4. Click Finish

Configure Default Groups (Optional)

If you are not using SCIM to manage users and groups in Parsec, SAML users will not be assigned to a group in Parsec automatically. However, it is possible to configure default groups by sending additional claims in the SAML response. Automatic assignment to default groups can only be assigned during initial provisioning and cannot be updated for existing users. The group(s) must exist in Parsec and have a matching name, a new group will not be created automatically. If you're using SCIM or don't want to assign people to a group by default you can skip ahead to the next section, these steps are optional.

• Go to Directory > Users > More options > Manage custom attributes

• Click Add Custom Attribute
  • Category:  Default Groups
  • Name: Default groups
  • Type: Text
  • No. of values: Single Value
• Click Add

• In Directory > Users populate Default Groups with a comma delimited list of group name(s). If there are commas in the group name, surround the name with double quotes ("). The list may be with or without spaces after the separator (,).
  • <group_name>, <group2_name>, "<group3_name, location>", ...
  • <group_name>,<group2_name>,"<group3_name, location>", ...

OR

• Go to Apps > Web and mobile apps and edit your SAML app
• Add a new SAML attribute mapping
  • Google Directory attributes: Default groups
  • App attributes: DefaultGroups

Upload Metadata To Parsec

Now, you just need to provide some IdP metadata to Parsec. In the SAML setup section at the Teams administration portal, you can either upload a metadata XML file, paste the raw contents of the metadata XML, or enter the IdP metadata manually, which your IdP will provide. The most convenient method for Google SSO is to just use the metadata XML, demonstrated below.

• In the main page for the Parsec app you made on Google's panel, click Download metadata in the sidebar and then click the Download metadata button in Option 1
  • If you downloaded the metadata earlier, you don't need to complete this step

• Go into the SAML section in the Teams administration portal
• In the "Register IdP with Parsec" section, select XML
• Click Choose File and select the metadata XML you downloaded while creating a new app for Parsec. If you didn't download it, you can go to the main page of your app in Google and click "Download metadata" in the left sidebar
• Click Parse Metadata

 

Other

Parsec's SSO implementation works with any identity provider that supports the SAML authentication protocols. Generally, your identity provider will ask for the ACS and Metadata endpoints we provided above at some point. You can check the common providers we gave examples of to get a general idea.

You'll also need to choose a unique identifier for the name ID, for Parsec to associate your accounts. You must use the email address as the name ID.

If you're not using SCIM to manage users and groups in Parsec, you can assign default groups to users by sending an additional attribute in the user claims. The attribute must use the name DefaultGroups and the value should be a comma delimited list of group name(s). If there are commas in the group name, surround the name with double quotes ("). The list may be with or without spaces after the separator (,). Please note assigning default groups is optional.

• • <group_name>, <group2_name>, "<group3_name, location>", ...
  • <group_name>,<group2_name>,"<group3_name, location>", ...

Once that is done, you just need to provide some IdP metadata to Parsec. In the SAML setup section at the Teams administration portal, you can either upload a metadata XML file, paste the raw contents of the metadata XML, or enter the IdP metadata manually, which your IdP will provide. Depending on what your IdP provides, you'll use one of the methods below.

Metadata XML file

In case you find an XML metadata file, you can upload it into the Teams panel's SAML section, in the XML tab, and click Parse Metadata. This is the easiest method.

Raw Metadata XML

Some identity providers may give you the metadata XML in text form, which you can copy and paste directly into the "Metadata XML" field in the Teams panel. It'll look something like the image below.

Manually enter the IdP metadata

In case you can't find either of the things above, you can still manually enter the Entity ID, SSO URL and the x509 public certificate in the IdP tab.

For example, here's where Azure AD provides this information. It actually gives out two certificate formats, but here I download the Base64 one, open it with notepad and copy the Base64 string into the x509 Public Certificate field in the Teams panel. For other providers, you may see a raw string of characters, which you can copy and paste directly into the Teams panel.

If you have any trouble setting things up with your provider and you need help, contact us.

At this point, SAML should be set up. Make sure to assign the users in your IdP. After that, SAML users will join the team and consume a seat after logging in through Parsec for their first time via SAML.

 

SAML alias, enforcement and session settings

Some additional settings for SAML are in the Teams admin panel's 'Domain & SAML' and 'App Rules' sections. 

Team Alias

Team Alias is available to be changed under the Domain & SAML section. You can choose an alias for your team's SAML authentication to be used instead of your Team ID in order to login. Each member of your team will need to know the alias to log in using SAML. Keep in mind the alias is globally unique, so grab yours before someone else does.

Enforce SAML and session duration

These settings are available to be changed under the App Rules section, in 'Security settings'.

The Enforce SAML setting forces all team members except the owner to use SAML. If you choose to enforce SAML authentication across your team, people who are already on your team will not be able to log in with the password and email combination they may have created previously on Parsec. You should make sure every person on your team has been added to your IdP before enforcing SAML. If you do not do this, people will be locked out of their account.

Once you enforce SAML, you can no longer send team invites through Parsec, instead you must add members of your team directly from within your IdP. A member of your team can only go back to their email/password combination from before using SAML if they leave the team. When you're ready, you can choose to email your entire team immediately upon enforcing SAML across the organization, but before you do this, please choose an alias that is easy to remember.

The Client Session Duration setting lets you dictate how long team members remain authenticated before they have to log in again. As an example, in the image above, users will have to re-authenticate after 7 days of inactivity. If the user has been active, however, the session will auto-refresh for another 7 days until the user has been inactive or Parsec has not been running for 7 days.