SAML

Overview

The SAML integration allows Onefile users to authenticate through an external Identity Provider (IdP), enabling seamless login without visiting the Onefile login page. Users can log in directly via your organisation’s website or select SSO on Onefile’s login page and enter your domain to authenticate.

Purpose

This enables secure, centralised authentication and removes the need for users to maintain separate Onefile credentials.

User Roles

This setup is typically managed by:

• Centre Manager / Technical Administrator

Set-up

Pre‑requisites

• SAML integration is enabled — contact your Account Manager if not.
• API is enabled, and an API key is supplied to your organisation.
• A Microsoft Entra ID (formerly Azure AD) account.

Microsoft Entra Configuration

1. Navigate to Enterprise Applications > All applications and create a new entry for Onefile.
2. Under Basic SAML Configuration, add:
   • Identifier (Entity ID): https://login.onefile.co.uk/api/SAMLSSO/meta
   • Reply URL (ACS URL): https://login.onefile.co.uk/api/SAMLSSO
   • Sign-on URL: Leave blank for now.
3. Under Attributes & Claims, edit and add:
   • Name ID (Unique User Identifier) → Value: user.objectid
4. Under SAML Certificates:
   • Create and activate a new certificate.
   • Set Signing Option to: Sign SAML response and assertion.
   • Set Signing Algorithm to: SHA‑256.
   • Download the Base64 certificate.
5. Under Set-up section, note:
   • Login URL
   • Microsoft Entra Identifier
   • Logout URL

Configure SAML in Onefile

1. Go to Centre > Integrations > SAML.
2. Enter the following:
   • Training Provider Website Domain — your organisational domain.
   • Single Sign On Service URL — Login URL from Entra.
   • Single Logout Service URL — Logout URL from Entra (not currently used).
   • SAML Entity ID — Microsoft Entra Identifier (must end with a forward slash).
3. Shared token or certificate:
   • Open the Base64 certificate file in a text editor.
   • Remove the header and footer:
     • -----BEGIN CERTIFICATE-----
     • -----END CERTIFICATE-----
   • Remove all line breaks so it becomes one single line.
   • Paste this into the certificate field in Onefile.
4. Click Test Connection.
5. If successful, click Save.
6. Copy the automatically generated Assertion Consumer Service URL.
7. Return to Microsoft Entra →
   • Edit Step 1 (Basic SAML Configuration).
   • Paste the ACS URL into Sign-on URL.

Provisioning Users

Users must be provisioned before SAML login will work. Provisioning aligns Onefile accounts with your SAML IdP accounts using a unique identifier.

To do this:

1. Authenticate using the Onefile API (see API documentation).
2. Send a POST request to the provisioning endpoint with this body:

{
  "OneFileUserId": 0,
  "Email": "string",
  "SAMLId": "string"
}
  

• OneFileUserId — user ID in Onefile.
• Email — user’s login email.
• SAMLId — the user’s Object ID in Microsoft Entra.

Once submitted successfully, the user is fully provisioned for SAML sign‑in.

User Flow

• On the Onefile login page, users select SSO and enter your organisational domain.
• Onefile sends an AuthnRequest using SAML2 POST binding.
• You may also embed your unique SAML link on your website for direct login:
  Format: login.onefile.co.uk/api/samlsso/{guid}

SAML Request & Response Notes

• AuthnRequest uses POST binding and is not signed.
• SAML Response must:
  • Use POST binding
  • Be signed with the certificate provided to Onefile
  • Use SHA‑256
  • Contain the NameID as the SAMLID
• RelayState is not implemented.

Multiple Centre Organisations

If your organisation has multiple Onefile Centres, you only need to configure SAML on one centre. The configuration automatically applies to all linked centres.

Terminology

The terminology used in this article may differ depending on your Centre’s configuration.

Need Help?

If you need assistance, please contact Onefile Support or your internal support team.