Single Sign On is one of those computing magic tricks where the magicians never reveal their secrets. Sometimes, us muggles are asked to perform works of sorcery and illusion and we have to put on a good show.
I recently tasked myself with setting up our Mist environment to work with our central SSO system. We were about to begin letting our helpdesk users into the Mist UI and I realized that there needed to be a better way to control access than the local accounts we had originally set up. Mist does support SAML out of the box, and I know our SSO solution supports SAML, so how hard could it be?

SSO is something best left to the “professionals”. Not because it’s a terribly difficult technology, but because it is so nuanced and comes with a long list of vocabulary words that the un-initiated (SAML pun intended), might not completely understand. Here’s a quick summary, and by no means are my definitions going to be the textbook-correct ones:
SSO – Single Sign On. System which lets users authenticate and be authorized to use other systems. Think of it like AAA for the application layer.
SAML – Secure Authentication Markup Language. This is to SSO what JSON is to a good API.
IdP – Identity Provider. The system which provides a method of authenticating user accounts.
SP – Service Provider. The application you are trying to log in to.
Certificate – The magical file of random numbers and letters which tells two systems to trust each other.
Metadata – More magical information that IdP and SP systems use to learn about each other. Vaguely human-readable XML that has answers you’ll need.
Attribute – Data that is communicated between an IdP and an SP other than the username. Things like First Name, Last Name, Department, etc.
So, how do we set this up for Mist? Well, Mist does provide some documentation: https://www.mist.com/documentation/category/saml/ but it didn’t translate exactly to what our system is. (We are using CAS, by the way.) Here’s how I did it:

You’ll notice a few things are already filled out for you – Name (which you just entered), Type (which is SAML), and the ACS URL and Single Logout URL. Everything else you need to figure out.
<EntityDescriptor entityID="blahblahblahblah">.-----BEGIN CERTIFICATE-----
BLOCK OF RANDOM NUMBERS AND LETTERS HERE
-----END CERTIFICATE-----
The Signing Algorithm I left at the default of SHA256. This worked in my case, but if your certificates are using another method, you’ll need to change that. The IdP admin I was working with didn’t know what it was, so I think we just got lucky by picking SHA256. Fortunately, there’s not a long list to choose from, so you can quickly run through them all if you need to make a brute-force selection.


You may want to create more roles in your scenario. Say for local IT staff in a remote/branch office, you might want to give them Site Admin access. You’ll create a role for each site. (If you have the quintessential 500 sites, you can use the Mist API to create these roles too! The Mist API can be used to do everything we’ve done here! https://api.mist.com/api/v1/docs/Org#sso-saml)
These Roles will also be used in the IdP backend, so make sure you provide the Name of each role to your IdP admin. They are case-sensitive and spaces/punctuation must match as well. The IdP admin will need to program a bit of logic that maps, say an Active Directory Security Group, to each role. You’ll want to figure out if you have an existing AD Group that makes sense, or if you’ll need to create new ones specific for Mist. (You might already have an AD Group for your Helpdesk staff, for instance, but not one for your Wi-Fi Engineers.) You’ll want to document what the groups being used are, so that in the future when you have to add/remove users’ access to Mist you know what groups to modify. The code that our IdP admin had to program looked something like:
return (attributes['memberof'].contains('CN=Network Engineers,OU=IT Department,OU=Security Groups,DC=domain,DC=example,DC=com'))?'Super User':''
That essentially says, if the user is a member of the Network Engineers group in AD, then pass the role “Super User” back to Mist, otherwise return a null string (”) which indicates that the users is not authorized to access the Mist system. Obviously, the logic needs to be a bit more complex if you have more Roles to assign, and every IdP system handles this in a different way.

But first, open a new browser tab and paste the following URL into it: https://api.mist.com/api/v1/orgs/:org_id/ssos
Then, replace the :org_id bit with the Organization ID from the Mist UI so it looks something like https://api.mist.com/api/v1/orgs/12345678-abcd-1234-5678-1234567890ab/ssos and browse to that page. You’ll get to something that looks like the following:

That "id" value is what you’re after. Open another browser tab and paste the following URL into it: https://api.mist.com/api/v1/orgs/:org_id/ssos/:sso_id . Replace the :org_id bit again with your Organization ID, and then also replace the :sso_id bit with the "id" field we just discovered.
It should look something like
https://api.mist.com/api/v1/orgs/12345678-abcd-1234-5678-1234567890ab/ssos/11111111-2222-3333-4444-555555555555/metadata and when you browse to it, you should get:

The "acs_url" and "logout_url" are the same as you saw in the GUI. The "entity_id" and "metadata" lines are the new information we’re after. Provide them to your IdP admin. But, here’s a big gotcha! The entity_id displayed here is actually wrong! You’ll need to provide an entity ID to your IdP admin that looks more like: https://api.mist.com/api/v1/saml/REDACTED/login With the REDACTED part matching the part that is unique to your configuration in Mist. So, if the /metadata page showed:
"entity_id": "https://saml-12345678.mist.com" you’ll want to actually use the entity ID https://api.mist.com/api/v1/saml/12345678/login . Strange? Yes. Undocumented? Also yes. Fortunately Mist Support knows what they’re doing and was able to tell me about this while I was setting SSO up.
Your IdP admin probably also wants the "metadata" line as well. You should see that it is just XML in there.
You IdP admin will also want to know what Attributes to send to the Mist SP. You should provide “FirstName”, “LastName”, and “Role” in addition to the “NameID” formatted as an email address.
https://login.example.com/some/long/url/here/Unsolicited/SSO?providerId=https://api.mist.com/api/v1/saml/12345678/login . Going to that URL (in a private browser tab!) brought my to my SSO login page, and then redirected me to Mist after I logged in.
The scary bit here for me is that “any existing API tokens will be deleted”. Since I’m a heavy user of the Mist API, I needed to make sure that my tokens would remain active. SSO users in Mist cannot get user-specific tokens for using the API. Instead, you’ll need to keep a local account in Mist which holds tokens, or better yet, use Org-Specific Tokens for your scripts/apps that you’ve made. Click convert, and you’ll be logged into Mist with your shiny new SSO account. Not much will look different.
SSO Accounts do not appear in the Organization>Administrators page in Mist (or the equivalent API), but they will show up in Audit Logs. If you want to know who has what access to Mist, you’ll need to look in your Active Directory (or similar) that your IdP refers to.
Pro Tip! That IdP-Initated login URL is pretty hard to remember, right? Ask your load balancer admin to create a 301 Redirect for you! Make a DNS name like mist-login.example.com and have it point to your company’s load balancer. Then, the load balancer can respond with an HTTP 301 Redirect and have a browser go to the long, complicated URL instead! (A CNAME in DNS won’t work, as we need to not only redirect the domain name, but also the path and querystring. CNAMEs only redirect the domain name, nothing else.)
After an account has successfully logged into Mist once using an IdP-Initated login, you can do SP-Initiated logins from https://manage.mist.com/ if you choose. You can also keep doing IdP-Initated logins too. Personally, that’s what I’ve been doing as I’m not prompted to enter my email address into Mist’s login page if I’ve already signed into SSO for the day. You should, however, check that the SP-Initiated login does work while you’ve still got your IdP admin working with you. Again, private browser tabs are your friend here.
That’s about it. SSO is not trivial to setup, and Mist’s implementation of it is a bit arcane, but it’s something that you’ll have to do once and never touch it again.
Pro Tip! I’ll also mention the browser plugin SAML Tracer (Firefox: https://addons.mozilla.org/en-US/firefox/addon/saml-tracer/, Chrome: https://chrome.google.com/webstore/detail/saml-tracer/mpdajninpobndbfcldcmbpnnbhibjmch?hl=en). It’s great for debugging SSO processes. Basically, install this plugin, open it up, and start logging into something. It will sniff the traffic between the IdP and SP and display it in a nice format for you. Messages identified as containing SAML are highlighted and decoded

Another Pro Tip! Mist’s API will provide information on failures and error messages that the SP backend is logging, which could be helpful to you if when you get stuck setting this up. https://api.mist.com/api/v1/orgs/12345678-abcd-1234-5678-1234567890ab/ssos/11111111-2222-3333-4444-555555555555/failures is the URL to use. It’s the same as the /metadata URL from earlier, but it’s /failures instead. I don’t know how far back these logs are kept, but you probably won’t care much about them after the initial setup of SSO.
Because I don’t say it enough, Mist Support is awesome. If you get into trouble configuring SSO, you should reach out to them. They can sort you out in no time.