The AAA infrastructure

The NACM data model is targeted specifically towards access control for NETCONF operations, and thus lacks some functionality that is needed in NSO, in particular support for authorization of CLI commands and the possibility to specify the "context" (NETCONF/CLI/etc) that a given authorization rule should apply to. This functionality is modeled by augmentation of the NACM model, as defined in the tailf-acm.yang YANG module.

The ietf-netconf-acm.yang and tailf-acm.yang modules can be found in $NCS_DIR/src/ncs/yang directory in the release, while tailf-aaa.yang can be found in the $NCS_DIR/src/ncs/aaa directory.

NACM options related to services are modeled by augmentation of the NACM model, as defined in the tailf-ncs-acm.yang YANG module. The tailf-ncs-acm.yang can be found in $NCS_DIR/src/ncs/yang directory in the release.

The complete AAA data model defines a set of users, a set of groups and a set of rules. The data model must be populated with data that is subsequently used by by NSO itself when it authenticates users and authorizes user data access. These YANG modules work exactly like all other fxs files loaded into the system with the exception that NSO itself uses them. The data belongs to the application, but NSO itself is the user of the data.

Since NSO requires a data model for the AAA information for its operation, it will report an error and fail to start if these data models can not be found.

When a user logs in over NETCONF or the CLI using the built-in SSH server, with public key login, the procedure is as follows.

The user presents a username in accordance with the SSH protocol. The SSH server consults the settings for /ncs-config/aaa/ssh-pubkey-authentication and /ncs-config/aaa/local-authentication/enabled .

In all cases the keys are expected to be stored in a file called authorized_keys (or authorized_keys2 if authorized_keys does not exist), and in the native OpenSSH format (i.e. as generated by the OpenSSH ssh-keygen command). If authentication succeeds, the user's group membership is established as described in the section called “Group Membership”.

This is exactly the same procedure that is used by the OpenSSH server with the exception that the built-in SSH server also may locate the directory containing the public keys for a specific user by consulting the /aaa/authentication/users tree.

# ssh-keygen -b 4096 -t rsa
Generating public/private rsa key pair.
Enter file in which to save the key (/home/bob/.ssh/id_rsa):
Created directory '/home/bob/.ssh'.
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/bob/.ssh/id_rsa.
Your public key has been saved in /home/bob/.ssh/id_rsa.pub.
The key fingerprint is:
ce:1b:63:0a:f9:d4:1d:04:7a:1d:98:0c:99:66:57:65 bob@buzz
# ls -lt ~/.ssh
total 8
-rw-------  1 bob users 3247 Apr  4 12:28 id_rsa
-rw-r--r--  1 bob users  738 Apr  4 12:28 id_rsa.pub

<user>
  <name>bob</name>
  <uid>100</uid>
  <gid>10</gid>
  <password>$1$feedbabe$nGlMYlZpQ0bzenyFOQI3L1</password>
  <ssh_keydir>/var/system/users/bob/.ssh</ssh_keydir>
  <homedir>/var/system/users/bob</homedir>
</user>

HostKeyAlgorithms=+ssh-dss
PubkeyAcceptedKeyTypes=+ssh-dss

Password login is triggered in the following cases:

In this case, NSO will by default try local authentication, PAM, external authentication and package authentication in that order, as described below. It is possible to change the order in which these are tried, by modifying the ncs.conf. parameter /ncs-config/aaa/auth-order. See ncs.conf(5) in Manual Pages for details.

If authentication succeeds, the user's group membership is established as described in the section called “Group Membership”.

On operating systems supporting PAM, NSO also supports PAM authentication. Using PAM authentication with NSO can be very convenient since it allows us to have the same set of users and groups having access to NSO as those that have access to the UNIX/Linux host itself.

If we use PAM, we do not have to have any users or any groups configured in the NSO aaa namespace at all. To configure PAM we typically need to do the following:

PAM is the recommended way to authenticate NSO users.

As an example, say that we have user test in /etc/passwd, and furthermore:

# grep test /etc/group
operator:x:37:test
admin:x:1001:test

thus, the test user is part of the admin and the operator groups and logging in to NSO as the test user, through CLI ssh, Web UI, or netconf renders the following in the audit log.

<INFO> 28-Jan-2009::16:05:55.663 buzz ncs[14658]: audit user: test/0 logged
    in over ssh from 127.0.0.1 with authmeth:password
<INFO> 28-Jan-2009::16:05:55.670 buzz ncs[14658]: audit user: test/5 assigned
    to groups: operator,admin
<INFO> 28-Jan-2009::16:05:57.655 buzz ncs[14658]: audit user: test/5 CLI 'exit'

Thus, the test user was found and authenticated from /etc/passwd, and the crucial group assignment of the test user was done from /etc/group.

If we wish to be able to also manipulate the users, their passwords etc on the device we can write a private YANG model for that data, store that data in CDB, setup a normal CDB subscriber for that data, and finally when our private user data is manipulated, our CDB subscriber picks up the changes and changes the contents of the relevant /etc files.

A common situation is when we wish to have all authentication data stored remotely, not locally, for example on a remote RADIUS or LDAP server. This remote authentication server typically not only stores the users and their passwords, but also the group information.

If we wish to have not only the users, but also the group information stored on a remote server, the best option for NSO authentication is to use "external authentication".

If this feature is configured, NSO will invoke the executable configured in /ncs-config/aaa/external-authentication/executable in ncs.conf , and pass the username and the clear text password on stdin using the string notation: "[user;password;]\n".

For example if user "bob" attempts to login over SSH using the password "secret", and external authentication is enabled, NSO will invoke the configured executable and write "[bob;secret;]\n" on the stdin stream for the executable.

The task of the executable is then to authenticate the user and also establish the username-to-groups mapping.

For example the executable could be a RADIUS client which utilizes some proprietary vendor attributes to retrieve the groups of the user from the RADIUS server. If authentication is successful, the program should write "accept " followed by a space-separated list of groups the user is member of, and additional information as described below. Again, assuming that Bob's password indeed was "secret", and that Bob is member of the "admin" and the "lamers" groups, the program should write "accept admin lamers $uid $gid $supplementary_gids $HOME\n" on its standard output and then exit.

Thus the format of the output from an "externalauth" program when authentication is successful should be:

"accept $groups $uid $gid $supplementary_gids $HOME\n"

Where

It is further possible for the program to return a token on successful authentication, by using "accept_token" instead of "accept":

"accept_token $groups $uid $gid $supplementary_gids $HOME $token\n"

Where $token is an arbitrary string. NSO will then, for some northbound interfaces, include this token in responses.

It is also possible for the program to return additional information on successful authentication, by using "accept_info" instead of "accept":

"accept_info $groups $uid $gid $supplementary_gids $HOME $info\n"

Where $info is some arbitrary text. NSO will then just append this text to the generated audit log message (CONFD_EXT_LOGIN).

Yet another possibility is for the program to return a warning that the user's password is about to expire, by using "accept_warning" instead of "accept":

"accept_warning $groups $uid $gid $supplementary_gids $HOME $warning\n"

Where $warning is an appropriate warning message. The message will be processed by NSO according to the setting of /ncs-config/aaa/expiration-warning in ncs.conf.

There is also support for token variations of "accept_info" and "accept_warning" namely "accept_token_info" and "accept_token_warning". Both "accept_token_info" and "accept_token_warning" expects the external program to output exactly the same as described above with the addition of a token after $HOME:

"accept_token_info $groups $uid $gid $supplementary_gids $HOME $token $info\n"

"accept_token_warning $groups $uid $gid $supplementary_gids $HOME $token $warning\n"

If authentication failed, the program should write "reject" or "abort", possibly followed by a reason for the rejection, and a trailing newline. For example "reject Bad password\n" or just "abort\n". The difference between "reject" and "abort" is that with "reject", NSO will try subsequent mechanisms configured for /ncs-config/aaa/auth-order in ncs.conf (if any), while with "abort", the authentication fails immediately. Thus "abort" can prevent subsequent mechanisms from being tried, but when external authentication is the last mechanism (as in the default order), it has the same effect as "reject".

Supported by some nortbound APIs, such as JSONRPC and CLI over SSH, the external authentication may also choose to issue a challenge:

"challenge $challenge-id $challenge-prompt\n"

For more information on multi factor authentication, see the

the section called “External multi factor authentication” section.

When external authentication is used, the group list returned by the external program is prepended by any possible group information stored locally under the /aaa tree. Hence when we use external authentication it is indeed possible to have the entire /aaa/authentication tree empty. The group assignment performed by the external program will still be valid and the relevant groups will be used by NSO when the authorization rules are checked.

When username, password authentication is not feasible, authentication by token validation is possible. Currently only RESTCONF supports this mode of authentication. It shares all properties of external authentication, but instead of a username and password, it takes a token as input. The output is also almost the same, the only difference is that it is also expected to output a username.

If this feature is configured, NSO will invoke the executable configured in /ncs-config/aaa/external-validation/executable in ncs.conf , and pass the token on stdin using the string notation: "[token;]\n".

For example if user "bob" attempts to login over RESTCONF using the token "topsecret", and external validation is enabled, NSO will invoke the configured executable and write "[topsecret;]\n" on the stdin stream for the executable.

The task of the executable is then to validate the token, thereby authenticating the user and also establish the username and username-to-groups mapping.

For example the executable could be a FUSION client which utilizes some proprietary vendor attributes to retrieve the username and groups of the user from the FUSION server. If token validation is successful, the program should write "accept " followed by a space-separated list of groups the user is member of, and additional information as described below. Again, assuming that Bob's token indeed was "topsecret", and that Bob is member of the "admin" and the "lamers" groups, the program should write "accept admin lamers $uid $gid $supplementary_gids $HOME $USER\n" on its standard output and then exit.

Thus the format of the output from an "externalvalidation" program when token validation authentication is successful should be:

"accept $groups $uid $gid $supplementary_gids $HOME $USER\n"

Where

It is further possible for the program to return a new token on successful token validation authentication, by using "accept_token" instead of "accept":

"accept_token $groups $uid $gid $supplementary_gids $HOME $USER $token\n"

Where $token is an arbitrary string. NSO will then, for some northbound interfaces, include this token in responses.

It is also possible for the program to return additional information on successful token validation authentication, by using "accept_info" instead of "accept":

"accept_info $groups $uid $gid $supplementary_gids $HOME $USER $info\n"

Where $info is some arbitrary text. NSO will then just append this text to the generated audit log message (CONFD_EXT_LOGIN).

Yet another possibility is for the program to return a warning that the user's password is about to expire, by using "accept_warning" instead of "accept":

"accept_warning $groups $uid $gid $supplementary_gids $HOME $USER $warning\n"

Where $warning is an appropriate warning message. The message will be processed by NSO according to the setting of /ncs-config/aaa/expiration-warning in ncs.conf.

There is also support for token variations of "accept_info" and "accept_warning" namely "accept_token_info" and "accept_token_warning". Both "accept_token_info" and "accept_token_warning" expects the external program to output exactly the same as described above with the addition of a token after $USER:

"accept_token_info $groups $uid $gid $supplementary_gids $HOME $USER $token $info\n"

"accept_token_warning $groups $uid $gid $supplementary_gids $HOME $USER $token $warning\n"

If token validation authentication failed, the program should write "reject" or "abort", possibly followed by a reason for the rejection, and a trailing newline. For example "reject Bad password\n" or just "abort\n". The difference between "reject" and "abort" is that with "reject", NSO will try subsequent mechanisms configured for /ncs-config/aaa/validation-order in ncs.conf (if any), while with "abort", the token validation authentication fails immediately. Thus "abort" can prevent subsequent mechanisms from being tried. Currently the only available token validation authentication mechanism is the external one.

Supported by some nortbound APIs, such as JSONRPC and CLI over SSH, the external validation may also choose to issue a challenge:

"challenge $challenge-id $challenge-prompt\n"

For more information on multi factor authentication, see the

the section called “External multi factor authentication” section.

When username, password or token authentication is not enough, a challenge may be sent from any of the external authentication mechanisms to the user. A challenge consists of a challenge id and a base64 encoded challenge prompt, and a user is supposed to send a response to the challenge. Currently only JSONRPC and CLI over SSH supports multi factor authentication. Responses to challenges of multi factor authentication has the same output as the token authentication mechanism.

If this feature is configured, NSO will invoke the executable configured in /ncs-config/aaa/external-challenge/executable in ncs.conf , and pass the challenge id and response on stdin using the string notation: "[challenge-id;response;]\n".

For example a user "bob" has received a challenge from external authentication, external validation or external challenge and then attempts to login over JSONRPC with a response to the challenge using challenge id:"22efa",response:"ae457b". The external challenge mechanism is enabled, NSO will invoke the configured executable and write "[22efa;ae457b;]\n" on the stdin stream for the executable.

The task of the executable is then to validate the challenge id, response combination, thereby authenticating the user and also establish the username and username-to-groups mapping.

For example the executable could be a RADIUS client which utilizes some proprietary vendor attributes to retrieve the username and groups of the user from the RADIUS server. If challenge id, response validation is successful, the program should write "accept " followed by a space-separated list of groups the user is member of, and additional information as described below. Again, assuming that Bob's challenge id, response combination indeed was "22efa", "ae457b" and that Bob is member of the "admin" and the "lamers" groups, the program should write "accept admin lamers $uid $gid $supplementary_gids $HOME $USER\n" on its standard output and then exit.

Thus the format of the output from an "externalchallenge" program when challenge based authentication is successful should be:

"accept $groups $uid $gid $supplementary_gids $HOME $USER\n"

Where

It is further possible for the program to return a token on successful authentication, by using "accept_token" instead of "accept":

"accept_token $groups $uid $gid $supplementary_gids $HOME $USER $token\n"

Where $token is an arbitrary string. NSO will then, for some northbound interfaces, include this token in responses.

It is also possible for the program to return additional information on successful authentication, by using "accept_info" instead of "accept":

"accept_info $groups $uid $gid $supplementary_gids $HOME $USER $info\n"

Where $info is some arbitrary text. NSO will then just append this text to the generated audit log message (CONFD_EXT_LOGIN).

Yet another possibility is for the program to return a warning that the user's password is about to expire, by using "accept_warning" instead of "accept":

"accept_warning $groups $uid $gid $supplementary_gids $HOME $USER $warning\n"

Where $warning is an appropriate warning message. The message will be processed by NSO according to the setting of /ncs-config/aaa/expiration-warning in ncs.conf.

There is also support for token variations of "accept_info" and "accept_warning" namely "accept_token_info" and "accept_token_warning". Both "accept_token_info" and "accept_token_warning" expects the external program to output exactly the same as described above with the addition of a token after $USER:

"accept_token_info $groups $uid $gid $supplementary_gids $HOME $USER $token $info\n"

"accept_token_warning $groups $uid $gid $supplementary_gids $HOME $USER $token $warning\n"

If authentication failed, the program should write "reject" or "abort", possibly followed by a reason for the rejection, and a trailing newline. For example "reject Bad challenge response\n" or just "abort\n". The difference between "reject" and "abort" is that with "reject", NSO will try subsequent mechanisms configured for /ncs-config/aaa/challenge-order in ncs.conf (if any), while with "abort", the challenge response authentication fails immediately. Thus "abort" can prevent subsequent mechanisms from being tried. Currently the only available challenge response authentication mechanism is the external one.

Supported by some nortbound APIs, such as JSONRPC and CLI over SSH, the external challenge may also choose to issue a new challenge:

"challenge $challenge-id $challenge-prompt\n"

The Package Authentication functionality allows for packages to handle the NSO authentication in a customized fashion. Authentication data can e.g. be stored remotely, and a script in the package is used to communicate with the remote system.

Compared to external authentication, the Package Authentication mechanism allows specifying multiple packages to be invoked in the order they are appear in the configuration. NSO provides implementations for LDAP, SAMLv2, and TACACS+ protocols with packages available in $NCS_DIR/packages/auth/. Additionally, you can implement your own authentication packages as detailed below.

Authentication packages are NSO packages with the required content of an executable file scripts/authenticate. This executable basically follows the same API, and limitations, as the external auth script, but with a different input format and some additional functionality. Other than these requirements, it is possible to customize the package arbitrarily.

Package authentication is enabled by setting the ncs.conf options /ncs-config/aaa/package-authentication/enabled to true, and adding the package by name in the /ncs-config/aaa/package-authentication/packages list. The order of the configured packages is the order that the packages will be used when attempting to authenticate a user. See ncs.conf(5) in Manual Pages for details.

If this feature is configured in ncs.conf, NSO will for each configured package invoke script/authenticate, and pass username, password, original HTTP request (i.e. the user supplied "next" query parameter) HTTP request, HTTP headers, HTTP body, client source IP, client source port, northbound API context, and protocol on stdin using the string notation: "[user;password;orig_request;request;headers;body;src-ip;src-port;ctx;proto;]\n".

For example if an unauthenticated user attempts to start a single sign-on process over northbound HTTP based APIs with the cisco-nso-saml2-auth package, package authentication is enabled and configured with packages, and also single sign-on is enabled, NSO will, for each configured package, invoke the executable scripts/authenticate and write "[;;;R0VUIC9zc28vc2FtbC9sb2dpbi8gSFRUUC8xLjE=;;;127.0.0.1;59226;webui;https;]\n". on the stdin stream for the executable.

For clarity, the base64 decoded contents sent to stdin presented: "[;;;GET /sso/saml/login/ HTTP/1.1;;;127.0.0.1;54321;webui;https;]\n".

The task of the package is then to authenticate the user and also establish the username-to-groups mapping.

For example the package could support a SAMLv2 authentication protocol which communicates with an Identity Provider (IdP) for authentication. If authentication is successful, the program should write either "accept ", or "accept_username ", depending on if the authentication is started with username or if an external entity handles the entire authentication and supplies the username for a successful authentication. (SAMLv2 uses accept_username, since the IdP handles the entire authentication.) The "accept_username " is followed by a username and then followed by a space-separated list of groups the user is member of, and additional information as described below. If authentication is successful and the authenticated user Bob is member of the groups "admin" and "wheel", the program should write "accept_username bob admin wheel 1000 1000 100 /home/bob\n" on its standard output and then exit.

Thus the format of the output from a "packageauth" program when authentication is successful should be either the same as from "externalauth" (see the section called “External authentication”) or the following:

"accept_username $USER $groups $uid $gid $supplementary_gids $HOME\n"

Where

In addition to the "externalauth" API, the authentication packages can also return the following responses:

It is also possible for the program to return additional information on successful authentication, by using "accept_info" instead of "accept":

"accept_info $groups $uid $gid $supplementary_gids $HOME $info\n"

Where $info is some arbitrary text. NSO will then just append this text to the generated audit log message (NCS_PACKAGE_AUTH_SUCCESS).

Yet another possibility is for the program to return a warning that the user's password is about to expire, by using "accept_warning" instead of "accept":

"accept_warning $groups $uid $gid $supplementary_gids $HOME $warning\n"

Where $warning is an appropriate warning message. The message will be processed by NSO according to the setting of /ncs-config/aaa/expiration-warning in ncs.conf.

If authentication fails, the program should write "reject" or "abort", possibly followed by a reason for the rejection, and a trailing newline. For example "reject 'Bad password'\n" or just "abort\n". The difference between "reject" and "abort" is that with "reject", NSO will try subsequent mechanisms configured for /ncs-config/aaa/auth-order, and packages configured for /ncs-config/aaa/package-authentication/packages in ncs.conf (if any), while with "abort", the authentication fails immediately. Thus "abort" can prevent subsequent mechanisms from being tried, but when external authentication is the last mechanism (as in the default order), it has the same effect as "reject".

When package authentication is used, the group list returned by the package executable is prepended by any possible group information stored locally under the /aaa tree. Hence when package authentication is used, it is indeed possible to have the entire /aaa/authentication tree empty. The group assignment performed by the external program will still be valid and the relevant groups will be used by NSO when the authorization rules are checked.

The tailf-acm.yang module augments the rule-list entry in ietf-netconf-acm.yang with a cmdrule list:

augment /nacm:nacm/nacm:rule-list {

  list cmdrule {
    key "name";
    ordered-by user;
    description
      "One command access control rule. Command rules control access
       to CLI commands and Web UI functions.

       Rules are processed in user-defined order until a match is
       found.  A rule matches if 'context', 'command', and
       'access-operations' match the request.  If a rule
       matches, the 'action' leaf determines if access is granted
       or not.";

    leaf name {
      type string {
        length "1..max";
      }
      description
        "Arbitrary name assigned to the rule.";
    }

    leaf context {
      type union {
        type nacm:matchall-string-type;
        type string;
      }
      default "*";
      description
        "This leaf matches if it has the value '*' or if its value
         identifies the agent that is requesting access, i.e. 'cli'
         for CLI or 'webui' for Web UI.";
    }

    leaf command {
      type string;
      default "*";
      description
        "Space-separated tokens representing the command. Refer
         to the Tail-f AAA documentation for further details.";
    }

    leaf access-operations {
      type union {
        type nacm:matchall-string-type;
        type nacm:access-operations-type;
      }
      default "*";
      description
        "Access operations associated with this rule.

         This leaf matches if it has the value '*' or if the
         bit corresponding to the requested operation is set.";
    }

    leaf action {
      type nacm:action-type;
      mandatory true;
      description
        "The access control action associated with the
         rule.  If a rule is determined to match a
         particular request, then this object is used
         to determine whether to permit or deny the
         request.";
    }

    leaf log-if-permit {
      type empty;
      description
        "If this leaf is present, access granted due to this rule
         is logged in the developer log. Otherwise, only denied
         access is logged. Mainly intended for debugging of rules.";
    }

    leaf comment {
      type string;
      description
        "A textual description of the access rule.";
    }
  }
}

Each rule has seven leafs. The first is the name list key, the following three leafs are matching leafs. When NSO tries to run a command it tries to match the command towards the matching leafs and if all of context, command, and access-operations match, the fifth field, i.e. the action, is applied.

For the rule processing to be written to the devel log, the /ncs-config/logs/developer-log-level entry in ncs.conf must be set to trace.

If no matching rule is found in any of the cmdrule lists in any rule-list entry that matches the user's groups, this augmentation from tailf-acm.yang is relevant:

augment /nacm:nacm {
  leaf cmd-read-default {
    type nacm:action-type;
    default "permit";
    description
      "Controls whether command read access is granted
       if no appropriate cmdrule is found for a
       particular command read request.";
  }

  leaf cmd-exec-default {
    type nacm:action-type;
    default "permit";
    description
      "Controls whether command exec access is granted
       if no appropriate cmdrule is found for a
       particular command exec request.";
  }

  leaf log-if-default-permit {
    type empty;
    description
      "If this leaf is present, access granted due to one of
       /nacm/read-default, /nacm/write-default, or /nacm/exec-default
       /nacm/cmd-read-default, or /nacm/cmd-exec-default
       being set to 'permit' is logged in the developer log.
       Otherwise, only denied access is logged. Mainly intended
       for debugging of rules.";
  }
}

If access is permitted due to one of these default leafs, the /nacm/log-if-default-permithas the same effect as the log-if-permit leaf for the cmdrule lists.

The rules in the rule list are used to control access to rpc operations, notifications, and data nodes defined in YANG models. Access to invocation of actions (tailf:action) is controlled with the same method as access to data nodes, with a request for "exec" access. ietf-netconf-acm.yang defines a rule entry as:

list rule {
  key "name";
  ordered-by user;
  description
    "One access control rule.

     Rules are processed in user-defined order until a match is
     found.  A rule matches if 'module-name', 'rule-type', and
     'access-operations' match the request.  If a rule
     matches, the 'action' leaf determines if access is granted
     or not.";

  leaf name {
    type string {
      length "1..max";
    }
    description
      "Arbitrary name assigned to the rule.";
  }

  leaf module-name {
    type union {
      type matchall-string-type;
      type string;
    }
    default "*";
    description
      "Name of the module associated with this rule.

       This leaf matches if it has the value '*' or if the
       object being accessed is defined in the module with the
       specified module name.";
  }
  choice rule-type {
    description
      "This choice matches if all leafs present in the rule
       match the request.  If no leafs are present, the
       choice matches all requests.";
    case protocol-operation {
      leaf rpc-name {
        type union {
          type matchall-string-type;
          type string;
        }
        description
          "This leaf matches if it has the value '*' or if
           its value equals the requested protocol operation
           name.";
      }
    }
    case notification {
      leaf notification-name {
        type union {
          type matchall-string-type;
          type string;
        }
        description
          "This leaf matches if it has the value '*' or if its
           value equals the requested notification name.";
      }
    }
    case data-node {
      leaf path {
        type node-instance-identifier;
        mandatory true;
        description
          "Data Node Instance Identifier associated with the
           data node controlled by this rule.

           Configuration data or state data instance
           identifiers start with a top-level data node.  A
           complete instance identifier is required for this
           type of path value.

           The special value '/' refers to all possible
           data-store contents.";
      }
    }
  }

  leaf access-operations {
    type union {
      type matchall-string-type;
      type access-operations-type;
    }
    default "*";
    description
      "Access operations associated with this rule.

       This leaf matches if it has the value '*' or if the
       bit corresponding to the requested operation is set.";
  }

  leaf action {
    type action-type;
    mandatory true;
    description
      "The access control action associated with the
       rule.  If a rule is determined to match a
       particular request, then this object is used
       to determine whether to permit or deny the
       request.";
  }

  leaf comment {
    type string;
    description
      "A textual description of the access rule.";
  }
}

tailf-acm augments this with two additional leafs:

augment /nacm:nacm/nacm:rule-list/nacm:rule {

  leaf context {
    type union {
      type nacm:matchall-string-type;
      type string;
    }
    default "*";
    description
      "This leaf matches if it has the value '*' or if its value
       identifies the agent that is requesting access, e.g. 'netconf'
       for NETCONF, 'cli' for CLI, or 'webui' for Web UI.";

  }

  leaf log-if-permit {
    type empty;
    description
      "If this leaf is present, access granted due to this rule
       is logged in the developer log. Otherwise, only denied
       access is logged. Mainly intended for debugging of rules.";
  }
}

Similar to the command access check, whenever a user through some agent tries to access an rpc, a notification, a data item, or an action, access is checked. For a rule to match, three or four leafs must match and when a match is found, the corresponding action is taken.

We have the following leafs in the rule list entry.

If no matching rule is found in any of the rule lists in any rule-list entry that matches the user's groups, the data model node for which access is requested is examined for presence of the NACM extensions:

If examination of the NACM extensions did not result in access being denied, the value (permit or deny) of the relevant default leaf is examined:

If access is permitted due to one of these default leafs, this augmentation from tailf-acm.yang is relevant:

augment /nacm:nacm {
  ...
  leaf log-if-default-permit {
    type empty;
    description
      "If this leaf is present, access granted due to one of
       /nacm/read-default, /nacm/write-default, /nacm/exec-default
       /nacm/cmd-read-default, or /nacm/cmd-exec-default
       being set to 'permit' is logged in the developer log.
       Otherwise, only denied access is logged. Mainly intended
       for debugging of rules.";
  }
}

I.e. it has the same effect as the log-if-permit leaf for the rule lists, but for the case where the value of one of the default leafs permits the access.

When NSO executes a command, the command rules in the authorization database are searched, The rules are tried in order, as described above. When a rule matches the operation (command) that NSO is attempting, the action of the matching rule is applied - whether permit or deny.

When actual data access is attempted, the data rules are searched. E.g. when a user attempts to execute delete aaa in the CLI, the user needs delete access to the entire tree /aaa.

Another example is if a CLI user writes show configuration aaa TAB it suffices to have read access to at least one item below /aaa for the CLI to perform the TAB completion. If no rule matches or an explicit deny rule is found, the CLI will not TAB complete.

Yet another example is if a user tries to execute delete aaa authentication users, we need to perform a check on the paths /aaa and /aaa/authentication before attempting to delete the sub tree. Say that we have a rule for path /aaa/authentication/users which is an permit rule and we have a subsequent rule for path /aaa which is a deny rule. With this rule set the user should indeed be allowed to delete the entire /aaa/authentication/users tree but not the /aaa tree nor the /aaa/authentication tree.

We have two variations on how the rules are processed. The easy case is when we actually try to read or write an item in the configuration database. The execution goes like:

foreach rule {
    if (match(rule, path)) {
       return rule.action;
    }
}

The second case is when we execute TAB completion in the CLI. This is more complicated. The execution goes like:

rules = select_rules_that_may_match(rules, path);
if (any_rule_is_permit(rules))
    return permit;
else
    return deny;

The idea being that as we traverse (through TAB) down the XML tree, as long as there is at least one rule that can possibly match later, once we have more data, we must continue.

For example assume we have:

If we in the CLI stand at "/system/config" and hit TAB we want the CLI to show foo as a completion, but none of the other nodes that exist under /system/config. Whereas if we try to execute delete /system/config the request must be rejected.

By default, NACM rules are configured for entire tailf:action or YANG 1.1 action statements, but not for input statement child leafs. To override this behaviour, and enable NACM rules on input leafs, set the following parameter to 'true': /ncs-config/aaa/action-input-rules/enabled. When enabled all action input leafs given to an action will be validated for NACM rules. If broad 'deny' NACM rules are used, you might need to add 'permit' rules for the affected action input leafs to allow actions to be used with parameters.

By design NACM rules are ignored for changes done by services - FASTMAP, Reactive FASTMAP, or Nano services. The reasoning behind this is that a service package can be seen as a controlled way to provide limited access to devices for a user group that is not allowed to apply arbitrary changes on the devices.

However, there are NSO installations where this behavior is not desired, and NSO administrators want to enforce NACM rules even on changes done by services. For this purpose, the leaf called /nacm/enforce-nacm-on-services is provided. By default, it is set to false.

Note however that currently, even with this leaf set to true, there are limitations. Namely, the post-actions for nano-services are run in a user session without any access checks. Besides that, NACM rules are not enforced on the read operations performed in the service callbacks.

It might be desirable to deny everything for a user group and only allow access to a specific service. This pattern could be used to allow an operator to provision the service, but deny everything else. While this pattern works for a normal FASTMAP service, there are some caveats for stacked services, Reactive FASTMAP and Nano services. For these kinds of services, in addition to the service itself, access should be provided to the user group for the following paths:

In deployments with many devices it can become cumbersome to handle data authorization per device. To help with this there is a rule type that works on device group membership (for more on device groups, see the section called “Device Groups” in User Guide). To do this, devices are added to different device-groups and the rule type device-group-rule is used.

The IETF NACM rule type is augmented with a new rule type named device-group-rule which contains a leafref to the device-groups. See Example 2, “Device Group model augmentation”.

augment "/nacm:nacm/nacm:rule-list/nacm:rule/nacm:rule-type" {
  case device-group-rule {
    leaf device-group {
      type leafref {
        path "/ncs:devices/ncs:device-group/ncs:name";
      }
      description
        "Which device group this rule applies to.";
    }
  }
}

In Example 3, “Device group configuration” we configure two device-groups based on different regions, and add devices to them.

<devices>
  <device-group>
    <name>us_east</name>
    <device-name>cli0</device-name>
    <device-name>gen0</device-name>
  </device-group>
  <device-group>
    <name>us_west</name>
    <device-name>nc0</device-name>
  </device-group>
</devices>

In Example 4, “NACM group configuration” we configure an operator for the us_east region:

<nacm>
  <groups>
    <group>
      <name>us_east</name>
      <user-name>us_east_oper</user-name>
    </group>
  </groups>
</nacm>

In Example 5, “Device Group Authorization rules” we configure the device group rules and refer to the device group and the us_east group.

<nacm>
  <rule-list>
    <name>us_east</name>
    <group>us_east</group>
    <rule>
      <name>us_east_read_permit</name>
      <device-group xmlns="http://tail-f.com/yang/ncs-acm/device-group-authorization">us_east</device-group>
      <access-operations>read</access-operations>
      <action>permit</action>
    </rule>
    <rule>
      <name>us_east_create_permit</name>
      <device-group xmlns="http://tail-f.com/yang/ncs-acm/device-group-authorization">us_east</device-group>
      <access-operations>create</access-operations>
      <action>permit</action>
    </rule>
    <rule>
      <name>us_east_update_permit</name>
      <device-group xmlns="http://tail-f.com/yang/ncs-acm/device-group-authorization">us_east</device-group>
      <access-operations>update</access-operations>
      <action>permit</action>
    </rule>
    <rule>
      <name>us_east_delete_permit</name>
      <device-group xmlns="http://tail-f.com/yang/ncs-acm/device-group-authorization">us_east</device-group>
      <access-operations>delete</access-operations>
      <action>permit</action>
    </rule>
  </rule-list>
</nacm>

In summary device group authorization gives a more compact configuration for deployments where devices can be grouped and authorization can be done on a device group basis.

Modifications on the device-group subtree is recommended to be controlled by a limited set of users.

Assume that we have two groups, admin and oper. We want admin to be able to see and and edit the XML tree rooted at /aaa, but we do not want users that are members of the oper group to even see the /aaa tree. We would have the following rule-list and rule entries. Note, here we use the XML data from tailf-aaa.yang to exemplify. The examples apply to all data, for all data models loaded into the system.

<rule-list>
  <name>admin</name>
  <group>admin</group>
  <rule>
    <name>tailf-aaa</name>
    <module-name>tailf-aaa</module-name>
    <path>/</path>
    <access-operations>read create update delete</access-operations>
    <action>permit</action>
  </rule>
</rule-list>
<rule-list>
  <name>oper</name>
  <group>oper</group>
  <rule>
    <name>tailf-aaa</name>
    <module-name>tailf-aaa</module-name>
    <path>/</path>
    <access-operations>read create update delete</access-operations>
    <action>deny</action>
  </rule>
</rule-list>

If we do not want the members of oper to be able to execute the NETCONF operation edit-config, we define the following rule-list and rule entries:

<rule-list>
  <name>oper</name>
  <group>oper</group>
  <rule>
    <name>edit-config</name>
    <rpc-name>edit-config</rpc-name>
    <context xmlns="http://tail-f.com/yang/acm">netconf</context>
    <access-operations>exec</access-operations>
    <action>deny</action>
  </rule>
</rule-list>

To spell it out, the above defines four elements to match. If NSO tries to perform a netconf operation, which is the operation edit-config, and the user which runs the command is member of the oper group, and finally it is an exec (execute) operation, we have a match. If so, the action is deny.

The path leaf can be used to specify explicit paths into the XML tree using XPath syntax. For example the following:

<rule-list>
  <name>admin</name>
  <group>admin</group>
  <rule>
    <name>bob-password</name>
    <path>/aaa/authentication/users/user[name='bob']/password</path>
    <context xmlns="http://tail-f.com/yang/acm">cli</context>
    <access-operations>read update</access-operations>
    <action>permit</action>
  </rule>
</rule-list>

Explicitly allows the admin group to change the password for precisely the bob user when the user is using the CLI. Had path been /aaa/authentication/users/user/password the rule would apply to all password elements for all users. Since the path leaf completely identifies the nodes that the rule applies to, we do not need to give tailf-aaa for the module-name leaf.

NSO applies variable substitution, whereby the username of the logged in user can be used in a path. Thus:

<rule-list>
  <name>admin</name>
  <group>admin</group>
  <rule>
    <name>user-password</name>
    <path>/aaa/authentication/users/user[name='$USER']/password</path>
    <context xmlns="http://tail-f.com/yang/acm">cli</context>
    <access-operations>read update</access-operations>
    <action>permit</action>
  </rule>
</rule-list>

The above rule allows all users that are part of the admin group to change their own passwords only.

A member of oper is able to execute NETCONF operation action if that member has exec access on NETCONF RPC action operation, read access on all instances in the hierarchy of data nodes that identifies the specific action in the datastore, and exec access on the specific action. For example an action is defined as below.

container test {
  action double {
    input {
      leaf number {
        type uint32;
      }
    }
    output {
      leaf result {
        type uint32;
      }
    }
  }
}

To be able to execute double action through NETCONF RPC, the members of oper need the following rule-list and rule-entries.

<rule-list>
  <name>oper</name>
  <group>oper</group>

  <rule>
    <name>allow-netconf-rpc-action</name>
    <rpc-name>action</rpc-name>
    <context xmlns="http://tail-f.com/yang/acm">netconf</context>
    <access-operations>exec</access-operations>
    <action>permit</action>
  </rule>
  <rule>
    <name>allow-read-test</name>
    <path>/test</path>
    <access-operations>read</access-operations>
    <action>permit</action>
  </rule>
  <rule>
    <name>allow-exec-double</name>
    <path>/test/double</path>
    <access-operations>exec</access-operations>
    <action>permit</action>
  </rule>
</rule-list>

Or, a simpler rule set as the following.

<rule-list>
  <name>oper</name>
  <group>oper</group>

  <rule>
    <name>allow-netconf-rpc-action</name>
    <rpc-name>action</rpc-name>
    <context xmlns="http://tail-f.com/yang/acm">netconf</context>
    <access-operations>exec</access-operations>
    <action>permit</action>
  </rule>
  <rule>
    <name>allow-exec-double</name>
    <path>/test</path>
    <access-operations>read exec</access-operations>
    <action>permit</action>
  </rule>
</rule-list>

Finally if we wish members of the oper group to never be able to execute the request system reboot command, also available as a reboot NETCONF rpc, we have:

<rule-list>
  <name>oper</name>
  <group>oper</group>

  <cmdrule xmlns="http://tail-f.com/yang/acm">
    <name>request-system-reboot</name>
    <context>cli</context>
    <command>request system reboot</command>
    <access-operations>exec</access-operations>
    <action>deny</action>
  </cmdrule>

  <!-- The following rule is required since the user can -->
  <!-- do "edit system" -->

  <cmdrule xmlns="http://tail-f.com/yang/acm">
    <name>request-reboot</name>
    <context>cli</context>
    <command>request reboot</command>
    <access-operations>exec</access-operations>
    <action>deny</action>
  </cmdrule>

  <rule>
    <name>netconf-reboot</name>
    <rpc-name>reboot</rpc-name>
    <context xmlns="http://tail-f.com/yang/acm">netconf</context>
    <access-operations>exec</access-operations>
    <action>deny</action>
  </rule>

</rule-list>

Debugging the AAA rules can be hard. The best way to debug rules that behave unexpectedly is to add the log-if-permit leaf to some or all of the rules that have action permit. Whenever such a rule triggers a permit action, an entry is written to the developer log.

Finally it is worth mentioning that when a user session is initially created it will gather the authorization rules that are relevant for that user session and keep these rules for the life of the user session. Thus when we update the AAA rules in e.g. the CLI the update will not apply to the current session - only to future user sessions.