Search
Varnish Controller

Organizations

Introduction

This tutorial goes through how to create a new organization, add an initial user and then add more users to the organization. It will also show how to manage users and their permissions.

Prepare Environment

The following steps assumes a running brainz, api-gw, NATS and a PostgreSQL database. We don’t really need any agents or routers for this tutorial as we only manage the auth system parts.

# Login towards the API-GW
vcli login https://api-gw -u test

New Organization

In order to create a new organization we need to login with a system admin user. A system admin account is the only account that can add new organizations and also assign the first user to an organization.

# Create the new organization called 'myOrg'
vcli org add myOrg

We could also create the organization with a bit more configuration options:

# Create the organization with custom access and refresh token 
# expiration. Also lock the organization so no one can login.
vcli org add myOrg --access-expire 60m --refresh-expire 24h --lock

An organization can be updated after creation with the above settings.

# Update access token expiration to 10m and unlock the organization to allow logins.
# '1' is the ID of the previously created organization (vcli org ls).
vcli org update 1 --access-expire 10m --lock=false

Create and Assign First User

Now when the organization is created we need to create a user that should be responsible for the organization.

The first user assigned to a new organization will have full read/write permissions for that organization.

# Create the account 'magnus' with the password 'mysecret'
vcli account add magnus --password mysecret

# Now assign the user to our organization 
# '1' is the organization ID of 'myOrg' (vcli org ls)
# '2' is the user ID of 'magnus' (vcli account ls)
vcli org assign 1 --account 2

When listing the organization this would be the expected output (ID’s can differ):

$ vcli org ls                  
+----+-------+-----------+--------+------------+-------------+--------+---------------------+---------------------+
| ID | Name  | Accounts  | IDP ID | Access TTL | Refresh TTL | Locked |       Created       |       Updated       |
+----+-------+-----------+--------+------------+-------------+--------+---------------------+---------------------+
|  1 | myOrg | magnus(2) |      0 | 5m0s       | 24h0m0s     | false  | 2022-03-17 14:19:35 | 2022-03-17 14:19:35 |
+----+-------+-----------+--------+------------+-------------+--------+---------------------+---------------------+

Login and Create New User

Now login with the new user that have full permissions for all resources of the organization. This also incudes accounts. The new user ‘magnus’ can only create regular users, not system admin users.

When the user ‘magnus’ is logged in to the org ‘myOrg’ and creates a new user, the new user will only have access to the organization ‘myOrg’. A newly created account, created by a regular user, will only have very basic permissions for resources. A user can be part of multiple organizations and have different permissions within these organizations.

# Login as the new user
vcli login -u magnus -o myOrg

# Create the new user 
vcli account add dude --password secret

To verify that the user now only have basic permissions we can list the permissions for the account.

# The new user 'dude' has the ID 3 here (vcli account ls)
$ vcli perm ls -f account_id=3
+----+---------------+---------+----------+------+-------+---------------------+---------------------+
| ID | Resource Type | Account |   Org    | Read | Write |       Created       |       Updated       |
+----+---------------+---------+----------+------+-------+---------------------+---------------------+
| 19 | agent         | dude(3) | myOrg(1) | true | false | 2022-03-17 14:36:20 | 2022-03-17 14:36:20 |
| 20 | router        | dude(3) | myOrg(1) | true | false | 2022-03-17 14:36:20 | 2022-03-17 14:36:20 |
| 21 | tag           | dude(3) | myOrg(1) | true | false | 2022-03-17 14:36:20 | 2022-03-17 14:36:20 |
+----+---------------+---------+----------+------+-------+---------------------+---------------------+

Manage Permissions

A user with write permission for ‘perm’ can update permissions for users of that organization. In this case ‘magnus’ has the rights to update permissions (remember that ‘magnus’ was the first assigned organization account with full permissions).

Add read permissions for the account ‘dude’ to ‘logentry’ so that the user can read Varnish Controller logs.

vcli perm add logentry -a 3 --read

Listing permissions for the ‘dude’ account the ‘logentry’ permission has been added.

$ vcli perm ls -f account_id=3      
+----+---------------+---------+----------+------+-------+---------------------+---------------------+
| ID | Resource Type | Account |   Org    | Read | Write |       Created       |       Updated       |
+----+---------------+---------+----------+------+-------+---------------------+---------------------+
| 19 | agent         | dude(3) | myOrg(1) | true | false | 2022-03-17 14:36:20 | 2022-03-17 14:36:20 |
| 20 | router        | dude(3) | myOrg(1) | true | false | 2022-03-17 14:36:20 | 2022-03-17 14:36:20 |
| 21 | tag           | dude(3) | myOrg(1) | true | false | 2022-03-17 14:36:20 | 2022-03-17 14:36:20 |
| 22 | logentry      | dude(3) | myOrg(1) | true | false | 2022-03-17 14:40:35 | 2022-03-17 14:40:35 |
+----+---------------+---------+----------+------+-------+---------------------+---------------------+

Lock Accounts

Accounts can be locked so that they can no longer login. This is a easier way to block accounts instead of changing permissions for the account.

Lock the account ‘dude’ from logging in:

vcli account update 3 --lock

Now when the user ‘dude’ tries to login, the login attempt will fail.

vvcli login -u dude -o myOrg 
...
Error: account dude(3) is locked (401)
...

Just as easy can we unlock the account again.

vcli account update 3 --lock=false

References

A less comprehensive guide for authorization and authentication can be found here.