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

[david_macalpine]

Hi Jonatan and the rest of the community,

Firstly, thanks for the work and thought that went into providing the code/configuration and the time taken to write it up for all to benefit from.

Our customer desires the auto provisioning of users but this is a new Fuji instance and we have enabled the Multiple Provider SSO plugin.   Are there likely to be issues around using the Mulit Provider plugin, rather than a vanilla SAML2.0_update_1?

Has anyone had a chance to look at this in the Fuji context, yet, or assessed the use of the provided (and highly desirable) with the Multiple Provider plugin?  

Any news most welcome.

Regards,

David Macalpine

[enojardi]

Hi David

Thanks for the feedback!

It's been on my to-do for a while to release a Fuji compatible version of this functionality. I just haven't found the time, and now with Knowledge even less! I'll see if I can do something next month.

My gut feeling says that it wouldn't just work straight away, since the Installation Exits have changed. That being said, I have a feeling it would be pretty easy to migrate my code to those (if you look at the code, I have prefixed all the additions with some comments).

By the way, you'll be pleased to know that I'm working with the developers to get this as OOTB for a future release

[david_macalpine]

Fantastic news re your enlisting the Dev team to put this in out of the box.   I look forward to seeing the result, and, good luck with knowledge next week.

[Brian189]

Hi Jonatan,

We are running this SAML User provisioning and it has been working great.   We upgraded to Fuji patch 1 in our DEV environment last Thursday and found out that SSO is broken unless I inactivate this SAML user provisioning.   I am not sure what is needed to fix this, but wanted to let you know I ran into problems after upgrading to Fuji.   Any help on this would be appreciated.   On the SAML properties page I also have the warning - Please upgrade to the latest SAML plugin as soon as possible - 'Integration - Multiple Provider Single Sign-On Installer'.   I opened a ticket with HI to see if they can help me with this issue.

Further researching today, we isolated the SAML2SingleSignon_update1 script erring on this line -   if (action && (JSUtil.type_of(action) === 'string')) {.   Not sure why, will continue working on this and will post an update if I find out why it is failing.

Thanks,

Brian

[Brian189]

We found that the script include JSUtil was marked as Accessible from "This application scope only".   Changing it to "All application scopes" allowed the SAML script to reference JSUtil and the script started working again.   I am not sure why this change was made to JSUtil, but will post again if I find out any more information.

Thanks,

Brian