SAML Single Sign-on Setup
Whimsical supports Single Sign-on (SSO) based on the SAML spec, and it's included at no additional charge for all Organization Workspaces.
Table of Contents
* * *
1. SAML IdP Providers We Support
Please see the end of the article for screenshots that help you walk through setup for each provider.
Other - if you use another SAML IdP that isn't listed here (like Auth0), we should still be able to support it. Select Other from the drop-down to upload your XML. If this gives you any trouble at all, please reach out to Support for help via email or in the app!
* * *
2. Instructions for setting up SAML SSO in Whimsical
To begin setup within Whimsical, navigate to your Workspace Settings via this link or via the drop-down in the upper left of your screen.
We've tried to make the SAML SSO setup as simple as possible, and the SAML setup screen shows all the variables you will need to make SAML work for your workspace.
However, the naming of some SAML attributes varies depending on the Identity Provider (IdP), which is why this page is needed 🙂
There are some attributes that are the same for all IdP's:
Entity ID: https://whimsical.com
Name ID Format: EmailAddress
Username/Name ID: Email
Whimsical uses the e-mail address of the SAML user to identify them on Whimsical. This will come up with configuration options like "Name ID Format" or "Name ID". When in doubt, try to choose the option that will return the e-mail of the user.
❗Important note before we proceed:
Whimsical supports JIT (Just-in-time) account provisioning. That means that Whimsical will create an account for a user authenticating via SAML if necessary.
When you're setting up SAML in Whimsical, you can choose the default user role. You can choose between:
Editors - paid role with full ability to create & edit
Viewers - free role with read & comment only limited permissions
If you choose the default role as Editor, this may result in unexpected charges if a lot of new members sign up via SAML. Workspace admins can always change the member role from Editor to Viewer or Viewer to Editor later on:
If you already have a Whimsical account created before enabling SAML for a Workspace, you can continue using it with both means of authentication:
Log into your existing account, using the existing login method
Then log in using your SAML SSO provider
The e-mail address returned by the SAML IdP should now be added to your existing account, and you should be able to login with both authentication methods.
❗Note: A Workspace admin may choose to enforce SAML-only authentication method for a Workspace, which means that a user will still be able to log into their account using other login methods, but will require using SAML SSO before accessing the particular Organization Workspace with the SAML enforced.
* * *
3. Examples of how to set up some specific SAML SSO providers:
You can find Whimsical in Okta's Application Network, and see a setup walkthrough here.
Attribute mapping in G Suite does not happen automatically, but you should manually map the first name and last name attributes so that those get sent to Whimsical:
❗Note: Unfortunately, profile photo mapping is not supported.
Azure Active Directory
We're working on being listed in the Azure Active Directory Marketplace, but in the meantime here are a couple of gotchas for setting up AAD SAML authentication with Whimsical:
The EntityID and User Identifier format is still the same as before and listed at the top of this page
The Reply URL (ACS URL) can be found in your Workspace Settings
The User Attributes have to be WITHOUT Namespace, and the capitalization is important.
Example of a complete, working SAML setup:
Listing of all claims/attributes:
Example on how to remove the Namespace URI for a claim:
While we don't have specific integration support for Auth0 at the moment, we have successfully setup Auth0 integrations with this minimal setup:
Replace the Application Callback URL with the ACS URL provided in Whimsical, and configure the rest of the values like this.
There may of course be other values in your configs, but these are the ones that matter to the Whimsical SAML integration.
Also please note that you may have setup Auth0 differently, and may have different names for values inside of Auth0. But these are the mappings, formats and probes that work for an out-of-the-box setup.