Skip to main content

Single Sign-On

Updated

Administrate supports Single Sign-On (SSO) for:

  • Administrate Core – staff Users logging in to the TMS
  • Administrate LMS – learners logging in to the LMS

Administrate uses OpenID Connect (OIDC), an industry-standard protocol for authentication.

Enabling SSO allows users to authenticate using an external identity provider, reducing the need to manage separate credentials.

Single Sign-On configuration

Use SSO for Administrate Core and/or Administrate LMS

Activating providers

After configuring a provider, you control where it applies:

  • Enabled for Core – allows staff Users to log in to Administrate using SSO
  • Enabled for LMS – allows learners to log in to the LMS using SSO

Update Provider dialog box

Update Provider dialog box

These two settings control staff login to the TMS and learner login to the LMS. Learner-facing portals have their own SSO configuration, described next.

SSO on portals

Each portal (Student Portal and LMS portals, and WebLink) has its own SSO configuration, separate from the Enabled for Core and Enabled for LMS settings above. SSO is not switched on globally for all portals at once: an identity provider is linked to each portal individually, and different portals can use different providers.

Portals require providers that use OpenID Connect (OIDC). SAML providers apply to TMS staff login only.

Set up SSO on a portal

  1. Configure the identity provider in Administrate, following the provider sections below (Google, Azure, or another OIDC provider).
  2. Link the provider to the portal. There is currently no control panel screen for this step: the link is made through the GraphQL API by a Super User, using the portal addIdentityProvider mutation, or by contacting Administrate Support or your Customer Success Manager with the portal and provider names.
  3. Review the portal's sign-in options described below. For WebLink portals these are in the portal's General Settings in the Control Panel.
  4. Test by signing in to the portal as a learner. Once linked, the provider appears as a sign-in option on that portal's login page.

Portal sign-in options

  • Single Sign-On Only restricts the portal to SSO logins. When disabled, SSO and username/password credentials coexist.
  • Auto-provision Learners via Single Sign-On creates a contact and credentials the first time an unknown learner signs in through SSO, optionally assigning them to a default account. See Auto-provision Learners in LMS.

A brand can also carry its own identity provider configuration, and brands have their own Single Sign-On Only setting (Control Panel, Brands, Security), which applies to the portals using that brand.

If SSO works on one portal but not another, check that the provider is linked to the second portal: each portal's provider list is independent.

Google SSO

Google SSO is preconfigured in Administrate. To use it:

  • Enable it for Core and/or LMS
  • A Login with Google button will appear on the login page

Login with Google button

Log in to Administrate using Google credentials

On first login, users must grant permissions to Administrate.

First time signing in through Google SSO

First-time Google SSO authorization

If login fails, users are returned to the login screen with the message: No user registered with this email address.

Google SSO error when no matching user exists

Failed login example

Set up Azure SSO

Azure SSO requires configuration in both Azure and Administrate.

Azure setup

  1. Sign in to Azure Portal.
  2. Navigate to Azure Active Directory → App registrations.
  3. Create or select an application.
  4. Add redirect URIs: - https://login.getadministrate.com/oauth2 - https://identity.getadministrate.com/oauth2/finalize
  5. Copy the Application (client) ID.
  6. Create and copy a Client Secret.
  7. Copy the Directory (tenant) ID.
  8. Ensure permissions include Sign in and read user profile.

Administrate setup

  1. Open Control Panel → Login Configuration.
  2. Select Create Configuration → OAuth 2.0.
  3. Complete the fields:
  • Name: Azure SSO
  • Redirect URI: https://login.getadministrate.com/oauth2
  • OAuth2 Client ID: Azure Application ID
  • OAuth2 Client Secret: Azure secret
  • OAuth2 Auth URI: https://login.microsoftonline.com//oauth2/authorize
  • OAuth2 Token URI: https://login.microsoftonline.com//oauth2/token
  • OAuth2 Userinfo URI: https://login.microsoftonline.com//openid/userinfo
  • Scope: openid profile email

Enable the provider for Core and/or LMS, then click Save.

If LMS mapping is required, contact Administrate Support .

Add a different SSO provider

Administrate supports any provider that uses OpenID Connect (OIDC).

Click + Add and enter the provider’s OAuth details.

Add Provider details screen

Add Provider details screen

Hint

Use Lookup issuer (for example, accounts.google.com) to auto-populate OAuth endpoints where supported.

Redirect URI defaults:

  • Core: https://identity.getadministrate.com/oauth2/finalize
  • LMS: https://identity.getadministrate.com/oauth2/finalize

Add a SAML 2.0 provider (TMS only)

Select SAML 2.0 from Create Configuration to configure a SAML provider.

Create SAML configuration

SAML SSO is only available for the TMS (Core).

Setting up SAML is a round trip: you create the configuration in Administrate first (using placeholders for the IdP details you don't have yet), generate the Service Provider metadata from it for your IdP team, then come back and replace the placeholders with the real values from your IdP. The steps below walk through that order.

Step 1: Create the SAML configuration

Administrate can only generate SP metadata from a saved configuration, and every field must be filled in before you can save. Since some of these values come from your IdP's SAML app — which your IdP team may not be able to create until they have Administrate's metadata — it is expected and safe to save the configuration with placeholder values first. Nothing you type into these fields is included in the generated metadata, so the placeholders won't leak into what you hand to your IdP team.

Fill in the fields as follows (you'll replace the placeholders in Step 4):

  • Name — a label for this configuration (e.g. your company name or IdP name). This is a real value, not a placeholder.
  • IDP Entity ID — any placeholder text if you don't have the real value yet
  • IDP SSO Redirect URL — must look like a URL, so use a placeholder such as https://example.com
  • IDP Public Certificate — any placeholder text
  • Email URN — any placeholder text

Set the checkboxes to their intended final values now if you know them: the Service Provider and Identity Provider signing options are the one part of the form that is reflected in the generated metadata (see the tip in Step 4 for what they must match). If you're unsure, leave the defaults and confirm them with your IdP team in Step 4.

Click Save. The configuration now appears in the Login Configuration list.

Step 2: Generate your SP metadata

In the Login Configuration list, click the saved SAML configuration and choose Generate Metadata. This XML file contains everything your IdP needs to trust Administrate as a Service Provider.

A sample metadata file looks like this:

<md:EntityDescriptor entityID="https://identity.getadministrate.com" ...>
 <md:SPSSODescriptor ...>
   <md:KeyDescriptor use="signing">...</md:KeyDescriptor>
   <md:KeyDescriptor use="encryption">...</md:KeyDescriptor>
   <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>
   <md:AssertionConsumerService
     Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
     Location="https://identity.getadministrate.com/saml/acs?brand=...&provider=..."
     index="1"/>
 </md:SPSSODescriptor>
</md:EntityDescriptor>

Save this file or keep the page open — you'll reference specific values from it in Step 3.

The metadata is generated for one specific brand and SAML provider: the brand and provider query parameters in the AssertionConsumerService URL identify your configuration, and the entityID can also be configuration-specific. Always generate the metadata from the configuration you are actually setting up — never copy another organisation's (or another brand's) metadata or its encoded brand/provider identifiers, and regenerate it if you recreate the SAML configuration. Metadata pointing at the wrong configuration typically shows up as one login direction working (for example IDP-initiated) while the other fails.

Editing the configuration's fields later (Step 4) does not change the entityID or AssertionConsumerService URL — those are fixed when the configuration is created — so your IdP team can build their side from this metadata while you finish Step 4.

If you change any of the Service Provider signing options after generating metadata, regenerate the metadata and update your IdP configuration to match. Only deleting and recreating the configuration changes the entityID/ACS identifiers.

Step 3: Map metadata values into your identity provider

Each value in the metadata file corresponds to a field in your IdP's SAML app configuration, though the field names vary by provider. Use the table below to find the right field for your IdP.
Value in Administrate's metadata What it is Where to find it in the XML
entityID (root attribute) The unique identifier for Administrate as a Service Provider <md:EntityDescriptor entityID="...">
AssertionConsumerService Location The URL your IdP sends the SAML response to after a successful login <md:AssertionConsumerService ... Location="...">
X509Certificate (signing) The public certificate Administrate uses to verify/sign SAML messages — only needed if your IdP requires an SP certificate upload <md:KeyDescriptor use="signing">
NameIDFormat Confirms Administrate expects the user's email address as the NameID <md:NameIDFormat>

Provider-specific field names
Provider Entity ID field ACS URL field
Okta Audience URI (SP Entity ID) Single sign-on URL
Azure AD / Entra ID Identifier (Entity ID) Reply URL (Assertion Consumer Service URL)
OneLogin Audience Recipient / ACS (Consumer) URL
Google Workspace Entity ID ACS URL
PingFederate SP Entity ID / Partner's Entity ID Assertion Consumer Service URL
ADFS Relying Party Identifier Endpoint (SAML Assertion Consumer)

Tip: Regardless of what your IdP calls it, the Entity ID field should always be set to the value of the entityID attribute at the top of the metadata file (https://identity.getadministrate.com by default), and the ACS URL field should be set to the full Location value from AssertionConsumerService — including the brand and provider query parameters. These parameters are unique to your Administrate instance, so don't truncate the URL.

Step 4: Replace the placeholders with your IdP's details

Once your IdP team has created their SAML app using the metadata from Step 2, they can give you the values for Administrate's side. In the Login Configuration list, click the SAML configuration, choose Edit Configuration, and replace the placeholders:

  • IDP Entity ID — your identity provider's Entity ID (sometimes called the "Issuer URL" or "Identity Provider Issuer" in your IdP's own SSO settings)
  • IDP SSO Redirect URL — your IdP's SAML sign-on URL (sometimes called "Login URL," "SSO URL," or "SAML 2.0 Endpoint")
  • IDP Public Certificate — paste the X.509 signing certificate from your IdP, and nothing else. Do not paste your IdP's federation metadata XML. Several providers, including Microsoft Entra ID, offer that as a download right next to the certificate, and a configuration with metadata in this field will fail at login rather than at save. In Entra, use the Certificate (Base64) download from the SAML Signing Certificate section. Depending on the IDP, when viewed in a text editor, the certificate may or may not include the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines. You can paste the certificate text with or without those lines.
  • Email URN — the SAML attribute name your IdP uses to send the user's email address (this depends on how your IdP maps user attributes — confirm the exact attribute name/URN in your IdP's attribute statement configuration)

This is also the moment to confirm the checkboxes you set in Step 1 against how the IdP's SAML app was actually configured.

Where to find these values in your IdP
Provider IDP Entity ID field IDP SSO Redirect URL field
Microsoft Entra ID (Azure AD) Microsoft Entra Identifier Login URL
Okta Identity Provider Issuer Identity Provider Single Sign-On URL
OneLogin Issuer URL SAML 2.0 Endpoint (HTTP)
Google Workspace Entity ID SSO URL
PingFederate Issuer / Entity ID SSO Application Endpoint
ADFS Federation Service identifier SAML 2.0 endpoint

Tip: The IDP Entity ID and the IDP SSO Redirect URL are two different values, and pasting the sign-on URL into both is the most common mistake at this step. It saves without complaint and then fails at login. In Microsoft Entra ID the two look quite different: the Entity ID is https://sts.windows.net/<tenant-id>/, including the trailing slash, while the sign-on URL is https://login.microsoftonline.com/<tenant-id>/saml2. Both appear in the Set up panel of the Entra SAML app, listed under the name of your application. If you have the IdP's federation metadata XML open, they are the entityID attribute on the root element and the SingleSignOnService Location respectively.

Under Service Provider, decide whether you want Administrate to:

  • Signs Authentication Request Message — sign outgoing SAML requests
  • Signs Metadata — sign the SP metadata file

Under Identity Provider, set these to match how your IdP is configured to send responses:

  • Signs Messages
  • Signs Assertions
  • Sends NameID with Response
  • Encrypts NameID
  • Encrypts Assertions

Tip: The checkboxes under Identity Provider must match your IdP's actual behavior, not just be toggled on for "more security." For example, if your IdP doesn't encrypt assertions, leaving Encrypts Assertions checked here will cause login to fail because Administrate will expect an encrypted payload that never arrives. Check your IdP's SAML app settings to confirm which of these are actually enabled before matching them here.

Click Save, then enable the provider for Core as needed (see Activating providers).

Troubleshooting SAML Configuration

If login fails after setup, double check:

  • The Entity ID in your IdP exactly matches the entityID value in Administrate's metadata
  • The ACS URL includes the full brand and provider query parameters
  • The NameID format your IdP sends matches emailAddress, and that the email matches the User record in Administrate

If sign-in succeeds at your IdP and then fails at Administrate, the response is arriving but is being rejected. That points at the values you entered in Step 4 rather than at user or app assignment in your IdP, because your IdP would have refused the login earlier. Check them in this order:

  1. IDP Public Certificate holds only the certificate, not the federation metadata XML.
  2. IDP Entity ID matches your IdP's issuer exactly, including any trailing slash, and is not a copy of the sign-on URL.
  3. IDP SSO Redirect URL is your IdP's SAML 2.0 endpoint.
  4. The Identity Provider checkboxes match what your IdP actually sends, especially Signs Assertions and Encrypts Assertions.

Each of these is checked strictly, so a value that is nearly right, such as a missing trailing slash, fails in the same way as one that is entirely wrong.

If it still fails, contact Administrate Support with the error reference shown on the failure page and the approximate time of the attempt. That reference lets Support match your login to the underlying reason, which is more specific than anything shown on screen.

FAQ

I can’t log in through SSO

Ensure the email address in Administrate matches the one provided by your identity provider.

Example: user@company.com vs user@googlemail.com will fail.

Resources

OpenID Connect – official documentation

Related to

Related articles