It seems like your browser didn't download the required fonts. Please revise your security settings and try again.
Barracuda CloudGen Access

How to Use the Admin API

  • Last updated on

You can manage your administrators and view user activity via the Admin API. For installation instructions for access-cli, see https://github.com/barracuda-cloudgen-access/access-cli#installation.

Command Help

All commands provide a help text with the available sub-commands and flags. For example, running access-cli admins will let you know about the getlistaddedit and delete sub-commands, and access-cli admins edit --help will list all available flags for the edit admins command, including pagination, sorting, and filtering flags.

list command

List all the account administrators:

access-cli admins list

help command

The help flag tells you the things you can change:

access-cli admins edit --help
edit command

The edit command allows you to edit the information:

access-cli admins edit 755 —name ‘FirstName LastName’
create command

The create command lets you create new admins:

access-cli admins create --name 'Oliver Brown' --email 'obrown@acme.com' --password 'ThisIsATest123' --roles admin

You can also edit the admin roles. It is possible to assign multiple roles to the admin. Here are the current admin roles:

  • owner – Has access to all the APIs, including the Administrator API.
  • owner_ro  Has access to all the APIs, including the Administrator API, but only for listing and searching. Modification, creation, or deletion is not permitted.
  • admin – Has access to all APIs except the Administrator API. It cannot list, add, modify, or delete admins.
  • admin_ro – Has the same logic as the owner_ro. It is a read-only admin. Modifications are not permitted.
  • moderator – Has access to all APIs except for the User, Groups, and Administrator API (cannot add, modify, or remove users, groups or admins).
  • enrollment  Has access to listing and searching users, and to manipulate everything related to device enrollments (create a new enrollment link, delete it, add more allowed devices to an existing enrollment link, and send enrollment emails).
  • evaluate_resource – Useful for service accounts. It only allows access to the evaluate_resource API (used for troubleshooting).
  • read_events – Only has access to the records objects (the Activity menu on the web console). It is useful for service accounts configured to export records through our CLI to later import them into a SIEM solution.
access-cli admins edit 756 --roles admin_ro,enrollment

Specify the new authentication type for the admin:

access-cli admins edit --authn-type sso
delete command

The delete command lets you delete admins:

access-cli admins delete 756

user command

The user command has access to all users. It can list, add, modify, or delete users for a tenant.  This command gives a list of users that match the email address given. The result is in json format. 

access-cli users list -q stran@thisdomain.com -o json

records command

The records command can only list events, and you can filter for attributes. You can get particular events by their id, list a range of events using the provided filters, or watch events as they come in. You will not be able to modify events or create new ones with access-cli.

If you run the help on the access-cli records list command, you get the filter options. 

 myUsername@ENG-myUsername-MB ~ % access-cli records list -h
 List records
 
 Usage:
  access-cli records list [flags]
 Aliases:
  list, ls
 Flags:
  --range-start int start of the range of items to return (default 1)
  --range-end int end of the range of items to return (0 to return all items past range-start) (default -1)
  --list-all list all items. Alias for --range-start=1 --range-end=0
  --sort string sort output. Possible options include: id_{asc|desc}, name_{asc|desc}, created_{asc|desc}, updated_{asc|desc}
  --filter-event-name strings filter output event-name
  --filter-user-id int filter output user-id
  --filter-from-date string filter output from-date
  --filter-to-date string filter output to-date
  -o, --output string output format (table, json, json-pretty or csv) (default "json" if pipe) (default "table")
  -t, --tenant string tenant ID to perform operation on
  -h, --help help for list


Use case example: export user web surfing activity (allow and denied) web access

Begin by getting the userid. The users command  gives a list of users that match the email address "stran@thisdomain.com". On macOS, the jq tool extracts information from the result set, and this command 
is piped to the access-cli command, operating on the returned json:

pjones@ENG-PJONES-MB ~ % MY_USER=$(access-cli users list -q stran@thisdomain.com -o json | jq -r '.[0].id') 

The jq tool looks for the first item in the returned list and gets its 'id' key, which is the user id wanted in this example. This id is saved to the bash MY_USER variable, which can be accessed with the $ operator. Filter all events by only getting the events for this userid you just saved:

--filter-user-id $MY_USER 

Furthermore, you can filter for event names that are of interest to you for this user:

--filter-event-name domainAllowed,domainBlocked

This would only look for all allowed and blocked domains that are triggered by hitting the configured web security policies on that account. Here is a list of event names that you can filter for:

accessProxyAdmittance, domainAllowed, domainBlocked, ssoAdmittance, tunnelState

This example combines the users command to get the user_id with the records command to get events of interest for this particular user.

 pjones@ENG-PJONES-MB ~ % access-cli records list --filter-user-id $MY_USER --filter-event-name domainAllowed,domainBlocked
 +----------------------------------------+----------------+--------------+--------------------------+
 | ID | Name | User | Date |
 +----------------------------------------+----------------+--------------+--------------------------+
 | 03a9bab22169f53d3d6fe40d4bcc195ef3cc2f | domain_blocked | Sue Tran | 2023-07-06T19:34:05.000Z |
 |
 | 77aa9e13ddf711c21500041536 | | | |
 | d10bac0d00fcb6af35d1974ed4dfa78b426ef7 | domain_blocked | Sue Tran | 2023-07-05T13:38:05.000Z |
 | 044b9ec1665b256b4177c92cec | | | |
 +----------------------------------------+----------------+--------------+--------------------------+
 (20 records out of 726)

Now you can be even more specific by giving this a date range (by default it looks for the last 30 days of events):

--filter-from-date '2023-07-05' --filter-to-date '2023-07-06'

This returns all events from July 5th up to July 6th, excluding any events on July 6th itself. Here is a combined example of all the filters above:

 access-cli records list --filter-user-id $MY_USER --filter-event-name domainAllowed,domainBlocked --filter-from-date '2023-07-05' --filter-to-date '2023-07-06'
 +----------------------------------------+----------------+--------------+--------------------------+
 | ID | Name | User | Date |
 +----------------------------------------+----------------+--------------+--------------------------+
 | 0a1093867d2576fe025bdefd26e27a9285ac45 | domain_blocked | Sue Tran | 2023-07-05T20:18:04.000Z |
 | 
 | a52984424074144036fb9aaefc | | | |
 | 3818e3c76d64451eda2e4f2af55208b9fa21d3 | domain_blocked | Sue Tran | 2023-07-05T02:09:19.000Z |
 | c3e41f848e2d8cc5e416addcff | | | |
 +----------------------------------------+----------------+--------------+--------------------------+
 (17 records)