Cisco NSO integration overview

Itential Platform integrates with Cisco Network Services Orchestrator (NSO) through adapter-nso, a dedicated adapter that manages the connection between Platform and NSO, and itential_tools, a package installed on the NSO server that exposes NSO capabilities to Platform workflows.

Together these components allow Platform automations to read and write device configurations through NSO, apply service models, subscribe to NSO events, and perform device lifecycle operations — all programmatically via workflows and the RESTCONF or NETCONF protocols.

How the integration works

The NSO adapter connects to NSO over two interfaces simultaneously:

HTTP/HTTPS — used for JSON-RPC calls and RESTCONF. This is the web interface port (default 8080 or 8888 for SSL).
NETCONF over SSH — used for configuration transactions and event stream subscriptions (default port 2022).

Each time the adapter establishes a connection to NSO, it reads the service models advertised by NSO. Platform workflows then interact with those service models and devices through workflow tasks such as runAction, restAction, and eventListener.

NSO does not need to be installed on the same server as Platform, but it must be network-accessible from Platform.

Integration components

Component	Where it lives	Purpose
`adapter-nso`	Itential Platform	Manages the connection to NSO; exposes NSO operations as workflow tasks
`itential_tools`	NSO server	NCS package that provides the action paths Platform uses to interact with NSO
`ph-auth.py`	NSO server	Optional external authentication script that allows NSO to validate users against Platform

Authentication strategies

The adapter supports two authentication modes, configured via authenticationStrategy.method.

`machineLogin`

All transactions to NSO are made using a single global service account. This is the default and simpler mode. NSO sees all Platform-initiated operations as coming from one user (typically admin).

Use machineLogin when:

You do not need per-user authorization in NSO
NSO NACM rules are not in use or are applied at the service/device level rather than per user

`tokenLogin`

Platform makes calls on behalf of specific authenticated users. When a workflow performs an operation, NSO receives the request as the individual user (for example, bobjones) rather than the service account. This requires NSO to be configured with external authentication using the ph-auth.py script.

Use tokenLogin when:

Your organization requires per-user audit trails in NSO
NSO NACM rules are applied per user or per group
Compliance requirements mandate that individual user actions be attributed in NSO

See Authentication and access control for configuration steps.

Protocols

The adapter supports three protocols for interacting with NSO. The appropriate protocol depends on your NSO version and use case.

Protocol	NSO support	Notes
RESTCONF	NSO 5.x and later	Recommended for configuration operations. NSO 5.4 and later support RESTCONF only (REST is removed).
JSON-RPC	All versions	Used internally by `itential_tools` actions.
NETCONF	All versions	Used for configuration transactions and subscribing to NSO event streams.

NSO 5.3 is the last version to support both RESTCONF and the legacy REST API. NSO 5.4 and later support RESTCONF only.

Layered Service Architecture (LSA)

Platform supports NSO deployments using Layered Service Architecture, where an upper NSO node manages service models and one or more lower NSO nodes connect to physical devices.

Configure a separate adapter-nso instance for each NSO node:

Create one adapter instance pointing to the upper NSO node (service models).
Create one additional adapter instance for each lower NSO node (device management).

Platform’s adapter broker handles routing automatically. When a workflow task references a device or service model by name, Platform queries all configured NSO adapter instances to locate which one manages that resource, then routes the operation to the correct adapter.

Itential does not support multiple NSO instances that share device names or service model names/paths. Each device and each service model path must be managed by exactly one NSO instance.