decorative image for blog discussing new features in zendhq
January 25, 2024

Exploring New ZendHQ Role-Based Authentication Features


Companies have a variety of software access restriction requirements, and these often extend to tools like ZendHQ. In this blog, we'll dive in on the new role-based authentication features in ZendHQ, show how to administer permissions, and discuss what those changes mean for ZendHQ users.

Schedule a Custom ZendHQ Demo for Your Team

Ready to see ZendHQ in action? Schedule a custom demo via the link below.


Back to top

Why Role-Based Authentication In ZendHQ Matters

Since we introduced ZendHQ almost two years ago, the GUI has operated under a single-role paradigm, with a single set of credentials, offering full administrative access to ZendHQ. Several of our customers have communicated a need for more robust and granular access controls to suit their organizational needs. As examples:

  • They may want to limit who is able to define and modify monitoring rules, to ensure that they are setup in a way that will not inundate their IT operations staff with notifications, or to ensure that actionable notifications are provided.
  • Some organizations want to control who is able to create and delete queues, or who can suspend or re-activate queues, or who can create jobs via the admin.
  • Some organizations may not need their IT operations staff to be able to initiate Z-Ray sessions.
  • The ability to delete or archive historical data captured by ZendHQ may need to be restricted to administrators, and not accessible by developers.

Earlier this week, we released version 1.6.0 of ZendHQ, which provides identity and access management for ZendHQ. This feature provides the ability to define your own groups, assign permissions to each service ZendHQ exposes, and to assign users to groups. Let's take a look. 

Back to top

ZendHQ Role-Based Authentication Overview

At the highest level, you can can create groups, assign groups permissions to ZendHQ services, and then define users and assign them to groups. When logging into ZendHQ, users will use the credentials provided to them by their ZendHQ administrator, and features of ZendHQ will either be omitted from the GUI, or disabled, if they are not accessible to them.

The general workflow for an administrator will be:

  • Create groups.
  • Assign permissions to groups.
  • Create users.
  • Assign users to groups.

Users can be assigned to multiple groups. If they are, they will have access to features based on the greatest access allowed to any group to which they are assigned. For instance, if a user is assigned to a group that provides read-only access to all features, and also to another group that provides write access to Z-Ray, the user will be able to initiate Z-Ray sessions (as that permission is provided with write access to Z-Ray).

Back to top

Administering Identity and Access Management in ZendHQ

ZendHQ now ships with a new command-line tool, zendhqctl. This tool provides an "access" module that allows listing services and permission information related to them, managing groups, and managing users.

The services exposed by ZendHQ are as folllows.

ZendHQ ServiceDescription
confUsed for accessing monitoring configuration.
monUsed for accessing monitoring events.
ctUsed for accessing code-traces.
zrayUsed for accessing Z-Ray requests, as well as initializing Z-Ray sessions.
jqUsed for accessing JobQueue queues and jobs.

Permissions are created using a bitmask. While these can be expressed as integers, you can also reference them using notation you're already familiar with: unix file permissions. For example, if you wanted to provide read-only access to monitoring, you'd use +r mon. If you wanted to provide the ability to initialize Z-Ray sessions and view history, you'd use +rw zray. To provide full access to JobQueue, you'd use +rwx jq.

A common request is to be able to define a read-only role. Let's create that, and assign it to a couple of users, Bob and Alice.

zendhqctl access group add readonly --permissions +r conf,mon,ct,zray,jq -c "Read-only group"

Breaking this down, we're creating the group "readonly". When we do, we're setting initial permissions to include "read" permissions to each of the services exposed. We are also providing a comment to associate with the group; this will be printed any time we print information for the group.

Now, let's define some users and assign them to this group:

zendhqctl access user add bob 
zendhqctl access user password bob #prompts to set the password 
zendhqctl access user add alice 
zendhqctl access user password alice # prompts to set the password 
zendhqctl access group add-user readonly alice,bob 

First we create each user, and assign them a password. Then we add both users to the "read-only" group.

There are a lot of different commands exposed by zendhqctl, and each contains copious documentation. Additionally, there are often multiple ways to accomplish something. For instance, in the above example, we could have instead called zendhqctl access user add-group alice readonly to add Alice to the read-only group. Read the zendhqctl access reference for full-details

Back to top

How Roles Affect Using ZendHQ

So, we know some basics of administering identity and access management in ZendHQ, but what does that mean when using the GUI administration tool?

First, for users who are upgrading to the new version, there's only one change that you'll notice at first. When you login, instead of having just the Hostname/IP and Token inputs:

ZendHQ Hostname / IP and Token login screen

You will now see a "User name" input, and "Token" becomes "User token" as well:

new zendhq login screen

But ZendHQ didn't have usernames previously! How do you login? For those upgrading, you can login without the username, using the configured ZendHQ token as you did previously. (Alternatively, you can specify the username "admin"!) ZendHQ is configured such that an "admin" role is already configured mimicing the permissions previously used, and using the admin token as configured by default with the service.

Once you have created users, you can now login as one of those users! To best see how this plays out in practice, view the following video.

Back to top

Wrapping Up

Different organizations have different access management needs for their developer and production tooling. The new role-based access support provided with ZendHQ allows organizations to define their own roles and the associated permissions. One side-benefit not mentioned previously is that users do not need to share credentials any longer, which also allows organizations to revoke access without having to change access for all users of the tool.

This is the first of a series of security features planned for ZendHQ. Future releases will build on the identity and access management provided with this release, enabling integration with business user directories.

Experience ZendHQ

Ready to see ZendHQ  monitoring, debugging, and automatiion features in person? Try free today with a ZendPHP/ZendHQ trial, or schedule a custom demo via the links below.

Try ZendHQ for Free  Schedule a Demo

Additional Resources

Back to top