Administrating roles

This component allows you to manage and administrate roles in your system, and/or create new roles, fine tuning access to your backend through a role based access system. Below is a screenshot of the component.

Roles in Magic

Notice, all access in Magic is based upon roles, implying all users belonging to the same role(s) have access to the same parts of your backend. This makes it easier to provide access to specific parts of your system(s), and/or also see which parts of your system specific users have access to. To create a new role click the plus button in the top/right corner of the component.

Internals

Magic does not create “access rights” associations for roles. Instead the system allows individual endpoints to declare themselves which roles are allowed to invoke the endpoint. This is done by invoking [auth.ticket.verify] in your Hyperlambda code, and pass in a comma separated list of roles that are allowed to invoke the endpoint. Below is an example.

// Some Hyperlambda endpoint file.
auth.ticket.verify:root, admin

The above Hyperlambda code will throw an exception if the user invoking the code does not belong to either the “admin” role or the “root” role. Importanly, the system does not validate that these roles exists, only that the JWT token the client submits contains this role in its claims. This reduces the number of touch points related to authorisation in Magic, for the cost of making it slightly more difficult to see which endpoints each user, and/or role is allowed to invoke. To see “access rights” for a specific role, you’ll have to use the “Endpoints” menu item, which will show you which roles are allowed to invoke your endpoints. Below is a screenshot illustrating this.

Authorisation in Hyperlambda endpoints

Above you can see how the “Authorization” object for that particular endpoint has the value of “root, admin” implying only root users and admin users are allowed to invoke it. If a user not belonging to any of the previously mentioned roles invokes the endpoint, and exception will be thrown, and the rest of your Hyperlambda file will not execute. You can also retrieve the access rights associations for all endpoints in the system from your own code by invoking the magic/system/auth/endpoints endpoint. This endpoint does not require authentication or authorisation, but returns all access rights associations for every single endpoint in your backend, allowing you to create frontend authorisation guards, dynamically building your frontend UI, according to which endpoints the user is legally allowed to invoke, which again of course is determined by what role(s) the user belongs to. The return value from this endpoint will resemble the following.

[
  {
    "path": "magic/foo/bar1",
    "verb": "get"
  },
  {
    "path": "magic/foo/bar2",
    "verb": "get",
    "auth": [
      "root",
      "admin"
    ]
  },
  {
    "path": "magic/foo/bar3",
    "verb": "post",
    "auth": [
      "*"
    ]
  }
]

In the above example the first endpoint can be invoked by anyone, including a user who is not authenticated at all. While the second endpoint can only be invoked by “admin” or “root” users. The third endpoint can be invoked by any user, but the user must be authenticated to invoke the endpoint. Notice, the auth/endpoints endpoint caches its result on the server for 5 minutes, implying if you create new endpoints, and/or change the roles requirements for an endpoint, you’ll either have to wait 5 minutes before the changes takes effect, or explicitly purge your server side cache.