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:

1. Initialize a new ledger in a Permguard workspace.
2. Clone an existing ledger into a Permguard workspace.
3. 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

Below is the output of the command.

{
  "zones": [
    {
      "zone_id": 273165098782,
      "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 --zone-id 273165098782  --name magicfarmacia --output json

Below is the output of the command.

{
  "ledgers": [
    {
      "ledger_id": "668f3771eacf4094ba8a80942ea5fd3f",
      "created_at": "2024-08-25T14:50:38.003Z",
      "updated_at": "2024-08-25T14:50:38.003Z",
      "zone_id": 273165098782,
      "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 localhost/273165098782/magicfarmacia