Articles in this section

See more

How to Enable Single Sign-On in Displayr

  • Updated
Follow

Single Sign-On (SSO) lets your team log in to Displayr using the same login your company already uses everywhere else, so there's no separate Displayr password to create or remember. It's worth setting up if your company already manages logins centrally and you want that same system to control who can access Displayr.

Setting it up involves at least two people:

  • You (a Displayr user, usually an administrator) decide how SSO should work for your account, including whether Displayr User Groups should be assigned automatically.
  • Your IT team configures the connection between Displayr and your company's identity provider (IdP) — the system that manages your company's logins, such as Microsoft Entra ID or Okta.

This article covers everything both of you need: what to decide, what to hand your IT team, how to configure it in Displayr, and how to fix the most common problems.

Setting up SSO is less technical than it looks. It's just another way of creating and managing Displayr user accounts: the same groups, licenses, and permissions you already use, just triggered by a different login step.

Requirements

  • A Displayr Enterprise account without SSO already configured (each account can only have one SSO).
  • Your company has a subdomain (e.g., mycompany.displayr.com). If you don't have one, please contact Displayr support. This is the URL that your SSO users will use to sign into Displayr, if not trying to access a document directly.
  • You or another user is a Displayr administrator, i.e., you are in the Administrators user group in Displayr.
  • Your company's password system ("identity provider" or IdP) supports SAML 2.0 SP initiated Web Browser Single Sign-On (also known as the "SP Redirect Request; IdP POST Response" profile). You will need help from an administrator of that system.
  • You understand How to Manage User Groups and Permissions in Displayr.

Decide whether to map your Displayr groups

Displayr User Groups control which dashboards and documents each user can see. Before your IT team configures anything, you need to decide how SSO should handle the groups.  

Option 1: Map groups automatically. Your IT team sends a group identifier from your identity provider each time a user logs in. Displayr matches it against a mapping table you set up, and keeps each user's groups in sync automatically. Every time a user logs in, Displayr adds them to any mapped group their IdP says they belong to, and removes them from any mapped group it says they don't. 

This is the better option if group membership can change over time and you don't want to update Displayr by hand every time a user needs to be added or removed. 

Option 2: Assign groups manually. You skip the mapping table and assign each SSO user to a User Group yourself the first time they log in. This is the better option if your company's IdP groups don't line up cleanly with your Displayr groups, or if only a handful of users need SSO.

You can also mix the two: map some User Groups automatically and leave others for manual assignment.

Make this decision now, and tell your IT team the answer before they configure your identity provider. If you choose automatic mapping, IT needs to know to include the correct group attribute in the SAML login response, and to tell you the identifier to use for each group in Displayr. Without this, they can't finish the setup correctly, and you may end up doing it manually anyway, after finding out the hard way.

If you choose Option 1 or a mix of both types, set up a mapping table with user names, emails, and user group assignments before proceeding and deliver that to your IT team.

Understand how Single Sign-On works

Each Displayr account can be configured for only one SSO connection. The setup involves getting information from Displayr's system to provide to your IT team. The IT team uses that information to configure the IdP to connect to Displayr. Once your IT team configures your IdP, it gives you a Certificate, a Login URL, and optionally a Logout URL, which you enter into Displayr's SSO settings.

Once SSO is enabled, users log in using your subdomain URL, or they'll be redirected there automatically if they try to open a document or dashboard that requires logging in. After signing in through your IdP, they land on the Documents page or on the item they were trying to open.

Logging out sends users to the Logout URL you configure (or to the default Displayr logout page if left blank). This doesn't necessarily log them out of your company's IdP, unless your IdP's logout page is configured to do that.

By default, Displayr asks SSO users to log in again every 24 hours. If your IdP's response includes a SessionNotOnOrAfter value, Displayr uses that instead.

This is a separate account from a Displayr account that uses a username and password. Signing in through SSO for the first time creates a new Displayr user, even for someone who already has a manually-created Displayr login. The SSO account has its own license and its own User Group assignments; nothing carries over automatically from an old account. You will need to (re)assign a license to the SSO user. Also see Use both SSO and manual logins below.

Set up Single Sign-On

  1. Click the initials icon in the top right, then select Account settings.
  2. Select Settings > Configure Single Sign-On (SAML).
  3. Under Service Provider Information, copy the values your IT team needs to configure your identity provider, or click Download Metadata xml file if your IdP accepts a metadata file instead.
  4. Send these to your IT team, along with the attributes below and your group mapping decision (see Decide whether to map your Displayr groups above).

Your IT team must configure your identity provider to send these SAML attributes with every login. These first three are not optional.

Without them, Displayr can't identify who's signing in: every user will show up as "SSO User" instead of their own name. Renaming them manually in Displayr won't fix it; your IT team has to fix it in the IdP configuration.

Email — sent as one of: 

  • User.email
  • emailaddress
  • mail
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/User.email
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/mail
  • or the saml:NameID attribute within the saml:Subjectattribute

First name — sent as one of: 

  • first_name
  • givenname
  • User.FirstName
  • FirstName 
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/first_name
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/User.FirstName
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/FirstName 

Last name — sent as one of: 

  • last_name
  • surname
  • User.LastName
  • sn
  • LastName
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/last_name
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/User.LastName
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/sn
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/LastName

If you chose automatic group mapping, your IT team must also send an attribute named groups (or http://schemas.microsoft.com/ws/2008/06/identity/claims/groups). 

Each value it contains should match one of the group identifiers you enter into the Group mappings table in Step 7. 

Forgetting this attribute is one of the most commonly missed steps in SSO setup. Without it, automatic group mapping does nothing, silently.

  1. Once your IT team has configured your identity provider, they'll give you a Login URL, a Certificate (in PEM format), and optionally a Logout URL.
  2. Enter these values on the same Configure Single Sign-On (SAML) page in Displayr.
  3. If you chose automatic group mapping, enter the group identifiers your IT team provided into the Group mappings table — see Manage groups below.
  4. Check Enable Single Sign-On (SAML), then click Save.
SingleSignOnBasicSetup.png

Set up Microsoft Entra ID (Azure Active Directory)

See Microsoft's tutorial: Integrate Displayr with Microsoft Entra ID for step-by-step instructions.

Entra ID doesn't send group data for a user who belongs to more than 150 groups. See Microsoft's guide on configuring group claims to avoid this limit.

Set up Okta

See Okta's guide on creating an app integration.

  • In Single Sign-On URL, enter the Assertion Consumer Service (ACS) URL shown under Service Provider Information in Displayr.
  • In Audience URI (SP Entity ID), use the EntityID from the same section.
  • In Name ID Format, use one of the email attribute names listed above in Set up Single Sign-On (e.g., User.email or emailaddress).
  • In Okta, set Audience Restriction to the EntityID from Displayr. Do not add "http://" at the start; only use the subdomain address. For example, use example.us.displayr.com and not http://example.us.displayr.com

Entering the wrong ACS URL is the most common cause of users getting stuck in a login loop when they try to sign in.

Manage groups

If you chose automatic group mapping, here's how it works:

  • Your IT team sends the group identifiers from your identity provider as the groups attribute described in Set up Single Sign-On above. Each group identifier should be sent as its own separate value within that attribute: one identifier per value, not a single combined string.
  • Enter the group identifiers your IT team gives you into the Group mappings table on the Configure Single Sign-On (SAML) page, matched against the Displayr User Group each one should apply to.
  • Every time a user logs in via SSO, Displayr re-syncs their mapped groups: it adds them to any mapped group their IdP response includes, and removes them from any mapped group it doesn't.
  • SSO entirely ignores any Displayr User Group left without a mapping.

Manually manage a group - To keep control of a specific group yourself, leave its identifier blank in the Group mappings table. You'll need to assign users to it by hand after they've signed in via SSO at least once. Manual changes to a mapped group won't stick; they're overwritten the next time that user logs in or out.

Saml_Group_Settings.png

Use both SSO and manual logins

Displayr allows a mix of SSO users and manually-created users (who log in with an email and password) on the same account.

  • SSO users appear in the Displayr Users list only after they've logged in for the first time.
  • Non-SSO users log in at app.displayr.com, or at mycompany.displayr.com/Login/Direct, where "mycompany" is your custom subdomain. If your account is on a regional server, use that region's URL, e.g., instead of app.displayr.com, use australiaeast.displayr.com.
  • Either type of user can be manually added to any User Group. For SSO users, membership in a mapped group is still reset on their next login, as described above.

Troubleshooting

Everyone's name shows up as "SSO User"

Your identity provider isn't sending name attributes. Ask your IT team to confirm they're sending the first and last name attributes listed in Set up Single Sign-On above. Renaming a user manually in Displayr won't fix it; the name is reset to "SSO User" on their next login, so the fix must be made in the IdP configuration by your IT team.

Users can't see the dashboards they expect

Check whether you and your IT team actually decided on group mapping in Decide whether to map your Displayr groups above before setup, or whether it got skipped. If you chose automatic mapping, confirm the Group mappings table has the right identifiers, and confirm with IT that the groups attribute is actually being sent for the affected users.

A user can't find documents or dashboards they used to have

This is expected if they used to log in manually and have now switched to SSO: it's a new, separate Displayr account, with its own group assignments. Add the new SSO account to the correct User Group(s) or set up automatic mapping to restore their access.

Okta users are stuck in a login loop

The Single Sign-On URL entered in Okta doesn't match Displayr's ACS URL. Compare it against the ACS URL under Service Provider Information in Displayr.

A user's group access changed on its own

If that User Group has a mapping in the Group mappings table, your IdP fully controls its membership. Check whether the user's group assignment changed there; Displayr re-syncs mapped groups on every login. You cannot manually assign a user to a mapped group. It must be set in your IdP.

A user sees a message that they don't have any editing hours left on their assigned license

If a user sees a message that says:

The requested action cannot be completed because you do not have any editing hours left on your assigned license. You can still view the document or go to the licenses page to manage your licenses.

This indicates that the user is likely logging in using their Displayr login and password. They will need to log in using their SSO credentials instead. If they are logging in via SSO, then check to make sure that their license is assigned to their SSO login vs their Displayr login.

Next

How to Invite New Users to Your Displayr Account

How to Manage User Groups and Permissions in Displayr

How to Customize My Displayr URL

Related articles