Authentication and authorisation slots

These are slots related to authentication and authorisation, and allow you to authenticate, change password of users, and other things related to the “auth” parts of the system. Notice, you would rarely if ever use these slots directly, since the system contains several endpoints helping you out with the consumption of these slots. However, to be complete, we’ve chosen to document these none the less.

[magic.auth.authenticate]

This slot authenticates a user towards your specific authentication and authorisation logic, which implies looking up the username in the magic.users database table, and ensuring the password is correct. If both the username exists, and the password is correct, the slot will return a valid JWT token, allowing you to use it as a token authorising you to act on behalf of the user, and/or return the JWT token to the client. Below is an example assuming your root password is “admin”. Try to execute the following code with your own root user’s password to see how it works.

signal:magic.auth.authenticate
   username:root
   password:admin

In addition to [username] and [password] the slot handles the following optional arguments.

  • [password-check] - If false, the password is not verified - allowing middleware that has already verified the user through other means, such as OIDC, to create a token
  • [expires] - Optional explicit expiration date for the JWT token

The above would return something resembling the following.

signal
   ticket:eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.xxx

[magic.auth.change-password]

Allows a user to change his or her password. This slot requires the user to be already authenticated and having a valid JWT token. An example of changing your own password to “admin2” can be found below.

signal:magic.auth.change-password
   password:admin2

If you invoke the above Hyperlambda, and log out from Magic, you’ll need to use “admin2” as your password to authenticate again. Notice, this slot will evaluate within the context of the “current user”, implying the only person who can change his or her password is the user currently being authenticated.

Yet again, Magic contains helper endpoints for these types of operations, and you would probably never want to directly invoke the slots yourself, but rather use the helper endpoints from your own frontend if you wish to use this type of functionality. See the endpoints section for details.

[magic.auth.create-user]

This slot allows you to create a new user in Magic, with the specified username/password combination, belonging to the specified role(s). Below is an example of usage.

signal:magic.auth.create-user
   username:foo
   password:bar
   roles
      .:guest

The above creates a new user called “foo” with the password of “bar” belonging to the “guest” role. If you execute the above Hyperlambda for then to go to your Users & Roles component item, you will find this user. Notice, you might want to delete the user after having verified it exists.

In addition the slot handles the following optional arguments.

  • [is_hashed] - If true, the specified password is assumed to already be hashed
  • [extra] - Extra fields to associate with the user, such as name and email, as a list of type/value nodes

[magic.auth.ensure-role]

This slot allows you to ensure that the specified role exists, and if not, create it. This is a useful slot when you create your own Hyperlambda modules, and your module depends upon some role existing in the system. Typically you’d invoke this slot from one of your module’s startup files, since these are executed both during startup and during installation of your module. Below is an example of usage.

signal:magic.auth.ensure-role
   role:foo-role
   description:This is the foo role

If you execute the above Hyperlambda and go to Users & Roles afterwards, you will see how you now have a “foo-role” in your system.