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 caveats, serialize and deserialize a token, append more caveats, and validate those caveats in the context of a request:
```rust use biscuit::{crypto::KeyPair, token::{Biscuit, builder::*}};
fn main() { let mut rng = rand::thread_rng();
// let's generate the root key pair. The root public key will be necessary // to verify the token let root = KeyPair::new(&mut rng);
// 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(&mut rng, &root);
// let's define some access rights
// every fact added to the authority block must have the authority fact
builder.add_authority_fact(&fact("right", &[s("authority"), string("/a/file1.txt"), s("read")]));
builder.add_authority_fact(&fact("right", &[s("authority"), string("/a/file1.txt"), s("write")]));
builder.add_authority_fact(&fact("right", &[s("authority"), string("/a/file2.txt"), s("read")]));
builder.add_authority_fact(&fact("right", &[s("authority"), string("/b/file3.txt"), s("write")]));
// we can now create the token
let biscuit = builder.build().unwrap();
println!("biscuit (authority): {}", biscuit.print());
biscuit.to_vec().unwrap()
};
// 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).unwrap();
let mut builder = deser.create_block();
// caveats are implemented as logic rules. If the rule produces something,
// the caveat is successful
builder.add_caveat(&rule(
// the rule's name
"caveat",
// the "head" of the rule, defining the kind of result that is produced
&[s("resource")],
// here we require the presence of a "resource" fact with the "ambient" tag
// (meaning it is provided by the verifier)
&[
pred("resource", &[s("ambient"), string("/a/file1.txt")]),
// we restrict to read operations
pred("operation", &[s("ambient"), s("read")]),
],
));
let keypair = KeyPair::new(&mut rng);
// we can now create a new token
let biscuit = deser.append(&mut rng, &keypair, builder.build()).unwrap();
println!("biscuit (authority): {}", biscuit.print());
biscuit.to_vec().unwrap()
};
// this new token fits in 402 bytes assert_eq!(token2.len(), 402);
/*** VERIFICATION *****/
// 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 biscuit1 = Biscuit::from(&token1).unwrap();
let mut v1 = biscuit1.verify(root.public()).unwrap(); v1.addresource("/a/file1.txt"); v1.addoperation("read"); // we will check that the token has the corresponding right v1.addrule(rule("readright", &[s("read_right")], &[pred("right", &[s("authority"), string("/a/file1.txt"), s("read")])] ));
let mut v2 = biscuit1.verify(root.public()).unwrap(); v2.addresource("/a/file1.txt"); v2.addoperation("write"); v2.addrule(rule("writeright", &[s("write_right")], &[pred("right", &[s("authority"), string("/a/file1.txt"), s("write")])] ));
let mut v3 = biscuit1.verify(root.public()).unwrap(); v3.addresource("/a/file2.txt"); v3.addoperation("read"); v2.addrule(rule("readright", &[s("read_right")], &[pred("right", &[s("authority"), string("/a/file2.txt"), s("read")])] ));
// the first token, that specifies no restrictions, passes all verifiers: assert!(v1.verify().isok()); assert!(v2.verify().isok()); assert!(v3.verify().is_ok());
let biscuit2 = Biscuit::from(&token2).unwrap();
let mut v1 = biscuit2.verify(root.public()).unwrap(); v1.addresource("/a/file1.txt"); v1.addoperation("read"); // we will check that the token has the corresponding right v1.addrule(rule("readright", &[s("read_right")], &[pred("right", &[s("authority"), string("/a/file1.txt"), s("read")])] ));
let mut v2 = biscuit2.verify(root.public()).unwrap(); v2.addresource("/a/file1.txt"); v2.addoperation("write"); v2.addrule(rule("writeright", &[s("write_right")], &[pred("right", &[s("authority"), string("/a/file1.txt"), s("write")])] ));
let mut v3 = biscuit2.verify(root.public()).unwrap(); v3.addresource("/a/file2.txt"); v3.addoperation("read"); v2.addrule(rule("readright", &[s("read_right")], &[pred("right", &[s("authority"), string("/a/file2.txt"), s("read")])] ));
// the second 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()); } ```
A Biscuit token is made with a list of blocks defining data and caveats that must be validated upon reception with a request. Any failed caveat 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 caveats that can be implemented with that language:
Like Datalog, this language is based around facts and rules, but with some slight modifications:
A caveat rule requires the presence of one or more facts, and can have additional constraints on these facts (the constraints are implemented separately to simplify the language implementation: among other things, it avoids implementing negation). 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", "caveat1"], we could have the following rule: #4 <- #0("file.txt") & #1(#2)that would be printed ascaveat1 <- resoucr("file.txt") & operation(read)`
biscuit implementations come with a default symbol table to avoid transmitting frequent values with every token.
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.