Skip to main content

Authorization

After authentication verifies who the user is, authorization determines what they can access. Squid implements a multi-layered authorization model that provides fine-grained access control.

How Authorization Works​

Squid Authorization Decision FlowSquid Authorization Decision Flow: Every API request passes through four sequential authorization checks. Failure at any check stops the request immediately. CHECK 1 - API ACCESS: The user must have the x_a46gh_squidx.rest role to access the Squid API. Without this role, the request fails with HTTP 403 Forbidden. The rest role is required for ALL API calls but does not by itself grant access to any data. CHECK 2 - CONFIGURATION LOOKUP: The requested configuration must exist, either as a predefined configuration or a custom configuration. If the configuration does not exist, the request fails with HTTP 404 Not Found. CHECK 3 - CONFIGURATION ROLES: The user must have at least one of the roles assigned to the configuration. Predefined configurations require the x_a46gh_squidx.defaultAccess role by default. Custom configurations can specify any roles. If the user lacks the required role(s), the request fails with HTTP 403 Forbidden. CHECK 4 - RELATIONS (OPTIONAL): This check only applies if the configuration has "Relations Restricted" enabled. When enabled, the user can only request relations that are explicitly listed in the configuration's "Allowed Relations" setting. If a disallowed relation is requested, the request fails with HTTP 400 Bad Request. RESULT: If all checks pass, the request proceeds to data access, where views and view filters control what data is returned. Summary of error codes: 403 Forbidden = missing rest role or missing configuration role. 404 Not Found = configuration does not exist. 400 Bad Request = requested relation not allowed.API RequestCheck 1: API Access• User must have the x_a46gh_squidx.rest role• Failure: 403 ForbiddenCheck 2: Configuration Lookup• Requested configuration must exist (predefined or custom)• Failure: 404 Not FoundCheck 3: Configuration Roles• User must have at least one role configured on the configuration• Predefined configs require x_a46gh_squidx.defaultAccess by default• Failure: 403 ForbiddenCheck 4: Relations (optional)• If relations restricted: requested relations must be in the allowed list• Failure: 400 Bad RequestProceed to Data Access

Squid Roles​

Squid roles fall into two categories based on where they are evaluated.

Squid Roles OverviewDiagram showing Squid's roles organized into two categories based on where they are evaluated. LEFT SECTION - "API Access" (evaluated by Squid): These roles control programmatic access to the Squid API from server-side integrations. "rest" role (API Gateway): Required for ALL API calls. Without this role, requests receive 403 Forbidden. The rest role does NOT grant access to any data - it only opens the door to the API. Badge: "REQUIRED". A dashed arrow points down to the configuration access roles. "defaultAccess" role (Predefined Configs): Grants access to all predefined Squid configurations. Badge: "DEFAULT". To restrict users to specific configurations: remove defaultAccess and assign custom roles instead. "Custom roles" (Specific Configs): For fine-grained access control. Assign custom roles to specific configurations, then grant those roles to users who need restricted access. RIGHT SECTION - "UI Access" (evaluated by ServiceNow): These roles control human access to the Squid configuration interface. Both roles are for human users only and have no effect on API access. The two roles are parallel alternatives for different user types. "admin" role (Configuration Management): For configuration authors who create and maintain Squid configurations. Allows creating, editing, and reading all configurations (predefined and custom). Badge: "UI ONLY". "read" role (Configuration Viewer): For developers of peripheral systems who need to understand configuration definitions - what fields are exposed, what filters apply, what relations are available. Provides read-only access to view all configurations. Badge: "UI ONLY". BOTTOM SECTION - "Typical Role Combinations": Four examples showing common patterns. API Access combinations (cyan): "Full API Access" = rest + defaultAccess, "Restricted API Access" = rest + custom roles. UI Access combinations (purple): "Config Author" = admin (optionally + rest for testing), "Config Viewer" = read. Key architectural insight: API access roles (rest, defaultAccess, custom) are evaluated by Squid at runtime. UI access roles (admin, read) are evaluated by ServiceNow's standard ACL system and only affect the configuration management interface.API ACCESSevaluated by SquidUI ACCESSevaluated by ServiceNowrest— API GatewayRequired for ALL API calls• Without this role: 403 Forbidden• Opens the door; config roles control what's insideREQUIREDdefaultAccess— Predefined Configs• Grants access to all predefined configurations• Remove to restrict users to specific configs onlyDEFAULTCustom roles— Specific Configs• Assign custom roles to specific configurations• Grant those roles for fine-grained access controladmin— Configuration ManagementFor configuration authors• Create and edit custom configurations• Read all configurations (predefined + custom)UI ONLYread— Configuration ViewerFor developers of peripheral systems• View configuration definitions (read-only)†• Understand exposed fields, filters, relationsUI ONLYTypical Role CombinationsFull API Accessrest + defaultAccessRestricted API Accessrest + custom rolesConfig AuthoradminConfig Viewerread † Database Views are not visible to non-sys_admin users. While ServiceNow technically allows granting read access through explicit ACLs on each view, this requires a separate ACL entry per view and does not scale. Details.

API Access Roles (evaluated by Squid)​

These roles control programmatic access from server-side integrations. Squid evaluates them at runtime.

RolePurposeGrants
x_a46gh_squidx.restAPI GatewayRequired for any API calls
x_a46gh_squidx.defaultAccessPredefined ConfigsAccess to all predefined configurations
(custom roles)Specific ConfigsAccess to configurations with matching role
info

The rest role alone does not grant access to any data. It only opens the door to the API—configuration access is controlled by defaultAccess or custom roles.

UI Access Roles (evaluated by ServiceNow)​

These roles control human access to the Squid configuration interface. ServiceNow enforces them through standard ACLs. They have no effect on API access.

RolePurposeGrants
x_a46gh_squidx.adminConfig AuthorsCreate/edit custom configs, read all configs
x_a46gh_squidx.readConfig ViewersRead-only access to view configuration definitions

The read role is useful for developers of peripheral systems who need to understand what fields are exposed, what filters apply, and what relations are available—without the ability to modify configurations.

Why defaultAccess Exists​

Consider a service account squid_accounting that should only access a few specific configurations. Without defaultAccess:

  1. This account would have access to ALL configurations that have no role restrictions
  2. You would need to manually add role restrictions to every configuration

With defaultAccess:

  1. All predefined configurations require this role by default
  2. Simply don't assign defaultAccess to accounts that need restricted access
  3. Then selectively grant access to specific configurations

Configuration-Level Authorization​

Each configuration can require specific roles for access. This is the second authorization layer after the rest role check.

A user must have at least one of the roles configured on a configuration to access it.

Configuration Role Settings​

SettingDescription
RolesList of roles, any of which grants access
Empty RolesAccessible to anyone with the rest role

Predefined vs Custom Configurations​

AspectPredefinedCustom
Default RoledefaultAccessdefaultAccess (configurable)
EditableNoYes
Role ChangeableNo (create copy)Yes

To modify role requirements on a predefined configuration, create a custom configuration with the same name. Your custom configuration takes precedence.

Referenced Configurations​

When Squid resolves references, authorization works differently:

  • Root Configuration - Full authorization checks (roles required)
  • Referenced Configurations - Accessed implicitly, no separate role check

This means if a user can access cmdb_ci_server, they can see referenced entities (like core_company for manufacturer) even if they couldn't directly access core_company as a root configuration.

Design Decision

This behavior is intentional. References are part of the data defined in the root configuration. Requiring separate authorization for each reference would make the system overly complex and difficult to configure correctly.

Relations Restriction​

Beyond configuration access, Squid provides control over which relations can be requested.

The Problem​

A user with access to cmdb_ci_server could potentially request relations like ci_to_user_group that reveal information they shouldn't see—even if they lack access to the sys_user_group configuration directly.

The Solution​

Each configuration has two security settings for relations:

SettingDescription
Relations RestrictedWhen checked, only explicitly allowed relations can be requested
Allowed RelationsComma-separated list of permitted relations

Example​

Configuration: cmdb_ci_server

  • Relations Restricted: ✓ (checked)
  • Allowed Relations: ci_to_network_adapter, ci_to_ip_address

With this configuration:

  • ✅ ?relations=ci_to_network_adapter - Allowed
  • ✅ ?relations=ci_to_ip_address - Allowed
  • ❌ ?relations=ci_to_user_group - Blocked (not in allowed list)

When to Use Relations Restriction​

Enable relations restriction when:

  • Certain relations expose sensitive data
  • You want explicit control over data exposure
  • Different user groups need different relation access

Practical Examples​

Example 1: Full Access Service Account​

For a monitoring system that needs broad access:

User: squid_monitoring_full
Roles:
  - x_a46gh_squidx.rest          → API access
  - x_a46gh_squidx.defaultAccess → All predefined configs

Example 2: Restricted Service Account​

For an accounting system that only needs asset data:

User: squid_accounting_assets
Roles:
  - x_a46gh_squidx.rest          → API access

Configurations Modified:
  - alm_asset: Add role "accounting_data_access"
  - alm_consumable: Add role "accounting_data_access"

User Additional Roles:
  - accounting_data_access

Example 3: Multiple Teams with Different Access​

Team A (Infrastructure):
  User: squid_team_a
  Roles: rest, infra_data_access

Team B (Application):
  User: squid_team_b
  Roles: rest, app_data_access

Configurations:
  - cmdb_ci_server: Roles = infra_data_access
  - cmdb_ci_appl: Roles = app_data_access
  - cmdb_ci (all CIs): Roles = infra_data_access, app_data_access

Notes​

† Database Views Limitation​

Users with the read role can view Squid configuration records but cannot access the underlying Database View definitions in ServiceNow. The view may not appear in form references or dropdowns—its existence is effectively hidden from non-admin users.

This occurs because ServiceNow requires explicit Read ACLs on each Database View; table-level ACLs do not inherit to views. While granting access is technically possible, it requires:

  • A separate Read ACL for each Database View
  • Read ACLs on all underlying tables joined in the view
  • Manual maintenance as views are added or changed

There is no bulk ACL mechanism. For environments with many Database Views, this approach does not scale. In practice, Database View visibility remains limited to sys_admin users.

For official documentation, see ServiceNow KB0535471.

Last updated on
We track. Ok?