Certificate based Authentication

/misc/config/grpc/ems.pem
/misc/config/grpc/ems.key
/misc/config/grpc/ca.cert

Note	For clients to use the certificates, ensure to copy the certificates from /misc/config/grpc/

Generation of Certificates

These certificates are typically generated using a Certificate Authority (CA) by the device. The EMS certificates, including the server certificate (ems.pem ), public key (ems.key ), and CA certificate (ca.cert ), are generated with specific parameters like the common name ems.cisco.com to uniquely identify the EMS server and placed in the /misc/config/grpc/ location.

The default certificates that are generated by the server are Server-only TLS certificates and by using these certificates you can authenticate the identity of the server.

Usage of Certificates

These certificates are used for enabling secure communication through Transport Layer Security (TLS) between gRPC clients and the EMS server. The client should use ems.pem and ca.cert to initiate the TLS authentication.

To update the certificates, ensure to copy the new certificates that has been generated earlier to the location and restart the server.

Custom Certificates

If you want to use your own certificates for EMS gRPC communication, then you can follow a workflow to generate a custom certificates with the required parameters and then configure the EMS server to use these custom certificates. This process involves replacing the default EMS certificates with the custom ones and ensuring that the gRPC clients also trust the custom CA certificate. For more information on how to customize the common-name , see Certificate Common-Name For Dial-in Using gRPC Protocol.

Updating the gRPC-Level Authorization Policy in the Router Using gNSI Client

Before you start

When a router boots for the first time, it should have the following prerequisites:

• The gNSI.authz service is up and running.

• The default gRPC-level authorization policy is added for all gRPC services.

• The default gRPC-level authorization policy allows access to all RPCs.

The following steps are used to update the gRPC-level authorization policy:

1. Initiate the gNSI.authz.Rotate() streaming RPC. This step creates a streaming connection between the router and management application (client).

   Note	Only one gNSI.authz.Rotate() must be in progress at a time. Any other RPC request is rejected by the server.

2. The client uploads new gRPC-level authorization policy using the UploadRequest message.

   Note

   There must be only one gRPC-level authorization policy in the router. All the policies must be defined in the same gRPC-level authorization policy which is being updated. As gNSI.authz.Rotate() method replaces all previously defined or used policies once the finalize message is sent. The upgrade information is passed to the version and the created_on fields. These information are not used by the gNSI.authz service. It is designed to help you to track the active gRPC-level authorization policy on a particular router.

3. The router activates the gRPC-level authorization policy.

4. The router sends the UploadResponse message back to the client after activating the new policy.

5. The client verifies the new gRPC-level authorization policy using separate gNSI.authz.Probe() RPCs.

6. The client sends the FinalizeRequest message, indicating the previous gRPC-level authorization policy is replaced.

   Note	It is not recommended to close the stream without sending the finalize message. It results in the abandoning of the uploaded policy and rollback to the one that was active before the gNSI.authz.Rotate() RPC started.

{
  "version": "version-1",
  "created_on": "1632779276520673693",
  "policy": {
    "name": "gNSI.ssh policy",
    "allow_rules": [{
      "name": "admin-access",
      "source": {
        "principals": [
          "spiffe://company.com/sa/V1",
          "spiffe://company.com/sa/V2"
        ]
      },
      "request": {
        "paths": [
          "/gnsi.ssh.Ssh/*"
        ]
      }
    }],
    "deny_rules": [{
      "name": "sales-access",
      "source": {
        "principals": [
          "spiffe://company.com/sa/V3",
          "spiffe://company.com/sa/V4"
        ]
      },
      "request": {
        "paths": [
          "/gnsi.ssh.Ssh/MutateAccountCredentials",
          "/gnsi.ssh.Ssh/MutateHostCredentials"
        ]
      }
    }]
  }
}

Updating the gRPC-Level Authorization Policy file Using Exec Command

Use the following steps to update the authorization policy in the router.

1. Create the users profiles for the users who need to be added in the authorization policy. You can skip this step if you have already defined the user profiles.

   The following example creates three users who are added in the authorization policy.

   
   Router(config)#username V1
   Router(config-un)#group root-lr
   Router(config-un)#group cisco-support
   Router(config-un)#secret x
   Router(config-un)#exit
   Router(config)#username V2
   Router(config-un)#group root-lr
   Router(config-un)#password x
   Router(config-un)#exit
   Router(config)#username V3
   Router(config-un)#group root-lr
   Router(config-un)#password x
   Router(config-un)#commit

2. Enable tls-mutual to establish the secure mutual between the client and the router.

   
   Router(config)#grpc
   Router(config-grpc)#port 0
   Router(config-grpc)#tls-mutual
   Router(config-grpc)#certificate-authentication
   Router(config-grpc)#commit

3. Define the gRPC-level authorization policy.

   The following sample gRPC-level authorization policy defines authorization policy for the users V1, V2 and V3.

   
   {
       "name": "authz",
       "allow_rules": [
           {
               "name": "allow all gNMI for all users",
               "source": {
                   "principals": [
                       "*"
                   ]
               },
               "request": {
                   "paths": [
                       "*"
                   ]
               }
           }
       ],
       "deny_rules": [
            {
               "name": "deny gNMI set for oper users",
               "source": {
                   "principals": [
                       "V1"
                   ]
               },
               "request": {
                   "paths": [
                       "/gnmi.gNMI/Get".
                   ]
               }
           },
   
           {
               "name": "deny gNMI set for oper users",
               "source": {
                   "principals": [
                       "V2"
                   ]
               },
               "request": {
                   "paths": [
                       "/gnmi.gNMI/Get"
                   ]
               }
           },
           {
               "name": "deny gNMI set for oper users",
               "source": {
                   "principals": [
                       "V3"
                   ]
               },
               "request": {
                   "paths": [
                       "/gnmi.gNMI/Set"
                   ]
               }
           }
       ]
   }
    
   

4. Copy the gRPC-level authorization policy to the router.

   The following example copies the gNSI Authz policy to the router:

   -bash-4.2$ scp test.json V1@192.0.2.255:/disk0:/
   Password: 
   test.json                                                                                                                 100%  993   161.4KB/s   00:00    
   -bash-4.2$
   

5. Activate the gRPC-level authorization policy to the router.

   The following example loads the policy to the router.

   
   Router(config)#gnsi load service authorization policy /disk0:/test.json
   Successfully loaded policy
   

Verification

Router#show gnsi service authorization policy
Wed Jul 19 10:56:14.509 UTC{
    "version": "1.0",
    "created_on": 1700816204,
    "policy": {
        "name": "authz",
        "allow_rules": [
            {
                "name": "allow all gNMI for all users",
                "request": {
                    "paths": [
                        "*"
                    ]
                },
                "source": {
                    "principals": [
                        "*"
                    ]
                }
            }
        ],
        "deny_rules": [
            {
                "name": "deny gNMI set for oper users",
                "request": {
                    "paths": [
                        "/gnmi.gNMI/*"
                    ]
                },
                "source": {
                    "principals": [
                        "User1"
                    ]
                }
            }
        ]
    }
}

In the following example, User1 user tries to access the get RPC request for which the permission is denied in the above authorization policy.

bash-4.2$ ./gnmi_cli -address 198.51.100.255 -ca_crt 
certs/certs/ca.cert -client_crt certs/certs/User1.pem -client_key 
certs/certs/User1.key -server_name ems.cisco.com -get -proto get-oper.proto

Output

E0720 14:49:42.277504   26473 gnmi_cli.go:195] 
target returned RPC error for Get("path:{origin:"openconfig-interfaces" elem:{name:"interfaces"}
 elem:{name:"interface" key:{key:"name" value:"HundredGigE0/0/0/0"}}}
 type:OPERATIONAL encoding:JSON_IETF"): 
rpc error: code = PermissionDenied desc = unauthorized RPC request rejected 

gNSI Acctz Data Logging

The gNSI accounting (Acctz) is a gNSI accounting protocol that collects and transfers accounting records from a router to a remote collection service over a gRPC transport connection.

Starting from Release 24.3.1, you can log gRPC AAA accounting data through gNSI accounting (Acctz). The gNSI Acctz data is logged, stored in accounting records, and sent to gNSI client for monitoring purposes. These gNSI Acctz accounting records contain

• users' login or logout times,

• network access resources such as interface IP and port, and

• duration of each session.

The gNSI Acctz logging can be done using the RecordSubscribe() gRPC request to a router. For more information on the RecordSubscribe() RPC, see the GitHub repository.

gNSI Acctz Logging Stream Capacity

The gNSI Acctz logs are recorded in a queue, maintaining a history of the 10 most recent records. When the accounting queue is full and no gNSI Acctz collectors are connected, the stream drops the records. Besides the 10 records stored for streaming, up to 512 additional records are stored during processing. As new records arrive, the data stream continues until the gNSI session ends or an error occurs, such as a client disconnection due to network issues or the server going down. If the server's output buffer remains full for an extended period, new records are dropped until the collector starts receiving them.

When the queue reaches its full capacity, the system automatically replaces the oldest records with the newest ones. The router then transmits this logged information through gNSI to gNSI client for real-time monitoring purposes. You can configure the queue size using the grpc aaa accounting queue-size command.

Supported Records for gNSI Acctz Logging

gNSI Acctz logging system supports Command and gRPC service records.

Default Behavior and Verification of gNSI Acctz Logging

By default, gNSI Acctz records are logged when the configuration is enabled. You can verify the gNSI Acctz using show gnsi state , show gnsi acctz statistics , and show aaa accounting statistics commands.