This is a technical article, targeting network and system engineers that have a strong familiarity with SAML and IdP configurations.
LemonadeLXP offers SAML2 SSO in addition to its standard registration mechanism. SAML2 is a system that describes a relationship between two servers - one being the identity provider (IdP, you) and the other being the service provider (SP, LemonadeLXP).
LemonadeLXP recommends and supports SP-initiated SAML2. "SP-initiated" means that users visit your LemonadeLXP URL, click a login link, and log in after that. The SAML process will transport them between LemonadeLXP and your systems to establish identity. It can be a very friction-free experience for the user since they're typically logged into your headquartered systems already!
LemonadeLXP can work in "dual mode," allowing both standard and SAML2 registrations. You can also restrict login to SAML2 only. Doing so ensures that your systems are the only ones that control identity and provisioning.
Configuring SAML2 SSO
To configure SSO, head to /admin and:
SELECT "SETTINGS"
SELECT "Config"
CLICK the third tab in the wizard, "Single Sign On"
You will be presented with this screen. Your systems administrator should be able to provide you with all of the information that should be entered into these fields.
Please continue reading below, for more details on the Attribute Mapping section.
Notes
Field | Description |
Require Single Sign-On | If you enable this setting, the standard registration will be disabled. Users will be limited to SSO, without exception. |
Type | The setting allows you to toggle between "Disabled" and "SAML 2.0". When you toggle to "Disabled" your settings are not lost. |
Sign AuthN requests | This setting is highly recommended. You'll need to install the SP cert into your IdP, but it ensures that the SP can authenticate the login request. This gives you an additional measure of protection against forged auth requests.
Download the SP certificate from the link at the bottom of this configuration panel. (Hint: locate the text that reads "You can download the SP public certificate here") |
Attribute Mapping
Attribute Mappings are how we tell LemonadeLXP what labels your IdP affixes to user information. In the tech world, these are called "Claims".
LemonadeLXP can only draw your user attributes from claims. It cannot extract information from any other aspect of your SAML2 payload.
LemonadeLXP can act on five different claims, 4 of which are required.
Type | Default Claim Label | Description |
Email Address* | The user's email address | |
First Name* | FirstName | The user's first name |
Last Name* | LastName | The user's last name |
Unique User Id* | User | A distinct user ID, that is permanent for each user record. Important, do not use recycled IDs, or IDs that could collide. For these reasons, email address is not a good candidate. |
Group Claim | No default claim used | Group Claim is a special claim that can be used to automatically trigger group associations. For more on this, please read the "Automatic Group Management" section below. |
* Required claim information
Tip: We offer the "Override" flexibility to satisfy cases where the IdP's claim labels are difficult to change. You have the option of changing the IdP to use LemonadeLXP's claim labels, or you can specify overrides to tell LemonadeLXP in which claim arrays to find the relevant information.
Automatic Group Management
If your SAML2 IdP supports pushing group information through with the SAML2 payload, then you can instruct LemonadeLXP to use your IdP's data to organize learners into groups.
The first step is to specify the Group Claim label Attribute Mapping. This tells LemonadeLXP where to "read" group information.
Then, head over into your individual Groups and specify the Claim "strings" that LemonadeLXP should match against. These exist in the individual Group edit panels, under "To which SAML2 group claims should this group auto-attach?". You can configure multiple strings per group, or a similar string across many groups.
This complex relationship is best explained through an example:
Group Binding Example
A. We want all learners in the "Technology" directory of our IdP to automatically join the "Development" and "Security" Groups in LemonadeLXP.
B. We use Google's SAML2 which supports pushing the employee info through a "Department" field.
Given these constraints:
On the Google side, we ensure that the SAML2 binding is sending "Department" information. This way, LemonadeLXP has something to 'read' in the attribute mapping.
In LemonadeLXP, we specify the Override for "Group Claim" as "Department", as dictated by Google.
Still in LemonadeLXP, editing Groups, we add "Technology" to the "To which SAML2 group claims should this group auto-attach?" section in both groups (Development and Security).
Subsequently, when the IdP pushes the word "Technology" through the "Department" claim, LemonadeLXP will scan its database for all groups that contain the substring "Technology" as match claim. If groups are found, they will be automatically associated with the learner as they log in.
What's more, if you enable the Automatically Manage Groups, LemonadeLXP will automatically remove groups not found in the claim data sent by your IdP. That way, LemonadeLXP group associations are adjusted with each user login. Note, this subfeature is only enabled for non-admin users.
It's a substring match!
This is best explained with some examples.
Group Auto-Attach String | SAML2 Claim | Will it match? | Why? |
tech | technology | Yes | tech, is a substring of technology |
customer service | customerservice | No | whitespace is important, the string is not the same |
bank-tellers-new-york-12 | bank-tellers-new-york | No | the group auto-attach string is more specific than the saml2 claim |
bank-tellers-new-york | bank-tellers-new-york-12 | Yes | The auto-attach string is a proper substring of the claim |
In practice, learners often belong to many groups within your active directory. You can still communicate this information to LemonadeLXP by collating your group names together in the claim formulated by the IdP.
Careful, some IdP systems will escape characters such as slashes, and LemonadeLXP has no means to understand this. Experiment with your claims and your IdP to see how it behaves.
Advanced Group Binding Example
Building on the example just above, if you have assigned hidden groups through triggers or manual assignment, you will find that every SAML login 'strips' groups from users. In matching mode, LemonadeLXP ensures that groups are synchronized with your claim configuration.
If you want to use matching mode, yet preserve any hidden group assignments, you will notice there is a second toggle in the "Automatically Manage Groups" section under Settings > Config > Single Sign On. Its label reads: "Do not remove hidden groups when under matching mode. This allows you to automate group assignment via SAML claims, while still allowing you to manually add hidden groups otherwise."
Check this option to prevent matching mode from stripping hidden groups on login. This allows you to combine triggers or manual assignment with SAML matching.
A hidden group, is a group whose "Can users freely register into this group?" toggle is set to No.
On SP Cert Expiry
The SP cert can operate beyond its expiry. It is also generated from a private CA.
SP certs are destined for server-to-server exchanges, so their expiry isn't as sensitive as say, a website SSL cert would be. SSL certs expire to ensure that issuers can apply the latest security standards. If you examine the signature on our SP cert, you will see that it is using a very standard and recent composition.
What's most vital to consider, is that the SAML2 payload that is encrypted with this SP cert is still posted over SSL with a valid cert.
FAQ
Q. Can I use email address as user id in the attributes configuration?
In theory, you could - and it might work for awhile - but you really (really!) shouldn't. Email addresses can change, which breaks the concept of a UID (stable). We've encountered cases where people get married and their email address changes, or, email nomenclature causes a collision as people join and leave your organization. In these cases, your accounts would get mixed irreparably with email as a primary key. In most AD systems, you have an official user ID that is immutable and distinct. You should use this type of identifier (system generated, auto incremented, etc.). Not something that a human can adjust.
Q. Can I send something other than an email, as email address?
No, the email address travels very deep into the system and serves a multitude of purposes. LemonadeLXP needs a valid email address per user.
Q. What happens if the system sends two primary IDs via SAML bindings for a same user?
There should never be a case where a user is attributed two primary IDs in your IdP. If this occurs, the log-in will be prevented on the LemonadeLXP side because of the discrepancy. You should correct your GUID choice in the IdP side, and when complete, write your LemonadeLXP CX rep to organize a manual clearing of IdP keys. This will allow LemonadeLXP to automatically bind your new primary ID to users as they log in (automatic).
Q. Will LemonadeLXP automatically adjust email addresses as users log in via SSO?
Suppose your user's email address changes at the IdP (but their primary ID remains stable). In that case, they will still experience a seamless log-in experience; however, LemonadeLXP will not automatically adjust the email address in its database.
Q. When SSO is enabled, and even forced, what is chosen as "username"?
Email address is used as username input. Username is an artifact from LemonadeLXP's early days. The concept of username is deprecated and will be removed in a future iteration. At present, it only works as an "auth-alternative."
Q. If a user registered with "standard registration" using '[email protected]', and then uses SAML2 to sign in. If the SAML2 payload denotes that their email is '[email protected]', what happens?
To answer this question, you have to focus on an extra detail - the GUID that is in the SAML2 payload. One of two situations is true:
GUID exists in the database | Email Match is Found | Action |
No | Yes | The SAML2 authentication, will bind its GUID to the existing user account, essentially merging authentication. Because LLXP uses email verification, it is assumed that your IdP is factual, so the operation is assumed to be idempotent with standard login. |
Yes | Yes | Alert! In this case, the system halts the auth process. A GUID collision prevents login, since the GUID could only have been injected by a separate account. In this case, it is assumed that there is a problem at the IdP level (no two accounts should have the same GUID). LLXP prevents login to mitigate damage. |
Q. Will the LemonadeLXP support team manage my IDP certificates?
No. It is your responsibility to react to internal certificate changes, certificate expiry, and certificate intake. Make sure that your LemonadeLXP instance gets registered into your internal change management ledger, so that you are aware that your LLXP instance must be adjusted when certificates are manipulated.
Q. Can you please issue a new SP certificate just for us?
No. Doing so would force all our clients to change functional configurations for no reason other than the cert's expiry date, which is not vital to protecting the data it contains. The imposition far outweighs the benefits. Note, the SP certs would however be changed if a vulnerability in the current certificate's construction were identified.