Manage Biscuits with SxT CLI

These instructions detail managing authorization for your tables using the Space and Time CLI version 0.0.2. Space and Time uses biscuits for decentralized authorization. For more information on biscuits, see the Biscuit authorization page.

Note: you can run the help command at any point to display information about the specified command. Example:

sxtcli help

Output:

Usage: <main class> [COMMAND]
Commands:
  help          Display help information about the specified command.
  authenticate  Perform platform authentication commands.
  biscuit       Perform biscuit commands.
  discover      Perform resource discovery commands.
  sql           Perform SQL commands.
  sql-support   Perform supporting SQL commands.

And for biscuit:

sxtcli biscuit help 

Usage: <main class> biscuit [COMMAND]
Perform biscuit commands.
Commands:
  help      Display help information about the specified command.
  keypair   Generate (or regenerate) a biscuit key pair.
  generate  Generate a biscuit.

Step 1: Generate key pair

❗️

Note: this keypair is entirely separate from the keypair you generated for yourself when you authenticated to Space and Time.

Think about it this way: you have your own keypair for authenticating, and your tables have thier own keypair for authorizing access. Just like with your own keypair, always keep your table's private key private and secure. You'll share the public key to authorize access.

Generating a new key pair to create biscuits for your tables is easy:

sxtcli biscuit keypair

Save your private key somewhere safe, like a password manager. You'll also need it for the next step.

Step 2: Generate a Biscuit

sxtcli biscuit generate help table                                                                                  

Usage: <main class> biscuit generate table
Generate a database table biscuit.
      --operations=<_operations>[,<_operations>...]...
                    The set of desired SQL operations to include (multiple
                      values should be comma separated). Valid options:
                      [CREATE, ALTER, DROP, INSERT, UPDATE, MERGE, DELETE,
                      SELECT]
      --privateKey=<_privateKey>
                    The private key (NOTE: does not leave your machine)
      --readOnly    Allow all read-only operations
      --readWrite   Allow all read-write operations
      --resources=<_resources>[,<_resources>...]...
                    The set of desired tables to include (multiple values
                      should be comma separated)

To generate a biscuit for a table, you'll need your privateKey from above, and the resourceId you want to provide authorization too. ResourceId is simply the SCHEMA.TABLE. Please note, you can specify a single resourceId or multiple comma-separated resourceIds, as seen below.

sxtcli biscuit generate table --privateKey=$b_priv_key --resources="<SCHEMA>.<TABLE_1>,<SCHEMA>.<TABLE_2>" --operations="SELECT,INSERT,UPDATE"

The command will return a biscuit!

EvQCCokCCgpjYXBhYmlsaXR5CgpkZGxfY3JlYXRlChVzZV90dXRf...

With that command, there is something important going on behind the scenes. The SxTCLI also embeds a series of capability facts into the biscuit token. For example, the following capabilities can be decoded from the token:

sxt:capability("dml_insert", "my_schema.my_table_1");
sxt:capability("dml_insert", "my_schema.my_table_2");
sxt:capability("dml_update", "my_schema.my_table_1");
sxt:capability("dml_update", "my_schema.my_table_2");
sxt:capability("dql_select", "my_schema.my_table_1");
sxt:capability("dql_select", "my_schema.my_table_2");

Save your biscuit. You will need it later for different interactions with your table(s) on SxT.

Step 3: Generate CREATE TABLE statement

📘

This step simply generates a sample SQL CREATE TABLE statement for you. It does not create a new resource in the Space and Time data warehouse.

sxtcli sql-support table-authz --accessType="PUBLIC_READ" --privateKey=$b_PRI_KEY --resourceId="MY_SCHEMA.MY_TABLE_1"

Biscuit: Eq8BCkUKDnN4dDpjYXBhYmlsaXR5CgpkZGx.....==
Table create DDL: CREATE TABLE MY_SCHEMA.MY_TABLE_1 (ID INT, NAME VARCHAR, PRIMARY KEY (ID)) WITH "public_key=D94F936D8431797F132C92B047F4F5AC0A47931A31FE8F8582F236FAFE0F53CD,access_type=public_read"

You can create a table with the configure resources DDL endpoint with query returned above.