Oauth 2.0 authenticated Azure Monitor to ITOM Health (Event Management) Integration

[RemcoLengers]

This post describes OAUTH 2.0 authentication method to integrate Azure Monitor into ServiceNow ITOM Event Management. 

In <this> blog I explained the simplest method to integrated Azure Monitor. However using Oauth 2.0 is considered to be more secure as the credentials are not transmitted with each REST call, only the temporary token which gets regularly renewed. The official documentation can be found <here>.

The high level steps are:

1. Configure an "App Registration" in Azure

2. Create an Integration User in ServiceNow

3. Configure "Azure OAuth Config" in ServiceNow

4. Setup an Azure Event integration in the "Service Operations Workspace", "Integration Launch pad"

5. Configure the "Action Group" in Azure Monitor and test the integration

Oauth 2.0 can use v1 and v2  tokens so depending on which one you need to use the procedure is the same but the data entered has slight variations.

The screenshots are with v1 tokens, the changes needed for v2 tokens are pointed out in the text but are summarised below for clarity.

There are 4 places in the configuration process where there are differences 

- Manifest file "accessTokenAcceptedVersion" (null, 1 (v1) or 2 (v2))

- Application string to use  "Application ID URI" (v1)  or  "Application (client) ID" (v2)

- Remove "v2.0" from the  "OIDC Metadata URL" when using v1 tokens

- Claim name to use appid (v1) or azp (v2)

Configure an "App Registration" in Azure

Create a new App in "App registrations"

Add an "Application ID URI" 

Add and Save

This will have the following result:

For V1 tokens copy the "Application ID URI" field.

For V2 tokens copy the "Application (client) ID" field. 

From the "Endpoints" copy the "OpenID Connect metadata document" :

In the "App registration" "Manifest" file the "accessTokenAcceptedVersion": null," or 1 is correct for v1 tokens. For v2 tokens use 2. 

UDPATE: There seems to be a recent change in the Manifest file. Here is an example of the parameter "

"requestedAccessTokenVersion": 2," that need to be changed (In this case 2 for v2 tokens)

You may need to add yourself as the owner of the App registration so it will show up in the Action Group at the end later.

Create an Integration User in ServiceNow

Go to "User Administration - Users" and

1. create a new user and

2 assign the "evt_mgmt_integration" role.

3. Add the "Source" Field to the form and copy the V1 "Application ID URI". For v2 tokens use  "Application (client) ID" 

So the result looks like

Config "Azure OAuth Config" in ServiceNow

In the ServiceNow instance goto "Azure Oauth Config"

And edit the existing "Azure OAuth OIDC Entity"

Step 1 Update the "Client ID" with  the V1 "Application ID URI" and Save.  For V2 tokens use the "Application (client) ID" in the "Client ID" field.

Step 2 Open the record with the label "OAuth OIDC Provider Configuration" and edit the record to enter the "OpenID Connect metadata document" data in the "OIDC Metadata URL" field. Note for v1 tokens remove the "v2.0" part from the URL:

And Save.

Final configuration on the same record is the "JWT Claim Validations". for V1 tokens the claim name needs to be "appid" and for v2 tokens it needs to be "azp" which is the default.

Setup an Azure Event integration in the "Service Operations Workspace", "Integration Launch pad".

Give the integration a name

Save and activate and copy the URL.

Configure the "Action Group" in Azure Monitor and test the integration

Goto Monitor, Alerts and then "Action Groups". Edit and existing action group or create a new one.

And "Edit"

In "Actions" add a line with a "Secure Webhook". Use the correct Object ID (App registration) and the URI needs to be the URL you collected from the Integration Launch Pad -  Azure Event Integration. 

Then select "Test action group"

And if all is well:

See the Event show up in the Event Management Integration. Nice!

If you think this is helpful and it is worth investing time in writing these blog posts click the "ThumbsUp" button.

[tonychaffe]

@RemcoLengers This is an excellent post, thank you for taking the time to document it.

[tonychaffe]

@RemcoLengers I would like to query this part here though from your reply above:

1. 1. Token audience → pick the OIDC config

   • Azure issues the token with aud = your Application ID URI (V1) or the Application (client) ID (V2). - This part I can confirm is correct. Decoding the JWT Token on jwt.io, the aud claim value does indeed include the Client ID for V2 tokens.

   • In ServiceNow, your OAuth OIDC Entity has “Client ID” set to that same value. That’s how ServiceNow knows which verifier to use to validate the token. - Yes, and by verifier, your specifically referring too the OIDC Provider Configuration, which contains the metadata URL and the User Claim to user Field mapping. 

   1. Token claim → resolve the “integration user” - This is the part I'm not sure is accurate.

   • After validation, ServiceNow uses a claim (V1: appid, V2: azp, per current guidance) to locate the correct sys_user and run the endpoint in that user context.

   • That’s why you populated the Source field on the integration user with the Application ID URI (V1) or App (client) ID (V2). The inbound Azure-events logic/verification uses that value to resolve the user. In other words, the “link” is indirect via the JWT claims, not a hardcoded username/password.

For 2, more accurately, the OIDC provider configuration (verifier) posted in the screenshot has the User Claim set to 'aud' and User Field set to 'source'. Isn't this mapping what enables the platform to locate the user?

It's suggested that the 'azp' JWT Claim validation provides a mapping to the sys_user and I'm just not sure that is the case. If you change the User Claim to preferred_username and User Field to email for example, authentication will fail, confirmed with testing in my PDI.

As (quoted from above):

ServiceNow doesn’t “bind” the Action Group to a user by name; instead it derives the user at request time from the token.

And that's because it can't, an Azure Service Principal (Application Registry) doesn't have identifiable attributes, like a preferred_username or email, so, deriving a user from the token is required, which is where the User Claim to User Field mapping comes into play.

There are a couple token claims that could be used, sub == subject (The subject of the JWT (the user) is probably the most appropriate.

It would be really useful, if it were made possible to configure multiple User Claim to User Field mappings in the OIDC Provider configuration, given that it isn't possible to define additional verifiers using the same metadata url.

This is to cater for requirements where different User Claim & User Field mappings maybe necessary to locate and authenticate users, this use case being a good example of machine to machine authentication where user identifiers may not be available.

[RemcoLengers]

@tonychaffe  If you would like to see product enhancement you can leave it at the idea portal (and get votes on it).

https://support.servicenow.com/now?id=ideas_list&sysparm_module_id=enhancement_requests

From a quick glance it may be that your wording on the "indirect claim" may be a better way to explain how it happens. I may look into that later.