Announcing: Advanced Roles and Permissions

Keygen's role-based access control (RBAC) system hasn't changed much since 2016. Since our launch, we've only introduced a handful roles, each with a fixed permission set. It all started with user and admin, and then we added a product role, and then a license role. We've always tried to keep roles simple and straight-forward.

With each new role came different forms of authentication, and along with that, different levels of authorization.

Over the years, we've introduced a few new administrative roles, with their own unique permission set: support-agent, sales-agent and developer. These are essentially admins, but with less permissions.

We always wanted to do away with those last 3 roles and allow our customers to create admins with custom permission sets, essentially making those last few roles redundant. For example, we could recreate the developer role by creating an admin that can do everything except read and modify the account's billing information.

(Permissions weren't exposed via the API, but they've always been there.)

Although we didn't like introducing those 3 additional roles (because they broke our idea of keeping things simple), they were a good stop-gap for what was to come.

So, without further ado…

Today, we're excited to announce a powerful new permission system built on top our RBAC system. The permission system is currently available on our Ent tiers, the first of a handful of new enterprise-grade features that we'll be rolling out.

When creating new users, licenses, products and tokens via the API (or UI), you can now assign a custom permissions set to the new object:

curl -X POST https://api.keygen.sh/v1/accounts/demo/users \
  -u 'token:prod-4bb8293179294f72d0ad352449dce6c16b9ca2607af870fed8127v3' \
  -d '{
        "data": {
          "type": "users",
          "attributes": {
            "firstName": "Dustin",
            "lastName": "Henderson",
            "email": "[email protected]",
            "password": "neverendingstory",
            "role": "user",
            "permissions": [
              "license.validate",
              "license.read",
              "machine.create",
              "machine.delete",
              "user.read"
            ]
          }
        }
      }' 
curl -X POST https://api.keygen.sh/v1/accounts/demo/users \
  -u 'token:prod-4bb8293179294f72d0ad352449dce6c16b9ca2607af870fed8127v3' \
  -d '{
        "data": {
          "type": "users",
          "attributes": {
            "firstName": "Dustin",
            "lastName": "Henderson",
            "email": "dustybun@netflix.example",
            "password": "neverendingstory",
            "role": "user",
            "permissions": [
              "license.validate",
              "license.read",
              "machine.create",
              "machine.delete",
              "user.read"
            ]
          }
        }
      }' # [tl! highlight:-9,7]
content_copy

The above creates a new user that's only allowed to validate and read licenses, activate and deactivate machines for their license, and read their own user object. Even though the user role by default allows much more than that, we've limited what they can do. Any other action will result in a 403 Forbidden API error.

Permissions are applied to the object itself, and are inherited by all of the object's tokens as well. For example, if you created a license with the license.validate and license.read permissions, all of the license's tokens would also inherit and intersect that permission set. In addition, the permission set would also be applied when using tokenless schemes, like license key authentication.

Using custom permissions, we could create a new admin that can only read specific resources, essentially creating the much coveted read-only admin object.

(We use read-only permissions for demos!)

Or perhaps you want to create a Keygen admin for your accounting department, one that can only read and operate on the account's billing information.

Or you could create a product token with a limited set of permissions for server-side use, e.g. grant a token the license.suspend permission for a micro-service that deals with suspending overdue licenses.

We built the permission system with all of these scenarios in mind, with the overarching goal to enhance the security of our enterprise customers and of their integrations, and we hope you can utilize the system to accomplish that goal.

Let us know if you have any feedback. We're all ears.

Until next time.

p.s. We'll be digging into how we handle authorization soon. If you're a fan of Ruby on Rails, and Pundit for authz, you'll want to keep your eyes peeled.