Download PDF

1. Overview

The Securing Management Plane feature provides the capability to restrict the access to the management plane only to authenticated and authorized subjects.

The authentication identifies a subject, and the authorization validates if the subject is allowed to execute the action.

sec mgmt dataflow
Figure 1. External Dataflow

The figure-1 shows the data flow when accessing an rtbrick-switch. Each call against the switch in more detail against the API Gateway Daemon (APIGWD) of the switch has to be authenticated with an access token. There is only one exception when accessing the CTLRD’s UI; it is possible to be redirected to an OpenIDConnect Authenticator.

The APIGWD validates the access token against an JSON Web Key Set (JWKS) ( This key set can be loaded from a file locally on the system or auto discovered via the OpenIDConnect server.

A valid access token, in the sense of syntactically correct but also successfully validated signature by one of the JSON Web Key of the JWKS files, leads in an authenticated user. If the validation is unsuccessful, the call will be rejected.

The access token contains scopes which are used internally for the authorization checks. The authorization is a role based authorization where the scopes equal to the roles.

Internally the access token is converted to an RtBrick token, and all the communications inside the switch is authenticated via this RtBrick token.

The dataflow inside of the switch can be seen in Figure 2.

The scopes of the access token are copied to the RtBrick Token.

sec mgmt internal flow
Figure 2. Internal Dataflow

1.1. Supported Platforms

Not all features are necessarily supported on each hardware platform. Refer to the Platform Guide for the features and the sub-features that are or are not supported by each platform.

2. RtBrick Token

2.1. JSON Web Tokens

JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object.

This information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret (with the HMAC algorithm) or a public/private key pair using RSA or ECDSA.

Note RFC and draft compliance are partial except as specified.

For more information about JSON Web Token, see

2.1.1. Structure

In its compact form, JSON Web Tokens consist of three parts separated by dots (.), which are:

  • Header

  • Payload

  • Signature

Therefore, a JWT typically looks like the following.

xxxxx.yyyyy.zzzzz Header

The header typically consists of two parts:

  • The type of the token, which is JWT

  • The signing algorithm that is being used, such as HMAC SHA256 or RSA

The suite of specifications on JWT provisions a few different options to identify particular cryptographic keys. The most straightforward mechanism is the "kid" claim. This claim can be added to the header of the token. It is intended to contain a string-based key identifier.

For example:

  "alg": "HS256",
  "typ": "JWT",
  "kid": "0815"

Then, this JSON is Base64Url encoded to form the first part of the JWT. Payload

The second part of the token is the payload, which contains the claims. Claims are statements about an entity (typically, the user) and additional data.

There are three types of claims:

  • registered

  • public

  • private

    Registered claims

    These are a set of predefined claims which are not mandatory but recommended, to provide a set of useful, interoperable claims. Some of them are: iss (issuer), exp (expiration time), sub (subject), aud (audience), and others.

    Public claims

    These can be defined at will by those using JWTs. But to avoid collisions they should be defined in the IANA JSON Web Token Registry or be defined as a URI that contains a collision resistant namespace.

    Private claims

    These are the custom claims created to share information between parties that agree on using them and are neither registered or public claims.

An example payload is as follows:

  "sub": "1234567890",
  "name": "John Doe",
  "iat": 1516239022,
  "exp": 1600000000,
  "scope": "user"

The payload is then Base64Url encoded to form the second part of the JSON Web Token. Signature

To create the signature part you have to take the encoded header, the encoded payload, a secret, the algorithm specified in the header, and sign that.

For example if you want to use the HMAC SHA256 algorithm, the signature will be created in the following way:

  base64UrlEncode(header) + "." +

The signature is used to verify the message wasn’t changed along the way, and, in the case of tokens signed with a private key, it can also verify that the sender of the JWT is who it says it is.

2.1.2. Putting all together

The output is three Base64-URL strings separated by dots that can be easily passed in HTML and HTTP environments. AccessToken

The Access Token is a JSON Web Token. The token is typically sent in the Authorization header using the Bearer schema. The content of the header should look like the following:

Authorization: Bearer <token>

The API Gateway also supports sending the token as Cookie, but this is not described here, that is only used for the CTRLD web UI.

The token has to have the kid claim in the header. This kid is used to find the right JSON Web Key (JWK) from one of the JSON Web Key Sets (JWKS).

APIGWD searches for the jwks file under /etc/rtbrick/apigwd/access_secret_jwks.json, but it is also possible to provide an additional oicd endpoint. By that the keysets are searched in the provided order:

  • local file specified by command line -access-token-jwks-file-name

  • oicd auto discovery -oidc-issuer

The scope claim contains the roles the user has. For example:

  "sub": "1234567890",
  "name": "John Doe",
  "admin": true,
  "iat": 1516239022,
  "exp": 1600000000,
  "scope": "user operator"

This user has the roles user and operator.

2.1.3. JWKS Validation

The example below shows how to create a public/private key set file (for example with

sec mgmt jwks validation

Example PubPrivJwks.json:

  "keys": [
      "p": "-3WNqU2aWKy8Q7mblRpw_aOknW47YvZKVNQzlWdijXW5E1hQ5c6sfjqo92pq5mNKJ_Xkl71xHyp-WBfw-xJqZ9pUuG4jnUiKgzYHvkccDF5XIMrpA67VnBozmyLckQOKEXesRD2hacrjb-T89dcIZQHBUK1RYXGRxHCM_hPeBok",
      "kty": "RSA",
      "q": "07STzbuUh6p_iN2wzTegIQdnXBLnzPObCKt-KLSjkLtrZMv2YxM2yhMs-56SsLR7EICFRAB2vdCzlovXKShubU9NSKgVI38qpGV9hii8rqN5N3dEM4Gscp_TR36ex1NoSC6kHBF2hsyPfgD7U-txguZr6w9MN6rK4bAcg0TWGM0",
      "d": "IWcC4aKuPVlVGZeBhb3mla1mOsOcJuLxjpkZAu-QaQO7phWzeGLEfln3tojKtIK6e11FEz137ow75Je0_oMAzE-eTAMyseUTHZhn4LhmIdOwnsp9OZrMbNmLFpaF_rGYb0630xg27GdR4gC_lZvMuy1uCP1sr8Iyl1ujN7n_6ETMYbdXPLOtEAB4Dag6XFTjy1l8aVvBxpscm8gKg64fgBGRvGY6PiUfqY3gaq_vX9SOOHVPN5WoShKA4fguxukRBiLLYNxDMDb3-h8pd1_fr2WayDzmcIXpxvVjRVZHt71C-0Uhap6eRDMQocZXih8IdNV8zHUF_LeciE36fIb3oQ",
      "e": "AQAB",
      "use": "sig",
      "kid": "access",
      "qi": "3His_DaBkf_r7uDx9-8BOhOQPhcudT95XC9WyS5MrYIBtgqQi6IscHIqvtXFpjmPRey-chO7p9msOAB_T8j_mg1l6UWOx6j4h_fyHEbOwRqfNemKng2Hs0uCrwpjgGf2eXzaBY8T9HlbFlTJAAARGh_PePBi-F-IfAxGayj4hiM",
      "dp": "NJuYYpZAt1KUJJsdSKl6gCYPV3xrYj3iuTKYBCbYAH5jlP-CFUIS5mnBVdnmuYKGTivsgi55DysluapwmSZ2KnoMBXXNb6dwixjvr8hSvuex1MN-0m1udTUqHMfDW3dhGFxwJuq57VcsFAnVPl2ZfQBMAGPyRa-r7mwZo0Jmzfk",
      "alg": "RS256",
      "dq": "XL-4IWIU6Hrh9OxrEP1VwiKkPcpqk3gGa_31_49kOXxiyH4zK6S3VECibHpEefYYFFq6B9jMLMzKYSJS2U1FU85yZWp-GFcWL3_nRmeCgmBMMuilkIs3KeCrh58JoPoBrd4BN-rOqq_kDagQc-uqh1a74PeKxLimucmWNExsH-E",
      "n": "z_NDmLu8M3KGvxvfJt8CAhdLdsqkskfY7vf9X9pW1LE_r31_HU85-l6NNHeUWYbSNe6lt9YODnL8-vTT6oCgre96byvpdYZ7Ki5KGe4fU96x0_ZF5LceUQc4l5dx6aptNi9mWgcZ9nkc2Xh83ASg9otG2YoYsAnI1cO0TjzV9cMI7u7VON6SON9wbWFY01--ixMqxRAZuEJjbg4QAdL7DndRQXvmq1m7lv-nnPPQ0a7ZTg7NZDEn5lMmadUlTVl5uvSNsACtC49R5kEkNCc1Hc-3gootU5VyVPBx6IFHtNC2BiGasQAUpsDXZl7YtvBZwzYZwznUlluPiKLDk-4TtQ"

The APIGWD only needs to know the Public part:

 "keys": [
     "kty": "RSA",
     "e": "AQAB",
     "use": "sig",
     "kid": "access",
     "alg": "RS256",
     "n": "z_NDmLu8M3KGvxvfJt8CAhdLdsqkskfY7vf9X9pW1LE_r31_HU85-l6NNHeUWYbSNe6lt9YODnL8-vTT6oCgre96byvpdYZ7Ki5KGe4fU96x0_ZF5LceUQc4l5dx6aptNi9mWgcZ9nkc2Xh83ASg9otG2YoYsAnI1cO0TjzV9cMI7u7VON6SON9wbWFY01--ixMqxRAZuEJjbg4QAdL7DndRQXvmq1m7lv-nnPPQ0a7ZTg7NZDEn5lMmadUlTVl5uvSNsACtC49R5kEkNCc1Hc-3gootU5VyVPBx6IFHtNC2BiGasQAUpsDXZl7YtvBZwzYZwznUlluPiKLDk-4TtQ"

Now to create a token you can use, and paste the PubPrivJwks.json into the RSA Key Field and provide as Payload.

For example:

  "sub": "1234567890",
  "scope": "user operator",
  "name": "John Doe",
  "admin": true,
  "exp": 1600000000,
  "iat": 1516239022

This results in the following token:


The apigwd can decode that token and validates the token with the corresponding key in the specified JKWS file.

2.2. OIDC Authentication

If you use OpenID Connect for Authentication, that the Token is generated by the OIDC Connect server.

It is important to understand how the validation of the tokens works. Either the JWKS file which corresponds to the OIDC server is located locally on the system, or the OpenID Connect Server (issuer) is specified.

The first configuration possibility we already discussed. If the oicd connect server is specified the server provides an endpoint where the clients can download the public keys.

As an example for this configuration of an oidc-issuer here an excerpt of:

     "oidc_issuer" : "http://<keycloak>/auth/realms/<real name>",
     "client_id" : "<client id>",
     "client_secret" : "<secret>",
     "redirect_url": "",

Specific information about the issuer can be found at http://<keycloak>/auth/realms/<realm name>/.well-known/openid-configuration.

If you also specify the client secret and the client id, this allows the APIGWD to redirect to the login page of the OIDC server. This is needed for browser-based applications like CTRLD UI.

3. Role Based Access Control (RBAC)

Role Based Access Control (RBAC) is an approach to restrict the system access to authorized users. The authorization model is role-based. There will be three items in a role-based modeel: sub, obj, and act.

  • sub: the user (role) that wants to access a resource.

  • obj: the resource that is going to be accessed

  • act: the operation that the user performs on the resource

The RBAC Data Model is implemented in RBFS, and it allows you to define Permission or User Roles to various type of resources.

The model contains:

  • Resource Type: The type of resource we are talking about (for example, BDS Table, BDS Object, REST)

  • Resource: The identifier of the Resource (for example, Table Name, Rest endpoints). Regular expressions are allowed.

  • Permissions: Indicates the action that a user is allowed to perform on the resource. The Permissions are CRUD (Create, Read Update, Delete). The permission gets a semantic with respect to the resource type.

  • Role: The role of a user who tries to access a resource.

3.1. CTRLD Authorization Configuration

3.1.1. Activate or Deactivate Authorization in CTRLD

"auth_disabled": true

It is possible to specify the permissions in CTRLD exactly in the way specified above.

Where sub is the role a user needs to have, obj species the url endpoint the user wants to reach, and act is the HTTP Method the user wants to call on the endpoint.

For example:

 "permissions": [
   {"sub": "supervisor", "obj": "/*", "act": ".*" },
   {"sub": "reader", "obj": "/*", "act": "GET"},
   {"sub": ".*", "obj": "/api/v1/rbfs/elements/{element_name}/services/{service_name}/proxy/*", "act": ".*"}
  • The user with the role supervisor is allowed to access all rest endpoints, and act on them with all HTTP methods.

  • The user with the role reader is allowed to access all rest endpoints, but can only call the HTTP GET method.

  • All authenticated users are allowed to access the proxy endpoint with all HTTP methods.

To configure that policy CTRLD offers 2 endpoints:

  • PUT /api/v1/ctrld/authorization/permissions

  • GET /api/v1/ctrld/authorization/permissions

Please refer to API Documentation for more information.

3.2. RBFS Authorization configuration

3.2.1. RBFS Role Configuration via REST

 "objects": [
   { "attribute": { "role": "operator", "permission": "create|read|delete", "resource_regex": "global.*", "resource_type": "object" } },
   { "attribute": { "role": "operator", "permission": "create|read|delete", "resource_regex": "global.*", "resource_type": "table" } }
 "table": { "table_name": "", "table_type": "authorization_config_table" }

 "objects": [
   { "attribute": { "role": "user", "permission": "-|read|-", "resource_regex": "global.*", "resource_type": "table" } },
   { "attribute": { "role": "user", "permission": "-|read|-", "resource_regex": "global.*", "resource_type": "object" } }
 "table": { "table_name": "", "table_type": "authorization_config_table" }
  • role : Represents role in the system

  • resource_type : Represents resources in the RBFS (table|object).

  • resource_regex : Regex for the resources to be accessed.

  • permission : Bitmap representing permissions to create, read and delete. create|read|delete

Action BDS Table BDS Object


Create a BDS Table

Create/Update a BDS Object


Read Table Header Objects or Metadata

Read BDS Objects


Delete a BDS Object

Delete a BDS Object

3.2.2. RBFS Authorization CLI Configurations

Global user role configuration:

set system authorization global role <name> rbac-permission <resource-type> <resource-regex> permission <permission-map>


Represents role in the system


Represents resources in the RBFS (table/object).


Regex for the resources to be accessed.


Bitmap representing permissions to create, read and delete.









admin@rtbick: cfg> set system authorization global role admin rbac-permission table global.* permission create/read/delete

Lawful user role configuration

set system authorization lawful role <name> rbac-permission <resource-type> <resource-regex> permission <permission>


Represents lawful interceptor (LI) role in the system


Represents resources in the RBFS (table/object).


Regex for the resources to be accessed.


Bitmap representing permissions to create, read and delete.









admin@rtbick: cfg> set system authorization lawful role fbi rbac-permission table local.* permission -/read/-

4. SSH with TACACS+

RBFS provides a custom pluggable authentication module that gets invoked by the stock sshd on login. The necessary configurations are pre-installed on RBFS.

RtBrick-PAM, referred to as RTB-PAM helps in landing the TACACS authentication on the appropriate user in the Ubuntu container and helps in providing necessary details for the secure management plane feature.

Once the PAM client requests TACACS for the authentication, with successful authentication TACACS responds with a few RtBrick specific details.

     rtb-deny-cmds: “clear bgp peer”
     priv_lvl : some_level

On successful authentication, the RTB-PAM module creates a token (JWT) for the logged-in ssh user.

4.1. RTB-PAM Token

Token created by the RTB-PAM module contains the same claims that are defined under the RtBrick Token section, and this token is signed with the secret_jwks.json key.

The scope claim in the rtb-token is derived from the Linux groups that the locally mapped user belongs to.

The deny commands are converted into the claim rtb-deny-cmds. Once the token is created, it is transferred to the environment variable.

setenv RTB_TOKEN = {
  "sub": "83692",
  "iat": 1516239022,
  "exp": 1517239022,
  "name": "Admin User",
  "preferred_username", "user1",
  "scope": "operator tacacs_priv_lvl_8"
  "rtb-deny-cmds": "^clear bgp peer"

After the RTB-PAM token is created, the CLI prompt appears. If a token is not created for the logged-in user, then the user cannot perform communication with the BD.

4.2. SSH User Prompt

After you successfully log into RBFS via SSH, you can see the rtb-token using the shell environment. For example, an SSH prompt may look like the example below.

rtbng@b908f71f63b7:~$ env
LESSCLOSE=/usr/bin/lesspipe %s %s
SSH_CLIENT= 33136 22
SUDO_PROMPT=[sudo] password for rtbng:
LESSOPEN=| /usr/bin/lesspipe %s
Note The users having access to the Linux shell only can see the installed rtb-token in the shell environment.

4.3. User Login Flow

The figure below shows the user login flow.

user login flow

As shown in the figure above, the following steps are involved in the user login flow.

  1. User starts to initialize using ssh

  2. The SSH daemon (sshd) refers to the Name Service Switch (NSSWITCH) for user lookup

  3. NSSWITCH performs a user lookup at the TACACS server

Note A user lookup happens at TACACS user database even for the local users, except for the user 'supervisor'.
  1. If the user is not found at TACACS user database, then the user look up happens at the local user database.

  2. User authentication is performed by PAM modules

  3. PAM communicates to the TACACS server for authentication if it is a TACACS user

Linux pre-configured users and groups
User Name Group Name Privilege



level 15



level 7-14



level 0-6

4.4. In-Band and Out-of-Band TACACS user SSH Login

4.4.1. In-band TACACS user SSH Login

A TACACS user can login using SSH to rtbrick container through inband management. RBFS should be configured with inband-management TACACS server for TACACS user login, and inband management configuration should be enabled with TACACS service.

4.4.2. Out-of-band TACACS user SSH Login

TACACS user can login via SSH to ONL though out-of-band management. RBFS should be configured with out-of-band management TACACS server for TACACS user login.

4.5. Configuring TACACS+ for RBFS

To configure TACACS+ server for RBFS, enter the the following commands.


set system authorization tacacs server-ip <IP address> type <management type> secret-plain-text <secret key>

set system authorization tacacs server-ip <IP address> type <management type> server-port <server port number>

Command Arguments
<IP Address> IP address of the TACACS Server

<management type>

in-band or out-of-band management


Secret plain text string. The secret string input can be plaintext format. If string starts with 1 then system considers it as encrypted string and stores key as it is. Also if secret string starts with 0, then system considers it as secret in plaintext and hence it stores in the system in encrypted format.

<server port number>

Server port number. This attribute is optional and by default system tries to connect to server running on port number 49.

Note For TACACS login to work with inband management, inband configuration must be enabled with the following command:
set inband-management instance <instance-name> tacacs true
root@rtbrick: cfg> set system authorization tacacs out-of-band secret-plain-text testkey

root@rtbrick: cfg> set system authorization tacacs server-ip type inband server-port 1234
Note A TACACS user is not allowed to login without TACACS server configuration.

The example below shows the running configuration after you configure TACACS.

  "rtbrick-config:system": {
    "authorization": {
      "tacacs": [
          "ipv4-address": "",
          "type": "out-of-band",
          "secret-encrypted-text": "$202a74ca845585855b6f8df57cdbf7858"

4.5.1. Example: TACACS User Configuration in the TACACS Server

The example below shows the server configurations for rtb-deny-cmds.

accounting file = /var/log/tac_plus.acct
key = tacacskey

user = bob {
	login = cleartext "bob"
	member = Network_Operator
group = Network_Operator {
  default service = permit
  service = exec {
     	priv-lvl = 10
     	rtb-deny-cmds = "show bgp.*"
Note priv-lvl is a mandatory attribute in the TACACS user configuration.

Multiple cmd-regexes can be configured with each regexes separated by semicolon (;).


rtb-deny-cmds = "show bgp .*;show isis .*"

4.5.2. Troubleshooting NSS User Lookup Issues

To look up the TACACS username with all NSS methods, enter the following command:

ubuntu@rtbrick:~$ sudo getent passwd <tac_user>

To look up the local user within the local user database, enter the following command:

ubuntu@rtbrick:~$ sudo getent -s compat passwd <local_user>

To look up the TACACS user within the TACACS+ server database, enter the following command:

ubuntu@batman:~/development$ sudo getent -s tacplus passwd <tacuser>

If TACACS does not appear to be working correctly, You can enable debug logging by adding the debug=1 parameter to one or more of these files:


4.6. Configuring Secure Management Logs

4.6.1. SSH User Login Logs

The transaction logs of users (in the PAM module) are available in the following log file:


Commands to enable secure-management logging:

Full Syntax

set log bd <bd_name> module secure_management logmap <log_map> level <log-level>

Parameter descriptions

Command modes

Behavior description

Enables secure-management logging in the system


confd> set log bd all module secure_management logmap all level Info

©Copyright 2024 RtBrick, Inc. All rights reserved. The information contained herein is subject to change without notice. The trademarks, logos and service marks ("Marks") displayed in this documentation are the property of RtBrick in the United States and other countries. Use of the Marks are subject to RtBrick’s Term of Use Policy, available at Use of marks belonging to other parties is for informational purposes only.