Biscuit is an authorization token for microservices architectures with the following properties:
Non goals:
In this example we will see how we can create a token, add some checks, serialize and deserialize a token, append more checks, and validate those checks in the context of a request:
```rust extern crate rand; extern crate biscuit_auth as biscuit;
use biscuit::{crypto::KeyPair, token::{Biscuit, verifier::Verifier, builder::*}, error};
fn main() -> Result<(), error::Token> { // let's generate the root key pair. The root public key will be necessary // to verify the token let root = KeyPair::new(); let public_key = root.public();
// creating a first token let token1 = { // the first block of the token is the authority block. It contains global // information like which operation types are available let mut builder = Biscuit::builder(&root);
// let's define some access rights
// every fact added to the authority block must have the authority fact
builder.add_authority_fact("right(#authority, \"/a/file1.txt\", #read)")?;
builder.add_authority_fact("right(#authority, \"/a/file1.txt\", #write)")?;
builder.add_authority_fact("right(#authority, \"/a/file2.txt\", #read)")?;
builder.add_authority_fact("right(#authority, \"/b/file3.txt\", #write)")?;
// we can now create the token
let biscuit = builder.build()?;
println!("biscuit (authority): {}", biscuit.print());
biscuit.to_vec()?
};
// this token is only 266 bytes, holding the authority data and the signature assert_eq!(token1.len(), 266);
// now let's add some restrictions to this token
// we want to limit access to /a/file1.txt and to read operations
let token2 = {
// the token is deserialized, the signature is verified
let deser = Biscuit::from(&token1)?;
let mut builder = deser.create_block();
// checks are implemented as logic rules. If the rule produces something,
// the check is successful
// here we verify the presence of a `resource` fact with a path set to "/a/file1.txt"
// and a read operation
builder.add_check("check if resource(#ambient, \"/a/file1.txt\"), operation(#ambient, #read)")?;
let keypair = KeyPair::new();
// we can now create a new token
let biscuit = deser.append(&keypair, builder.build())?;
println!("biscuit (authority): {}", biscuit.print());
biscuit.to_vec()?
};
// this new token fits in 402 bytes assert_eq!(token2.len(), 402);
/*** VERIFICATION *****/
// let's deserialize the token: let biscuit2 = Biscuit::from(&token2)?;
// let's define 3 verifiers (corresponding to 3 different requests): // - one for /a/file1.txt and a read operation // - one for /a/file1.txt and a write operation // - one for /a/file2.txt and a read operation
let mut v1 = biscuit2.verify(publickey)?; v1.addresource("/a/file1.txt"); v1.add_operation("read");
// a verifier can come with allow/deny policies. While checks are all tested // and must all succeeed, allow/deny policies are tried one by one in order, // and we stop verification on the first that matches // // here we will check that the token has the corresponding right v1.add_policy("allow if right(#authority, \"/a/file1.txt\", #read)"); // default deny policy, equivalent to "deny if true" v1.deny();
let mut v2 = biscuit2.verify(publickey)?; v2.addresource("/a/file1.txt"); v2.addoperation("write"); v2.addpolicy("allow if <- right(#authority, \"/a/file1.txt\", #write)"); v1.deny();
let mut v3 = biscuit2.verify(publickey)?; v3.addresource("/a/file2.txt"); v3.addoperation("read"); v3.addrule("allow if right(#authority, \"/a/file2.txt\", #read)"); v1.deny();
// the token restricts to read operations: assert!(v1.verify().isok()); // the second verifier requested a read operation assert!(v2.verify().iserr()); // the third verifier requests /a/file2.txt assert!(v3.verify().is_err());
Ok(()) } ```
A Biscuit token is made with a list of blocks defining data and checks that must be validated upon reception with a request. Any failed check will invalidate the entire token.
If you hold a valid token, it is possible to add a new block to restrict further the token, like limiting access to one particular resource, or adding a short expiration date. This will generate a new, valid token. This can be done offline, without asking the original token creator.
On the other hand, if a block is modified or removed, the token will fail the cryptographic signature verification.
Biscuit tokens get inspiration from macaroons and JSON Web Tokens, reproducing useful features from both:
We rely on a modified version of Datalog, that can represent complex behaviours in a compact form, and add flexible constraints on data.
Here are examples of checks that can be implemented with that language:
Like Datalog, this language is based around facts and rules, but with some slight modifications:
A check rule requires the presence of one or more facts, and can have additional expressions on these facts. It is possible to create rules like these ones:
To reduce the size of tokens, the language supports a data type called "symbol". A symbol is a string that we can refer to with a number, an index in the symbol table that is carried with the token. Symbols can be checked for equality, or presence in a set, but lack the other constraints on strings like prefix or suffix matching.
They can be used for pretty printing of a fact or rule. As an example, with a table containing ["resource", "operation", "read", "rule1"], we could have the following rule: #4 <- #0("file.txt") & #1(#2) that would be printed as rule1 <- resource("file.txt"), operation(read)
biscuit implementations come with a default symbol table to avoid transmitting frequent values with every token.
This project can generate C bindings with cargo-c.
compile it with:
cargo cinstall --prefix=/usr --destdir=./build
Run C integration tests with:
cargo ctest
Licensed under Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be licensed as above, without any additional terms or conditions.