Single sign-on (SSO) lets your staff, students and parents log in to PortalHQ with the school account they already use every day, rather than a separate PortalHQ password. PortalHQ supports SAML 2.0, the open standard every major identity provider speaks, so it works with Microsoft Entra ID (formerly Azure AD), ADFS, Cloudwork, Studentnet, Okta and any other SAML 2.0 identity provider (IdP).
Once SSO is switched on, every login for your school goes through your IdP. Users are matched to their PortalHQ account by email address, and their PortalHQ role (staff, student or parent) is set from a role attribute your IdP sends. There is no separate PortalHQ password to forget, and disabling someone in your IdP stops them getting into PortalHQ.
Before you start
- You’ll need a portal administrator in PortalHQ to reach Settings → Single Sign-on. If you aren’t sure who that is, see User roles and permissions.
- You’ll need someone who can create an enterprise application in your IdP. For most schools that is the IT team’s Microsoft Entra ID administrator.
- Your users must already exist in PortalHQ, normally through your SIS sync, with the same email address your IdP will send. SSO authenticates people. It doesn’t replace the SIS integration that gives them their classes, children and contact data.
- One IdP per school. PortalHQ has a single SSO configuration per school. If your staff and parents live in different directories, they need to be federated behind one IdP before PortalHQ can sign them all in.
- Decide who will use SSO. Most schools start with staff only. Students and parents can be added later by widening the IdP application’s user assignment and role mapping.
How the setup works
The setup is a short exchange between your IT team and PortalHQ:
- Your portal administrator opens Settings → Single Sign-on in PortalHQ and copies the PortalHQ URLs listed there.
- Your IT team registers PortalHQ as a SAML application in your IdP using those URLs, and configures the user attributes PortalHQ needs.
- Your IT team sends the IdP’s metadata URL to your portal administrator (or to PortalHQ support).
- The metadata URL and IdP name are saved in Settings → Single Sign-on.
- A couple of staff accounts are tested.
- Enable SAML is ticked, and from then on every login for your school goes through the IdP.
The only thing PortalHQ needs from you is the IdP metadata URL and a display name. Everything else is generated by PortalHQ or set up on your IdP’s side.
Step 1: Get the PortalHQ details for your IdP
In PortalHQ, go to Settings → Single Sign-on. Under the form you’ll see a table headed Use the following SAML settings in your Identity Provider setup, with a copy button next to each value:
| Value on the page | What it is | Where it goes in your IdP |
|---|---|---|
| Metadata URL | PortalHQ’s service provider (SP) metadata, which also serves as the Entity ID / Identifier | Entity ID, or import it as the SP metadata |
| ACS (Assertion Consumer Service) URL | Where your IdP posts the login response | Reply URL / Assertion Consumer Service URL (HTTP-POST) |
| SAML Logout Response endpoint | Logout endpoint (HTTP-Redirect binding) | Logout URL, if your IdP asks for one |
| SAML Logout Response POST endpoint | Logout endpoint (HTTP-POST binding) | Alternative logout URL for IdPs that only support POST |
| Required User Attributes | mail, role |
Claims / attribute statements (see Step 2) |
| Optional User Attributes | givenName, sn |
Claims / attribute statements |
| Logout Request Preferred Binding | HTTP Redirect | Logout binding |
All of these URLs use your school’s PortalHQ web address. If your school uses a custom domain for PortalHQ, they’ll show that domain, and that is the one to use.
PortalHQ generates its own signing and encryption certificates for your school and publishes them in the metadata URL, so you don’t need to create or upload any certificates. Most IdPs read them automatically when you import the metadata; if yours asks you to paste a certificate, download it from the metadata URL.
Step 2: Register PortalHQ in your IdP
Create a new custom SAML 2.0 application in your IdP (an enterprise application in Microsoft Entra ID).
Fill in the values from Step 1, then set up the user attributes (called claims in Entra ID, attribute statements in Okta). PortalHQ looks for these by exact name, so turn off the namespace prefix that Entra ID adds to claims by default (leave the Namespace field blank for each claim):
| Attribute name | Required | Value to send | What PortalHQ does with it |
|---|---|---|---|
mail |
Yes | The user’s email address | Matches the user to their PortalHQ account. Must match the email PortalHQ already holds for them |
role |
Yes | One of staff, faculty, student, parent, affiliate, employee, contractor |
Sets the user’s PortalHQ type: staff or faculty → Staff, student → Student, parent or affiliate → Parent, employee or contractor → Contractor |
givenName |
No | First name | Used only when PortalHQ has to create the account |
sn |
No | Surname | Used only when PortalHQ has to create the account |
groups |
No | Group names | Adds the user to PortalHQ groups of the same name, creating them if needed. Send display names, not object IDs |
username |
No | SIS ID | Only for schools whose Username type is SIS ID (see the settings table) |
Two things trip most schools up here:
roleis mandatory. If it’s missing, or isn’t one of the values above, the login is refused. For a staff-only rollout, the simplest option is a constant claim ofstaff. If you assign students or parents to the application later, driverolefrom a directory attribute or group membership so each audience gets the right value.- Case doesn’t matter for
mail, but the address does. If your IdP sendsj.smith@school.edu.auand PortalHQ holdsjsmith@school.edu.au, the match fails.
Other settings to check in the IdP application:
- Sign the SAML assertion. PortalHQ requires signed assertions. Signing the whole response as well is fine.
- Accept signed requests. PortalHQ signs its login and logout requests with the certificate in its metadata.
- NameID format can be left as the default (PortalHQ uses a transient NameID and identifies users by the
mailattribute instead). - Assign users. Only users (or groups) assigned to the application can sign in. Start with your test accounts.
When the application is saved, copy its App Federation Metadata Url (Entra ID) or equivalent metadata URL. It must be a public HTTPS address PortalHQ can fetch, not a downloaded XML file. PortalHQ re-reads it on each login, so certificate rollovers in your IdP are picked up automatically as long as the URL stays the same.
Step 3: Save the IdP details in PortalHQ
Back in Settings → Single Sign-on, fill in the form and click Save Changes:
| Setting | What to enter |
|---|---|
| Enable SAML | Leave unticked until testing is finished (see Step 4) |
| IdP Name | A display name for your identity provider, e.g. Microsoft Entra ID |
| IdP Metadata URL | The metadata URL from Step 2 |
| Username type | Email for almost every school. SIS ID is only for schools whose SIS sync is configured to use the SIS identifier as the login name. Changing it needs a re-sync before it takes effect |
| Reset AD group membership for parents | Leave unticked unless you send the groups attribute for parents and want their PortalHQ group memberships rebuilt from it on every login |
Saving the form is what creates your school’s SSO configuration. If you copied the URLs in Step 1 before ever saving this page, save it now with the IdP details and re-check the table: the values don’t change, but the certificates behind the metadata URL are created on first save.
Step 4: Test, then enable
Testing is done with Enable SAML still unticked, because once it is ticked every login for your school is redirected to the IdP, and a mistake in the IdP application locks everyone out.
- Ask your IT team to assign one or two staff members to the IdP application. Those staff must already have a PortalHQ account with the same email.
- Open the IdP’s test option (in Entra ID, the Test button on the SAML single sign-on page), or browse directly to your school’s PortalHQ address followed by
/saml2/login/. - Sign in at the IdP. You should land on the PortalHQ dashboard as that staff member.
- Check the account in PortalHQ: correct name, correct type (Staff), expected groups.
If you see an Access Denied page with Authentication Error beneath it, the message under that tells you what PortalHQ rejected. Work through the Troubleshooting section below, fix the IdP application, and test again.
When a test login works end to end, tick Enable SAML and click Save Changes. From that point:
- Browsing to your school’s PortalHQ address, or to the login page, sends the user straight to your IdP.
- Users who are already signed in to the IdP in their browser go straight through without seeing a login screen.
- Deep links keep working: a user who opens a link to a specific page is sent to the IdP and returned to that page afterwards.
Roll out to more users by widening the assignment in the IdP application. Nothing further needs to change in PortalHQ.
Logging out
Logging out of PortalHQ ends the PortalHQ session only. It does not sign the user out of your IdP or any other application, and PortalHQ does not currently support IdP-initiated single logout. On a shared device, users should also sign out of the IdP or close the browser.
Troubleshooting
Everyone is redirected to the IdP and nobody can get in. Enable SAML was ticked before the IdP application was working. PortalHQ support can turn it off for you; then test with the steps above before re-enabling.
“Authentication Error” after signing in at the IdP. The IdP accepted the user but PortalHQ rejected the response. Usual causes, in order:
- The
roleattribute is missing or has a value outside the allowed list. Check the claim name has no namespace prefix and the value is lower-case. - The
mailattribute is missing or has a namespace prefix. - The assertion isn’t signed.
- The metadata URL in PortalHQ points at a different application, or isn’t reachable from the internet.
The user lands in PortalHQ but as the wrong type, or as a new account. The mail value didn’t match an existing account, so PortalHQ created one. Fix the email on either side, then ask PortalHQ support to remove the duplicate.
Some users can sign in, others get an IdP error before reaching PortalHQ. Those users aren’t assigned to the application in the IdP.
Groups aren’t appearing in PortalHQ. The groups claim is sending object IDs or distinguished names rather than plain names, or the claim isn’t configured at all.
The IdP certificate was renewed and logins stopped. PortalHQ reads the metadata URL on every login, so a rollover published at the same URL is picked up automatically. If your IdP issued a new metadata URL, paste it into IdP Metadata URL.
A staff member needs to get in without SSO. Untick Enable SAML temporarily, or contact PortalHQ support.