Miro's SAML-based single sign-on (or SSO) feature will provide your end-users with access to the Miro application through an identity provider (IdP) of your choice.
Miro also supports SCIM with any Identity Provider of your choice (both SP- and IDP-initiated logins).
In this article:
- Configuring SSO
2.1 Configure your identity provider
2.2 Enable SSO option in Miro
2.2.1 Domain verification for SSO
2.2.2 Configure Just In Time Provisioning for new users (optional)
- Possible Issues and How to Resolve Them
Once SSO is enabled for the Enterprise account, the following rules apply to the end-users:
- The SSO process is applied to the corporate domains that you add to the SSO settings. Your company account's end-users with the corporate domains must log into Miro via the SSO option using their identity provider credentials.
Other authorization options (the standard login+password, Google, Facebook, Slack, and O365 buttons) are disabled for them.
This also means that you can use the same Identity Provider configuration with multiple Miro Enterprise accounts for as long as different accounts claim different domains. However, you will only be able to provision via SCIM to one single Miro Enterprise account (since every Enterprise account has a unique token but your SCIM configuration will accept only one of them)
✏️ End-users with other domains are not required to use SSO and should instead log in using the standard methods. This scenario exists for guests, independent contractors, etc. who have access only to certain company boards and might not have profiles with your identity provider.
- If an end-user is a member of team workspaces outside the Enterprise umbrella they are still required to log in via SSO as soon as the feature is enabled. However, they will be able to access other teams and accounts. If you wish to also prevent your end-users from doing that, check out the Domain Control feature.
- The end-users are not allowed to change their passwords or edit their names, last names, or profile pictures in Miro. The data is instead automatically attributed by your identity provider upon successful login.
FirstName and LastName attributes are updated after every successful user authentication if SAMLResponse contains new non-empty values.
✏️ However, if you need to change your end-users email addresses, you can do so only via SCIM.
If you do not use SCIM then the following procedure is required: the email address change needs to first be made on the Miro side (please reach out to the Support Team for assistance) and then on the identity provider side before an end-user tries to use their new credentials to log into Miro. Our system recognizes the user by their email address - if the system is not notified about the change prior to the next login, the person will be recognized as a new user and will have a new profile registered instead of being logged into their existing profile.
Step 1: Configure your identity provider
Feel free to use any identity provider of your choice. The how-tos for the most popular identity platform solutions that provide a pre-configured Miro application link can be seen below:
First, go to your identity provider's configuration panel and follow the provider's instructions to configure Single Sign-On.
Then be sure to add the following data (however, depending on the identity provider you may have more or fewer fields to be filled out. We recommend skipping optional fields or set everything to default values).
- Protocol: SAML 2.0
HTTP Redirect for SP to IdP
HTTP Post for IdP to SP.
- The service URL (SP-initiated URL) (aka Launch URL, Default Relay State, Reply URL, Relying Party SSO Service URL, Target URL, SSO Login URL, Redirect URL, Identity Provider Endpoint, etc): https://miro.com/sso/saml
- Assertion Consumer Service URL (Allowed Callback URL): https://miro.com/sso/saml
- Identifier (Entity ID, Relying Party Trust Identifier): https://miro.com/
- Signing Requirement:
An unsigned SAML Response with a signed Assertion
A signed SAML Response with a signed Assertion
- SubjectConfirmation Method: "urn:oasis:names:tc:SAML:2.0:cm:bearer"
Identity Provider SAML-response must contain Public key x509 certificate issued by the Identity Provider.
Miro will accept:
- An unsigned SAML Response with a signed Assertion
- A signed SAML Response with a signed Assertion
Detailed examples can be found here. Encryption and Single Log Out are not supported.
User Credentials (Claim Types):
- Required Attribute (aka SAML_Subject, Primary Key, Logon Name, Application username format, etc) - NameID: equals a user’s email address (please do not mix with EmailAddress which is usually a separate attribute) - <NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:email">
Optional attributes to be sent with the assertion:
- “FirstName” or "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname" - It will be used to update the display name every time Miro user successfully logs in via SSO;
- “LastName” or "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname" - It will be used to update the display name every time Miro user successfully logs in via SSO;
- “ProfilePicture“ - The encoded URL of the image that will update the current avatar each time Miro user successfully logs in via SSO
Again anything else can be set to default or unspecified.
Miro SP metadata file (XML) can be downloaded here.
See detailed SSO and SCIM schema here.
Step 2: Enable SSO option in Miro
It is strongly recommended to configure the feature in the incognito mode of your browser. This way you keep the session in the standard window, allowing you to switch off the SSO authorization in case something is configured incorrectly. If you wish to set up a test account before enabling SSO on production, please request it with your Account Executive or reach out to the Support Team for assistance. Only those who configure SSO will be added to this test account.
To enable SSO for your Miro Enterprise account, go to the Settings > Security, enable the SSO feature and specify the following values:
- SAML 2.0 Endpoint URL (in most cases it opens your Identity Provider's page where your end-users are to enter their credentials)
- Public Key x.509 Certificate (issued by your Identity Provider)
- The list of domains allowed/required to authenticate via your SAML server.
Domain verification for SSO
After you enter a domain name, you will be required to verify it. Enter the email address from the added domain to prove that you represent it and the system will send you a verification letter to complete the process.
Until the domain is added to the list and verified the SSO processes are not applied to it (if the field does not contain any confirmed domains no users are affected by SSO).
⚠️ The requirements for successful verification are as follows:
- The person who performs the verification (initiates and/or completes it) must be a Company Admin. If you are a Company Admin and wish to send the verification letter to the email address that belongs to a person who's not a Company Admin they may give you the confirmation link from their letter so you could complete the process.
- The email address used must be real (and able to receive letters).
- Public domains (e.g. @gmail.com, @outlook.com, etc.) are not allowed.
- The SSO feature must be enabled and the domain name must not be deleted from the field until the verification is completed (the verification letter comes within 15 minutes).
If you manage a lot of domains and subdomains (subdomains are recognized as separate names and require separate verification), please verify at least one domain name and then submit a request to the Support Team sending us a list of the domains (must be separated by a comma) so we confirm them at once for you.
To finish click the Save button. After that, your end-users will be able to start using SSO authorization.
Just In Time Provisioning for new users (optional)
Help your end-users engage with Miro right away, without waiting for someone to invite them to the account or making them go through the full onboarding process and prevent creating trial and free accounts outside of your managed Enterprise umbrella.
⚠️ Miro JIT feature affects only newly-registered users. The users that already have an existing profile with Miro still require an invitation to your Enterprise account. All users provisioned under JIT are assigned the default license of your subscription:
- For Business and Enterprise subscriptions without Flexible License Program: a Full license if you don't use Day Passes; an Occasional license if you do. If your subscription runs out of licenses the users start getting provisioned under Free Restricted license (applicable to Enterprise plan only).
- For Enterprise subscriptions with Flexible License Program activated: Free or Free Restricted license depending on the default account license.
To enable the Miro JIT feature open your SSO settings > tick the respective box > and choose the designated team.
Enable Just in Time provisioning feature in the Security settings
All newly registered users from the domains that you list in the settings will be automatically added under your Enterprise Umbrella to this particular team when they sign up with Miro.
Possible Issues and How to Resolve Them
- My domain addresses are not accepted in the SSO settings - `DomainName is busy` message.
- For security reasons, we support an organization's domain(s) in one Company umbrella (Enterprise account) only. It is possible that your domains are already set up in another Business plan or Enterprise plan account, preventing you from enabling SSO with the desired domain. Feel free to check it with your colleagues beforehand.
- I follow the link in the Domain Verification email but the verification does not go through.
- The link is supposed to send you to the Security tab of the Settings. If you're not landing there, please check if you're using any anti-phishing software that can break the flow.
- We need to change the email addresses of our end-users / We changed the emails of our users and now they are unable to access their boards.
- If your company is changing its domain name and therefore the email addresses of the end-users need a change of their SSO credentials please reach out to our Support Team for assistance.
- We would like to use a separate gateway (for instance MFA, like Duo Dag) for the SSO procedure.
- You can certainly do that, Miro will support your preferred solution for as long as it works under SAML 2.0.
If one or all of your users encounter an error when trying to sign into Miro, please check this list of common errors and how to resolve them.