SAP Analytics Cloud User and Team Provisioning SCIM API Sample Scripts Update v0.7 – what’s new

My SAP Analytics Cloud User and Team Provisioning SCIM API Sample Scripts recently received an update to version 0.7. This blog post is for those that already use the samples and would like to understand what’s new and a few tips on how to update to this version from earlier version.

If you’re new to the samples, then there’s no need to read this as the main introductory blog post and the user guide have already been updated. The ‘Sample Scripts Presentation’ will be updated soon. It means everything is in one place for you, rather than having to read lots of different blog posts. Nevertheless, you might find it interesting.

Highlights

• No need to edit code to set default settings for new users. This update now stores these settings (date, time, and number formats etc.) as Postman Environment variables. It introduces a kind of ‘default user’ concept and means you can copy the settings of an existing user as the basis for new users.
• Much improved support for the SAMLSSO ‘custom’ option. It means you can now create users with a custom SAML mapping that is different from the userid and without the need to edit code or run multiple scripts.
• New sample scripts to delete and update users by identifying the users by either email or SAML mapping, which are handy when you don’t necessarily know the userid.

Default New User Settings

You no longer need to edit code so new users have the correct user settings for things like date, time, and number formats. This version now stores these default setting in the Postman Environment. You can either update these setting manually or run a new sample script “021-U-Ue-Fcj-Update New User Default settings” to read an existing user and use that user’s settings as the default for all new users.

If you do have different groups of users needing different default settings, then you can either

• Continue as you did before, duplicate the script and edit the code in each script (Collection)
• Stop making code changes, instead use a Postman Environment for each group of users, each environment having the appropriate settings for each group of users. Or simply run the script ‘021’ between each group of users so to update the variables appropriately. This also makes updating your scripts easier when I make a new version available!

Improved Custom SAML SSO support

My earlier 0.6 version introduced support so the scripts where SAMLSSO aware. This latest version extends this support specifically for the ‘custom’ option.

Now, when SAMLSSO is ‘custom’ a new field is required in the data file called ‘file_samlmapping’. This field needs to contain the value for your custom property you’re using for the subject nameid in your SAML response. (The thing you’re using to map users from your Identity Provider to SAP Analytics Cloud). For example:

SAP Analytics Cloud userid	file_userid	M_SHAW
Email address	file_email	[email protected]
SAML Custom property (userName)	file_samlmapping	M-SHAW

You can create a user with a different value for the userid compared to the saml mapping. (The saml mapping is the same as the userName, which is the same as the subject nameid).

This new field ‘file_samlmapping’ is required only when SAMLSSO is ‘custom’ and is only applicable for the ‘SAML’ variants of the scripts (namely 131, 132, 133 and 231, 232, 233).

Some organisations use the ‘custom’ option to map to an email address because the ‘email’ option doesn’t work for them. (The ‘email’ option requires the cAsE to be the same and has limitation on the types of characters). You can create a new user like this without any code edits and all within a single script:

SAP Analytics Cloud userid	file_userid	M_SHAW
Email address	file_email	[email protected]
SAML Custom property (userName)	file_samlmapping	[email protected]

Before you may have run two scripts, one to create the user and one to update the user with the custom saml property. You no longer need to do this; you can now do it all in one script and without the need to edit code.

It can be confusing to understand which sample script to use depending upon which SAMLSSO setup you have, since my samples are very all encompassing. To make it easier I’ve made things clearer in the user guide and it includes this guidance:

Authentication Type	Recommended	Try to avoid
Default	101, 102, 103 121, 122, 123 201, 202, 203	111, 112, 113
SAML SSO mapped on ‘userid’	101, 102, 103 111, 112, 113 201, 202, 203
SAML SSO mapped on ‘email’ or ‘custom’	131, 132, 133 231, 232, 233	101, 102, 103 111, 112, 113 201, 202, 203

If you are in any doubt, then sample scripts 131, 132, 133 and 231, 232, 233 are always safe, just not necessarily the most efficient.

New sample scripts to identify users by email or SAML mapping

Extending the support for ‘custom’ SAMLSSO, I’ve created a number of scripts that identify users by their email address or by their SAML mapping. These will be useful for those that don’t necessarily know the userid for the user.

To delete users

• 311-U-D-Du-Fcj-Es-Delete Users (by saml mapping)
• 321-U-D-Du-Fcj-Es-Delete Users (by email)

You could already delete users ‘by userid’ with ‘301’.

For updating the saml mapping:

• 419-U-U-Um-Fcj-Es-Update SAML Mapping (by saml mapping)

You could already update ‘by userid’ with ‘409’ and ‘by email’ with ‘429’

For updating roles directly assigned:

• 418-U-U-Ur-Oarrk-Fj-Es-Update User Role (by saml mapping)
• 428-U-U-Ur-Oarrk-Fj-Es-Update User Role (by email)

You could already update ‘by userid’ with ‘408’

An example data file for ‘428’:

{
    "file_email": "[email protected]",
    "file_JSON_roles": [{"value":"Role2"},{"value":"Role3"}],
    "file_roles_action": "add"
  },
{
    "file_email": "[email protected]",
    "file_JSON_roles": [],
    "file_roles_action": "replace"
  }

Would mean the user with email [email protected] will be assigned 2 new roles, Role2 and Role3 and the user with email [email protected] would have any and all directly assigned roles removed.

Updating users’ email when SAMLSSO is userid or custom

To continue the SAMLSSO support I’ve improved the checks made to update a user. When SAMLSSO is set to ‘userid’ or ‘custom’, then the email address cannot be updated. All the samples are now aware of this and means a user update may not be necessary in such cases. In turn, it could improve the throughput of updating users in such cases.

How to update to version 0.7

Regardless of the existing version of these samples you are using the update process is the same.

Run the new sample script 001 (and 011 if applicable). This will add new environment variables:

• SAMLSSO (and it will be set to ‘default’. If you’ve enabled SAML SSO set it to ‘userid’, ’email’, or ‘custom’)
• TimeZoneHours, TimeZoneMinutes and TimeZoneDescription. Update these as you see fit. Hours and Minutes needs to be a number, -23 to 23, and -30, 0 or 30 respectively. Set the description to be whatever suits ‘GMT’ ‘CET’ ‘CTT’ ‘IST’ ‘PST’ etc.

You may have already done this step if you already updated to version 0.6.

The new version of script ‘001’ will also add 9 new variables to your Postman Environment as the default settings when new users are created. The variables are:

SCIM_NewUserDefault_preferredlanguage
SCIM_NewUserDefault_active
SCIM_NewUserDefault_dataaccesslanguage
SCIM_NewUserDefault_dateformatting
SCIM_NewUserDefault_timeformatting
SCIM_NewUserDefault_numberformatting
SCIM_NewUserDefault_cleanupnotificationsnumberofdays
SCIM_NewUserDefault_systemnotificationsemailoptin
SCIM_NewUserDefault_marketingemailoptin

The values will be the default values used by SAP Analytics Cloud.

Then, you can either manually update these variables, or better still just run sample “021-U-Ue-Fcj-Update New User Default settings” to read an existing user and use that user’s settings as the default for all new users. Remember to set the new userid in the sample data file to be the user you’d like the settings to be copied from.

If you have SAMLSSO set to ‘custom’ then you’ll need to add the field file_samlmapping to your data files. My sample data files provide a handy template for you to copy.

As you would expect, the user guide, has been appropriately updated.

I don’t currently plan any further improvements in the short-term to these samples, but please do expect an update once the SCIM version 2 of the API is available.

Feedback

• Feedback is very welcome.
• I’d love to hear if you like the new updates
• However, in general, please only comment on the main blog post so others can find it all in one place.

Many thanks

Matthew Shaw @MattShaw_on_BI

https://people.sap.com/matthew.shaw/#content:blogposts