> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Cisco NSO integration overview

> How Itential Platform integrates with Cisco NSO for network service orchestration, and how to choose an integration approach.

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](./authentication) 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:

1. Create one adapter instance pointing to the upper NSO node (service models).
2. 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.

## Related reading

* [Supported NSO versions](./supported-versions)
* [Configure the NSO adapter](./configure-adapter)
* [Authentication and access control](./authentication)
* [NETCONF event streams](./netconf-events)
* [RESTCONF API](./restconf-api)
* [Itential Tools actions](./itential-tools-actions)
* [Device customization](./device-customization)