Prior to this week, I did not know who <a href="https://www.talentlms.com/">TalentLMS</a> is, what <a href="https://wiki.oasis-open.org/security/FrontPage#SAML_V2.0_Standard">SAML</a> does, and how <a href="https://auth0.com/">Auth0</a> fits into the SSO alphabet soup. However, when a client wants something figured out, that's what I am here to do! After pouring over documentation for both TalentLMS and for Auth0, going down several dead-end paths, and nagging a few of my coworkers to "try it again?", I now successfully (and very delicately) have credentials collected from Auth0 logging a user into TalentLMS.
The primary steps involved in this process include:
<ol>
<li><a href="#enable-saml20-sso-integration-in-talentlms">Enable SAML2.0 SSO integration in TalentLMS</a></li>
<li><a href="#create-an-auth0-application">Create an Auth0 Application</a></li>
<li><a href="#map-setting-in-talentlms">Map Setting in TalentLMS</a></li>
<li><a href="#create-auth0-rule-to-define-saml-mapping">Create Auth0 Rule To Define SAML Mapping</a></li>
<li><a href="#capturing-first--last-name">Capturing First &#x26; Last Name</a></li>
<li><a href="#how-to-break-talentlms">How to Break TalentLMS</a>
<ol>
<li><a href="#talentlms-username-must-match-auth0-name">TalentLMS "Username" must match Auth0 "Name"</a></li>
<li><a href="#dont-switch-sso-login-screen-until-everything-works">Don't Switch "SSO login screen" Until Everything Works</a></li>
<li><a href="#talentlms-does-not-permanently-delete-users">TalentLMS Does Not Permanently Delete Users</a></li>
</ol>
</li>
<li><a href="#is-there-a-better-way">Is There a Better Way?</a></li>
</ol>
This post was updated on 2020-01-31, adding information about TalentLMS's <code>nameidentifier</code> requirements and how to lock down user accounts.
<h2>Prerequisites</h2>
TalentLMS requires a subscription level of Basic or above to implement Single Sign-On. I could not find any way around this, even temporarily. They don't have any sort of a "developer" plan or other trial period to be able to demonstrate a proof-of-concept. At $159.00 per month, one will need to invest at least that much to make this work. Thankfully, my client had no problem bumping up their subscription tier without even knowing if SSO would work.
An Auth0 account is also required. Their free tier includes everything necessary, but even if it didn't, a newly created instance includes all paid features for a few weeks to get you started.
<h2>Enable SAML2.0 SSO integration in TalentLMS</h2>
Over in TalentLMS, go to <code>Home / Account &#x26; Settings / Users</code> and change the <code>SSO integration type</code> to "SAML2.0".
<img src="/images/sso-step1-talent-settings.png" alt="TalentLMS - Settings - Users - SSO Integration type">
At the bottom of the page is the <code>Identity provider (IdP) configuration</code> section. There are values in here that need to go over to Auth0.
<pre><code>The Entity ID is:
{instance}.talentlms.com

The Assertion Consumer Service (ACS) URL is:
https://{instance}.talentlms.com/simplesaml/module.php/saml/sp/saml2-acs.php/{instance}.talentlms.com

The Single Logout Service URL is:
https://{instance}.talentlms.com/simplesaml/module.php/saml/sp/saml2-logout.php/{instance}.talentlms.com
</code></pre>
<h2>Create an Auth0 Application</h2>
Within the Auth0 dashboard, go to <code>Applications</code>, click <code>Create Application</code>, given it a name (like "TalentLMS") and choose the <code>Regular Web Application</code>.
<img src="/images/sso-step2-auth0-createapp.png" alt="Auth0 - Applications - Create Application">
For now, skip the Quick Start and Settings; go to Addons and flip the toggle for "SAML2 Web App".
<img src="/images/sso-step3-auth0-saml2webapp.png" alt="Auth0 - Applications - SAML2 Web App">
Put the url for the TalentLMS instance as the <code>Application Callback URL</code> and paste the Settings JSON below (replacing "{instance}" with your value).
<pre><code>{
 "mappings": {
 "user_id": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
 "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
 "name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
 "given_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
 "family_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname",
 },
 "passthroughClaimsWithNoMapping": true,
 "mapUnknownClaimsAsIs": true,
 "logout": {
 "callback": "https://{instance}.talentlms.com/simplesaml/module.php/saml/sp/saml2-logout.php/{instance}.talentlms.com",
 "slo_enabled": true
 }
}
</code></pre>
Since TalentLMS requires a unique identifier (TargetedID), a First name, a Last name, and an Email, we need to have Auth0 capture all four fields on sign-up and pass them through with the SAML identity claim. This requirement is what took up the bulk of my time trying to figure out. We'll come back to adding all the finishing pieces needed to make it work.
After you click the <code>Save</code> button at the bottom of the modal, switch over to the <code>Usage</code> tab, and click on "Download Auth0 certificate". Save this file and open it in your favorite text editor. It will look something like this:
<pre><code>-----BEGIN CERTIFICATE-----
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDMYfnvWtC8Id5bPKae5yXSxQTt
BAMTEGhjLXBvYy5hdXRoMC5jb20wHhcNMTkxMTA4MTgwNzM0WhcNMzMwNzE3MTgw
NzM0WjAbMRkwFwYDVQQDExBoYy1wb2MuYXV0aDAuY29tMIIBIjANBgkqhkiG9w0B
AQEFAAOCAQ8AMIIBCgKCAQEAvyV51yFcm+SJgWT8AKcw0uFTFRZnjkrmJZCMuKvC
+Zpul6AnnZWfI2TtIarvjHBFUtXRo96y7hoL4VWOPKGCsRqMFDkrbeUjRrx8iL91
KjIU8w3a8+9TDRpVbTLYtG9t8f1SjDcroBHLaF1XE8gH253L3tzK0Vfw3v7SHM9V
lso3/gsf/CfJIxQXVkCtUinRElRAIGbSSuOL9fP5Coy29uC4h+w+Tkan0IQsVoTu
bE5TH49mTN/ZF9Pcio1dktJOLVi+Ww4yl9l4Qbu4K4tEK4FXWyNqTDc+11SFd2uU
C3RMtsyO6qT+KeuwBtBjqgKHjB0jl1Yn/Du8ljPESb2mgwIDAQABo0IwQDAPBgNV
HRMBAf8EBTADAQH/MB0GA1UdDgQWBBRXd2raOpQViBgFHsR9seM1fN9CdTAOBgNV
4/srnyf6sh9c8Zk04xEOpK1ypvBz+Ks4uZObtjyQjtQ8mbDOsiLLvh7wIDAQABad
1l1v5K/yIqt1b17mtnIw5EXGpnwe2INxeUVvOz2eQAff1UdmyKh605LUKAFd9SZk
DnRiFU4QD0yenFkSlpnjU3Xy7UzGg2Nv5j/d8RsPGrg+pJDVGwFSriEg1TQQX4ZX
MhcxkOZFsw+EjKjx8j9x6gDZ3q+e5GvTPNO/jUX9gfO8Bz8SnhKyDiqHtvZhkBlG
yQjtQ8mbDOsiLLvh7wIDAQAB/5ml3plqk252APWd9hsW1IbLCrc4yttA6usDYJ1d
zohmAMID02C7cYoiR1e2dK+wjHsuBGptjGmOkL44ZjjY1FCljomvzYalCFeNeHo=
-----END CERTIFICATE-----
</code></pre>
<h2>Map Setting in TalentLMS</h2>
Flipping over to that other tab (you didn't close it, right? Because there's a lot more of this back-and-forth to do) - now we can fill out most of these values:
<img src="/images/sso-step4-talentlms-saml.png" alt="TalentLMS - SAML - Settings">
<ol>
<li>The <code>Identity provider</code> in TalentLMS matches the <code>Issuer</code> in Auth0.</li>
<li>Click the "or paste your SAML certificate" link and drop in the big block of random looking characters from the PEM file.</li>
<li><code>Remote sign-in URL</code> comes from Auth0's <code>Identity Provider Login URL</code>.</li>
<li><code>Remote Sign-out URL</code> is the <code>Identity Provider Login URL</code> with "/logout" appended.</li>
<li><code>TargetedID</code>, <code>First name</code>, <code>Last name</code>, and <code>Email</code> get the schema values from the <code>mappings</code> section of the Auth0 JSON.</li>
</ol>
Now that everything has been pasted into their respective fields, go ahead and click the <code>Save and check your configuration</code> button. You should be prompted to Log In or Sign Up. Proceed with signing up, which should then kick you back to the TalentLMS "Check your SSO configuration" page.
<img src="/images/sso-step5-login-signup.png" alt="TalentLMS Check your SSO configuration">
<h2>Create Auth0 Rule To Define SAML Mapping</h2>
There are two pieces still missing: sending the <code>given_name</code> and <code>family_name</code> fields from Auth0, and capturing those fields during the Sign Up process.
Auth0 stores any additional data that is captured into <code>user_metadata</code>, which can be viewed in <code>Users &#x26; Roles -> Users</code>, select a user, then scroll down to the <code>Metadata</code> section. The next step is in our process to add these SAML configuration mappings to pull data from the <code>user_metadata</code>. To do this, we are going to add a new Auth0 rule. Click on <code>Rules</code>, <code>+ Create Rule</code>, select <code>&#x3C;/> Empty rule</code>. Give it a name like "TalentLMS SAML Mappings" and <a href="https://gist.github.com/drovani/41b6f9c5acb186e8ca5ef4b4c7321c54#file-auth0-rule-talentlms-samlmapping-js">paste the following</a> into the Script section:
<pre><code>function (user, context, callback) {

 if (context.clientID === '{{auth0-application-client-id}}') {

 const RULE_NAME = 'talentlms-samlmappings';
 const CLIENTNAME = context.clientName;
 console.log(`${RULE_NAME} started by ${CLIENTNAME}`);

 if (!user.user_metadata.given_name || _.isEmpty(user.user_metadata.given_name) ||
 !user.user_metadata.family_name || _.isEmpty(user.user_metadata.family_name))
 {
 console.log(`${RULE_NAME} Insuffient user_metadata for TalentLMS - given_name: ${user.user_metadata.given_name} family_name: ${user.user_metadata.family_name}`);
 callback(null, user, context);
 }

 var auth0Identity = _.find(user.identities, function(u) { return u.provider === 'auth0'; });
 var alphanumericUserId = auth0Identity.provider + auth0Identity.user_id;

 user.app_metadata = user.app_metadata || {};
 user.app_metadata.alphanumeric_auth0_user_id = alphanumericUserId;

 context.samlConfiguration.mappings = {
 "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier": "app_metadata.alphanumeric_auth0_user_id",
 "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress": "email",
 "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/given_name": "user_metadata.given_name",
 "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/family_name": "user_metadata.family_name"
 };

 }

 callback(null, user, context);
}
</code></pre>
<ul>
<li>Line 3: substitute {{auth0-application-client-id}} with the <code>Client ID</code> value for this Auth0 application. This ensures the rule only runs for the Auth0 application configured for TalentLMS login.</li>
<li>Line 5-7: simple logging to validate the rule runs when it is supposed to</li>
<li>Line 9-14: validate that the first and last names have been captured already, otherwise abort. A subsequent rule can be made to enable <a href="/posts/2019/auth0-progressive-profiling-proof-of-concept/">Progressive Profiling</a></li>
<li>Line 16-20: strip out the pipe in the Auth0 id, assign it to the cached <code>user</code> object</li>
<li>Line 22-27: map the fields from the rule's scope of variables to the SAML schema.</li>
</ul>
Click <code>Save Changes</code>. You can even click <code>Try This Rule</code>.
<ol>
<li>Replace the <code>User</code> part of the test input:</li>
</ol>
<pre><code>{
 "name": "jdoe@foobar.com",
 "email": "jdoe@foobar.com",
 "user_id": "auth0|0123456789",
 "nickname": "jdoe",
 "picture": "http://foobar.com/pictures/jdoe.png",
 "identities": [
 {
 "provider": "auth0",
 "user_id": "0123456789",
 "connection": "Username-Password-Connection",
 "isSocial": false
 }
 ],
 "user_metadata": {
 "given_name": "John",
 "family_name": "Doe"
 }
}
</code></pre>
<ol>
<li>Replace the <code>clientID</code> portion of the <code>Context</code> script with the same value used in the rule.</li>
</ol>
After clicking the <code>Try</code> button, the "Output" should indicate that the rules context has a <code>samlConfiguration</code> object containing a <code>mappings</code> object that matches when you entered above.
<h2>Capturing First &#x26; Last Name</h2>
The final step is to customize the Sign Up page to require the user to enter values for First and Last name. The simplest way (that I found) to do this is to customize the login page in Auth0. Under <code>Universal Login</code>, click on the <code>Login</code> tab, toggle the "Customer Login Page" and select the "Lock" Default Template. This uses the <a href="https://auth0.com/docs/libraries/lock/">Auth0Lock</a> and for our purposes, we will be utilizing the <code>additionalSignUpFields</code> array <a href="https://auth0.com/docs/libraries/lock/v11/configuration#additionalsignupfields-array-">configuration option</a>. Add the following JSON snippet to the code block:
<pre><code>additionalSignUpFields:[{
 name: "given_name",
 placeholder: "Enter your First Name"
},
{
 name:"family_name",
 placeholder:"Enter your Last Name"
}],
</code></pre>
And it should look something like this:
<img src="/images/sso-step7-customize-login-page.png" alt="Auth0 - Customize Sign Up Fields">
Click <code>Save Changes</code> and that should be it!
Flip back to the TalentLMS <code>Check your SSO configuration</code> page, click the <code>Log out</code> button (to clear your Auth0 session), and click the <code>Log in</code> button. Once you do so, you should now have four green checkmarks!
<img src="/images/sso-step6-successfully-logged-in.png" alt="TalentLMS - Successfully logged in.">
If you get an error here, it is probably because the profile you are using did not have a <code>given_name</code> and <code>family_name</code> in the user's meta data. Within Auth0, go to <code>Users &#x26; Roles -> Users</code>, edit the user you are logging in with, scroll down to the <code>user_metadata</code> window and add the following:
<pre><code>{
 "given_name": "TestGivenName",
 "family_name": "TestFamilyName"
}
</code></pre>
Save changes, go back to TalentLMS, and attempt to log in again.
<h2>How to Break TalentLMS</h2>
The major problem I found with this solution is that it is extremely fragile. There are several ways to completely break logging in.
<h3>TalentLMS "Username" must match Auth0 "Name"</h3>
When setting us TalentLMS for SAML, the field that gets mapped to "TargetedID" becomes the user's "Username". By default, this is editable by the user in TalentLMS. If the user changes that value in TalentLMS, then the next time Auth0 sends over the authenticated user information, the values won't match. TalentLMS will then try to create another user, but will fail because the email address is already on an existing account.
Thankfully, the steps are straightforward in how to disable the ability for a user to change their username in TalentLMS:
<ol>
<li>From the administrator panel, click on "User types"</li>
<li>Click the edit icon next to the Learner-Type</li>
<li>Expand the General -> Profile tree</li>
<li>Disable "Update" and "Reset password" settings</li>
<li>Click the Save button</li>
<li>Repeat these steps for Trainer-Type and Admin-Type (you cannot remove the ability from the SuperAdmin user type)</li>
</ol>
<img src="/images/sso-step8-talentlms-disable-profile-update.png" alt="TalentLMS - Disable Profile Editing">
<h3>Don't Switch "SSO login screen" Until Everything Works</h3>
At the bottom of the Users settings page in TalentLMS is an innocent looking drop down list with the label of "SSO login screen" with two options: "Login page + IdP login link" and "IdP login page". Since I was just testing things out, I flipped the option to the second of the two, clicked "Save" and promptly locked myself (and everyone else) out of the TalentLMS instance. It required submitting a support ticket to have them revert the setting - quite an embarrassing moment, since I had to go back to the client and have them verify to customer support that this change needed to be made. TalentLMS should really have a modal pop up that says:
<blockquote>
Are you sure? Because if SSO login isn't perfectly working, you're going to screw things up. Also, if you haven't already made a SSO user a "SuperAdmin" you should do that, or you won't be able to get back into the administrative dashboard to fix any SSO settings.
Save Changes? or Revert?
</blockquote>
After you have everything working with SSO, and have an SSO user as a SuperAdmin, then you can change the login to be "IdP login page". This will force users directly to Auth0 to authenticate, removing the step of clicking the "Log in with SAML 2.0" link.
<h3>TalentLMS Does Not Permanently Delete Users</h3>
In my testing, I would frequently delete a user from both TalentLMS and Auth0 so that I could restart the entire sign up / log in workflow from the beginning. However, I quickly ran into an issue where TalentLMS would claim that an email address was already taken - even though I knew I had deleted the user.
It turns out that TalentLMS only soft-deletes users (even if an Admin clicks the Delete button). If you want to <a href="https://help.talentlms.com/hc/en-us/articles/360014658253-How-to-delete-users-and-courses-permanently">permanently delete users</a> you need to go through the convoluted process to permanently delete them. Thankfully, the Knowledge Base article was easy to find.
<h2>Is There a Better Way?</h2>
TalentLMS and Auth0 also support OpenID Connect as an SSO option, so that would also be an option. I don't have a good reason why I went with SAML over OpenID. Maybe someone else can share their experience and we'll see what the advantages for each might be.

Rovani's Sandbox

talentlms

Using SAML 2.0 with Auth0 to Authenticate Users in TalentLMS