Auth.Biscuit.Servant

Documentation

type RequireBiscuit = AuthProtect "biscuit"

Type used to protect and API tree, requiring a biscuit token to be attached to requests. The associated auth handler will only check the biscuit signature. Checking the datalog part usually requires endpoint-specific information, and has to be performed separately with either checkBiscuit (for simple use-cases) or handleBiscuit (for more complex use-cases).

authHandler :: PublicKey -> AuthHandler Request CheckedBiscuit

Servant authorization handler. This extracts the biscuit from the request, checks its signature (but not the datalog part) and returns a CheckedBiscuit upon success.

genBiscuitCtx :: PublicKey -> Context '[AuthHandler Request CheckedBiscuit]

Helper function generating a servant context containing the authorization handler.

checkBiscuit :: (MonadIO m, MonadError ServerError m) => CheckedBiscuit -> Verifier -> m a -> m a

Given a CheckedBiscuit (provided by the servant authorization mechanism), verify its validity (with the provided Verifier). If you don't want to pass the biscuit manually to all the endpoints or want to blanket apply verifiers on whole API trees, you can consider using withVerifier (on endpoints), withFallbackVerifier and withPriorityVerifier (on API sub-trees) and handleBiscuit (on the whole API).

data WithVerifier m a

Wrapper for a servant handler, equipped with a biscuit Verifier that will be used to authorize the request. If the authorization succeeds, the handler is ran. The handler itself is given access to the verified biscuit through a 'ReaderT Biscuit'.

Constructors

WithVerifier

Fields

• handler_ :: ReaderT Biscuit m a

  the wrapped handler, in a ReaderT to give easy access to the biscuit

• verifier_ :: Verifier

  the Verifier associated to the handler

handleBiscuit :: (MonadIO m, MonadError ServerError m) => CheckedBiscuit -> WithVerifier m a -> m a

Given a handler wrapped in a WithVerifier, use the attached Verifier to verify the provided biscuit and return an error as needed.

For simpler use cases, consider using checkBiscuit instead, which works on regular servant handlers.

withVerifier :: Monad m => Verifier -> ReaderT Biscuit m a -> WithVerifier m a

Wraps an existing handler block, attaching a Verifier. The handler has to be a 'ReaderT Biscuit' to be able to access the token. If you don't need to access the token from the handler block, you can use withVerifier_ instead.

withVerifier_ :: Monad m => Verifier -> m a -> WithVerifier m a

Wraps an existing handler block, attaching a Verifier. The handler can be any monad, but won't be able to access the Biscuit. If you want to read the biscuit token from the handler block, you can use withVerifier instead.

noVerifier :: Monad m => ReaderT Biscuit m a -> WithVerifier m a

Wraps an existing handler block, attaching an empty Verifier. The handler has to be a 'ReaderT Biscuit' to be able to access the token. If you don't need to access the token from the handler block, you can use noVerifier_ instead.

This function can be used together with withFallbackVerifier or withPriorityVerifier to apply policies on several handlers at the same time (with hoistServer for instance).

noVerifier_ :: Monad m => m a -> WithVerifier m a

Wraps an existing handler block, attaching an empty Verifier. The handler can be any monad, but won't be able to access the Biscuit. If you want to read the biscuit token from the handler block, you can use noVerifier instead.

This function can be used together with withFallbackVerifier or withPriorityVerifier to apply policies on several handlers at the same time (with hoistServer for instance).

withFallbackVerifier :: Verifier -> WithVerifier m a -> WithVerifier m a

Combines the provided Verifier to the Verifier attached to the wrapped handler. _facts_, _rules_ and _checked_ are unordered, but _policies_ have a specific order. withFallbackVerifier puts the provided policies at the _bottom_ of the list (ie as _fallback_ policies). If you want the policies to be tried before the ones of the wrapped handler, you can use withPriorityVerifier.

withPriorityVerifier :: Verifier -> WithVerifier m a -> WithVerifier m a

Combines the provided Verifier to the Verifier attached to the wrapped handler. _facts_, _rules_ and _checked_ are unordered, but _policies_ have a specific order. withFallbackVerifier puts the provided policies at the _top_ of the list (ie as _priority_ policies). If you want the policies to be tried after the ones of the wrapped handler, you can use withFallbackVerifier.