Articles in this section

Single sign-on (SSO)

Catherine
  • Updated

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). 

Available for: Enterprise, Business plans
Set up by: Company Admins

Rules

Once SSO is enabled for the account, the following rules apply to the end-users:

  1. The SSO process is applied to the corporate domains that you add to the SSO settings. Your account's end-users (members, guests) with the corporate domains must log into Miro via the SSO option using their identity provider credentials.
    sso_domains.jpg
    Domains in SSO settings
    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 accounts for as long as different accounts claim different domains. However, you will only be able to provision via SCIM to one single Miro Enteprise 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. 
  2. If an end-user is a member of any team outside your account 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. 
  3. The end-users are not allowed to change their password, first name or last name in Miro (profile pictures can also be included in the range). The data are instead automatically attributed by your identity provider upon successful login.
    mceclip1.png
    Miro Username is updated after every successful user authentication if SAMLResponse contains new non-empty values. For more information on how to set up Miro username see Optional Settings below.
    ✏️ 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.
  4. For any users who want to sign in to Miro’s Desktop, Tablet, or Mobile apps using SSO, they will be automatically redirected to the web browser in order to use the company SSO. Once the browser SSO is successful, users will be automatically redirected back to the native apps to continue using Miro.
  5. Users from your domain who are not members of your account are not subject to your account's SSO procedure. 

Configuring SSO

Configure your IdP

Feel free to use any identity provider of your choice. The how-tos for the most popular identity platform solutions can be seen below:

Here you can also find an article on how to set up Jumpcloud SSO (and SCIM). 

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).

Configuration specs (metadata)

  • Protocol: SAML 2.0
  • Binding:
         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:

  1. An unsigned SAML Response with a signed Assertion
  2. 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)

mceclip0.png

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. 

Enable SSO in Miro

It is strongly recommended to test the login procedure 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.

⚠️ Business plan Admins can find SSO settings in Team settings > Security tab. To enable SSO on an Enterprise account, go to the Company settings > Enterprise integrations.

Specify the following values:

  1. SAML Sign-in URL (in most cases it opens your Identity Provider's page where your end-users are to enter their credentials)
  2. Public Key x.509 Certificate (issued by your Identity Provider)
  3. The list of domains allowed/required to authenticate via your SAML server.

Miro_SSO_settings.jpg
Miro SSO settings

Verify your SSO domains

Set up by: Company Admins

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 a verification letter to the specified email. Note that the verification link from the letter should be clicked by a Company Admin. To finish click the Save button. After that, your end-users from the verified domain will be able to start using SSO authorization.
domain_confirmation_modal.jpg
SSO domain verification pop-up

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 is not a Company Admin, they may resend 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. 

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). If a domain is not verified, you will see a note Verify email in the settings. 

verify_email.jpg
Non-verified domain in Miro SSO settings

Optional Settings 

Optional settings section is used by advanced users who are familiar with SSO configuration. For more information please refer documentation on SAML2.0 standards.

Just In Time Provisioning for new users 

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 account. 

⚠️ Miro JIT feature affects only newly-registered users. The users that already have an existing profile with Miro still require an invitation to your account.

All users provisioned under JIT are assigned the default license of your subscription:

  • For all Business plan subscriptions and Enterprise subscriptions without Flexible License Program: a Full license. On Enterprise plan, if your subscription runs out of licenses, users start getting provisioned under Free Restricted license (applicable to Enterprise plan only). On Business plan, if your subscription runs out of licenses, users are not automatically captured and JIT stops working
  • 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_JIT.jpg
Enable Just in Time provisioning feature on the Enterprise integrations page

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.

⚠️ On the Enterprise plan this team will also be shown in the list of discoverable teams if you enable Team Discoverability. 

Setting DisplayName as the default username

In Miro the Username is comprised as follows:

  • By default Miro will use FirstName + LastName attributes
  • Alternatively you can request to use DisplayName instead. Please get in touch with your Customer Success Manager or Miro Support to make DisplayName your preferred SSO Username
  • If neither of the three attributes are present in your SAML communication Miro will show the user's email address as Username

Syncing user profile pictures from IdP

When this setting is turned on:

  • profile picture set at IDP side will be set as profile picture in user’s Miro profile
  • users won’t have the ability to update or remove profile picture themselves
⚠️ Same as with the user name, the users lose the option to change their data on the Miro end immediately but the data sync is not immediate, the IDP side sends the update to Miro only with the user's next SSO authentication (provided that “Sync user profile photos from IDP” setting is still active at that point).
⚠️ ProfilePicture attribute is not supported by Azure.

If the profile picture is set in IDP and you wish the attribute to be passed in SAML communication Miro will expect the following schema:

<saml2:Attribute Name="ProfilePicture" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
<saml2:AttributeValue
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">https://images.app.goo.gl/cfdeBqKfDKsap1icxecsaHF
</saml2:AttributeValue>
</saml2:Attribute>

Possible issues and how to resolve them

  1. 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.

  2. 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 Enterprise integrations page. If you're not landing there, please check if you're using any anti-phishing software that can break the flow. 

  3. 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.

  4. 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. 

  5. We enabled SSO but user profiles' data (names, profile pictures - if supported by your IdP) in Miro are not synchronized with those in the IdP.
    - Miro user name and profile picture are updated after every successful user authentication if SAMLResponse contains new non-empty values. For more information on how to set up Miro username see Optional settings.

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. 

Frequently asked questions

  1. When I turn on SSO, are users automatically logged out and forced to log in via SSO?
    - The users will remain logged in and able to use Miro. If a user logs out/session expires/logs in from a new device - the user will be forced to authorize with the SSO. This is only applicable to end-users of your Enterprise account with corporate domains.

  2. If I have JIT enabled, do the newly registered users sign in via SSO?
    - Yes, SSO is required for JIT provisioning.

  3. If I enable SSO, will customers/partners/externals still be able to access Miro?
    - Yes. SSO will only be required for users that are part of your Enterprise account and have a domain listed in your SSO configuration. If your customers/partners/externals have a different domain (not listed in your SSO configuration), they will not be affected by your account's SSO.

Was this article helpful?
Yes, thanks Not really
Sorry about that! Why wasn't the article helpful?
If you would like to get a reply from the Miro Support team, please create a ticket here
Thank you for your feedback!
Error! Please try later...
Return to top

Related articles