Microsoft Entra ID SAML SSO

This guide walks you through connecting Wallboard to Microsoft Entra ID (formerly Azure Active Directory) with SAML 2.0, from creating the application to your first successful login.

For a field-by-field description of every SAML setting, see Custom Domain.

Prerequisites

Before you begin, make sure you have:

• A custom domain already set up by the Wallboard team. If you do not have one yet, contact [email protected].
• Administrator access to Wallboard.
• An Entra ID role that can create enterprise applications and app registrations — Cloud Application Administrator or Application Administrator.

---

Step 1: Copy Wallboard's SP Details

In Wallboard, navigate to Customer Settings > Custom Domain > SAML Settings. The SP Details section contains the two values Entra ID needs.

Wallboard field	Enter it in Entra ID as
Audience URI (SP Entity ID)	Identifier (Entity ID)
ACS URL (Assertion Consumer Service)	Reply URL (Assertion Consumer Service URL)

Save yourself the copying

Click the export icon next to SP details and choose Download Metadata XML file. Entra ID can import this file directly in Step 3, which fills both fields for you.

---

Step 2: Create the Enterprise Application

1. In the Microsoft Entra admin center, go to Entra ID > Enterprise applications.
2. Click New application, then Create your own application.
3. Name the application (for example, Wallboard).
4. Select Integrate any other application you don't find in the gallery (Non-gallery).
5. Click Create.

---

Step 3: Configure Basic SAML Configuration

1. In your new application, go to Single sign-on and select SAML as the sign-on method.

2. In the Basic SAML Configuration card, click Edit.

3. Either click Upload metadata file and select the XML you downloaded in Step 1, or enter the values manually:

   Entra ID field	Value
   Identifier (Entity ID)	The Audience URI from Wallboard
   Reply URL (Assertion Consumer Service URL)	The ACS URL from Wallboard

4. Click Save.

Sign on URL

Wallboard supports both SP-initiated login (the user starts at your custom domain's login page) and IdP-initiated login (the user starts from Microsoft My Apps).

Leave Sign on URL empty to have the Wallboard tile in My Apps start an IdP-initiated login. Set it to your custom domain URL if you would rather the tile send users to the Wallboard login page first. Signing in directly at your custom domain works either way.

---

Step 4: Check Attributes & Claims

Entra ID's default claims already match what Wallboard expects when you select the Microsoft IdP type, so in most cases there is nothing to change here.

Wallboard attribute	Entra ID claim
Email	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
Display name	http://schemas.microsoft.com/identity/claims/displayname
Role, Teams, UI profile	http://schemas.microsoft.com/ws/2008/06/identity/claims/role

The email claim must be a real email address

Wallboard identifies users by the email attribute, and it must be unique across all your users. By default, Entra ID sends user.userprincipalname in the email claim. If your user principal names are not email addresses — for example, UPNs like [email protected] while people actually use [email protected] — edit the claim and change its source to user.mail.

Wallboard reads the email from this claim only. A SAML NameID on its own is not enough, and login fails if the claim is missing.

---

Step 5: Define App Roles (Optional)

Skip this step if you only want users to sign in and you will manage roles, teams, and UI profiles inside Wallboard.

Entra ID sends every App Role a user holds as separate values under a single role claim. Wallboard reads them all from that one claim and routes each value by its prefix, so one App Role list can drive roles, teams, and UI profiles at once.

1. Go to Entra ID > App registrations, open the app registration created alongside your enterprise application, and select App roles.

2. Click Create app role and add one role per value you want to assign. The Value field is what Entra ID sends in the assertion.

   Display name	Value	Allowed member types
   Owner	role-OWNER	Users/Groups
   Technician	role-TECHNICIAN	Users/Groups
   Approver	role-APPROVER	Users/Groups
   Editor	role-EDITOR	Users/Groups
   Viewer	role-VIEWER	Users/Groups
   Team — Retail North	team-e7c5a8b5aa06482e8d7573c3b8b5f09b	Users/Groups
   Team — Retail South	team-3b94c4c671e34cbaa1198a4c16c8ae5c	Users/Groups
   Team — Corporate HQ	team-9f2d1c7b4e5a4f0d8c3b6a1e2d4f5a7c	Users/Groups
   UI profile — Standard	ui-profile-432	Users/Groups
   UI profile — Restricted	ui-profile-518	Users/Groups

note

The example above uses role-editor in lower case. Prefixes and role names are matched case-insensitively, so role-editor and role-EDITOR behave identically.

Required prefixes:

Prefix	Maps to	Example
role-	User role	role-EDITOR
team-	Team assignment	team-e7c5a8b5aa06482e8d7573c3b8b5f09b
ui-profile-	UI profile	ui-profile-432

Accepted role values are VIEWER, EDITOR, APPROVER, TECHNICIAN, and OWNER (case-insensitive).

note

Team IDs and UI profile IDs are found in Wallboard under their respective settings pages. Copy them exactly.

How Wallboard Combines Multiple App Roles

A user can hold several App Roles at once. Entra ID sends them all as separate values under the same role claim, and Wallboard applies them like this:

Prefix	How many values are used
role-	One. If a user holds more than one, Wallboard takes the first one in the assertion, which is not a predictable order. Assign exactly one role per user.
team-	All of them. This is how a user ends up in several teams.
ui-profile-	One. Same rule as role-.

Values that do not start with one of the three prefixes are ignored, so unrelated App Roles on the same app registration are harmless.

Both claim formats work

Entra ID normally sends each App Role as its own value, as shown below. Some tenants and some claim transformations instead emit everything as a single comma-separated string:

<Attribute Name="http://schemas.microsoft.com/ws/2008/06/identity/claims/role">
  <AttributeValue>role-EDITOR,team-e7c5a8b5aa06482e8d7573c3b8b5f09b,ui-profile-518</AttributeValue>
</Attribute>

Wallboard accepts both. A single value containing commas is split and each part routed by its prefix, with surrounding spaces trimmed.

The split only applies when the claim carries exactly one value, so never mix the two formats — a claim with several values where one contains commas leaves that value unsplit and unmatched.

If a user holds no value for one of the prefixes, Wallboard falls back to the matching entry in Single sign on settings — Default role, Default teams, or Default user interface profile. Note that Default teams are added on top of whatever team- values were sent, so members always end up in those teams.

Worked Examples

Regional content editor — edits content for two retail regions on a restricted UI.

App Roles assigned in Entra ID:

role-EDITOR
team-e7c5a8b5aa06482e8d7573c3b8b5f09b
team-3b94c4c671e34cbaa1198a4c16c8ae5c
ui-profile-518

Entra ID sends them as one multi-valued claim:

<Attribute Name="http://schemas.microsoft.com/ws/2008/06/identity/claims/role">
  <AttributeValue>role-EDITOR</AttributeValue>
  <AttributeValue>team-e7c5a8b5aa06482e8d7573c3b8b5f09b</AttributeValue>
  <AttributeValue>team-3b94c4c671e34cbaa1198a4c16c8ae5c</AttributeValue>
  <AttributeValue>ui-profile-518</AttributeValue>
</Attribute>

In Wallboard the user gets the Editor role, membership of Retail North and Retail South, and the Restricted UI profile.

Technician covering every site — needs device access everywhere, standard UI.

role-TECHNICIAN
team-e7c5a8b5aa06482e8d7573c3b8b5f09b
team-3b94c4c671e34cbaa1198a4c16c8ae5c
team-9f2d1c7b4e5a4f0d8c3b6a1e2d4f5a7c
ui-profile-432

All three team- values are applied, so the user belongs to all three teams.

Read-only regional manager — one team, no UI profile assigned.

role-VIEWER
team-9f2d1c7b4e5a4f0d8c3b6a1e2d4f5a7c

The user gets the Viewer role and Corporate HQ membership. Because no ui-profile- value was sent, they receive the Default user interface profile from Single sign on settings — or none at all if that setting is empty.

Misconfigured user — two roles assigned by mistake.

role-APPROVER
role-EDITOR
team-9f2d1c7b4e5a4f0d8c3b6a1e2d4f5a7c

Only one of the two roles takes effect, and which one depends on the order Entra ID happens to send them. Remove the extra App Role assignment so the result is predictable.

---

Step 6: Assign Users and Groups

1. Go back to Enterprise applications > your application > Users and groups.
2. Click Add user/group, pick the users or groups, and select the App Role to grant.
3. Repeat for each App Role a user needs. A user assigned to several App Roles receives all of them as separate values in the same claim.

warning

Users who are not assigned to the application cannot sign in to Wallboard through SSO.

---

Step 7: Copy Entra ID's Metadata URL

1. Return to Single sign-on > SAML.
2. In the SAML Certificates card, copy the App Federation Metadata Url.

---

Step 8: Enter Entra ID's Details in Wallboard

Back in Wallboard, on the SAML Settings page:

1. If you defined App Roles in Step 5, first turn on the toggles you need in the Mapping section — Sync User Roles from IdP, Sync Team Assignments from IdP, and Sync UI Profiles from IdP. Their attribute fields only appear once the matching toggle is on.
2. Click the gear icon (⚙) next to IdP configuration.
3. Set IdP type to Microsoft (Azure AD / Entra ID). This pre-fills all the attribute names with Microsoft's claim URIs — including the shared role claim used for mapping. No further changes are needed.
4. Paste the App Federation Metadata Url from Step 7 into IdP Metadata URL. Wallboard fills in the IdP Entity ID, IdP SSO URL, and IdP Public Certificate automatically.
5. Click Save.

Certificate rotation is then handled for you

Because you supplied a metadata URL rather than a fixed certificate, Wallboard re-reads Entra ID's metadata once a day and picks up a new signing certificate on its own. The previous certificate is retained and still accepted while the changeover settles, so logins keep working through an Entra ID certificate rollover.

Wallboard also emails a warning 30 days before the current certificate expires, and records each refresh in Settings > Activity Logs.

None of this applies if you enter the certificate by hand instead of using a metadata URL — you would then have to replace it yourself before it expires.

---

Step 9: Enable SSO and Test

1. Toggle SAML SSO enabled at the top of the SAML Settings page.
2. Review the Single sign on settings card. If you want users who have never logged in before to be created automatically, enable Enabled automatic user creation when role and customer information is given and set a Default role — the least privileged role is recommended.
3. Open your custom domain in a private browser window and sign in with an assigned Entra ID account.

tip

Keep a working administrator session open in another browser while you test. Turning on Hide username and password fields on login page before SSO is confirmed working can lock everyone out of the domain.

---

Troubleshooting

Where to Look First

A failed SSO login is quiet. The person signing in does not reach Wallboard — the browser stops on an error at the callback URL — and the reason is not written for them to read. Diagnose from these sources, in this order:

Source	What it tells you
Wallboard > Settings > Activity Logs	The outcomes Wallboard records. Enable the Log Level and Message columns and look for messages starting with SAML.
Entra ID > Sign-in logs	Whether Entra ID issued an assertion at all, and whether the user was allowed to launch the application.
A browser SAML trace	The raw assertion, when you need to see exactly which claims were sent and under what names.

Not every failure reaches Activity Logs

Wallboard records a successful provisioning (New user '…' created via SAML SSO with role '…') and a user turned away because automatic user creation is off (SAML login attempt for non-existent user '…').

Assertions rejected during validation — a missing email claim, a signature that does not verify — are refused before anything is logged. A failed login that leaves no Activity Logs entry at all points at the assertion itself, so check the Entra ID sign-in logs and a SAML trace next.

Common Causes

What you observe	Likely cause and fix
Login fails right after Entra ID redirects back, and no Activity Logs entry appears	The email claim is absent or its name does not match. Check the claim in Attributes & Claims and the Email attribute name in Wallboard. Remember that a NameID alone is not enough.
Activity Logs shows SAML login attempt for non-existent user	Automatic user creation is disabled. Either enable it in Single sign on settings or create the user in Wallboard first.
A user's role, teams, or UI profile changes unexpectedly after they log in	Mapping is enabled, but Entra ID sent no value for that user, so Wallboard applied the default from Single sign on settings — or cleared the value if no default is set. Assign the user the matching App Role, or turn the sync toggle off.
Users get the default role instead of their assigned one	The App Role value is missing its role- prefix, or the user is not assigned to that App Role.
Logins that worked yesterday now fail for everyone	The signing certificate changed and Wallboard is still on the old one. If you configured Wallboard with the App Federation Metadata Url this should correct itself daily, so look in Activity Logs for Failed to refresh SAML certificate — a metadata URL that Wallboard cannot reach is the usual cause. If you pasted the certificate by hand, replace it yourself, or switch to the metadata URL so future rollovers are automatic.
Entra ID reports a successful sign-in, but Wallboard still refuses the user	SSO may be disabled on that individual Wallboard user account. Check the user's settings in Wallboard.

---

Need Help?

Contact us at [email protected] or [email protected]