Purpose

The SAML integration allows Onefile users to authenticate through an external provider (yourself) to then get logged straight into their account. Users can log in via your website directly without needing to visit Onefile’s login page. However, They can still choose to log in via Onefile’s login page but they can instead select SSO and enter your domain to login.

Set-up

Pre-requisites:

• SAML integration is enabled – please contact the account manager if this is not.
• API is enabled and an API key is supplied to the customer (separate to SAML but vital for user provisioning)
• A Microsoft Entra account

On Microsoft Entra (previously Azure):

• Navigate to Enterprise Apps > All applications and create a new entry for Onefile
• Under basic SAML configuration, please add the following:
  1. Identifier (Entity ID):https://login.onefile.co.uk/api/SAMLSSO/meta
  2. Reply URL (Assertion Consumer Service URL): https://login.onefile.co.uk/api/SAMLSSO
  3. Sign on URL -Leave this blank for now, but you will revisit this at a later stage.

It should look like this:

• Under Attribute & Claims please press edit.
  1. Add a required claim for Unique User Identifier (Name ID) with type SAML and the value of user.objectid

• Under step 3 for SAML certificates, please press the edit icon. 
  1. Add a new certificate and make that active. Make sure the Signing Option is set to Sign SAML response and assertion and the signing algorithm is set to SHA-256 and press save.
  2. Download the Base64 certificate onto your computer and keep that handy for now.

Next navigate to your Onefile configuration for SAML (Centre >> Integrations >> SAML) and start filling out everything.

Training Provider Website Domain: This is your website domain

Single Sign On Service URL: This is the Login URL from step 4 of Entra

Single Logout Service URL: This is the logout URL from Entra (although this step is no longer used with Onefile)

SAML Entity ID: This is the Microsoft Entra Identifier URL. Please make sure the URL ends in a slash as when copied from Entra.

Shared token or certificate: 

This is from the base64 file. Before copying over the certificate onto the field, you must first open the certificate onto a text editor like Notepad.

Then you must delete the first and last lines (-----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----)

Then you need to delete each and every carriage return so the token is one long line rather than have carriage returns (new lines). See example with a dummy certificate:

 Once you have the certificate in one line, please copy this unto Onefile’s certificate textbox.

• Test connection and upon successful connection, press Save.
• When you go back into the integration on Onefile, you should see that the Assertion Consumer Service URL is automatically generated. Please copy this.

Navigating back onto Microsoft Entra

Once this is done, your integration is set up between Onefile and Entra. You can test this on Entra but do note that it will fail if your user is not provisioned (see below for steps on how to provision).

If you are enforcing the users to log on via your website, the sign on will be called via the Assertion URL from Onefile.

PLEASE NOTE: When changing the configuration, specifically the certificate on Onefile’s Integration page, this generates a new Assertion URL. Please make sure to update your configuration everywhere if doing so.

Provisioning

Now that you have the configuration set-up, you will need to provision each one of your users so when they sign into via your identity provider (Idp), they are then logged straight into their Onefile account.

Our system employs SAML user alignment to link OneFile users with your SAML accounts. This resolves the issue of users not sharing the same email domain due to variations in systems or organisational structures.

During user provisioning, an additional API call is required to set a unique identifier for the user account used in the authentication. This ensures secure access through SAML authentication.

Enabling SAML user alignment eliminates the constraint of shared email domains, accommodating diverse users and systems. This simplifies access and enhances security, allowing users from different domains to seamlessly connect with their designated SAML accounts, irrespective of email or domain differences.

To do this, you must first have access to our API. You need to first authenticate successfully using your provided API key first (See: Onefile Help Centre : Authenticate via the API)

Once authenticated, the provisioning URL is OneFile Eportfolio API Documentation

It takes the body:

{

  "OneFileUserId": 0,

  "Email": "string",

  "SAMLId": "string"

}

• OneFileUserId: This is the UserID of the user/learner on Onefile. You can either find this on the URL on the Eportfolio UI or you can call the API on the User endpoint (OneFile Eportfolio API Documentation) to find this.
• Email: This is the login email of the user. You can find this on the User endpoint as well.
• SAMLId: This is the ObjectID of that user on Microsoft Entra. You can find this by searching that user.

When you send a POST to the provisioning endpoint above with the body, upon successful response, that user will be successfully provisioned.

User flow

• When configuring your SAML Integration within OneFile, you must provide a domain field. This is used on our login page, if your users arrive at our site directly. Users click SSO on our login page, type in your domain (e.g. onefilecollege.ac.uk) and we will use SAML2 Post binding to send the user with an Authnrequest. 
• We will give you a link such as login.onefile.co.uk/api/samlsso/{guid}. This guid is unique to your integration and you can use this in a simple HTML link on your site to start the authentication process for your users. This will generate and POST the Authnrequest to your system. 

AuthnRequests

As the Service Provider we will send you an AuthnRequest

• We only use POST binding.
• Our Authnrequest is not signed. 

SAML Response

• We only support POST binding. 
• We do not process any additional attributes.  
• We expect the Subject NameId to contain a guid, which we refer to as the SAMLID. This guid is the representation of the user in your IdP system. 
• We do support unsolicited SAML Response processing, so you can send us a SAML Response directly. 
• We expect your SAML response to be signed using the certificate provided to us when you configured the integration in our system. 
• SAML Responses must be signed using SHA256. 
• RelayState is currently not implemented.

Multiple centre organisation?

If you're an organisation with multiple OneFile Centres, you'll only need to configure SAML on one centre and the changes will apply accross all centres linked to your organisation.