Service Account Migration and Netskope Client Auditing

This article is a comprehensive guide for Netskope administrators migrating API integrations from the legacy REST API V2 token model to the secure, role-driven RBAC V3 Service Account framework.

This migration is a critical step, as the RBAC V3 framework represents a mandatory architectural shift to a decentralized, “API First” architecture, ensuring consistent authorization for both WebUI and REST API interactions.

REST API V2 Token Deprecation and Mandatory Service Account Workflow

The previous REST API V2 token provisioning workflow is deprecated and will become unavailable after RBAC V3 functionality is activated.

• V2 Token Deprecation Status: You can no longer provision new V2 tokens using the deprecated interface (Settings > Tools > Rest API V2) once RBAC V3 is enabled.
• Existing V2 Tokens: Any existing V2 tokens will continue to function until their specified expiration date. However, these tokens cannot be extended.
• New Workflow Requirement: All future token provisioning must be performed using the new Service Account creation process, which is fully integrated with the RBAC V3 role management framework.

Proactive API Client Auditing (Critical Pre-Enforcement Step)

Before enabling IP allowlists for any new RBAC V3 role or globally, administrators must conduct a proactive audit of all API client source IPs. This is the only way to prevent a catastrophic service outage.

Enabling a role-based or global IP allowlist without a complete inventory of existing API clients can result in a “self-inflicted denial-of-service attack.”

Activating the allowlist will instantly block all API calls from unlisted IPs, halting critical security and operational integrations, including:

• Security Information and Event Management (SIEM) platforms ingesting logs
• Security Orchestration, Automation, and Response (SOAR) tools orchestrating responses
• SCIM user provisioning flows
• Custom scripts and automated reporting tools

Using the REST API for IP Inventory

The definitive method and the most reliable source of truth for administrative API activity is the Netskope REST API V2 itself, not the UI Audit Log.

Step 1: Identify Audit Scope

1. Recommended Audit Window: Use a minimum of a 90-day audit window. This period aligns with Netskope’s default log retention and ensures both frequent and infrequent API activities are captured.
2. Required Endpoints: Query the REST API v2 datasearch endpoints, which are designed for ad-hoc queries, focusing on events most likely to contain API activity:

    ◦ /api/v2/events/datasearch/alert

    ◦ /api/v2/events/datasearch/application

    ◦ /api/v2/events/datasearch/page

3. Key Data Point: Extract the value of the srcip field from the returned log records, as this contains the source IP address of the API client.

Step 2: Extract Inventory Using a Script (Example)

To effectively handle pagination and process the large volume of data, programmatic querying is required.

The core task is to programmatically query these event logs, extract the srcip, and aggregate a final, unique list of all source IP addresses.

Example Implementation Logic:

• The script should iterate through the defined datasearch endpoints for the 90-day period.
• It must handle pagination by incrementing the offset parameter until no more records are returned.
• It should parse the JSON response and extract unique srcip values, ultimately providing an exhaustive list of all client source IPs.

Step 3: Implement the Role-Based Allowlist

1. Review and Approve: The aggregated list of unique IPs must be reviewed to correlate each IP with its owner and purpose (e.g., SIEM platform, custom tool).
2. Configure Role Allowlist: Navigate to the role settings (Settings > Administration > Roles) and populate the IP Allowlist section with the approved IPv4 addresses.

    ◦ The IP addresses must be space-delimited and be valid IPv4 addresses.

3. Critical Security Note: The role-based IP allowlist supersedes and overrides any previously configured global IP allowlist settings. If enabled on the role, it becomes the sole source of truth for access control for that service account.

SCIM Integration Update: Step-by-Step Migration to Service Account V3

The migration from a legacy API token to a new RBAC V3 Service Account requires a sequential, three-part process: Role Creation, Service Account Creation, and Integration Update.

Step 1: Role Creation (Principle of Least Privilege)

Since RBAC V3 is role-driven, you must create the role first before creating the service account.

1. Navigate to Role Management: Go to Administration > Roles and click New.
2. Define Permissions (PoLP): Assign a descriptive name (e.g., scim_provisioner). Apply the Principle of Least Privilege (PoLP).

    ◦ For SCIM, select the Administration category.

    ◦ Explicitly deselect permissions for UI functions and any other non-essential operations, as service accounts are non-interactive.

    ◦ Set the permission level to Manage for the Users and Group APIs, as these are required for SCIM provisioning.

3. Apply IP Allowlist: If you performed the audit (Section 2), navigate to the IP Allowlist tab and add the approved source IPv4 addresses of your Identity Provider (IdP).

Step 2: Service Account and Token Creation

1. Create Service Account: Navigate to Administration > Administrators & Roles and click Service Account.
2. Configure Account: Type the name of the service account and select the custom role created in Phase A (e.g., scim_provisioner).
3. Set Expiration: Specify the token’s expiration period (e.g., 12 months).
4. Generate and Store Token (Critical Step): Click Create. The API token is displayed only once upon successful creation. It is critical to copy and securely store this token immediately as it cannot be retrieved later.

Step 3: SCIM Integration Update

1. Update API Token: In your Identity Provider’s (IdP’s) SCIM provisioning settings (e.g., Okta or Entra ID), replace the old V2 API token with the new V3 Service Account token.
2. Update Base URL: The older SCIM service URL is being deprecated and must be modified to point to the new RBAC V3-compliant endpoint.

    ◦ New Base URL Format: https://<tenant-name>.goskope.com/api/v2/scim.

3. Test Connection: After updating both the token and the base URL, test the connection to ensure the integration is functioning correctly.

Troubleshooting Connection Errors

If the connection test fails, the most common reason is a conflict with the role-based IP allowlist.

• Verify Source IPs: Check the role’s IP allowlist configuration to ensure that the current source IP addresses used by your specific SCIM provider (e.g., Okta’s cell IPs or Microsoft Entra ID ranges) are accurately included in the role’s allowlist. Remember that the role-based allowlist supersedes any global settings.