Skip to main content
Version: Omada Identity on-premises 16.0.1

ServiceNow installation and configuration

Before configuring the Omada Service Catalog application in ServiceNow, set up its client application and service user as described in Authenticate API clients with OAuth. This guide uses Microsoft Entra ID as the identity provider (IdP). Because ServiceNow acts on behalf of users, also follow Act on behalf of users (impersonation).

The ServiceNow application uses the OAuth 2.0 client credentials flow to authenticate to Omada Identity. This guide uses Microsoft Entra ID as the IdP.

Prerequisites:

  • In Omada Identity Cloud Management Portal, authentication must be configured to use OpenID.

  • The application that your users sign in to Omada Identity with (the OpenID application) must be configured for OpenID Connect. Refer to the Authentication and Single Sign On section for more information.

Prerequisites for Omada Identity on-premises

on-prem The OpenID application must be configured for OpenID Connect authentication.

If you use another authentication type for the primary end-user authentication (for example, Windows Authentication), then it is required to create an additional Omada Identity Website/URL specifically for the ServiceNow integration.

We recommend that you configure a Reverse Proxy to route the web traffic from ServiceNow to Omada Identity as illustrated below. The configuration of the reverse proxy is not described in this document.

Reverse proxy routing traffic from ServiceNow to Omada Identity.

Install and configure the ServiceNow application​

Purchase the application:

  • Go to the ServiceNow Store and request to purchase the application. After approval, you will be able to install the application.

Using the Guided Setup​

Here, you can find information on how to use the Guided Setup. Skip to Configure ServiceNow properties below if you are familiar with how to use a Guided Setup in ServiceNow already.

  1. Go to the Guided Setup for the Omada application.

    ServiceNow Guided Setup for the Omada application.
  2. The Guided Setup has three sections with tasks to complete.

    Guided Setup tasks for the Omada ServiceNow integration.
  3. Open the first task in the section. Read the details and when done, click the Mark as Complete button, then move to the next section.

    Guided Setup task with the Mark as Complete button.
  4. Click Configure button to go to the page, where the task can be configured.

    Guided Setup task with the Configure button.

Configure ServiceNow properties​

Follow these steps to configure ServiceNow properties:

  1. To select Omada as your current application, click the Globe icon in the top menu, search for Omada and select it as the current application. Click Mark as Complete.

    ServiceNow application selector with Omada selected.
  2. In the Provide Omada endpoint URL section, click Configure.

  3. Set the Value to your Omada instance URL, and save the record (click Update) or right-click the header and select Save. Mark the task as Complete.

    ServiceNow system property for the Omada instance URL.
  4. In the Modify Catalog Item section, read the details and click Configure to open the Omada Access Request catalog item.

  5. Modify the catalog item as required:

    • Add the catalog item to one or more catalogs and categories to allow your users to find the item on the service portal.

    • Define which users or groups can and cannot access the catalog item.

    • Update the name of the catalog item if required.

      ServiceNow catalog item configuration for Omada Access Request.
  6. Save the object and return to the Guided setup to mark the task as Complete.

  7. Go to the Configure authentication section.

Configure authentication​

In this section, provide the details you noted when you set up the client application in Microsoft Entra ID:

  • Application (client) ID of the client application
  • Application ID URI of the OpenID application, for example api://<Application (client) ID of the OpenID application>
  • Authorization endpoint (v2)
  • Token endpoint (v2)
  • Client secret
  1. In the Create a service account in Omada section, mark it as Complete if you have created the service user as described in Create the service user in Omada Identity.

  2. In Configure OAuth in ServiceNow, click Configure. This opens the Application Registry (oauth_entity). You will now create a new record.

    • You can enter any name you prefer for the OAuth entity.

    • Enter the Client ID and Client Secret of the client application.

    • Set the Default Grant type to Client Credentials.

    • Enter the Authorization URL and Token URL .

      ServiceNow Application Registry form for configuring OAuth client credentials.
  3. From the OAuth Entity Scopes tab, double-click on Insert a new row to create a new entity scope.

    • Enter Omada as the name and click the green checkmark.

    • Double-click on the OAuth scope field and input the OAuth scope value, using the format <Application ID URI of the OpenID application>/.default (for example, api://<Application (client) ID of the OpenID application>/.default), then click the green checkmark.

      ServiceNow OAuth Entity Scopes tab with the Omada scope configured.
  4. Save the record and return to the Guided Setup.

  5. In Configure REST Messages to use the new OAuth profile, click Configure to open the Omada Integration REST message record (sys_rest_message)

    • In the Authentication tab, select the newly created OAuth profile in the OAuth profile field.

      ServiceNow REST message record with the OAuth profile selected.
  6. Save the record and return to the Guided Setup.

Export and import SSL certificate​

Now, import an SSL Certificate.

  1. Skip to step 9 if you already have the required certificate and don't need to export it.

  2. Open your Omada instance and log in, if required.

  3. Click the padlock icon, next to the URL in your browser window.

    Browser certificate details for the Omada site.
  4. Click Connection is secure and then click Connection is valid or Show certificate, depending on the browser you are using.

  5. In the certificate information window, click the Details tab.

  6. Click Copy to file or Export..., depending on the browser you are using, and follow the steps in the export wizard.

  7. The format of the certificate file should be: DER encoded binary X.509 (.DER).

  8. Save the file with a suitable name, for example, Omada.der.

    Certificate export wizard with the file save option.
  9. In ServiceNow, go to the Export SSL certificate from Omada section in the Guided Setup, and mark it as Complete.

  10. In the Import SSL certificate to ServiceNow section, click Configure to go to System Definition > Certificates to create a new record.

    ServiceNow form for importing an X.509 certificate.
  11. Save the record.

  12. Return to the Guided setup and mark the task as Complete.

You have now completed the configuration of the Omada setup.

Install approval widget​

The approval widget allows approvers to review and approve or reject Omada Identity access requests directly from the ServiceNow portal. To install the approval widget, follow these steps:

  1. Select the required application scope (Global by default).

  2. Go to All > Service Portal > Pages.

    • Alternatively, type sp_page.list under the All menu and click Enter.

      ServiceNow Service Portal Pages list.
  3. Identify the page where the Omada Approval Widget should be displayed, for example, the Home page (ID=index).

    ServiceNow page record for selecting the portal page to edit.
  4. In the page record, click on Open in Designer under Related Links.

    ServiceNow page record with the Open in Designer link.
  5. In the Service Portal Designer, search for Omada (full name: Omada Front Page Widget) and then drag and drop the widget to the desired location.

    Service Portal Designer showing the Omada Front Page Widget.
  6. Click the View page in new tab button in the upper right corner of the designer to see the updated page with the widget.

    ServiceNow portal page displaying the Omada widget.
info

The number of items shown per page can be changed in the system property (default is set to 5):

x_omas_omada.omada_max_approvals_per_page

Testing the configuration​

Admins can go to Omada > REST Messages and test each HTTP Method by using variable substitutions. This will return the HTTP response code and response body which can identify any issues.

ServiceNow REST message test showing the HTTP response.

The workflow context can provide additional details if the catalog item was able to submit successfully.

Configure allowed IP addresses in Omada​

Restrict impersonation requests to the outbound IP addresses used by your ServiceNow instance. Add these addresses to the AllowedImpersonationIPMask customer setting. For the setting format, see Act on behalf of users (impersonation).

note

In Omada Identity Cloud Private, ensure that your NSG (Network Security Group) rules allow inbound traffic from ServiceNow IP addresses, in addition to configuring the AllowedImpersonationIPMask setting. For details, see Networking prerequisites in the deployment guide.

How to find the IP addresses in ServiceNow?​

To find the relevant IP addresses for your ServiceNow Instance, follow these steps.

  1. Log in to ServiceNow Support portal support.servicenow.com.

  2. Go to Automation Store > My IP Information.

    ServiceNow Automation Store page with My IP Information.
    • Select the instance you want to retrieve the IP addresses for and click Submit.

    • Expand the Source address used for integrations into customer network with NO VPN.

      ServiceNow source addresses used for integrations into a customer network.
  3. Note down all IP addresses.

Change the customer setting​

You now need to update the customer setting AllowedImpersonationIPMask so it contains the IP addresses noted down from ServiceNow.

To update the AllowedImpersonationIPMask customer setting, follow these steps:

  1. Log in to Omada as a system administrator.

  2. Go to Setup > Administration > System settings > Customer settings.

  3. In value, enter the IP addresses separated with a comma. Click OK to save the changes.

    Omada Identity customer setting for AllowedImpersonationIPMask.

Post-installation configuration​

Disable the Context field​

It is possible to configure the system so that the context field is not available in the request in ServiceNow.

To hide the field, set the Business context field to Hidden (server-side) in the process template. This is the same setting used to hide the context field in the Omada Identity Cloud access request process. To do so, follow these steps:

  1. Log in to Omada Identity as a system administrator.

  2. Go to Setup > Process templates > Request access.

  3. Open the Process Template and select the first activity Request access. In the Attributes pane, open the form designer by clicking the form name Request access (ed2) -- Submit form.

  4. Click the Business context field.

    Request access form designer with the Business context field selected.
  5. Set the field to Hidden (server-side) and save the form and the process template.

    Request access form designer with the Business context field hidden server-side.

ServiceNow will no longer show the field in the request.

Configure requestable resources and systems​

In Omada Identity, you can control which resources are available for users to request through third-party applications such as ServiceNow. By default, all resources available in the Omada Identity Cloud access request process are also available through these applications. For example, to make only business roles available in ServiceNow, set the Prevent self-service in third-party applications property to True for the resources you want to exclude. You can set this property on an individual resource, a resource type, or an entire system.

Omada Identity resource settings with Prevent self-service in third-party applications enabled.
note

Setting the property on a system excludes that system's resources from the resource search in ServiceNow — searching for them returns no results. The system itself is not hidden: its name still appears wherever systems are listed, for example in the ServiceNow system filter.

tip

You can automate this by creating an event definition that sets the property when systems or resources are created. Alternatively, set the property in the Warehouse to Portal mapping for the relevant objects.

When a third-party application retrieves requestable resources through the application programming interface (API), the API respects the settings on the Selected resources (AR_REQ_RESOURCES) property, including the Prevent self-service in third-party applications setting and any access modifier applied to that property.

Configure paging for large ServiceNow environments​

When a ServiceNow table contains a large number of records, retrieving them without paging can affect reconciliation and synchronization. For example, environments with more than 10,000 users may experience reconciliation issues if the account mapping retrieves all records in a single request.

To retrieve records in batches, configure the ServiceNow account mapping to override the default paging settings and use the LinkHeader paging type. Set sysparm_limit to control the number of records returned in each response, and use a stable sort order such as sys_id.

Example​

This query limits each response to 100 users and sorts the results by sys_id:

now/table/sys_user?sysparm_fields=sys_id,user_name,name,active,last_login&sysparm_limit=100&sysparm_query=ORDERBYsys_id

Configure the account mapping as shown:

Paging settings in the ServiceNow account mapping

Recommendations​

When configuring mappings for large ServiceNow tables:

  • Choose an appropriate sysparm_limit for the number of records returned in each response.
  • Use a stable sort order, such as ORDERBYsys_id.
  • Confirm that reconciliation processes all pages and completes as expected.
  • Consider applying paging to other large ServiceNow tables used by the integration.

Troubleshooting​

Requests to Omada Identity are rejected

If the test of the REST messages returns status code 401, request a token with the client application and check its claims as described in Request a token. For typical causes and solutions, see Troubleshooting.

Testing succeeds, but requests fail to load data

For requests sent on behalf of a user, verify that the email address on the ServiceNow user record matches that user’s username in Omada Identity. ServiceNow uses this value to identify the user for impersonation.

Error message

If Omada Identity cannot find the user identified in the request, the following error message appears: There was an error retrieving your identity from Omada, please contact your Administrator. Check that the identifier sent by ServiceNow matches the user’s username in Omada Identity. For the impersonation requirements, see Act on behalf of users (impersonation).

This error can also occur if the user’s required group memberships do not apply at the Low authentication level used for impersonation. Check the authentication level of the relevant groups. For details, see Impersonation and authentication levels.