Frequently Asked Questions
Q: What are the basics of Mist’s SSO implementation I should know?
A: Mist supports SAML2.0 based SSO in several parts of our product, with identical implementations. While this document is written for Admin SSO, we also support SSO for guest access, as well as PPSK self provisioning where the implementations are the same, except for the mandatory attributes. So this document can be applied to all of Mist’s SSOs.
A user account in Mist can be one of three types of accounts, based on how it authenticates to Mist; as a local account to Mist, and SSO account, or and OAUTH2 account. An account can only be one of those types. So an SSO account would always authenticate to Mist via the IdP (unless the user changes their account type).
Make sure to sign the IdP assertion and response and return the correct attributes in the assertion with correct capitalization of the attribute names.
Q: What IdPs does Mist Support for SSO Access?
A: Mist supports any IdP that supports SAML2.0.
Q: Does Mist support SP and IdP initiated SSO?
A: Yes, Mist supports both SP and IdP initiated SSO. With the caveat that the very first login for a SSO user to Mist must be IdP initiated. Please also note for SP initiated login the entity ID entered in the IdP must be the same as ACS URL.
Q: What attributes do I need to send in my assertion?
A: These are the attributes Mist expects in the SAML assertion:
Note the capitalization is important.
- NameID
- Role
- FirstName
- LastName
NameID is required. Role is required except when you configuredefault_rolevia API. FirstName and LastName are recommended, or else you will see ? ? as the user’s first and last names.
Q: What NameID formats do you support
A: NameID is used as the unique identifier for the user. We support email and unspecified. Most people use email, but you can really send anything as long as you configure unspecified in the Mist SSO configuration. If you use unspecified, you can send us most anything, as long as it is unique and consistent. You will see we generate a unique ID for the user within Mist with unspecified.
Q: What is Role used for?
A: Role is used to derive the permission the user should be granted. The role returned in the assertion would match to a Role in the Mist SSO Role config on the Org settings page. Please note the user permission is dynamically generated per SSO login.
Q: Can I return multiple roles for a user?
A: Yes, if multiple roles are returned and matched, we will take the superset of the permissions. Please note, by default all roles must be matched, otherwise the user will be denied access. To allow partial matching of roles, there is an API option ignore_unmatched_roles. Alternatively, there is also an API option default_role, when no roles are matched.
We accept multiple roles in a variety of formats in the assertion. Multiple roles can be sent as comma separated, multiple AttributeValue pairs, or with CN parsing. Here are a few examples:
Comma-separated “Role” attributes
<Attribute Name="Role"> <AttributeValue>"Employee,Mist,Developer"</AttributeValue> </Attribute>
# parsed list of roles
['Employee', 'Mist', 'Developer']
Multiple “Role” attribute values pairs
<Attribute Name="Role"> <AttributeValue>"Employee"</AttributeValue> <AttributeValue>"Mist"</AttributeValue> <AttributeValue>"Developer"</AttributeValue> </Attribute>
# parsed list of roles
['Employee', 'Mist', 'Developer']
Combination of comma separated and multiple AV pairs
<Attribute Name="Role"> <AttributeValue>"Employee,Mist"</AttributeValue> <AttributeValue>"Developer"</AttributeValue> </Attribute>
# parsed list of roles
['Employee,Mist', 'Developer']
Example of CN extraction – “role_attr_extraction”: “CN”,
<saml2:Attribute ="Role">
<saml2:AttributeValue>CN=Employee,OU=groups,OU=ou1,OU=ou2</saml2:AttributeValue>
<saml2:AttributeValue>CN=Mist,OU=groups,OU=ou1,OU=ou2</saml2:AttributeValue>
<saml2:AttributeValue>CN=Developer,OU=ou1,OU=ou2</saml2:AttributeValue>
</saml2:Attribute>
# parsed list of roles
['Employee’, ‘Mist', 'Developer']
Q: How can I troubleshoot SSO failures?
A: For admin SSO, the user will see a failure reason. As an administrator you can view failures via API endpoint /api/v1/orgs/:org_id/ssos/:sso_id/failures which provides the failure reason as well as the assertion as we received it.
Q: Do I need to manually provision my SSO users within Mist?
A: No you don’t. Access for SSO users is granted on demand by your IdP. That is to say SSO users are authenticated by the IdP, not but Mist. The access level to the Mist Dashboard is controlled by the role attribute returned in the assertion matching to a role defined in Mist.
Q: How do I know which SSO users have accessed my Org?
A: You would check the Audit Logs under the Organization tab. You would see a log similar to: Austin Powers austin@groovy.com Login with Role “Groove-Master”
Q: Does Mist have a metadata file?
A: Yes, it can be found /api/v1/orgs/:org_id/ssos/:sso_id/metadata or /metadata.xml.
For example:
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" entityID="https://saml-x6qlonl8.mist.com" validUntil="2032-03-29T00:44:08.503310+00:00"> <md:SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"> <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://api.mist.com/api/v1/saml/x6qlonl8/logout"/> <md:NameIDFormat> urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified </md:NameIDFormat> <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://api.mist.com/api/v1/saml/x6qlonl8/login" index="0" isDefault="true"/> <md:AttributeConsumingService index="0"> <md:ServiceName xml:lang="en-US">Mist</md:ServiceName> <md:RequestedAttribute Name="Role" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" isRequired="true"/> <md:RequestedAttribute Name="FirstName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" isRequired="false"/> <md:RequestedAttribute Name="LastName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" isRequired="false"/> </md:AttributeConsumingService> </md:SPSSODescriptor> </md:EntityDescriptor>
Q: I need multiple SSOs in my Org. Does Mist Support that?
A: Yes, absolutely. Multiple SSOs within an Org are supported. Keep in mind, while an organization can have multiple SSOs, and a user can have permissions to multiple organizations, an SSO user in Mist can only “belong” to one SSO. This is typically most relevant when you have a “dev” and “production” SSO and use the same email for both.
Q: I have multiple organizations, can I use SSO with multiple Orgs?
A: Yes, this is also possible. It can be handled in two ways. First you have a “home” Org where you have the SSO. Then you can manually invite users to your second Org. When they login they would see both Orgs listed. The second way is to use our MSP feature (which is a controlled access feature). Where you place the SSO at the MSP Level and based on the role returned, users would have access to the MSP, or just specific orgs in the MSP.
Q: What happens when I delete an SSO within Mist?
A: When you delete an SSO, it will automatically delete all the user accounts within Mist associated with that SSO. This is particularly useful when migrating from one SSO to another, such as “dev” to “production.”
Q: How do API tokens work with SSO users?
A: SSO users are able to use Org API Tokens. Super Users can create Org API with necessary permissions. SSO users do not support “user based” API tokens. Alternatively, local service accounts can be used as well based on customer preference.
Q: Do I need a local user within Mist?
A: It is recommend to keep a local user as super user to the org to ensure you do not get locked out of the org, or in the event of an issue with the SSO, such as cert expired.