Initializing the Workspace
PermGuard provides a Command Line Interface (CLI) for managing authentication metadata (AuthN) and authorization metadata and configurations (AuthZ) for Zones.
- AuthN administration is handled through the CLI.
- AuthZ administration is managed via both the CLI and the Policy Language.
The authorization process follows a code-first approach. When working with Schemas and Policies, the CLI must be executed from a PermGuard workspace that contains configuration files written in Cedar.
Creating a PermGuard Workspace
There are three ways to create a PermGuard workspace and associate it with a PermGuard ledger:
- Initialize a new ledger in a PermGuard workspace.
- Clone an existing ledger into a PermGuard workspace.
- Fork an existing ledger into a working directory.
Workspace Structure
A PermGuard workspace contains the following files:
- Policy files written in the
Cedar
language. - A hidden
.permguard
directory, used by PermGuard to store metadata and intermediate files.- This directory is automatically managed by PermGuard and should not be modified manually.
- It should be added to
.gitignore
to prevent it from being committed to version control.
Initialize a New Ledger
When starting a new project, the first step is to create a zone:
permguard zones create --name magicfarmacia-dev --output json
{
"zones": [
{
"zone_id": 268786704340,
"created_at": "2024-08-25T14:07:59.634Z",
"updated_at": "2024-08-25T14:07:59.634Z",
"name": "magicfarmacia-dev"
}
]
}
Next, create a ledger:
permguard authz ledgers create --zoneid 268786704340 --name magicfarmacia --output json
{
"ledgers": [
{
"ledger_id": "668f3771eacf4094ba8a80942ea5fd3f",
"created_at": "2024-08-25T14:50:38.003Z",
"updated_at": "2024-08-25T14:50:38.003Z",
"zone_id": 268786704340,
"name": "magicfarmacia"
}
]
}
Finally, initialize the workspace and associate it with a Permguard remote
server:
permguard init
permguard remote add origin localhost
permguard checkout origin/273165098782/magicfarmacia
Clone an existing ledger
In advanced cases, a PermGuard ledger may already exist, and it may be necessary to recover the configuration files to a local PermGuard workspace.
To do this, simply clone the existing PermGuard ledger:
permguard clone origin/273165098782/magicfarmacia