SSO SAML 2.0: On-Demand Login/User Provisioning

[enojardi]

Overview

Following somewhat similar principles as the LDAP On-Demand Login functionality, this extension to the SAML 2.0 plugin allows the configuration of auto user provisioning. Out of the box, the SAML2.0 plugin requires that the user record exists in ServiceNow for authentication to be successful.

Detailed Explanation

---

This solution leverages the AttributeStatement element found in the SAML Assertion Response (XML), once authentication takes place. Most IdPs embed user attributes in the AttributeStatement element. This solution parses all the attribute-value pairs and then creating an import set. A Transform Map can then be defined to create/update the user in the sys_user (target) table. All of this happens before the Installation Exit performs the query on the user table to see if a user is found.

Technical Components

• (Script Include) SAML2_UserProvisioning: This is the main class used for parsing the XML Response.
• (Script Include) ImportSetUtilExtended: Extension of the out of the box ImportSetUtil Script Include.
• (Installation Exit) SAML2SingleSignon_update1: Extension of the existing SAML2.0 Installation Exit (Note: only 4 lines of code were added from the original)
• (Import Set Table) u_imp_saml_user: This is where all the staging data parsed from the XML will be saved
• (Transform Map) Import SAML User: Transform map used for transforming the user data
• ... And a few little things not worth mentioning...

If you want to watch a demo video on how it works, I have uploaded a short 2 min video here.

Steps to Implement

---

Attached is the update set which contains all the required configuration. Very simple configuration is required after installed. It goes without saying that the SAML2.0_update1 plugin must be installed prior to loading the update set.

Important: In Eureka patch 5, there's been an upgrade to the SAML2_update1 Script Include. This requires some small modifications to the extended Installation Exit included in the update set. Contact me if you get stuck. I will upload a new version once Fuji goes GA.

Some important things to note/configure after installation:

1. The update set will create an import set table called Import SAML User (u_imp_saml_user)
2. The import set table will not contain any fields initially (apart from the fields already inherited from sys_import_set_row)
3. Familiarise yourself with the Properties page and ensure no changes are needed for the two properties
4. For the first ever login, ensure the user already exists in ServiceNow. This will allow for the new fields to be added* to the import set table dynamically (that is, it will depend on how many Attributes are included in the AttributeStatement)
5. The first login may take a couple of extra seconds as the import set table will create the new fields
6. After first login, you're ready to map fields in the "Import SAML User" Transform Map, since the data should have been loaded already.
7. Ensure you use the same field for coalescing as the field you're using to match the user in the SAML Properties page
8. I recommend mapping at least the user_name and email in the Transform Map, otherwise it will be blank for new users.
9. New users created will have a random password set - this is to avoid local login if external authentication is not enforced (or if accessing side_door.do)

* If fields are not added, it could be because the AttributeStatement does not follow standard SAML format. You may need to tweak the Script Include "SAML_UserProvisioning". There are some comments/instructions in the _process method.

Bonus: Override NameId Policy

I've found that a few IdPs do not provide a persistent or unique key in the NameId Policy element. Instead, they provide a variable string (transient), which can sometimes be a sessionID. As you may have guessed, this value could never be used to match a user in ServiceNow, as the value will always be different. If for some X reason, you cannot change this, I have included some functionality to allow you to override the NameID policy. This works by providing the "Name" of the Attribute (from the AttributeStatement) you want to use, instead. To configure this is very simple and can be done through this new System Property: glide.authenticate.sso.saml2.nameid_policy_override.

Things to Remember

---

This is a custom solution. That being said, I have tested it successfully with 3 different IdPs: SSOCircle, Microsoft ADFS and OpenIdP - the last one even needing the NameId override. You could also apply the same logic from this solution for Unencrypted HTTP Header and Digest Token SSO methods as described in this other post here.

Message was edited by: Jonatan Jardi

[enojardi]

Thanks for sharing this, Brian! Good finding.

By the way, I have talked to the developers about getting this functionality as OOTB and they're keen, so you may see JIT/User Provisioning for SAML   sooner than you think

[Brian189]

That is good news, thanks Jonatan.   Here is the link for application scope - Application Scope - ServiceNow Wiki.   I think the last hurdle for SAML user provisioning will be to incorporate it into the Multi-Provider SSO setup in Fuji.   Do you have any plans to do that in the near future?   Or would it be something that is handled when it is incorporated as OOTB?

Thanks,

Brian

[enojardi]

Hi Brian, yes, that's the plan as MultiSSO is the way moving forward I haven't had time to sit down and convert it to MultiSSO, but I believe one of my colleagues here may have done that for a customer. It wasn't that hard from memory, just copying and pasting the lines into the right place

[Brian189]

Hi Jonatan,

I have a question on the SAML script, I am not sure why you added these lines and was wondering if you could explain why this is in there?

if (action && (JSUtil.type_of(action) === 'string')) {  

  action = this._action;

Thanks for the help,

Brian

[enojardi]

Hi,

Good question. That line is required since there is a global variable 'action' in transform maps which is set to either 'update' or 'insert', etc. This 'action' in the SAML script is used to parse the RelayState, so that's why I capture the value before the transformation runs, and then reset the value. Makes sense?