Authorizer is hard to handle

[amias-channer]

Hello All ,

Thanks for biscuits , its fascinating and very powerful :)

I'm getting my head round it but something i'm finding hard to handle is the way the authorizer signals success of failure.

if i pass an authorization i get back a zero , this feels wrong , shouldn't it be True or 1 ?

if i fail an authorization i get an exception , which is kind of ok but its not the opposite of what happens on success.
The exception seems to be of a type that will cause a try: except block to emit another error.

Traceback (most recent call last):
File "C:\Users\me\PycharmProjects\unicorn\biscuit.py", line 118, in
except biscuit_auth.UnverifiedBiscuit as e:
TypeError: catching classes that do not inherit from BaseException is not allowed

I get that this is wrapped from rust so options are limited , i would have patched this if i understood how the shimming works, but it feels like this would be much easier to use if it authorizer.authorize() return a boolean.

if you need exception handling inside the method then maybe just wrap the method in its own try except block so that it catches the exception itself and returns false , then we get very solid true or false behaviour which is easier to work with than one sided exceptions.

I also thought i should raise this now before you release the new version so it could be part of that.

I am software tester so i'd be happy to help with the new release somehow.

[amias-channer]

ok its less bad when i fix my exception handler to catch the right exception , doh

try:
    authorizer.authorize()
except AuthorizationError as e:
    print(f"UNVERIFIED: {e}")

but it still feels wrong that its raising exceptions for this at all. consider how you have to handle it

try:
     if authorizer.authorize()
           # doesn't happen because of the zero
     else:
           # where you do authed things
except:
    # do  the non auth things

when it could just be

 if authorizer.authorize()
        # authed 
else:
         # not authed

[divarvel]

the result of .authorize() is the index of the matched policy. if you don’t care about which allow policy matched, you can use

try:
    authorizer.authorize()
    # success goes here
except:
    # error handling goes here

I would argue that using exceptions is more pythonic than returning a boolean. That being said, just returning the policy index seems to be counter intuitive, we could instead return a structure representing a successful authorization (eg containing the actual policy as a string).

In any case, returning a boolean as the result of .authorize() is imo the wrong thing to do as it provides less context for authz errors and mixes different things (something unexpected happend with the token contents is different than everything evaluated as expected, but the request is not authorized), and requires explicit checking by the caller (compared to having the exception interrupt the flow.

[amias-channer]

thanks for the quick response , i had a slight suspicion is was a count that makes a lot more sense now.

I don't recall seeing this in the documentation and i think it would help a lot.

yes , i think a structured response might be a lot easier to use.

At the moment as i'm trying my various test pieces i am using the string dump of the authorizer to understand how my datalog is being understood and its helped me get past some results i didn't understand.

so is it correct that if i have 3 'allow ifs' then i should be expecting to get 3 back from authorize if all passed ?

[divarvel]

so is it correct that if i have 3 'allow ifs' then i should be expecting to get 3 back from authorize if all passed ?

allow if and deny if (policies) are tried in order, so the first one that matches will determine the authorization result (assuming all checks have passed).

So if you want to make sure that multiple conditions are successful, you need to either put it in the same allow if block, or in check if blocks.

If you want to try out datalog semantics, it might be simpler to use the playground: https://www.biscuitsec.org/docs/tooling/datalog-playground/

The API reference mentions that .authorize() returns the matched policy index: https://python.biscuitsec.org/api-reference#biscuit_auth.Authorizer.authorize but a class with proper fields will make it explicit

[amias-channer]

i have only ever got a 0 back from the auth or an exception despite having multiple matching checks and allows

Heres a string dump of the authorizer

Authorizer: // Facts:
// origin: 0
actions("Download Once", "Add to Random Radio", "Stream Once", "Stream Anytime");
owner("OUR UNIQUE CREATOR ID");
release("OUR UNIQUE RELEASE ID");
// origin: 2
action("Stream Once");
end(2025-03-12T11:32:52Z);
entity(1);
hostname("creatorhost.unicorn");
release(1);
start(2025-03-10T23:32:52Z);
time(2025-03-11T11:32:52Z);
// origin: authorizer
action("Stream Once");
end(2025-03-12T11:32:52Z);
entity(1);
hostname("creatorhost.unicorn");
release(1);
right(1, 1, "Add to Random Radio");
right(1, 1, "Download Once");
right(1, 1, "Stream Once");
right(1, 2, "Add to Random Radio");
right(1, 2, "Download Once");
right(1, 2, "Stream Once");
start(2025-03-10T23:32:52Z);
time(2025-03-11T11:32:52Z);

// Checks:
// origin: 0
check if release("OUR UNIQUE RELEASE ID");
check if owner("OUR UNIQUE CREATOR ID");
// origin: 1
check if action("Stream Once");
check if hostname("creatorhost.unicorn");
// origin: 2
check if time(2025-03-11T11:32:52Z), time(2025-03-11T11:32:52Z), 2025-03-11T11:32:52Z > 2025-03-10T23:32:52Z, 2025-03-11T11:32:52Z < 2025-03-12T11:32:52Z;

// Policies:
allow if right(1, 1, "Stream Once"), hostname("creatorhost.unicorn"), action("Stream Once"), time(2025-03-11T11:32:52Z), time(2025-03-11T11:32:52Z), 2025-03-11T11:32:52Z > 2025-03-10T23:32:52Z, 2025-03-11T11:32:52Z < 2025-03-12T11:32:52Z;
deny if time(2025-03-11T11:32:52Z), time(2025-03-11T11:32:52Z), 2025-03-11T11:32:52Z > 2025-03-12T11:32:52Z, 2025-03-11T11:32:52Z < 2025-03-10T23:32:52Z;

no matter how i arrange the checks and allows i can never get more than zero back , i had the allows as separate allows before with the same result. 0

Thanks for your continued indulgence :)

[amias-channer]

doesn't the exception also mean you can never know about deny rules ? if they match it stops the authorizer returning at all.

if i change this example to make the deny rule always fail the authorization ( switching the time constraint) then i get an exception 'AuthorizationError' but no way to know why.

It seems important to be able to know these things about the authorization to allow multiple paths to auth

[amias-channer]

i only get 0 because i'm only using one allow if and it is the zeroth one

[divarvel]

i only get 0 because i'm only using one allow if and it is the zeroth one

Exactly.

doesn't the exception also mean you can never know about deny rules ? if they match it stops the authorizer returning at all.

The rust library collects all failed checks and indeed stops at the first matching policy (be it deny of allow). So in case of success, you only need to know the policy id (which is always an allow policy).

In the case of error you are in one of these cases

• datalog evaluation encountered an error
• no policy matched and possibly failed checks
• a deny policy matched and possibly failed checks
• an allow policy matched and at least one failed check

The python library does not expose it for now, so I guess it would be good to have:

• An AuthorizationSuccess class with the matched allow rule index and the matched allow rule text.

• A more detailed AuthorizationError giving access to failed checks and the matched policy

[divarvel]

Would you be willing to work on a PR? I can offer guidance

[amias-channer]

yeah sure , i would love to help out with this :)

[amias-channer]

FYI the change in the authorizer and authorizerbuilder objects in 0.4.0b1 seems to have removed the authorize method from both objects which is serious breakage because now i cannot auth anything.

This causes a lot of unit test fails in biscuit_test.py

[divarvel]

There have been breaking changes on the 0.4.0b1 branch indeed. There is no migration documentation, but all examples, including doctests and biscuit_test.py have been updated.

https://github.com/eclipse-biscuit/biscuit-python/blob/main/biscuit_test.py the tests pass correctly on main: https://github.com/eclipse-biscuit/biscuit-python/actions/runs/13839574014/job/38723315495#step:6:8
https://python.biscuitsec.org/basic-use#parse-and-authorize-a-biscuit-token

I’m not sure why the tests don’t pass locally for you, do you have an up-to-date copy?

[amias-channer]

seems my copy was wierd , i refreshed and its fixed.
i got confused by the syntax in the demo

in the basic use doc it says
authorizer = AuthorizerBuilder( .... ).build(token)
authorizer.authorize()

it might be clearer as

authorizer_builder = AuthorizerBuilder( ... )
authorizer = authorizer_builder.build(authority)
authorizer.authorize()

Now things are working and i just completed my first biscuit based auth in my app :)

seems i am also getting lots of useful feedback now about the auth

[amias-channer]

am ready to start working on the PR , please add me to the project so i can create a branch

[divarvel]

you will need to open the PR from a fork. That’s roughly the same process for you, instead of pushing to this repo, you fork it, push to your fork and then open a PR