Authentication and access control

By default, the NSO adapter connects to NSO using a single global service account (machineLogin). To enable per-user authorization — where Platform makes NSO calls on behalf of individual authenticated users — configure external authentication using the ph-auth.py script and set the adapter to tokenLogin.

This page covers external authentication setup and NSO NETCONF Access Control Model (NACM) configuration.

External authentication

External authentication allows NSO to validate user identities against Itential Platform. When a workflow performs an NSO operation, NSO calls the ph-auth.py script, which queries Platform and returns the user’s group memberships. NSO then applies NACM rules based on those groups.

Network connectivity is required between NSO and Platform (typically port 3000) for external authentication to function.

Prerequisites

The following must be installed on the NSO server:

$ yum install -y python python-pip
$ pip install requests

Install and configure ph-auth.py

Locate the external authentication script

After installing itential_tools, the script is at:

/var/opt/ncs/packages/itential-tools/external_auth/ph-auth.py

Configure the Platform server address and port

Edit ph-auth.py and set the hostname and port of your Platform server:

1 PH_ADDRESS = "localhost"
2 PH_PORT = "3000"

Test the script

Run the script manually:

$ python /var/opt/ncs/packages/itential-tools/external_auth/ph-auth.py

When prompted, type the following and press Enter:

[test;test;]

A successful test returns:

reject

A reject response confirms the script is working — test is not a valid user, so NSO correctly rejects the credential.

Configure ncs.conf for external authentication

Edit /etc/ncs/ncs.conf to enable external authentication. Both external authentication and local or PAM authentication should be configured. Local authentication can be disabled once external authentication is confirmed working.

1 <aaa>
2   <ssh-server-key-dir>${NCS_CONFIG_DIR}/ssh</ssh-server-key-dir>
3 
4   <pam>
5     <enabled>false</enabled>
6     <service>system-auth</service>
7   </pam>
8 
9   <external-authentication>
10     <enabled>true</enabled>
11     <executable>/var/opt/ncs/packages/itential-tools/external_auth/ph-auth.py</executable>
12   </external-authentication>
13 
14   <local-authentication>
15     <enabled>false</enabled>
16   </local-authentication>
17 
18   <expiration-warning>prompt</expiration-warning>
19 </aaa>

Restart NSO after saving changes:

$ service ncs restart

Configure the adapter for tokenLogin

In the NSO adapter service config in Platform, change authenticationStrategy.method from machineLogin to tokenLogin:

1 "authenticationStrategy": {
2   "type": "dynamic",
3   "location": "NSO",
4   "method": "tokenLogin"
5 }

Configure default authgroup mappings

When using tokenLogin, verify that users map to the correct southbound device credentials in NSO. Run the following for each authentication group, substituting the appropriate device credentials:

$ ncs_cli -u admin -C
$ config
$ devices authgroups group default default-map remote-name admin remote-password admin
$ commit

NACM access control

NSO’s NETCONF Access Control Model (NACM) controls which users and groups can access which devices and services. The itential_tools package includes sample NACM rules to get started.

Groups model

The sample NACM rules assume three groups, shared between Platform and NSO:

Group	Description
`pronghorn`	Applied to the service account the NSO adapter uses when connecting to NSO
`users`	Applied to end users interacting with NSO through Platform workflows
`admins`	Applied to administrators of the system

The groups returned by the NSO AAA provider (via ph-auth.py) must match the group names defined in your NACM rule-lists. A mismatch will cause authorization failures even when authentication succeeds.

Sample rule-lists

The sample rules include three rule-lists:

Rule-list	Applied to groups
`pronghorn-system`	`pronghorn` group — the Platform service account
`pronghorn-users`	Platform user groups
`admins`	`pronghorn` and `admins` groups

Install the sample NACM rules

Load the included sample-nacm-rules.xml file into the NSO CDB:

$ ncs_cli -u admin -C
$ config
$ load merge sample-nacm-rules.xml
$ commit dry-run
$ commit

Review the commit dry-run output before committing to confirm the rules are correct for your environment.

Configure device whitelists

The sample rules include a rule-list for whitelisting devices to the users group. Add each device that users should be able to access:

$ ncs_cli -u admin -C
$ config
$ nacm rule-list whitelist-devices rule permit-device-mydevicename \
>   path /devices/device[name='mydevicename'] \
>   action permit
$ commit

In a NACM-enabled system, any device added to NSO — whether configured manually or onboarded through a Platform workflow — must have its NACM group assignments defined at the time of onboarding.

Configure service whitelists

Add service model instances to the users whitelist. To whitelist all instances of a service model:

$ ncs_cli -u admin -C
$ config
$ nacm rule-list whitelist-services rule permit-service-cisco-ios \
>   path /services/cisco-ios \
>   action permit
$ commit

To whitelist a single service instance:

$ ncs_cli -u admin -C
$ config
$ nacm rule-list whitelist-services rule permit-service-cisco-ios-101 \
>   path /services/cisco-ios[vlan=101] \
>   action permit
$ commit

In a NACM-enabled system, any new service instance added to NSO must have its NACM group assignments defined. Service instances may be restricted to a single group or made accessible to multiple groups using separate NACM rules.