RBAC API

[grossmj]

GNS3 3.0 will come with a RBAC (Role Based Access Control) API. Here is a quick presentation of what we already have. Of course, this can be (and will most likely) be improved.

Theory

RBAC allows you to leverage permissions to specify what can be accessed – be it actions, or resources – while eliminating the need to manage these permissions individually. Permissions are assigned to roles, and roles can be assigned to users or user groups.

Roles will often have titles that we see commonly, such as User or Administrator. Once you have identified and defined the roles and assigned them to each user, these roles can be assigned permissions which are then applied to the users within the role group. By managing permissions within a small set of roles, administration and security becomes an easier task.

A best practice is to assign roles to user groups rather than individuals and with no permissions existing by default. This is what we will do in GNS3.

General implementation

The GNS3 controller manages the RBAC system using a SQL database which is SQLite but could easily be MySQL, PostgresQL etc. if needed.

Because not all resources are recorded in the database (only computes, images, templates, users, user groups, permissions and roles) and because we also want something flexible, we have chosen to implement permissions based on the API URI paths and HTTP methods instead of associating permissions directly with resources like projects, nodes etc.

For example, to deny a specific project to be duplicated, a DENY permission on POST /projects/{project_id}/duplicate can be created and assigned to a role that is itself assigned to an user group which users belong to.

To summarize, the URI is the resource and the HTTP method is the action performed on this resource.

This idea originally comes from https://medium.com/practo-engineering/route-based-access-control-462861b04433

Something important here is the API must be organized in a way that allow permissions to be easily and logically created. Luckily the current API (documentation on https://apiv3.gns3.net/ or https://apiv3.gns3.net/redoc) is quite hierarchical and only minor adjustments should be needed.

Permissions management

Permissions are managed using these API endpoints: https://apiv3.gns3.net/#/Permissions

Here is an example with JSON data to create a new permission.

POST /v3/permissions

[
   {
       "description": "My description",
       "methods": ["GET", "POST", "PUT", "DELETE"],
       "path": "/path/to/resource",
       "action": "ALLOW"
   },
]

methods is the HTTP method to match. There can be multiple methods with:

POST = CREATE
GET = READ
PUT = UPDATE
DELETE = DELETE

Action can be ALLOW or DENY.

Path is the API URI to match. Creating a permission on an URI that does not exist is not allowed.

Roles management

Roles are managed using these API endpoints: https://apiv3.gns3.net/#/Roles

Here is an example with JSON data to create a new role

POST /v3/roles

{
   "name": "My custom role",
   "description": "This role is for guests"
}

Permissions can be assigned to the role once it is created with PUT /v3/roles/{role_id}/permissions/{permission_id} https://apiv3.gns3.net/#/Roles/add_permission_to_role_v3_roles__role_id__permissions__permission_id__put

Users management

Users are managed using these API endpoints: https://apiv3.gns3.net/#/Users

Here is an example with JSON data to create a new user

POST /v3/users

{
   "username": "john",
   "email": "john@example.com",
   "full_name": "John doe",
   "password": "My secure password"
}

Authentication

Users must be authenticated to access endpoints with the lock symbol shown in the API documentation on https://apiv3.gns3.net/, to authenticate an user, an API call to https://apiv3.gns3.net/#/Users/login_v3_users_login_post is done and a token is returned upon success. The token is then used for all other API calls, this is when the RBAC system checks the user is authorized or not.

There is one special case, all /users/me endpoints are authorized. This is to allow users to check or update his/her own information.

User groups management

User groups are managed using these API endpoints: https://apiv3.gns3.net/#/Users%20groups

Here is an example with JSON data to create a new group.

POST /v3/group

{
   "name": "My group"
}

Roles can be assigned to the group once it is created with PUT /v3/groups/{group_id}/roles/{role_id} https://apiv3.gns3.net/#/Users%20groups/add_role_to_group_v3_groups__user_group_id__roles__role_id__put

Users can be assigned to the group with PUT /v3/groups/{group_id}/members/{user_id}
https://apiv3.gns3.net/#/Users%20groups/add_member_to_group_v3_groups__user_group_id__members__user_id__put

Groups are the link between users and roles.

Defaults

These defaults are created when the controller is started and no database file exists, the file is stored in ~/.config/GNS3/3.0/gns3_controller.db. Deleting this file and restarting the controller will reset everything.

Super admin

The only user created by default is admin with default admin password, this is the super administrator which cannot be restricted in any way and completely bypass the RBAC system. This is the only account needed if users wish to use GNS3 in the same way as previous versions, without restrictions.

Default user groups

• Administators
• Users

A freshly created user must be assigned to Users by an Administrator otherwise this user won't be able to create/access anything.

Default roles

• Administrator
• User

Default permissions for the Administrator role

The Administrator role has access to everything.

[
   {
       "description": "Allow access to all endpoints",
       "methods": ["GET", "POST", "PUT", "DELETE"],
       "path": "/",
       "action": "ALLOW"
   },
]

Default permissions for User role

The User role can create create/list projects, create/list templates, use computes and create/list symbols. This is subject to changes.

[
   {
       "description": "Allow to create and list projects",
       "methods": ["GET", "POST"],
       "path": "/projects",
       "action": "ALLOW"
   },
   {
       "description": "Allow to create and list templates",
       "methods": ["GET", "POST"],
       "path": "/templates",
       "action": "ALLOW"
   },
   {
       "description": "Allow to list computes",
       "methods": ["GET"],
       "path": "/computes/*",
       "action": "ALLOW"
   },
   {
       "description": "Allow access to all symbol endpoints",
       "methods": ["GET", "POST"],
       "path": "/symbols/*",
       "action": "ALLOW"
   },
]

Permission priorities

Permissions are checked from the longest to shortest URI . For example:

/projects/{project_id}/duplicate will match first and then /projects/. We are considering adding an explicit priority field to permissions.

Automatically created permissions

Each time an user creates a new project or a new template, a permission is added to the user. The user is the owner of that resource and other users cannot access it excepting if explicitly allowed.

The generated permission would be /projects/{project_id}/* for a newly created project and /templates/{template_id}/* for a newly created template.

The /* gives access to all resources inside another one, for instance all nodes and links belonging to a project. A permission on /projects/{project.id} only allows requests matching exactly that path which means only GET, PUT or DELETE on that project but nothing else as seen in the API documentation for projects: https://apiv3.gns3.net/#/Projects

These kind of generated permissions are directly associated to users who create the resource. They are automatically deleted when a given project or template is deleted.

Note that while it is possible to assign permissions directly to an user, we encourage to use user groups and roles to do this. Also, role permissions are checked first before user permissions.

User created permissions

Users must already have a permission on a path before they can create a new permission on this path. We will have to perform more checks to make sure we cover all use cases here and everything is secure. Of course, users must have a permission for POST /v3/permissions in order to create new permissions and, for example, a permission for PUT and DELETE /v3/roles/{role_id}/permissions/* to allow the user to assign permissions.

SQL model

Here is our SQL model for those of you who are interested

[lurendrejer]

I am really looking forward to this.

Will 'cluster-nodes' be able to contact a central RBAC logon point?

[grossmj]

Will 'cluster-nodes' be able to contact a central RBAC logon point?

No sure I understand the question but there is only one central logon point since there is only one controller that manages everything.

[lurendrejer]

Ok.

Will 'cluster-nodes' be able to contact a central RBAC logon point?

No sure I understand the question but there is only one central logon point since there is only one controller that manages everything.

Ok, I might have missed something obvious.
If every node had it's own set of permissions and list of images and templates in a database, my work would have gotten a lot harder.

But after reading again, I'm still not sure if there will a single logon/web-server or users still have to access each node individually.

I have been doing something quite like this with a proxy in front if each node, filtering URLS like /duplicate{post}, etc. It worked out pretty OK but was very CPU-intensive. (https://pypi.org/project/gns3-proxy/)

[grossmj]

But after reading again, I'm still not sure if there will a single logon/web-server or users still have to access each node individually.

Do you mean to console to each node? currently we still expose the console port for each node which means users still have to access each node individually however we plan to change this later on.

[lurendrejer]

@grossmj - No, I never got the Controller/slave part of GNS3 working. I think I saw a post in the forum calling it 'scalable mode' - but i was never able to see the point, since the gui doesn't allow me to send certain users, to certain 'slaves'.

Every node in my cluster copies alle the templates from a central source and generates a working config (host-ip, etc.) and the users connect to them directly, from the GNS3-client.

[llevier]

Guys, that is Vigrid server farm. To say it short, ~gns3/GNS3 is central and so all servers, driven by the control tower who can do anything anywhere, manage everything (run/stop, snapshot, clones etc). Vigrid installation include Vigrid NAS format, mandatory to use filesystem extensions far better than Qemu & GNS3 (sorry Jeremy) ones.

[srieger1]

That's a big step forward! Awesome! Looking forward to use RBAC in GNS3! Thanks for the hard work that you put in this project!

[srieger1]

I'll try to squeeze in some time for that! As clustering GNS3 servers also seems to be on the roadmap already, maybe I can try to take a look at implementing the things that would be nice but have been difficult to implement while no such thing as RBAC support was there. LDAP would also supported at least indirectly through the upcoming OAuth support I suppose.

That would then only leave some nice to haves, like a course management system (Web Page) to handle starting/stopping labs according to course schedule. Replication of projects across backends etc. Maybe some reservation system to efficiently manage limited compute resources in off-peak scenarios when students are accessing labs outside of the class schedule. Maybe even an online examination system, like with time-bombed labs, submission/automatic testing of results etc. We're currently working on that in another area (to teach the use/benefits of SDN and deep network programming using P4). Maybe we can shift gns3-proxy to fix this gap, as I suppose and think to remember, that this will understandably be outside of focus for GNS3 ;) ...thanks to the big improvements in 3.x however it should finally be possible to build such a course/classroom/lab management system on top of it and also maybe directly integrate the Web GUI ;) We previously used guacamole to fill this gap.

Maybe I can try to motivate some capable bachelors' or masters' students to take a look at that...

[llevier]

I released Vigrid to public github some weeks ago. Vigrid relies on GNS3, adding much more features to industralize it, and providing Cyber Range design. Many things I built will be included into GNS3 directly, such as web consoles for nodes, getting rid of heavy clients, and without keymaps issues ;-)
However, all I built relying on extended operating systems functions is out of GNS3's scope and will not be included.
It remains Vigrid is opensource, just forbidden to commercial uses.. Easy for students to get it, add/change some things, sharing for the common good :-)

[lurendrejer]

@llevier what. Where?

[lurendrejer]

Ok, I found it - I still don't get what I does....

[llevier]

Hello @lurendrejer,
Today GNS3 is good for simple trainings, building networks on a single or multiple servers.
However, GNS3's business is not to replace existing features when they could be much better, as well as GNS3s is not "cloud oriented", meaning a built network could be copied xxx times, launched simultaneously any time on any servers, with a standard network design and associated infrastructure for all servers.

That is what I do with Vigrid, with a Cyber Range design. Cyber Ranges are training grounds for Security guys.

With Vigrid, you have a Web control tower added to GNS3, and all traffic is done via a single port, much easier in company environments.
So, as an example, a Vigrid infra is built with XX servers, configured in Clone Farm design, with Cyber Range network design.
You would launch OpenVPN to connect to the MAster server, acting as front-end. Port 443 is the one used for GNS3 heavy client, OpenVPN, Web & SSH. Credentials are not GNS3's ones but Vigrid. As with Sebastian's proxy (I could implement if RBAC@GNS3 is too long to come), I manage credentials & access control.

You build your virtual network, data is stored centrally.
Once it is done, you can either propose it to public, snapshotting the project for cloning, or industrially clone it.
In both cases, the cloning is immediate (atomic operation), costs no disk space, and is independant, so clone users can do whatever they want with their clone. At clone lifetime ended, Vigrid destroy it.
Of course, web permits to do everything : snapinghost/rollback, cloning and access to nodes without any client required, everything flows via the web and there are no VNC keymap issues as usual with UltraVNC ;-)
Vigrid also permits to extend the infrastructure anywhere in the world with a USB bootable key to provide seamless USERtoLAN or LANtoLAN access.

I created that because in my company there are trainings and with my design and another tool to manage clone demands with RBAC, this is not an official solution, but also because I am a Security Expert in my group managing our infrastructure to do 'Capture The Flag' exams. In these, we create a virtual network and it is cloned 100s of times so teams can play with it.
At this very moment, the biggest CTF I got was 200 clones spread on HP C7000 blades (3x4 BL660c + 3x6 BL460c) for 800 users at a time.

The clone source was 34GB on disk, it took 70seconds to create the 200 clones without disk space consumption, around 20mn to launch them all (I do that smoothly to avoid NFS bottleneck and sideeffects on VM disks). No user complained ;-)

Is it more clear that way ?

[llevier]

To add more points to the discussion.
GNS3 in scalable mode permits to have a single controller using other GNS3 to spread its resources. Today it is quite heavy because the other GNS3 server must have the resource and node is associated with it.
Glancing low level, I think there is no issue to have all scalable servers using the same NAS share ~gns3/GNS3, since nodes storage is using their uuid. If that is the case, then forcing a compute_id might not be required since all GNS3 data is available to all GNS3 servers in the Scalable Farm.
In Vigrid design, Cloning Farms (GNS3 servers are independant, each with its own controller I manage via the Control Tower with GNS3 API), all data is central so any GNS3 server can launch any project any node without issue...
This is GNS3's cloud ready ;-)

[grossmj]

Have have noticed a small problem with our current approach.

Let's say we want to prevent all users from duplicating their projects, we could do this by adding a DENY permission matching /projects/{project_id}/duplicate. However, a permission must explicitly match the project_id of existing paths like /projects/fc54c663-2231-4025-a2c2-1221f5f506e4/duplicate for instance. So adding an explicit permission every time a project is created wouldn't scale.

One way around that would be to allow generic permissions like /projects/{project_id}/duplicate or /projects/*/duplicate OR should we allow regexp?

[srieger1]

That's indeed also necessary here. I thought that you already had "" in mind in the URL path, for HTTP method etc., as you gave /projects/{project_id}/* and /* as an example in the RBAC description above. I also ended up using regexp's in gns3-proxy, though to be honest, a simpler "" or placeholder/variable solution "{xyz}" would also fit our needs currently. However regexps are more flexible and quite fast in our setup.

[grossmj]

I think I will go for the placeholder/variable solution matching to match the routes shown in API doc https://apiv3.gns3.net/ This is the easiest.

[llevier]

I think there is no reason not to permit regexp in RBAC endpoints. However, considering GNS3 Cloud as a target, this has a cost in select(). I would suggest to check received endpoint to build the fastest select() (no regexp, classical one)..

[grossmj]

The only problem I face with the placeholder solution is to check that an user has the right to create a permission. For example, the user wants to add /projects/{project_id}/duplicate or /projects/16fd2706-8baf-433b-82eb-8c7fada847da/nodes/{node_id}/duplicate

I am thinking about this solution: taking the path and keeping everything before the placeholder, e.g. /projects or /projects/16fd2706-8baf-433b-82eb-8c7fada847da/nodes and checking that the user has already a POST or PUT permission on these paths.

[llevier]

deny duplicate is just another right or deny. Yes, you can (even you must) consider a duplication permission. Else, logically, I am denied (example) to access the nodes, I dup the project, I can play with the nodes :-)
What I foresee is documentation (!). Allowing project_id/* means everything, denying specific nodes of this project does not protect from duplication (!!). RBAC will have to be thoroughly explained so admin clearly understand the model and associated risks...

[llevier]

About regexp, That is what I already do in Vigrid. However, I dont use SQL. If SQL can manage it, the only side effect is performance. Keep in mind you have to check at each API call :-(

[grossmj]

Hum, it was already very painful to use a SQL database since I am no expert and I dislike working with databases, so boring ;) So no I don't think it is necessary to switch to another tech which would delay us again.

That being said, looks like it is possible to use regexp in SQL queries: https://docs.sqlalchemy.org/en/14/core/sqlelement.html#sqlalchemy.sql.expression.ColumnOperators.regexp_match

[srieger1]

Makes sense. Interesting, what you said about databases. Sometimes I felt like I'm the only one to find working them boring ;) Somehow (sadly) from time to we need to store and access some data in a structured way... ;)

[grossmj]

Indeed, as you said we still need them ;)

[llevier]

@srieger1 In fact, neither Jeremy & I are good in SQL. I used my Group resources to design that. We discovered recently the SQL model was perfectly fitting RBAC SQL models. We did not considered noSQL thing, cant tell how interesting it could be. I'll ask the SQL designer. We are at the starting point, we can still change many thing with low impact. As written in another thread, performance is the key, no issue to have regexp in RBAC endpoint if we check for such a presence to avoid select() with regexp (probably slower) without reason.
We must also keep in mind SQL using cache is very fast. My servers are hosting running sports databases and since I configured properly the read cache, I climbed to 15000 queries/second in a less then 1GB database.
Today the only missing with currently model is ACE order in the ACL. I tried to enforce the fact these can be repositionned to permit things such as: permit nodes/x, deny nodes/, or permit console nodes/x, permit links nodes/x, deny nodes/. Jeremy found a nice way to keep part of this need giving long endpoints before shorter ones (with shared path) Long are usually the exception...

@grossmj, for regexp select in SQL, search for regexp_like(), that should be the common standard function.

[grossmj]

@grossmj, for regexp select in SQL, search for regexp_like(), that should be the common standard function

Actually the permissions in the database would be the regexp so this would not work when checking with a HTTP request path to match against the regexp. This would work if this was the opposite, like the path is the regexp and the permission the string to match. Hope this makes sense. Anyway, I don't think regexps would be really useful in our case since most of the API paths use uuids etc. and there is nothing your couldn't do using a few permissions, especially if we allow replacement variables like {project_id}, {node_id} etc.

[eantowne]

Why not just create a general permission called duplicate. That permission can be granted to users or groups as needed. Just like a create or delete?

[grossmj]

Permissions must match an API path. This is how the RBAC system is designed.

[llevier]

@grossmj I am considering general profiles (CREATION, USAGE etc). Since that should not be for gns3server (performance cost), I'll see if rbac_ui can manage this. After all, such profiles are simple a template to apply on object (eg. USAGE would permit console, power control, link access, denying duplication, changes and deletion). So we must think about such simple profiles...

[llevier]

@eantowne that is a discuss we started to have with Jeremy, but action should be taken as webui level : summarized rights.
To say it shortly, a list of standard profiles (CREATE/etc) that would generate a list of permissions.
Example: Project USAGE would allow console access, no updates, power ON/OFF, whatever...

[grossmj]

I wonder if those profiles could be built-in roles with associated permissions on server side, like a did for the Administrator and User roles?

[llevier]

Problem is : the more you compute at your level, the more you impact performance...
The 'profile template' concept good point is : easy to update (could be a text file or API call at source), and no need at your side...
But again, that's just an idea I raised, to be discussed :-).
This morning I met the new dev team, will have to motivate them to write for gns3 repo, than ball will move to my side to write the 'user path'...

[grossmj]

I am working on adding more default roles and permissions in #1987

So far I have this for the roles:

• Administrator: full control
• User: regular user that can only access the resources (projects, nodes, links) he/she creates
• Template manager: the template manager role can add, update and remove templates for all users
• Image manager: the image manager role can add, update and remove images for all users
• Supervisor: the supervisor role can update and remove projects for all users
• Project user: the project user role can only start/stop/suspend nodes and access the nodes' console in projects that are shared with them. They could also change link filters and capture packets.

Questions / comments

• Maybe template manager and image manager should be grouped into one role (what name?) since it could be confusing to manage templates and images separately?

• Project user should be named differently but couldn't come with a good name. I thought about "Read-only" but I am not sure about this too.

• Do you see any other roles that we could add by default?

[lurendrejer]

Would ownership of templates make sense?
I would like to have other people managing templates - without them having write-access to mine.

[grossmj]

Indeed, we have this in the pipe: #1980

[llevier]

Every '/v3/object' could be RBAC'ed, this include templates.
In fact with Jeremy we imagined the concept of 'public' versus 'private' for global objects as appliance, templates...
It also means YOUR appliance/template would then be only visible to granted users/groups, then right would apply to only use, or update...
This has major side effects to deal with. Appliance relies on disk file(s). So from now, each appliance would be into its home dir to avoid file overwrite. Later optimization would be required to avoid dup'ed files...