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

# Authentication and access control

> Configure external authentication and NACM access control for the Itential Platform NSO integration.

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:

```bash
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:

```python
PH_ADDRESS = "localhost"
PH_PORT = "3000"
```

#### Test the script

Run the script manually:

```bash
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.

```xml
<aaa>
  <ssh-server-key-dir>${NCS_CONFIG_DIR}/ssh</ssh-server-key-dir>

  <pam>
    <enabled>false</enabled>
    <service>system-auth</service>
  </pam>

  <external-authentication>
    <enabled>true</enabled>
    <executable>/var/opt/ncs/packages/itential-tools/external_auth/ph-auth.py</executable>
  </external-authentication>

  <local-authentication>
    <enabled>false</enabled>
  </local-authentication>

  <expiration-warning>prompt</expiration-warning>
</aaa>
```

Restart NSO after saving changes:

```bash
service ncs restart
```

### Configure the adapter for tokenLogin

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

```json
"authenticationStrategy": {
  "type": "dynamic",
  "location": "NSO",
  "method": "tokenLogin"
}
```

### 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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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.

## Related reading

* [Configure the NSO adapter](./configure-adapter)
* [NSO integration overview](./overview)

> Configure external authentication and NACM access control for the Itential Platform NSO integration.