Introducing gNSI: gRPC-native AAA for Cisco IOS XR – مقالات شبکه، هوش مصنوعی، رایانش ابری، تکنولوژی و مفاهیم پیرو آن

The Problem

For CLI, NETCONF, and SNMP, security is a solved problem. AAA (Authentication, Authorization, and Accounting) with TACACS+ and Syslog takes care of all three pillars. But when the Management Plane moved to gRPC and gNMI, that same security story did not come along for the ride.

TLS handles Authentication, but nobody standardized how to actually “manage” the Certificates — issuing them, renewing them, revoking them, rotating Trust Bundles and CRLs. Most operators end up copying PEM files around or using vendor-specific tools.

Authorization got worse, not better. gRPC needs Service-level control (“can this client call gNMI Set?”) while gNMI needs Path-level control (“can this client write to /system/?”). A single broad role does not cover either case well.

Accounting — the “A” that tells what actually happened — works fine for CLI and NETCONF sessions but does not automatically cover gRPC traffic.

And then there is Credential Rotation. gRPC TLS Certificates and SSH Host Keys live on completely different tracks. One can go stale without anyone noticing the other is fine.

Put it all together: inconsistent Security Posture and automation that breaks in ways that are hard to debug.

What is gNSI

gNSI stands for gRPC Network Security Interface. It is a set of gRPC Services defined by OpenConfig — the same community behind gNMI, gNOI, and gRIBI. Where those focus on config, operations, and routing, gNSI focuses on Security:

The five services map directly to the AAA model — Authentication, Authorization, and Accounting — in that order:

How TLS Certificates and Trust Bundles get rotated — that is Certz (Authentication)
How SSH Credentials get rotated — that is Credentialz (Authentication)
Who can call which RPCs — that is Authz (Authorization)
Which gNMI Paths a caller can touch — that is Pathz (Authorization)
What happened on the box (the Audit Trail) — that is Acctz (Accounting)

Every service has a Protobuf (Protocol Buffers — the serialization format gRPC uses) definition in the OpenConfig gNSI repository. Each IOS XR release pins to a specific API version of these definitions.

Why gNSI matters

Without gNSI, security configuration lives in CLI commands and manual file copies — hard to automate, hard to roll back, hard to verify at scale.

With gNSI, Controllers can Stage a new Policy or Certificate, Validate it, and Commit — all through a gRPC API. If something goes wrong, Rollback is built into the spec. This plugs directly into ZTP (Zero-Touch Provisioning) / Bootz (Bootstrap) pipelines, and the state is visible through YANG Telemetry (see OpenConfig public models — gNSI).

In short: repeatable, programmable security operations instead of one-off fixes.

Before and after gNSI

Rotating a gRPC TLS Certificate — the old way:

1. Generate key + CSR on a workstation
2. Get it signed by the CA
3. SCP the PEM files to the router's /misc/config/grpc/
4. Hope the filenames and paths are correct
5. Reload the gRPC server (or wait for a process restart)
6. If it breaks, SSH in and manually fix the files
7. No audit trail of what changed or who did it

The same operation with gNSI Certz:

1. Generate key + CSR (or let the router generate it)
2. Get it signed by the CA
3. grpcurl → Certz.Rotate: upload cert + key + trust bundle
4. Router validates the material before committing
5. grpcurl → Certz.Rotate: finalize (or cancel to roll back)
6. New cert takes effect for new connections — zero downtime
7. Acctz streams an audit record of the rotation

The same stage-validate-finalize pattern applies to Authorization Policies (Authz, Pathz) and SSH Credentials (Credentialz).

gNSI Services at a glance

Here is what each service does. IOS XR adds support for these across releases — always check the IOS XR Programmability Documentation for the target platform.

Service	What it controls	Example
Authentication	Certz	TLS Certificate Lifecycle	Rotate the gRPC Server Certificate and Trust Bundle with zero downtime
Credentialz	SSH Credential Rotation	Replace SSH Host Keys or user Authorized Keys without a reboot
Authorization	Authz	gRPC Service-level Authorization	Let a Controller call gNMI Set but block gNOI RPCs
Pathz	gNMI Path-level Authorization	Allow Subscribe on `/interfaces/` but deny Set on `/system/`
Accounting	Acctz	Accounting and Audit Streaming	Stream a record of every gRPC, CLI, and NETCONF action to a Collector

How the five services fit together

gNSI is a gRPC-native AAA framework. The five services map to Authentication, Authorization, and Accounting — and that order matters. A request must first prove its identity, then pass access-control checks, and finally get recorded. The diagram below reflects that flow from left to right.

 ┌─────────────────────────────────────────────────────────────────┐
 │ gRPC Management Plane │
 │ │
 │ AUTHENTICATION AUTHORIZATION ACCOUNTING │
 │ ────────────── ───────────── ────────── │
 │ ┌──────────────┐ ┌───────────┐ │
 │ │ Certz │ │ Authz │ ┌───────────┐ │
 │ │ (TLS certs │ ──────▶ │ (who can │ ──────▶ │ Acctz │ │
 │ │ + trust) │ │ call │ │ (audit │ │
 │ └──────────────┘ │ what) │ │ trail) │ │
 │ └───────────┘ └───────────┘ │
 │ ┌──────────────┐ ┌───────────┐ │
 │ │ Credentialz │ │ Pathz │ │
 │ │ (SSH keys + │ │ (which │ │
 │ │ passwords) │ │ gNMI │ │
 │ └──────────────┘ │ paths) │ │
 │ └───────────┘ │
 └─────────────────────────────────────────────────────────────────┘

The AAA flow on the wire:

Authentication — establish identity first.
Certz manages TLS Certificates and Trust Bundles — every gRPC connection starts here. Credentialz does the same for SSH Host Keys and user Credentials.
Authorization — decide what the authenticated identity can do.
Authz controls which gRPC Services each client is allowed to call. Pathz goes one level deeper, controlling which gNMI Paths can be read or written.
Accounting — record what happened.
Acctz streams Accounting Records for every gRPC, CLI, and NETCONF action, completing the Audit Trail.

IOS XR Release Support

Service	First IOS XR support	Key later enhancements
Authentication	Certz	24.1.1 — Rotate RPC, SSL Profiles, `grpc gnsi service certz ssl-profile-id`	24.1.1 — configurable CN for dial-in; 24.4.1 — TLS 1.3; 25.4.1 — legacy `/misc/config/grpc` paths deprecated, SSL Profiles are the path forward
Credentialz	24.2.1 — Rotate RPCs for SSH Credential Rotation	24.2.11 — Account-level and Host-level Credential scope documented
Authorization	Authz	7.11.1 — Rotate / Probe / Get RPCs, `gnsi load service authorization policy` CLI	24.4.1 — broader 8000 coverage (8200, 8700, 8800/P100); SPIFFE-ID to username mapping
Pathz	24.2.1 — gNMI Set only, OpenConfig models only	Later trains may add more RPCs and model families; default is ACCEPT_ALL until a Policy is loaded
Accounting	Acctz	24.3.1 — gRPC Accounting Stream (8000 / NCS 5500)	24.4.x — platform-specific extensions; check the target Release Notes

XRdocs deep dives

These articles walk through hands-on workflows on IOS XR, ordered by the AAA flow. Start with Certz to establish TLS authentication, then layer on Authorization with Authz and Pathz, and finish with Acctz for accounting.

Service	XRdocs article
Authentication	Certz	gNSI Certz — TLS Certificate Lifecycle on Cisco IOS XR
Credentialz	gNSI Credentialz — SSH Credential Rotation on Cisco IOS XR
Authorization	Authz	gRPC Authorization with Authz
Pathz	Securing gNMI with Pathz
Accounting	Acctz	gNSI Acctz — Management Plane Accounting on Cisco IOS XR

Prerequisites and setup

What the setup looks like

 ┌──────────────────┐ port 57400 ┌──────────────┐
 │ Workstation │ ────────── gRPC ───────────▶ │ IOS XR │
 │ │ (plaintext in lab, │ Router │
 │ grpcurl │ TLS in production) │ │
 │ gnmic │ │ EMSd runs │
 │ openssl │ │ gNSI RPCs │
 │ jq │ │ │
 └──────────────────┘ └──────────────┘
 ▲
 │ The.proto files from the cloned
 │ openconfig/gnsi repo tell grpcurl
 │ how to encode/decode gRPC messages.

Tools

Tool	What it does	Install
grpcurl	Command-line gRPC client — like `curl` but for gRPC	`go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest` or download binary
gnmic	gNMI CLI client (for YANG Telemetry examples)	`bash -c "$(curl -sL https://get.gnmic.openconfig.net)"`
jq	JSON processor (for Authz Policy formatting)	`brew install jq` / `apt install jq`
OpenSSL	TLS PKI operations (Certz)	Pre-installed on most systems

Proto files

grpcurl needs the .proto files to know how to encode and decode gRPC messages. Clone them once:

git clone --depth 1 https://github.com/openconfig/gnsi.git openconfig-gnsi
cd openconfig-gnsi
export GNSI_IMPORT="$PWD"

What the grpcurl flags mean

Every hands-on command in this series uses these flags:

Flag	What it does
`-plaintext`	Connect without TLS. Lab only — see caveat below.
`-import-path "$GNSI_IMPORT"`	Where grpcurl looks for `.proto` files (the cloned repo root)
`-proto "authz/authz.proto"`	Which `.proto` file defines the service being called
`-H "username:..."` / `-H "password:..."`	IOS XR metadata-based authentication (passed as gRPC headers)
`-d '{...}'`	The request payload as JSON (grpcurl converts it to protobuf)
`-d '@'`	Read the request payload from stdin (used for streaming RPCs)

Lab only: All hands-on examples in this series use -plaintext to skip TLS — this makes lab setup simpler but disables encryption and server authentication. In production, replace -plaintext with -cacert, -cert, and -key flags pointing to real TLS material. The Certz article covers how to set up that material.

Router requirements

IOS XR router with gRPC enabled — see the Programmability Configuration Guide
Minimum IOS XR version depends on the service (see Release Support)

Each service article includes its own environment setup block.

Quick start: verify gNSI on the router

Prerequisites

IOS XR router with gRPC enabled (7.11.1 or later for Authz — see Release Support)
grpcurl installed
OpenConfig gNSI protos cloned (see Proto files above)

Run the check

After installing grpcurl and cloning the protos, run this to confirm the router exposes Authz RPCs.

Important: Replace 198.51.100.1:57400 with the actual router IP and gRPC port. Replace the password with the router password.

export GNSI_IMPORT="${GNSI_IMPORT:-$PWD}"
export XR="${XR:-198.51.100.1:57400}" # ← replace with router IP:port
export XR_USER="${XR_USER:-cisco}"
export XR_PASS="${XR_PASS:-}" # ← replace with password
GRPC_MD=(-H "username:${XR_USER}" -H "password:${XR_PASS}")
grpcurl -plaintext \
 -import-path "$GNSI_IMPORT" \
 -proto "authz/authz.proto" \
 "${GRPC_MD[@]}" \
 "${XR}" \
 list gnsi.authz.v1.Authz

Expected output:

gnsi.authz.v1.Authz.Get
gnsi.authz.v1.Authz.Probe
gnsi.authz.v1.Authz.Rotate

If this works, the router is ready. Head to the Certz article to set up TLS authentication first, or jump to the Authz article to upload an authorization policy.