- Revision History
- About this Manual
- Scope
- Definitions/Abbreviations
- 1 Feature Overview
- 2 Functionality
- 3 Design
- 4 Flow Diagrams
- 5 Error Handling
- 6 Serviceability and Debug
- 7 Warm Boot Support
- 8 Scalability
- 9 Unit Test
| Rev | Date | Author | Change Description |
|---|---|---|---|
| 0.1 | 04/07/2020 | Nirenjan Krishnan | Initial version |
| 0.2 | 06/12/2020 | Nirenjan Krishnan | Update with review comments |
This document provides a high-level design approach for authentication and RBAC in the SONiC Management Framework.
TBD
| Term | Meaning |
|---|---|
| RBAC | Role-Based Access Control |
| AAA | Authentication, Authorization, Accounting |
| CLI | Command-Line Interface |
| REST | REpresentational State Transfer |
| gNMI | gRPC Network Management Interface |
| NBI | North-bound Interfaces (CLI, REST, gNMI) |
| HAM | Host Account Manager |
- For RBAC, the roles will be defined in the configuration database. Initially, two roles will be supported; admin (with read/write privileges), and operator (with read-only privileges); however, it shall be possible for the users with admin role to define additional roles.
- HAM will become the single source of truth for user management on SONiC systems.
- Local user management: CLIs and APIs for creating and managing local users on the system -- their usernames, passwords, and roles.
- Authentication control: CLIs and APIs to modify the allowed authentication modes on the REST and gNMI interfaces.
- CLI authentication mechanisms to REST server.
A variety of authentication methods must be supported:
- CLI authentication is handled via user detection on the Unix Socket.
- REST authentication
- Password-based Authentication
- JWT token-based authentication
- Certificate-based Authentication
- gNMI Authentication
- Password-based Authentication
- JWT token-based authentication
- Certificate-based Authentication
Given that the CLI module works by issuing REST transactions to the Management Framework's REST server, the CLI module must also be able to authenticate with the REST server when REST authentication is enabled. This can be accomplished via the following steps:
- KLISH must be launched as the corresponding user
- This is performed by the
-uargument todocker exec
- This is performed by the
- REST will listen in on a Unix socket. Listener will detect the user at the remote end of the connection, and use that for authentication/authorization.
- The REST server will authenticate the user and return a token with the username and role encoded in it. The KLISH CLI must cache this token and use it for all future requests from this KLISH session. The REST server will validate this token to username/role mapping with it so as to identify all future requests as well. This will also allow the REST server in creating audit logs for all the requests sent from KLISH, as well as pass the username and role to Translib for RBAC enforcement.
- KLISH CLI session will store the authentication token, and from then on, KLISH CLI will send REST requests using the persistent connection with the authentication token in the HTTP header to the REST server for all the CLI commands.
- The KLISH session must be able to cleanly handle ctrl-c breaks while it is busy waiting on a response from the REST server.
- When the user exits the KLISH CLI session, the HTTP persistent connection is closed. The REST server will clean up the corresponding authentication token for its corresponding KLISH CLI Client.
The CLI shall provide commands to modify the authentication methods of both the REST and gNMI interfaces.
Roles will not have a direct map to a primary Linux group, however, supplementary groups are used to allow access to additional functionalities.
adminusers will be added tosudoanddockergroupsoperatorusers will be added todockergroup only.- All non-admin users will be added to the
dockergroup only.
The default shell for all users is set to a script. This script will determine
if the user is a member of the admin group, and if so, drop them into a Bash
shell, otherwise, it will spawn KLISH to drop them into the CLI. Non-admin users
will only have access to the CLI and not be able to access Bash. Users cannot
run system commands from KLISH.
This is planned for future support.
Admin users shall be able to create customizable roles for further granularity beyond read-only and read-write. For instance, a secadmin role shall allow the users to configure security parameters on the switch. The custom role shall have a default deny policy. Custom roles shall map a set of features, and their access level to the feature. A feature is a set of YANG paths. The default policy is no access to a feature, if it is not specified in the role.
[
{
"name": "secadmin",
"features": [
{
"feature": "aaa",
"access": "rw"
},
{
"feature": "net",
"access": "ro"
}
]
}
]
Features map to a set of YANG paths. The features are saved in the ResourceTable, but a default feature set is defined in the system to allow users to start from a known state. Sample feature description is shown below.
[
{
"name": "aaa",
"paths": [
"openconfig-system:system/aaa/authentication/users/user={username}",
"openconfig-system:system/aaa/authentication/users"
]
},
{
"name": "net",
"paths": [
"openconfig-net:net/xyz"
]
}
]
An interface must be developed for local user management, so that administrators can add users and assign passwords and roles to them. Administrators with the appropriate role must be able to add/delete users, modify user passwords, and modify user roles. They must be able to do so through all of the NBIs, meaning that a YANG model and CLI tree must be developed.
Users must be added to the Linux database (/etc/passwd, /etc/group, and optionally /etc/shadow). That's where a user is mapped to a Linux User Identifier (UID) and primary Group Identifier (GID). When users are created they also need to be assigned roles. Roles are defined in the REDIS database. Users may also be assigned to supplementary Linux groups (/etc/group) in order to allow functionality required for their roles (e.g. Docker group membership in order to spawn the CLI).
Since these operations (i.e. creating Linux users, assigning roles, supplementary groups, etc.) are non-trivial, the process of creating users will be entrusted to the Host Account Management Daemon (hamd).
The hamd process runs on the host. It is accessed via a DBus interface that provides the ability to access and/or modify the host's Linux database (/etc/passwd, /etc/group, and optionally /etc/shadow). Since DBus is a secured interface we can control which processes will be allowed to access hamd.
The hamd process will provide the following APIs to create/modify/delete user and group (role) accounts:
- useradd: To create new users (similar to GNU useradd)
- userdel: To delete a user (similar to GNU userdel)
- passwd: To change a user password (similar to GNU passwd)
- setroles: To set a user's roles (similar to GNU usermod)
- groupadd: To create new groups/roles (similar to GNU groupadd)
- groupdel: To delete groups/roles (similar to GNU groupdel)
- usermod: To create or modify users. This method will accept a username, hashed password, and a list of strings corresponding to the roles.
The hamd process will add the users to the User Table in the Config DB.
In addition to providing APIs to create/modify/delete user and group (role) accounts, hamd also provides APIs to simply read user and group (role) accounts. Here's the list:
- getpwnam: To retrieve user credentials (similar to POSIX getpwnam)
- getpwuid: To retrieve user credentials (similar to POSIX getpwuid)
- getgrnam: To retrieve group/role credentials (similar to POSIX getgrnam)
- getgrgid: To retrieve group/role credentials (similar to POSIX getgrgid)
These APIs, however, are meant to be invoked through NSS (name service switch). That is, applications running in containers can simply continue invoking the standard POSIX APIs (getpwnam(), getgrnam(), etc) and a Host Account Management NSS module will ensure that the credentials get retrieved from hamd running on the host. The HAM NSS module (libnss_ham.so.2) need be installed and configured (/etc/nsswitch.conf) in the containers that require access to the host's Linux database.
Local users are managed via all the NBIs, i.e., CLI, REST and gNMI. The admin users may also create or modify local users from the Bash shell. All requests will be proxied to HAM to perform the actual user management.
- Translib will cache all the user information along with the privilege and resource information to avoid the overhead of querying them every time we receive a request.
- Will rely on notification to update any change in the user information, privilege or resource information
N/A
The Translib code (in sonic-mgmt-common) will be modified to support RBAC via Roles, rather than Groups. It will receive username data from the REST/gNMI NBIs and perform the role lookup for a given user.
Translib shall cache the user table and role list to amortize the cost of a database lookup over several transactions.
SONiC Management Framework, gNMI Telemetry containers
N/A
Enterprise networks that enforce authentication for their management interfaces.
This feature enables authentication and Role-Based Access Control (RBAC) on the REST and gNMI programmatic interfaces that are provided by the SONiC Management Framework and Telemetry containers. With respect to authentication, these programmatic interfaces will support password-based authentication with tokens, and certificate-based authentication.
Since the Klish CLI in the management framework communicates with the REST server in the back-end, the solution will also be extended to support CLI authentication to REST server.
RBAC will be enforced centrally in the management framework, so that users accessing the system through varying interfaces will be limited to the same, consistent set of operations and objects depending on their role. Users' roles will be mapped using Linux Groups.
Users and their role assignments may be managed via the NBIs. HAM shall provide tools to allow administrators to manage the users and roles from the shell using the hamctl command.
-
UserTable
This table contains the username to role mapping needed for enforcing the authorization checks. It has the following columns :
- user : This is the username being authorized. This is a string.
- tenant : This contains the tenant with which the user is associated. This is a string
- role : This specifies the role associated with the username in the tenant. This is a comma separated list of strings. The UserTable is keyed on <user, tenant>.
Future Support
-
PrivilegeTable
This table provides the information about the type of operations that a particular role is authorized to perform. The authorization can be performed at the granularity of a feature, feature group, or the entire system. The table has the following columns :
- role : The role associated with the user that is being authorized. This is a string.
- feature : This is feature that the role is being authorized to access. The granularity of the feature can be :
- feature - A logical grouping of multiple commands. If the user is authorized to access a particular feature, the column contains the tag associated with that feature.
- entire-system - If the user is being granted access to the entire system, the column contains all
- permissions : Defines the permissions associated with the role. This is a string.
- none - This is the default permissions that a role is created with. A role associated with none permission cannot access any resources on the system to read, or to modify them.
- read-only - The role only has read access to the resources associated with the feature.
- read-write - The role has permissions to read and write (create, modify and delete) the resources associated with the feature. The PrivilegeTable is keyed on <role, feature>
-
ResourceTable Though the resources are statically tagged with the features that they belong to, a ResourceTable is still needed so as to allow for future extensibility. It is possible that in the future, a customer wants a more granular control over the authorization and wants to either sub partition the features or override the default tagging associated with a feature. The ResourceTable will allow for this support in the future. In the Phase 2, this table will be create using the default tagging associated with the resources.
- resource : The xpath associated with the resource being accessed. This is a string.
- feature-name : The tag of the feature this resource belongs to. The ResourceTable is keyed on <resource, feature>
-
TenantTable (To be implemented in Phase 3 or when Multi-tenancy is introduced) In most systems today, a single SONiC system will serve multiple tenants. A tenant is a group of users who have a different privileges for resource instances. As SONiC becomes multitenant, RBAC needs to account for this when authorizing users. The TenantTable is needed to enable this and has the following columns :
- resource : The xpath associated with the resource being accessed. This is a string.
- tenant : The tenant for which the resource partitioning is being done. This is a string.
- instances : The instances of the resource allocated to this tenant. This is a list of instances. The TenantTable is keyed on <resource, tenant>
N/A
N/A
N/A
N/A
N/A
N/A
N/A. HAM is going to be the single source of truth, and it will take care of synchronizing the User Table and /etc/passwd
N/A
Users can be configured using OpenConfig models:
module: openconfig-system
+--rw system
+--rw aaa
+--rw authentication
+--rw users
Users may be managed via Linux tools like sonic-useradd, sonic-usermod, passwd, etc. They may also be managed via configuration.
username <name> password <password-string> role <role-string> -- Configures a user on the system with a given name, password, and role.
- name is a text string of 1-32 alphanumeric characters
- password-string is a text string of 1-32 alphanumeric characters
- role-string is a text string consisting of a role name. In the initial release, the user is recommended to use "admin" and "operator" roles, as other roles will not be supported. A text string is desired instead of keywords so that in the future, more roles may be implemented and expanded.
- Configuring another a user with the same name results in modification of the existing user.
no username <name> -- Deletes a user from the system.
- name is a text string of 1-32 alphanumeric characters
aaa authentication {rest-server | gnmi-server} {[password] [token] [certificate]}
aaa authentication {rest-server | gnmi-server} certificate no-authorization
no aaa authentication {rest-server | gnmi-server}
The certificate no-authorization mode will force users to authenticate via
certificate, however, there will be no role lookup performed. All authenticated
users will be treated as having full administrator access.
The no aaa ... command will disable authentication altogether, and will allow
all users to execute admin level commands via the REST/gNMI interfaces. The CLI
however, will still require a valid password based login, due to it being
accessed via SSH.
userrole <name> - Creates a new custom role and enters userrole config to
enable/disable individual features.
(config-userrole)# feature <feat-name> {read-only | read-write} - Enable
feature <feat-name> with read-only or read-write access.
(config-userrole)# no feature <feat-name> - Disable access to feature
<feat-name>.
no userrole <name> - Deletes a user role from the system.
show users
This will display a list of configured users on the system.
show roles
This will display a list of configured roles on the system.
N/A
N/A
Ability to configure local users via REST API.
N/A
The REST server should return standard HTTP errors when authentication fails or if the user tries to access a forbidden resource or perform an unauthorized activity.
The gNMI server should return standard gRPC errors when authentication fails.
Authentication will be handled by user detection on Unix sockets. However, the CLI must gracefully handle authorization failures from the REST server. While the CLI will render all of the available commands to a user, the user will actually only be able to execute a subset of them. This limitation is a result of the design decision to centralize RBAC in Translib. Nevertheless, the CLI must inform the user when they attempt to execute an unauthorized command.
Translib will authorize the user and when the authorization fails will return appropriate error string to the REST/gNMI server. Translib will also log an audit message with the username and the command that was attempted.
If a user authenticates but is not part of one of the pre-defined roles, they will not be allowed to do anything at all on the system.
All operations performed by NBIs (CLI commands, REST/gNMI operations) should be logged/audited with usernames attached to the given operation(s) performed.
Initially, users who are remotely authenticated will share a common role-specific username, so there will be a limitation here.
N/A
See previous section 1.1.3: Scalability Requirements
| Test Case | Description |
|---|---|
| REST with password | Authenticate to REST server with username/password and perform some operations |
| REST with token | Perform subsequent operations with token, ensure username/password are not re-prompted |
| REST authorized RBAC | Perform authorized operations as both Admin and Operator via REST |
| REST unauthorized RBAC | Attempt unauthorized operations as both Admin and Operator via REST |
| CLI with password | SSH to the system with username/password and execute some commands |
| CLI with RSA | SSH to the system with pubkey and execute some commands |
| CLI authorized RBAC | SSH to the system and perform authorized commands |
| CLI unauthorized RBAC | SSH to the system and perform unauthorized commands |
| RBAC no-group | Create a user and assign them to a non-predefined group; make sure they can't perform any operations |
| gNMI authentication | Test the same authentication methods as REST, but for gNMI instead |
| gNMI authorization | Test the same authorization as REST, but for gNMI instead |