Set up OAuth 2.0 Client Credentials authentication for ServiceNow

1. In ServiceNow, navigate to sys_properties.list using the filter navigator.

2. Create a new system property with the following values:

   • Name – glide.oauth.inbound.client.credential.grant_type.enabled

   • Type – true | false

   • Value – true

1. Navigate to User Administration > Users.

2. Choose New and complete the form:

   • User ID – A descriptive name (for example, svc.amazon.quick.kb).

   • Web service access only – Checked. This prevents interactive login.

   • Password – Set a strong password. The connector uses OAuth, but a password is required for account creation.

3. Choose Submit.

1. Open the service account (User Administration > Users > your service account).

2. Under the Roles tab, choose Edit and add the following roles:

   • knowledge_admin – Full read access to all knowledge base articles. Bypasses per-KB user criteria restrictions.

   • catalog_admin – Full read access to all service catalog items. Bypasses per-catalog restrictions.

3. Choose Save.

1. Navigate to System OAuth > Application Registry.

2. Choose New > Create an OAuth API endpoint for external clients.

3. Complete the form:

   • Name – A descriptive name (for example, Amazon-Quick-KB-Client).

   • Redirect URL – Leave blank. Not required for client credentials flow.

4. Choose Submit.

5. Immediately copy the Client ID and Client Secret. The Client Secret is only shown once.

1. Re-open the application record from the Application Registry list.

2. If the OAuth Application User field is not visible, add it using Configure > Form Builder.

3. Set the following fields:

   • OAuth Application User – Your service account (for example, svc.amazon.quick.kb).

   • Scope Restriction – Broadly scoped.

   • Client Type – integration_as_a_service.

4. Choose Update.

Create the Inbound Authentication Profile

1. Navigate to System Web Services > API Access Policies > Inbound Authentication Profile.

2. Choose New and set:

   • Name – For example, Amazon-Quick-KB-Client-Profile.

   • Type – OAuth.

   • OAuth Entity – Select your OAuth application.

3. Choose Submit.

4. Re-open the profile. In the Authentication Policies related list, choose Edit and add Allow Access Policy. Choose Save.

Create the REST API Access Policy

1. Navigate to System Web Services > API Access Policies > REST API Access Policies.

2. Choose New and set:

   • Name – For example, Table API Oauth access policy.

   • REST API – Table API.

   • REST API Path – now/table.

   • Apply to all methods – Checked.

   • Apply to all resources – Checked.

   • Apply to all tables – Checked.

   • Apply to all versions – Checked.

3. Choose Submit.

4. Re-open the policy. In the Inbound authentication profiles related list, choose Edit and add your Inbound Authentication Profile. Choose Save.

1. In ServiceNow, go to User Administration > Users, and open the OAuth 2.0 run-as user.

2. In the Roles related list, choose Edit, add impersonator, and save.

3. Confirm the assignment appears in sys_user_has_role for that user.

1. Go to Knowledge > User Criteria > New. Name it (for example, Amazon Bedrock Connector Read), add the service account to its User list, and leave everything else empty.

2. On each restricted knowledge base, add that criterion to Can Read.

1. Create the Scripted REST API.

   1. Navigate to System Web Services > Scripted REST APIs > New.

   2. Set a Name and API ID. The API ID plus the instance's application namespace determine the base path /api/NAMESPACE/.... Record the resolved base path — it must match the aclCheckPath you store later.

   3. In the Resources related list, choose New, and set the HTTP method to POST, the Relative path to /RESOURCE, and paste the script from the next step.

   4. On the resource Security tab, keep Requires authentication enabled, and make sure the OAuth 2.0 client user has an access control or role that permits POST (the default resource access control denies snc_external), holds the impersonator role, and has read on all tables listed in the prerequisites.

2. Add the resource script. Paste the following script into the resource.

   (function process(request, response) {
       // Contract:
       //   IN : { "user_email": "<email>", "document_ids": ["<sys_id>", ...] }   (<= 50 ids)
       //   OUT: 200 { "result": { "<sys_id>": true|false, ... } }   strict booleans
       //        404 { "error": "User not found or inactive" }        -> connector denies (USER_NOT_FOUND)
       //   A sys_id omitted from the map is treated as NOT granted (fail-closed).
   
       var body = request.body && request.body.data ? request.body.data : {};
       var userEmail = body.user_email;
       var documentIds = body.document_ids || [];
   
       if (!userEmail || !documentIds.length) {
           response.setStatus(200);
           response.setBody({ result: {} });
           return;
       }
   
       // Contract enforces up to 50 ids per call; reject oversized batches so the
       // connector's batching contract is validated at the boundary.
       if (documentIds.length > 50) {
           response.setStatus(400);
           response.setBody({ error: 'document_ids exceeds batch limit of 50' });
           return;
       }
   
       // Validate sys_id shape (32 hex chars) up front; a malformed id can never
       // match a record, and validating here keeps a bad input from silently
       // producing an omitted (deny) verdict that looks like a real decision.
       var SYS_ID = /^[0-9a-f]{32}$/;
       for (var v = 0; v < documentIds.length; v++) {
           if (!SYS_ID.test(String(documentIds[v]))) {
               response.setStatus(400);
               response.setBody({ error: 'Invalid sys_id in document_ids: ' + documentIds[v] });
               return;
           }
       }
   
       // Resolve the caller to a sys_user.
       var userGr = new GlideRecord('sys_user');
       userGr.addQuery('email', userEmail);
       userGr.addQuery('active', true);
       userGr.setLimit(1);
       userGr.query();
       if (!userGr.next()) {
           response.setStatus(404);
           response.setBody({ error: 'User not found or inactive' });
           return;
       }
       var userSysId = userGr.getUniqueValue();
   
       // Direct group membership only (sys_user_grmember). ServiceNow user_criteria
       // does NOT walk nested groups, so this is intentionally not recursive.
       var userGroups = {};
       var grm = new GlideRecord('sys_user_grmember');
       grm.addQuery('user', userSysId);
       grm.query();
       while (grm.next()) userGroups[grm.getValue('group')] = true;
   
       // Direct roles from sys_user_has_role, then transitively expanded through
       // sys_user_role_contains so a parent role implies the roles it contains.
       // ServiceNow resolves role containment when evaluating criteria, so a user
       // holding a parent role must be treated as holding the contained roles too.
       var userRoles = {};
       var directRoles = [];
       var uhr = new GlideRecord('sys_user_has_role');
       uhr.addQuery('user', userSysId);
       uhr.query();
       while (uhr.next()) {
           var r = uhr.getValue('role');
           userRoles[r] = true;
           directRoles.push(r);
       }
       expandContainedRoles(directRoles, userRoles);
   
       var result = {};
       for (var i = 0; i < documentIds.length; i++) {
           var docId = documentIds[i];
           result[docId] = evaluateDocument(docId, userSysId, userGroups, userRoles);
       }
   
       response.setStatus(200);
       response.setBody({ result: result });   // Scripted REST serializer wraps under "result"
   
       // ------------------------------------------------------------
       function evaluateDocument(articleSysId, uSysId, uGroups, uRoles) {
           var art = new GlideRecord('kb_knowledge');
           if (!art.get(articleSysId)) return false;               // unknown doc -> deny
           if (art.getValue('workflow_state') !== 'published') return false;
   
           var canRead = art.getValue('can_read_user_criteria');
           var cannotRead = art.getValue('cannot_read_user_criteria');
   
           var allowCriteria = [];
           var denyCriteria = [];
   
           if (canRead || cannotRead) {
               // ARTICLE-LEVEL: criteria live directly on the article.
               allowCriteria = splitIds(canRead);
               denyCriteria  = splitIds(cannotRead);
           } else {
               // KB-LEVEL FALLBACK: read parent KB's M2M criteria tables.
               var kbId = art.getValue('kb_knowledge_base');
               allowCriteria = mtomCriteria('kb_uc_can_read_mtom', kbId);
               denyCriteria  = mtomCriteria('kb_uc_cannot_read_mtom', kbId);
           }
   
           // DENY takes precedence: any satisfied deny criteria -> blocked.
           for (var d = 0; d < denyCriteria.length; d++) {
               if (satisfiesCriteria(denyCriteria[d], uSysId, uGroups, uRoles)) return false;
           }
   
           // No ALLOW criteria at all: nothing grants read -> deny (fail-closed).
           if (!allowCriteria.length) return false;
   
           // ALLOW: user must satisfy at least one allow criteria.
           for (var a = 0; a < allowCriteria.length; a++) {
               if (satisfiesCriteria(allowCriteria[a], uSysId, uGroups, uRoles)) return true;
           }
           return false;
       }
   
       function mtomCriteria(table, kbId) {
           var out = [];
           var gr = new GlideRecord(table);
           gr.addQuery('kb_knowledge_base', kbId);
           gr.query();
           while (gr.next()) out.push(gr.getValue('user_criteria'));
           return out;
       }
   
       // Transitively expand role containment: for every role the user holds,
       // add every role it contains (sys_user_role_contains), following the graph
       // to its full closure. Without this, a user granted a parent role would be
       // denied a criterion keyed on a contained role.
       function expandContainedRoles(seedRoles, roleSet) {
           var frontier = seedRoles.slice();
           while (frontier.length) {
               var current = frontier;
               frontier = [];
               var gr = new GlideRecord('sys_user_role_contains');
               gr.addQuery('role', 'IN', current.join(','));
               gr.query();
               while (gr.next()) {
                   var contained = gr.getValue('contains');
                   if (contained && !roleSet[contained]) {
                       roleSet[contained] = true;
                       frontier.push(contained);   // walk deeper for nested containment
                   }
               }
           }
       }
   
       // Split a comma- or newline-delimited criteria id list, trimming blanks.
       function splitIds(csv) {
           if (!csv) return [];
           var parts = csv.toString().split(/[,\n]/);
           var out = [];
           for (var i = 0; i < parts.length; i++) {
               var t = parts[i].trim();
               if (t) out.push(t);
           }
           return out;
       }
   
       // Evaluate one user_criteria record against the user.
       // Handles: allow-all (all fields empty), group, role, direct user, match_all AND/OR,
       //          and advanced (scripted) criteria via the criteria's own script.
       function satisfiesCriteria(criteriaId, uSysId, uGroups, uRoles) {
           var uc = new GlideRecord('user_criteria');
           if (!uc.get(criteriaId)) return false;
   
           if (uc.getValue('advanced') === 'true') {
               try {
                   return evaluateAdvancedCriteria(uc, uSysId);
               } catch (e) {
                   gs.error('[acl_verifier] advanced criteria eval failed for ' +
                       criteriaId + ': ' + e.message);
                   return false; // fail-closed
               }
           }
   
           var group = uc.getValue('group');
           var role  = uc.getValue('role');
           var user  = uc.getValue('user');
           var matchAll = uc.getValue('match_all') === 'true';
   
           // Allow-all: no group, role, or user, and not advanced -> public.
           if (!group && !role && !user) return true;
   
           var conditions = [];
           if (group) conditions.push(!!uGroups[group]);
           if (role)  conditions.push(!!uRoles[role]);
           if (user)  conditions.push(user === uSysId);
   
           if (!conditions.length) return false;
   
           if (matchAll) {                       // AND
               for (var c = 0; c < conditions.length; c++) if (!conditions[c]) return false;
               return true;
           }
           for (var o = 0; o < conditions.length; o++) if (conditions[o]) return true; // OR
           return false;
       }
   
       // Advanced/scripted user_criteria: evaluate the criteria's script for this user.
       function evaluateAdvancedCriteria(uc, uSysId) {
           var script = uc.getValue('script');
           if (!script) return false;
           var target = new GlideRecord('sys_user');
           if (!target.get(uSysId)) return false;
           // Advanced UC scripts set `answer` for the CURRENT user (gs.getUserID()).
           // Impersonate the target so the script sees the right user, then restore.
           var impersonator = new GlideImpersonate();
           var original = gs.getUserID();
           try {
               impersonator.impersonate(uSysId);
               // CRITICAL: verify impersonation actually took effect. If the run-as
               // integration user lacks the impersonator role, impersonate() silently
               // no-ops and the script would evaluate as the PRIVILEGED user, which can
               // return answer=true for everyone (false-ALLOW). Fail closed instead.
               if (gs.getUserID() !== uSysId) {
                   gs.error('[acl_verifier] impersonation did not take effect for ' +
                       uSysId + ' (missing impersonator role?) -- failing closed');
                   return false;
               }
               var answer = false;
               eval(script);   // criteria script body assigns to `answer`
               return answer === true;
           } finally {
               impersonator.impersonate(original);
           }
       }
   })(request, response);

   The endpoint applies the following access-decision logic:

   • Article-level criteria (can_read_user_criteria or cannot_read_user_criteria set on the article) are used directly.

   • Knowledge-base-level fallback: when both article fields are empty, the parent knowledge base's kb_uc_can_read_mtom (allow) and kb_uc_cannot_read_mtom (deny) criteria are used.

   • Deny precedence: if the user satisfies any deny criteria, access is denied.

   • Allow-all: a criterion with no group, role, or user and advanced = false is public.

   • match_all: true is AND across the populated conditions; false is OR. This must match the connector's crawl-time intersection semantics, because the verifier is the oracle for the retrieve-versus-crawl cross-check.

   • Groups are direct-membership only (sys_user_grmember), by design: ServiceNow user criteria don't walk nested groups, so a user in a child group is correctly denied a criterion keyed on the parent group.

   • Roles are expanded transitively through sys_user_role_contains, because ServiceNow resolves role containment: a user holding a parent role is treated as holding the roles it contains.

   • Advanced (scripted) criteria are evaluated by the criteria's own script under impersonation; the script re-verifies gs.getUserID() and fails closed if impersonation didn't take effect. Any failure fails closed (deny).

3. Verify the endpoint over HTTP. Obtain an OAuth 2.0 access token using the connector's clientId and clientSecret against https://INSTANCE.service-now.com/oauth_token.do, then call the endpoint with a real user email and one known published article sys ID.

   POST https://INSTANCE.service-now.comACL_CHECK_PATH
   Authorization: Bearer access_token
   Content-Type: application/json
   
   { "user_email": "email", "document_ids": ["sys_id"] }

   Confirm a 200 response with { "result": { "sys_id": true|false } }.

4. Set aclCheckPath on the connector secret. The connector reads the endpoint path from an aclCheckPath field on the OAuth 2.0 secret, alongside clientId, clientSecret, and instanceUrl. Add or update only that one key; leave the existing credential fields untouched.

   Option A (AWS Management Console). In the AWS Secrets Manager console, open the connector's secret, choose Retrieve secret value, choose Edit, and add a key aclCheckPath with the value ACL_CHECK_PATH (for example, /api/NAMESPACE/RESOURCE). The existing clientId, clientSecret, and instanceUrl values stay as they are. The console performs an in-place update that preserves the other fields.

   Option B (AWS Command Line Interface). put-secret-value replaces the entire secret value, so include all fields in the new JSON.

   aws secretsmanager get-secret-value \
     --secret-id SECRET_ARN --region REGION \
     --query SecretString --output text
   
   aws secretsmanager put-secret-value \
     --secret-id SECRET_ARN --region REGION \
     --secret-string '{"clientId":"...","clientSecret":"...","instanceUrl":"https://INSTANCE.service-now.com","aclCheckPath":"ACL_CHECK_PATH"}'

5. Validate end to end. Sync the ServiceNow data source so ACL-enabled articles are ingested. Then run Retrieve as an authorized user (the restricted article is returned) and as an unauthorized user (the restricted article is not returned).

   Expected result: the restricted article is returned only for the authorized user's Retrieve call, and is omitted for the unauthorized user.