SSO & SAML

Last updated: August 28, 2026

Housing.Cloud integrates with any SAML 2.0 identity provider (Azure AD, Okta, Shibboleth, Google, etc.). This article covers setup and the handful of issues that trip most schools up.

Setup, in Five Steps

  1. Register Housing.Cloud as a new Service Provider in your IdP, using the endpoints below.
  2. Create the attribute mappings (NameID, email, full name — see below).
  3. Share your IdP metadata XML with Housing.Cloud and confirm the attribute names you'll send.
  4. Housing.Cloud registers your IdP using that metadata.
  5. Provision the audience to the Housing.Cloud enterprise app: for sandbox, just housing/res-life + IT staff; for production, all current students + staff.

Endpoints

Register sandbox and production as separate Service Providers — they use different endpoints, and applying a cert or metadata to the wrong one is a common source of delay, so confirm which environment you're configuring.

Sandbox Production
SSO / ACS https://udpdwbajlucpsnfrttva.supabase.co/auth/v1/sso/saml/acs https://auth.housing.cloud/auth/v1/sso/saml/acs
Default Relay State https://udpdwbajlucpsnfrttva.supabase.co https://auth.housing.cloud
Audience / EntityID …/auth/v1/sso/saml/metadata https://auth.housing.cloud/auth/v1/sso/saml/metadata

Required Assertion Attributes

  • NameID — one of: emailAddress or persistent format.
  • Email — any of: mail, email, or the xmlsoap emailaddress claim.
  • Name (full name) — the xmlsoap name claim.

Choosing Your Unique Identifier

Housing.Cloud supports two unique identifiers for sign-in — email or sisId. Pick one; it applies to everyone. Choose persistent NameID + sisId if usernames/emails change over time and you want the link to survive; choose email if it's stable and simplest.

Common Issues & Fixes

  • "The profile email must match the SSO email." Sign-in matches the assertion against the student's profile email. If they differ, the user can't get in. Assert the same email that's in the profile feed.
  • Custom-claim error on first login. Usually just a claim that needs mapping — expected, and quick to fix. Capture the ACS response payload if it persists (see Troubleshoot "Invalid Custom Claims").
  • Metadata expiry (validUntil). SAML metadata has an expiry date; when it lapses, everyone is locked out. Track it and refresh before it expires.
  • Sandbox vs production drift. They're separate configs — a change in one does not carry to the other. Confirm which environment each change targets.