Mapping external users and groups to ServiceNow AI Platform users

AI Search external user mappings enable you to configure externally defined user and group aliases for ServiceNow AI Platform users. AI Search uses these aliased security principals to apply content security filters that control user access to search results indexed from external documents.

You can use mapped external user and group names when defining access permissions for external documents that you ingest for indexing via the External Content Ingestion API.

External content security user mapping overview

To configure user mappings for external content security, you must perform the following steps:

1. Create one or more user mapping tables. For instructions on this procedure, see Create a user mapping table.
2. Link a user mapping table to each of your external content indexed sources. For details on this task, see Link a user mapping table to an external content indexed source.
   Note:

   If no mapping is found for the current ServiceNow AI Platform user, AI Search only allows the user to view search results for external documents that have the everyone permission set to true. This can occur if no user mapping table is linked to a search result's indexed source, or if no mapping for the current ServiceNow AI Platform user exists in the indexed source's linked user mapping table.
3. Import user mappings into your user mapping tables with the AI Search External User Mapping API.

Users with the ais_high_security_admin role can review history records for import operations to verify that user mappings imported correctly. For instructions on this procedure, see View history records for user mapping import operations.

External user mapping security principal types

AI Search user mapping aliases can include externally defined group and user security principals.

Mapped security principal type	Description
Externally defined group	The ServiceNow AI Platform® user specified in the user mapping inherits group-level access permissions for all aliased external groups. For example, if you define external group report-users as an alias for ServiceNow AI Platform user [e-mail], AI Search allows [e-mail] to view indexed search results for external documents that include read access permission for report-users.
Externally defined user	The ServiceNow AI Platform user specified in the user mapping inherits user-level access permissions for all aliased external users. For example, if you define external user ad\abel-tuter as an alias for ServiceNow AI Platform user [e-mail], AI Search allows [e-mail] to view indexed search results for external documents that include read access permission for ad\abel-tuter.

Create a user mapping table

Define a table to store externally defined user and group aliases for ServiceNow AI Platform® users.

Before you begin

The External Content for AI Search plugin (com.glide.ais.external_content) must be activated in your instance.

Role required: ais_admin

About this task

User mapping tables store user mappings for use with external documents that have access permissions. Each mapping specifies externally defined user and group aliases for an individual ServiceNow AI Platform user. AI Search uses the mappings linked to an external document's indexed source to determine whether a ServiceNow AI Platform user can view the indexed record for the document.

All user mapping tables extend the AI Search External Search User Mapping Base [ais_external_search_user_mapping] table.

Procedure

1. Navigate to All > AI Search > External Content > Create User Mapping.
2. Enter a name for your user mapping table.
3. Select Submit.
   The dictionary form for your new user mapping table appears.

What to do next

Import user mappings into your new user mapping table. For an overview of this process, see Importing user mappings. For details on the relevant API endpoint, see AI Search External User Mapping API.

Link a user mapping table to an external content indexed source

Specify the user mapping table you want AI Search to use for external documents ingested through an indexed source.

Before you begin

The External Content for AI Search plugin (com.glide.ais.external_content) must be activated in your instance.

The source table for the indexed source must be an external content schema table.

Role required: ais_admin

About this task

A user mapping table linked to an indexed source defines external user and group aliases for ServiceNow AI Platform® users. AI Search uses these aliases to determine a user's effective access permissions when their search matches a record from the indexed source.

A user mapping table can be linked to any number of indexed sources.

Note:

If no mapping is found for the current ServiceNow AI Platform user, AI Search only allows the user to view search results for external documents that have the everyone permission set to true. This can occur if no user mapping table is linked to a search result's indexed source, or if no mapping for the current ServiceNow AI Platform user exists in the indexed source's linked user mapping table.

Procedure

1. Navigate to All > AI Search > AI Search Index > Indexed Sources.
2. Open the indexed source record that you want to link a user mapping to.
3. In the AI Search External Search User Mapping Table Data Source Relationships related list, create a new relationship record for the user mapping table that you want to link to the indexed source:
   1. Select New.
   2. On the AI Search External Search User Mapping Table Data Source Relationship form, fill in the fields.
   3. Select Submit.
      The user mapping table's name appears in the related list.

Importing user mappings

You can use the AI Search External User Mapping API to import mappings between ServiceNow AI Platform® users and externally defined users and groups.

To define a user mapping for import, you need the following information:

• The email address that uniquely identifies a ServiceNow AI Platform user in the User [sys_user] table.
• The list of externally defined groups that you want to alias to the ServiceNow AI Platform user. This list can be empty.
• The list of externally defined users that you want to alias to the ServiceNow AI Platform user. This list can be empty.

For more information on importing user mappings, see AI Search External User Mapping API.

View history records for user mapping import operations

Review the results for your user mapping import operations, including data, log messages, and any errors. Use this procedure to verify that your user mappings are imported correctly.

Before you begin

Role required: ais_admin, ais_high_security_admin, and import_transformer.

About this task

AI Search creates an import set for each batch of user mappings that you import via the AI Search External User Mapping API. The transform histories for these import sets provide insight into the results of your user mapping import operations.

Procedure

1. Elevate to the ais_high_security_admin role:
   1. Perform the appropriate action for your version of the UI:

      UI version	Action
      Next Experience UI	In the banner frame, select the icon for your account to open the user menu, then select Elevate role.
      Core UI	In the banner frame, select your name to open the user menu, then select Elevate Roles.

      A dialog box appears, displaying a checklist of your available privileged roles.

      

   2. In the dialog box, select the ais_high_security_admin option, then select Update (in Next Experience UI) or OK.
      The page reloads and an elevated role indicator appears next to your user name in the user menu. In Next Experience UI, this indicator displays the names of the active privileged roles. In Core UI, the indicator displays the elevated role icon .

      

      Note:

      When the page reloads, any unsaved edits are lost.
2. Navigate to All > AI Search > External Content > User mapping import history.
3. Review each user mapping import history record that you're interested in.
   1. Open the user mapping import history record.
   2. On the AI Search External Content User Mapping History Record form, select the Show Transform History related link.
      The Transform History [sys_import_set_run] table opens, with a filter applied for the import set from the selected user mapping import history record.
   3. Open the transform history record.
   4. Review import set results on the form, errors in the Import Set Row Errors related list, and log messages in the Import Log related list.