SCIM Provisioning from Microsoft Entra ID

[Steven Meissner]

Introduction to SCIM and Its Benefits with ServiceNow

ServiceNow SCIM (System for Cross-domain Identity Management) Provisioning brings significant benefits, including automated provisioning and de-provisioning of user accounts, which reduces manual administrative tasks and minimizes the chance of errors. It ensures quick access for new employees and secure deactivation for those departing, bolstering security by maintaining proper access rights. The scalability of SCIM makes it ideal for organizations of any size, supporting efficient identity management without added complexity. Moreover, SCIM’s flexibility across various identity providers promotes interoperability, which is crucial for hybrid and multi-cloud environments.

System for Cross-domain Identity Management (SCIM) is an open standard designed to simplify identity management across various platforms. By standardizing the exchange of user identity information, SCIM enables automated, secure, and scalable user identity management in cloud-based applications like ServiceNow. This standardization ensures the consistency and accuracy of user data, enhancing both operational efficiency and security.

 

Configuring SCIM Provisioning from Microsoft Entra ID to ServiceNow

Configuring SCIM Provisioning from Microsoft Entra ID to ServiceNow involves several steps. The most notable is that some of the current documentation lacks clarity, making it almost impossible to configure SCIM provisioning correctly. If you take the well documented path using the Microsoft Entra ID ServiceNow gallery application, you will uncover that it uses SOAP API calls to make provisioning calls into ServiceNow. While this works quite well, you do not get the benefits of SCIM by taking this approach.

The following steps will outline the process to configure SCIM provisioning for this scenario.

 

Install the ServiceNow SCIM Plugin

1. Login to your ServiceNow environment.
2. Open the Application Manager.
3. Search for the "SCIM v2 - ServiceNow Cross-domain Identity Management (com.snc.integration.scim2)" plugin.
   
4. Select "Install", then "Install" in the Review Activation Details popup.
   
   
5. Wait for the installation to complete before moving on.

You can find these steps in ServiceNow's documentation - Activating the SCIM plugin.

 

Configure ServiceNow SCIM for Microsoft EntraID using OAuth

1. Goto All -> System OAuth -> Application Registry.
2. Open the "SCIM API" record and use these details when configuring Entra ID.
   
   
3. Fill in the "Redirect URL" field with "https://<instancename>.service-now.com/login.do" and update the record.
4. Goto All -> System Web Services -> REST API Access Policies and open the "SCIM API Policy".
   
   
5. Confirm that the"SCIM API OAuth Policy" is available under "Inbound Authentication Profiles".
6. Open the "SCIM API OAuth Policy" record and confirm that the OAuth Entity is set to "SCIM API".
   
   

When reviewing the SCIM API Application registration in step 2, consider the values for the "Access Token Lifespan" and "Refresh Token Lifespan". The Access Token Lifespan will determine how often you need to update the OAuth credential in Microsoft Entra ID.

There is also a hidden field on the SCIM API Application registry record called "Enforce Token Restriction". Enabling this setting will ensure that the token you are generating is only valid for the SCIM API and cannot be used for other endpoints on the ServiceNow instance.

 

Setup a User / Service Account to be used for Provisioning

1. Navigate to User Administration.
2. Create a new user account using your standard service account naming convention.
3. Add the "Admin" role to the user account.
4. Ensure you leave the user configured as a standard user who can log in using the Web UI. Come back later and secure this account so that it can only be used as an Integration account.

All activity performed by the SCIM integration will appear to be made by this user.

 

Configure Microsoft Entra ID

1. Sign in to the Azure Portal.
2. Change to the "Microsoft Entra ID" service.
3. Navigate to "Enterprise Applications" -> All.
4. Create a "New Application" and then select "Create your own application".
   
   
5. Name your application as required.
6. Select the option "Integrate any other application you don't find in the gallery (Non-gallery. This step is critical to ensure your provisioning approach is SCIM compliant. Using the ServiceNow Gallery application will result in the provisioning process using SOAP calls to your ServiceNow instance rather than SCIM APIs.
7. And then click "Create".
   
   
8. Next, select "3. Provision User Accounts" and then click "Get Started".
   
   
9. Set the "Provisioning Mode" to "Automatic".
10. Fill in the "Tenant URL" in the form "https://<instancename>.service-now.com/api/now/scim"     Note the use of the SCIM API url here!
11. Then we need to fill in the "Secret Token".    To Bearer Token / Access Code using the instructions below.
12. Click on "Test Credentials" and if it returns successful, click on Save.
13. Note that there is a time limit that applies to the process of retrieving the Bearer Token and using it to test and save the provisioning configuration.  If it the "Test Credentials" step is unsuccessful, check the popup error message to determine if the credentials are invalid or access is denied.  If either occurs, retrieve a new Bearer Token and reattempt the configuration.

 

Generate and retrieve the Bearer Token (Secret Token)

1. Goto All -> System Oauth -> Application Registry.
2. Open the "SCIM API" record.
   
   
3. Take note of the "Client ID".
4. Update the "Client Secret" to a known value.  I recommend you select a complex 40-character secret; noting that you can only use alphanumeric characters.  Make sure you record the value.
5. Consider your "Access Token Lifespan" & "Refresh Token Lifespan". The Access Token Lifespan in particular will determine how often you need to reenter the Secret Token into Entra ID.
6. Update the record.  
7. Next we need to use the OAuth Token retrieval process to retrieve the Bearer Token.
8. Generate the Authorisation Code
   1. Using an Incognito window, navigate to the URL "https://<instancename>.service-now.com/oauth_auth.do?response_type=code&redirect_uri=https://<instancename>.service-now.com/login.do&client_id=<ClientID>&state=123"
   2. You should be redirected to the URL "https://<instancename>.service-now.com/oauth_login.do".
   3. Login with the credentials of the User Provisioning configured previously.
   4. On the OAuth confirmation page, click "Allow".
      
      
   5. Check the URL for the "Authorisation Code" when are you redirected to the Login page.
      
      
9. Generate the Bearer Token
   • The "oauth_token.do" page allows us to generate the access / bearer token as long as we have the access code, redirect uri, grant type, client id and client secret.
   • The simplest way to retrieve this is using Curl.
   • From the Command Prompt, issue the following command - curl -d "grant_type=authorization_code&code=<access code>&client_id=<clientid>&client_secret=<clientsecret>&redirect_uri=https://<instance-name>.service-now.com/login.do" https://<instance-name>.service-now.com/oauth_token.do
   • This should produce a response similar to the following which includes the access token
     • {"access_token":"_OmjfKUv1pevKZRZCwtrDzqTSxPgah_DP7ulz8ZZY0Bt_7w-nPwvIhBuFFmJ23wcV9mnm1_37v9FEUqgFA9mkQ","refresh_token":"kCMQS101TU8o6xKB6mUu5Z7V25sFDpOSxcwnhhzhckkfDMihe1uBA255YC9v8jol83kut28zH0MiFLegbkj3Lg","scope":"useraccount","token_type":"Bearer","expires_in":1799}
   • Use the "access_token" component as the Secret Token when configuring the Entra ID Enterprise Application provisioning.

Assign users to the Entra ID application

Assign users or groups to your Entra ID application so the provisioning process can identify what entities should be provisioned.

1. Navigate back to the home page for the Enterprise Application we created above.
2. Goto the Manage -> Users & Groups page.
3. Add the required Users and Groups.
   
   

Test the provisioning process

1. Navigate to the Enterprise Application -> Provisioning page.
   
   
2. Select "Provision on Demand".
3. Search and select an account to test with, then click Provision.
4. Review the results of the Provision step and confirm that it was successful.
5. Now check the list of Users on your ServiceNow instance, and you should see your test user created.

Finalise your configuration

Before you start automatic provisioning, review your overall configuration. You might consider the following items

1. Review your Entra ID Attribute mappings to ensure they meet your requirements. Microsoft provides this tutorial to assist - Customise user provisioning attribute-mappings for Saas applications in Microsoft Entra ID.
2. Review your ServiceNow SCIM settings to ensure they align correctly. Consider the following items in particular;
   • If you need to customise user and group attribute mappings, check out the "Create a SCIM ETL definition".
   • Need some additional attributes? Refer to "Create a SCIM Extension schema".

These 2 items allow you to perform simple attribute mappings, as well as complex script-based transforms of attributes prior to loading them into ServiceNow.

Turn on Automatic Provisioning

1. Navigate back to the Enterprise Application -> Provisioning
2. Click on "Start provisioning"
   
   

Outcomes

Many considerations need to be made before selecting the most appropriate approach to provisioning Users and groups onto the ServiceNow platform.

Hopefully, this post has provided the necessary information to ensure you can set up a SCIM-compliant approach should you choose this path.

[VishwajeetG]

Great article Steve. I'm just wondering how should we manage access token which is configured as secret token when configuring the Entra ID. Typically access tokens are short lived and every time we cannot go and change secret token in Entra ID. Is there any better solution to manage secret token?

[Steven Meissner]

For the access token, I typically look at setting a longer lifespan / expiration for the SCIM issued tokens.  Its best to work with your Security / Cyber team to verify what your policy allows, however in practice I find that a 12 month lifespan is typically Ok.   

Make sure you set up a process to manage the renewal of the token based on the lifespan that you set.

Further to this, I've also been setting the "Enforce Token Restrictions" to true on the Application Registry entry for the SCIM API.  This further limits the amount of access allowed by the token to only the SCIM API. 

[Matt_dev]

Hi @Steven Meissner ,

Can I ask if you did anything special with the Azure enterprise app? I only seem to see the basic authentication dropdown on the 'Authentication method' field. This is all I have ever seen and tested but I'd be keen to get SCIM working through OAuth. Microsoft previously came back and said they couldn't get this feature working so they disabled this. However given your article is very recent I'm wondering if you done some sort of update or something to allow this feature to work?

[IgorVirgilio]

Hi @Steven Meissner,

Thank you for this article, truly helpful so far.

But we're getting problems with provisioning attributes, for Users we getting the following first error when we try to provision one user :

We've tried to edit the "Title" attribute in "scim-user" ETL Entities to match to these attributes, but we got a worse second error:

We turned back to the OOTB attribute which come back to initial error.

Then we tried to create new attributes, then we got the second error again. But even after delete these new attributes the second error still happening.

Do you have any clue that could help us on it?

Thank you in advance.

Here is some configs:
Entra ID:

ServiceNow:

[Steven Meissner]

@IgorVirgilio 

ServiceNow's native SCIM capability does not support the Enterprise User extension

"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"

Instead, ServiceNow offer 2 specific extensions for User and Groups;

    "urn:ietf:params:scim:schemas:extension:servicenow:2.0:User",
    "urn:ietf:params:scim:schemas:core:2.0:User"

You can find some documentation on these extension schemas here - https://docs.servicenow.com/bundle/xanadu-api-reference/page/integrate/inbound-rest/concept/scim-api...

I have found that these can be problematic in some cases.  If you run into challenges, consider overlaying the value needed onto a core User or Group schema attribute.  e.g.  use the Home Address attributes to pass values through the SCIM process.

[Steven Meissner]

@Matt_dev 

If you only have Basic Auth available, you are most likely attempting to use the "ServiceNow" enterprise application available in the gallery for MS Entra ID provisioning.  When the ServiceNow gallery application was initially released, it did have OAuth capability - however it was removed as it wasn't working correctly.

My article however deals with the native SCIM capabilities of MS Entra ID and ServiceNow.   The steps above show some slight changes which are required to use the native capability as opposed to the gallery application.  Following these steps you should see only OAuth available.

[SN Arch Guy]

Good information! Do you have any suggestions for automating group provisioning? I believe your article suggests assigning users and groups to the application. For users, we've found this works OK because we can assign an appropriate OU and then just send all users in it. But we don't want to send all groups and so they need to be added to the application manually. There is a way to apply filters, so that whenever new users are added to the OU, a filtered set of users is then sent to ServiceNow. But for groups, we haven't yet found a way to filter, and so it looks like it's send everything, or manually add new groups to the application. The examples provided at Scoping users or groups to be provisioned with scoping filters in Microsoft Entra ID - Microsoft Ent... seem like they are primarily for user filtering. Do you have any examples or guidance for group filtering?

[Martin Ivanov]

@Steven Meissner Great article. 

Could you please provide some additional guidance on how the customizations must be done - extension schema, ETL mapping and subsequently, how to synchronize these to Entra ID to make them available during the mapping on EntraID side. The syntax can be quite confusing. 

Thanks!

[Matt_dev]

@Steven Meissner Thanks for your reply. That was what I missed and having done it your way, it worked! Just one thing I thought I'd share on here for anyone who gets a similar issue...

When retrieving a bearer token, using CURL threw me a server error. I therefore used postman and grant_type = password for this which worked successfully.

[PipesYu]

hi