Configure SAML SSO

The SAML 2.0 (SSO) plugin allows users to log in to Totara using an account from an Identity Provider (IdP). In this instance, Totara is your Service Provider (SP).

Enable SAML SSO

You can enable the SAML authentication method by following these steps:

1. Go to Quick-access menu > Plugins > Authentication > Manage authentication.
2. Click the eye icon () next to the SAML 2.0 (SSO) plugin to enable it (the eye will be open once the authentication method is enabled).

Configure an identity provider (IdP)

Once you have enabled the SAML 2.0 authentication plugin, you then need to configure an IdP, which will be available as a login option for users. In the SAML protocol, communication happens between an IdP and an SP over specific endpoints. The IdP provides the following endpoints for communication:

• SingleSignOnService
• SingleLogoutService

The SP provides the following endpoints for communication:

• AssertionConsumerService
• SingleLogoutService

To configure an IdP with Totara, you need to inform Totara of the IdP endpoints. This is done by providing Totara with the IdP's metadata (an XML file containing all of the required endpoints and a public key). You can provide the metadata by inputting a URL to fetch the metadata from or by inputting the content of the XML file directly into Totara.

You also need to inform the IdP of Totara's endpoints. How this is done varies for individual IdPs. We have documented how to configure the following IdPs with Totara:

• Azure AD
• Okta
• Auth0

Once both the IdP and the SP have been provided with each other's endpoints, they can communicate correctly. For a successful login request, the IdP provides a list of attributes to be used to identify the user. These attributes need to be mapped to Totara user fields to authenticate the user in your Totara instance.

Create an IdP connection

Follow these steps to create an IdP connection:

1. Go to Quick-access menu > Plugins > Authentication > SSO SAML > Settings.
2. Click Add Identity Provider.
3. Give your IdP a name. This will be the name displayed to users on the login screen.
4. Provide a link to the metadata or paste the IdP's metadata XML in the IdP metadata field.
5. Specify a User identifier and the Totara field you want to map it to. Unique user custom fields are also available as an option.
6. To configure the additional settings and field mappings, click Show advanced settings:
   • On the Field mappings tab, map user attributes provided by the IdP to your Totara instance user. Note that user attributes may be full URLs.
   • The Advanced settings tab contains the following options to modify Totara-specific behaviour when interacting with the IdP:
     • New users: Select how new users should be handled.
     • Existing users: Select how existing users should be handled. 
     • NameID format: Select the format you wish to use.
     • Entity ID: Override the Entity ID used in the SP Metadata.
     • Logout behaviour: Enforce logout at IdP when the user logs out of Totara.
     • Redirect after logout: Specify a redirect URL after logout.
     • Attribute Delimiter: Attribute delimiter used for IdP field mappings with multiple values.
     • Signatures: These settings are not required for secure operation, but may be useful in some cases. Select from the following options:
       • Sign metadata
       • Sign authentication requests
       • Require IdP to sign individual assertions
     • Hide on login page: If enabled the IdP will not be displayed on the login page.
     • Debug: Capture communications and the IdP for debugging purposes.
7. Click Save.
8. Ensure that the Status toggle is enabled to ensure the IdP will be visible on the login screen.
9. From the Manage identity providers page, click the icon of three dots () next to the IdP and select Test to test your new IdP connection.

Migrating users to SAML 2.0 (SSO)

Users must have their authentication method set to SAML 2.0 (SSO) in order to log in via SAML. When importing users via HR import you can set the Auth option to 'ssosaml'.

Alternatively, you can set the Automatically link setting for an IdP to Existing users, and optionally check the Require email verification option. With these settings enabled, existing non-SAML users will be able to log in via SAML if they match the conditions (while still being able to use their existing login methods).

Set up SAML SSO with Okta

To set up SAML SSO with Okta, follow these steps:

1. Sign in to Okta using your credentials.
2. Click Admin.
3. Go to Applications > Applications.
4. Click Create App Integration, then select SAML 2.0.
5. Enter a name and click Next.
6. In Totara, go to Quick-access menu > Plugins > Authentication > SAML 2.0 (SSO) > Settings.
7. Create an IdP.
8. Copy the following information and enter it in Okta:
   • ACS URL -> Single sign-on URL
   • Entity ID -> Audience URI
9. Expand the Advanced settings, then upload the certificate from Totara.
10. Enable Single Logout.
11. Copy the Single Logout URL from Totara to Okta.
12. Copy the Entity ID from Totara to the SP Issuer field in Okta.
13. Fill in the following attribute statements:
    • first_name -> user.firstName
    • last_name -> user.lastName
    • email -> user.email
14. Click Next, select either option, then click Finish.
15. Copy the Metadata URL from Okta, and paste it into Totara.
16. Return to Okta, go to the Assignments tab, and select the Everyone group.
17. In Totara, under User identifier, enter 'email' as the IdP field, and choose Email address as the Totara field.
18. Under Field mappings, add the following mappings:
    • First name -> first_name, on every login
    • Surname -> last_name, on every login
19. Click Save.
20. Click the icon of three dots () and click Test to check the integration works.

Set up SAML SSO with Microsoft Azure AD

To set up SAML with Microsoft Azure Active Directory, you will need a user account with Application Administrator privileges. Log in to your Azure portal and follow these steps:

1. In your Totara instance, go to Quick-access menu > Plugins > Authentication > SAML 2.0 (SSO) > Settings and create an IdP.
2. In Azure, click Azure Active Directory under Azure Services.
3. In the sidebar navigation, click Enterprise Applications.
4. Click + New application.
5. Click + Create your own application.
6. Give the application a name.
7. Select Integrate any other application you don't find in the gallery (Non-gallery).
8. Click Create. You will then be taken to the newly created enterprise application.
9. On the newly created enterprise application, click Single sign-on in the sidebar navigation.
10. Click SAML.
11. Click Edit on the Basic SAML Configuration card and provide the following from your newly created Totara IdP:
    • Identifier (Entity ID)
    • Reply URL (Assertion Consumer Service URL)
    • Logout Url 
    • Alternatively you can download your Totara metadata and upload it by clicking Upload metadata file
12. Click Save.
13. On the SAML Certificates card, click the download link next to Federation Metadata XML.
14. Copy the content in the XML file to your Totara IdP metadata instance.
15. Click Users and groups in the sidebar navigation.
16. Click + Add user/group and assign a user you have access to.
17. On your Totara site, go to your Totara instance and test the settings.
18. Map the attributes provided by the IdP to your Totara instance as required (use the Test Settings page to see what the IdP is providing).
19. To test IdP-initiated login, go to https://myapplications.microsoft.com/.
20. Search for the enterprise you created and click on it to login.

Set up SAML SSO with Microsoft AD FS

To set up SAML SSO with Microsoft AD FS, follow these steps:

1. Install and configure AD DS and AD FS on a Windows Server instance.
2. In Totara (make sure you're using https, and have purged your cache), go to Quick-access menu > Plugins > Authentication > SAML 2.0 (SSO) > Settings and create an IdP. Obtain the federation metadata XML from AD FS. 
3. Add the metadata in Totara as XML.
4. Map 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress' to User identifier.
5. Configure the following mappings:
   • Email address → http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
   • Given name → http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
   • Surname → http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
6. Click Save.
7. Download the metadata from Totara.
8. Connect to the AD FS server.
9. Open the AD FS management tool (Server Manager > Tools > AD FS).
10. Select Relying Party Trusts in the left sidebar, and choose Add relying party trust.
11. Select Claims aware.
12. Upload the metadata from Totara.
13. Give it a name so it can be easily identified.
14. Select Permit everyone.
15. Click Finish.
16. It may not import the ACS/SLO URLs, so right-click on the entry you added, then go to Properties > Endpoints. If it's empty, follow these steps:
    1. Click Add SAML and select Assertion consumer.
    2. Copy the ACS URL from Totara to Trusted URL, set binding to POST and check Default, then click Save.
    3. Do the same for SLO.
    4. Close Properties.
17. Right-click on the entry and click Edit claim issuance policy.
18. Add a rule and select Send LDAP attributes as claims.
19. Enter a name.
20. Choose Active Directory as the attribute store.
21. Map the following fields (LDAP → Outgoing):
    • User-Principal-Name → Name ID (this is important, as if Name ID is not mapped, AD FS will not send SessionIndex)
    • E-Mail-Address → E-Mail Address
    • Given-Name → Given Name
    • Surname → Surname