Biscuit authorization
Space and Time relies on biscuits to support decentralized authorization. This page describes how biscuits are used in the platform.
To learn more about biscuit authorization and generating biscuits, check out this blog post.
Background
Biscuits are used to authorize access to resources (e.g. tables) and are associated with a public/private key pair. Public keys are provided when the user creates a resource and are used to validate biscuit signatures during request authorization. Users create and attenuate their own tokens (using the corresponding private key) without involving the platform. A biscuit must contain, at minimum, a single capability specifying what operation is allowed on which resource.
For more information on biscuits, please see the official Biscuit documentation.
Public Key Cryptography
Biscuit authorization is based on public key cryptography, meaning each biscuit is associated with a public key and private key. The private key is used to sign the biscuit during creation, and the public key is used to validate the biscuit. When creating a table, you must specify a public key. It will be used to validate signatures on all biscuits provided during request authorization thereafter, and the public key cannot be changed. Make sure to keep your private key safe, as anyone with access can generate biscuits with any level of authority.
Biscuit public/private keys are independent of user public/private keys. Do not use the keypair you use for authentication for resource authorization.
Biscuit Standards
This section outlines the biscuit standards supported by Space and Time.
We are working on adding new standards to enable even more authorization support. Check back soon!
Operation
Operations define what action is being performed in a request. They are defined as follows:
operation($operation);
The $operation
must be a string and match one of the below:
- SQL operations:
- DDL: for operating on database objects & schema (e.g. table, view)
ddl_create
: SQLCREATE
commandddl_alter
: SQLALTER
commandddl_drop
: SQLDROP
command
- DML: for performing data manipulation
dml_insert
: SQLINSERT
commanddml_update
: SQLUPDATE
commanddml_merge
: DQLMERGE
commanddml_delete
: SQLDELETE
command
- DQL: for performing queries
dql_select
: SQLSELECT
command
- DDL: for operating on database objects & schema (e.g. table, view)
- Kafka ICM operations:
kafka_icm_create
: ICM createkafka_icm_read
: ICM readkafka_icm_update
: ICM updatekafka_icm_delete
: ICM delete
Resource
Resourced define what is being accessed in a request. They are defined as follows:
resource($resource);
The $resource
must be a lowercase string and match a valid, existing resource.
- SQL resources: It must include the full resource identifier (i.e., it must include both the namespace and resource name). As an example, the Transactions table in the ETH namespace would be
eth.transactions
. - Kafka ICM resources:
kafka_icm_infrastructure_group
: Kafka infrastructure groupskafka_icm_user
: Kafka userskafka_icm_acl
: Kafka ACLskafka_icm_topic
: Kafka topicskafka_icm_topic_mapping_config
: Kafka topic mapping configuration
Capability
Capabilities define what operation is allowed on a given resource, enabling easy specification of a operation-resource matrix. They are defined as follows:
capability($operation, $resource);
The $operation
must conform to Operation requirements, and the $resource
must conform to Resource requirements.
Working with Biscuits
Biscuit manipulation (creating, testing, attenuating, etc.) does not involve the platform, meaning you can create biscuits however you want, whenever you want. Please refer to the biscuit cli guide for more details on how to operate on biscuits on your local machine. The only requirement to create a biscuit is to have access to the appropriate private key. If you use the wrong private key, your biscuit signature won't be valid for the desired table.
Let's say you just created a table called TEST.CUSTOMER
and want to give yourself read-write access. You would specify the following payload in your biscuit:
capability("dql_select", "test.customer");
capability("dml_insert", "test.customer");
capability("dml_update", "test.customer");
capability("dml_delete", "test.customer");
If you later decide you want to give your friend access to query your table, you have two options. You can either generate a new biscuit with only the dql_select
capability, or you can attenuate your existing biscuit. Note that biscuits can never grow in scope, they can only become more restrictive (i.e., attenuated). So if you share a biscuit with someone else, they can never add new capabilities!
Namespacing
Biscuit specifications allow for namespacing facts. We're working on adding namespacing support across the platform for all SxT standards to help prevent potential future collisions. We'll work with Controlled Release customers when it's time to transition, but in case you're wondering what our updated namespaces will look like, see the below (we're just adding the sxt:
prefix):
sxt:operation($operation);
sxt:resource($resource);
sxt:capability($operation, $resource);
Updated 2 days ago