SAML Single Sign-on setup
In this article:
- Supported SAML Identity Providers
- Instructions for setting up SAML SSO in Whimsical
- Existing Accounts
- Tips for disconnecting SAML SSO in Whimsical
-
Examples of how to set up some specific SAML SSO providers:
Whimsical supports Single Sign-on (SSO) based on the SAML ( Security Assertion Markup Language) spec for customers on our Org Plan.
Supported SAML Identity Providers
Please see the end of the article for screenshots that walk you through setup for each provider.
- OKTA (we also support SCIM Provisioning with Okta)
- OneLogin
- Ping Identity
- Google Workspace (formerly G Suite)
- JumpCloud
- Microsoft/Azure Active Directory
- Shibboleth
- 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 us via email or in Whimsical under the question mark in the bottom right corner.
Instructions for setting up SAML SSO in Whimsical
To begin setup, go to "Workspace Settings" which you'll find under your workspace name in the top left:
The SAML setup screen shows all the variables you will need to set up SAML for your workspace.
We've tried to make the process as simple as possible, however the naming of some attributes may vary depending on your Identity Provider (IdP), which is why this page is needed. 😉
There are some attributes that are the same for all Identity providers:
-
Entity ID: https://whimsical.com
-
Name ID Format: email@address.com
-
Username/Name ID: email@address.com
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 user's e-mail.
Important
Whimsical supports JIT (Just-in-time) account provisioning. That means that Whimsical will create an account for a user authenticating via SAML if necessary.
They'll be created with the role and permissions you choose, 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 default user role from Editor to Viewer or Viewer to Editor later on:
Existing Accounts
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 in to 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 log in with both authentication methods.
Note
Workspace admin may choose to enforce SAML-only authentication method for a Workspace, which means that a user will still be able to log in to their account using other login methods, but will require using SAML SSO before accessing the particular Workspace with the SAML enforced.
Tips for disconnecting SAML SSO in Whimsical
Sometimes, it may be necessary to switch off SSO, or to switch SAML IdP. Here are a few tips to make that as smooth as possible.
Before you do anything, make sure that you disable the "Require SAML to log in" option in the Whimsical SAML settings. Then, switch off the SAML connection.
Disabling SAML shouldn't affect your workspace in a bad way and folks will still be able to continue using Whimsical. However, those who have only created their accounts via SAML will be asked to create a password the first time they'll try to log in after SAML is disabled.
If you set up SAML again with a different provider, you should follow the steps above as if it was the first time connecting.
Examples of how to set up some specific SAML SSO providers:
Google Workspace
Attribute mapping in Google does not happen automatically, but you should manually map the first name and last name attributes so that those get sent to Whimsical:
Note
Profile photo mapping is not supported. But you can add your own profile picture in Whimsical. Read this article to learn how.
Azure Active Directory
Use the pre-built Whimsical integration in the Azure Active Directory Marketplace for the easiest setup experience.
If the Integration doesn't work for you, or you want to set up things manually, here are a few gotchas to keep in mind:
-
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 of how to remove the Namespace URI for a claim:
AuthO
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.
{ "mappings": { "given_name": "givenName", "family_name": "LastName", "picture": "PhotoURL" }, "nameIdentifierFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress", "nameIdentifierProbes": [ "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" ] }
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.
OneLogin
- In OneLogin go to "Applications", and click "Add app".
- Search for "SAML Custom Connector (Advanced)".
- Enter the display name "Whimsical" and ensure that "Visible in portal" is checked.
- Optional, upload this icon to more easily identify your Whimsical app in OneLogin. To save this file to your computer right click and choose "Save Image As...":
- Hit "Save", then go to the "Configuration" tab on the left.
- Open the "More actions" dropdown in the top right corner and select "SAML metadata" this will download an XML file to your computer.
- Go to your workspace settings in Whimsical, enable "SAML SSO", and select OneLogin as your identity provider.
- Click "Select file", open the XML file you just downloaded, and hit "Save".
- Copy the ACS URL and paste it into the "ACS (Consumer) URL" and "Recipient" fields in the Configuration tab in OneLogin.
- Copy the Entity ID and paste it into the "Audience (EntityID)" field on the same tab.
- Paste this string into the "ACS (Consumer) URL Validator" field on the same tab:
[-a-zA-Z0-9@:%._\+~#=]{2,256}\.[a-z]{2,6}\b([-a-zA-Z0-9@:%_\+.~#?&//=]*)
- Save the configuration in OneLogin, then go to the "Parameters" tab.
- Click the plus button on the right to add a new parameter.
- Name it "FirstName", check the box to "Include in SAML assertion", then click "Save".
- Select "First Name" from the dropdown for value and save the parameter.
- Repeat steps 14 and 15 but name the field "LastName" and choose "Last Name" as the value.
- Click "Save" in the top right corner to save your parameters.
You can now assign Whimsical login to your users in OneLogin. 👍