Configuring Single Sign On

Single Sign On must be enabled for your account. If you're interested in Single Sign On, please contact support.

Getting started

Message provides a Single Sign On service that allows your organization control who has access to your Message account.  The service is pretty straightforward to configure, but you'll need to work with your account manager or implementation specialist to get it set up.

Before you begin, let's talk a little bit what you'll need to know.  Message SSO is a SAML 2.0-based Single Sign On service.  Because it's SAML 2.0, it will also work with other SSO services that support SAML, including Shibboleth and Active Directory.  You should confirm with your identity provider that it will support SAML 2.0 before trying to configure it with Message.

Our service is SP-initiated SSO, which means our web application will initiate the sign-in process. When configured, you'll receive a unique login URL that's assigned to your account.  When your users go to that login URL, they will be presented with your organization's login screen instead of the standard Message login screen.

At this time, Message does not offer an IDP-initiated option.

To get started with the configuration, you'll need to do 3 things:

  1. Configure the service on the your identity provider.
  2. Provide Message your IDP metadata.
  3. Configure the IDP metadata mapping to match what Message expects.

Configuring the service on your identity provider

We can't walk you through setting up the service on your identity provider - every provider is a little different - but here's what you'll need to know:

Provide Message your IDP metadata

Once you have the initial Message configuration setup in your identity provider, you should be able to retrieve IDP metadata for the service.  This metadata will include the issuer's name, expiration information, and keys that can be used to validate the SAML authentication response (assertions) that are received from your identity provider.

You will need to provide this information to Message so that we can configure things correctly on our end.  It can be provided as a file, copy+pasted into an email or sent as a link directly to publicly-available metadata.

Configure the IDP metadata mapping 

This is where setting up SSO is most likely going to encounter problems for your organization.  When an SSO login is successful, the identity provider passes along some information on the user to Message (the SAML 2.0 assertion). The information that your provider passes must match what Message expect, or else we'll be unable to complete the login and give the user access to their Message account.

Message is looking for 5 attributes that can be passed:

  1. uid: the unique identifier used by the identity provider
  2. givenName: the first name of the user
  3. sn: the last name of the user
  4. mail: the email address of the user
  5. telephoneNumber: the mobile number of the user (optional)

When passing those attributes to Message, it's crucial that the AttributeName in the assertion matches the names bolded above.  If the AttributeName does not match, Message will be unable to match the user to their Message account.

Right now, Message does not allow customization of those AttributeNames.

Additionally, a NameID value must be passed as part of the SAML response. Most SAML 2.0 identity services will include this automatically.  If you are using ADFS, the NameID must be set manually. You can follow these instructions to set the NameID to your preferred attribute.

Adding users

Once you've configured SSO, received the login URL from your account team and confirmed it's triggering your login screen, we can start adding users to Message.  Users are based on email address in Message - so it's important to add the user's email that matches the mail value that is passed in the assertion (from the last step).  This only becomes a problem if your users have multiple email aliases - whatever is their primary email and is passed in the assertion must be the email you use to invite them.

When a user is added, they will receive an email from Message inviting them to confirm their account. They have to confirm their account before they're able to login. While SSO will govern user authentication, we still require that users confirm their account and that admins manage permission levels within Message.

Common Issues

For most institutions, SSO setup is straightforward and painless, but it's not always so. There are a couple of common issues that may crop up:

  1. Payload Encryption
    We support transport layer encryption (HTTPS) but we do not currently support encrypted SAML payloads. Organizations will have to disable SAML payload encryption.
  2. Metadata Mismatch
    Unfortunately, Message's SSO does not currently have an option for mapping attributes. Your organization will have to match the AttributeName as listed above. This is the most common problem when SSO fails.



Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request



Article is closed for comments.