Network.Wai.Middleware.Biscuit

Biscuit parsing

parseBiscuit :: PublicKey -> Middleware

Given a public key, generate a middleware that will extract a biscuit token from incoming requests, parse it, and verify its signature. Requests without a verified biscuit are rejected, and the verified biscuit is added to the request context. The token is not authorized, only parsed and has its signature verified. Authorization is meant to be carried out in the application itself. If you want to carry out authorization in the middleware, have a look at authorizeBiscuit' (or authorizeBiscuitWith).

The token is expected as a base64-encoded string, provided as a bearer token in the Authorization header. A missing header results in a bodyless 401 HTTP response. An invalid token results in a bodyless 403 HTTP response. Errors are logged to stdout.

If you need custom extraction, parsing or error handling, have a look at parseBiscuitWith.

getBiscuit :: Request -> Maybe (Biscuit OpenOrSealed Verified)

Retrieve the parsed token from the request context. It is meant to be used in conjunction with the parseBiscuit (or parseBiscuitWith) middleware. It will not be set by the authorizeBiscuit' (or authorizeBiscuitWith) middleware.

parseBiscuitWith :: ExtractionConfig e -> Middleware

Given a way to extract a token from a request, parse it, and handle errors, generate a middleware that will extract a biscuit token from incoming requests, parse it, and verify its signature. Requests without a verified biscuit are rejected, and the verified biscuit is added to the request context. The token is not authorized, only parsed and has its signature verified. Authorization is meant to be carried out in the application itself. If you want to carry out authorization in the middleware, have a look at authorizeBiscuit' (or authorizeBiscuitWith).

If you don’t need custom extraction, parsing or error handling logic, have a look at parseBiscuit.

data ExtractionConfig e

Configuration for parseBiscuitWith.

Constructors

ExtractionConfig

Fields

• extractToken :: Request -> IO (Either e ByteString)

  How to extract a token from a request

• parseToken :: ByteString -> IO (Either e (Biscuit OpenOrSealed Verified))

  How to parse a token from the extracted serialized bytestring

• handleError :: e -> IO Response

  How to handle errors (this does not allow recovery)

defaultExtractionConfig :: PublicKey -> ExtractionConfig BiscuitError

Default behaviour for token extraction and parsing.

• Extract the token as a bearer token from the Authorization header;
• Parse the token as URL-safe base64 strings, using the provided public key;
• Errors are logged to stdout;
• Missing tokens are rejected with a bodyless 401 HTTP response;
• Parsing errors are rejected with a bodyless 403 HTTP response.

Biscuit authorization

authorizeBiscuit' :: PublicKey -> (Request -> IO Authorizer) -> Middleware

Given a public key and a way to generate an authorizer from a request, generate a middleware that will extract a biscuit token from incoming requests, parse it, verify its signature and authorize it. Requests without an authorized biscuit are rejected, and the authorized biscuit is added to the request context. The underlying application will only receive requests where the whole authorization process succeeded. If you want to only parse tokens and delegate actual authorization to the underlying application, have a look at parseBiscuit (or parseBiscuitWith).

The token is expected as a base64-encoded string, provided as a bearer token in the Authorization header. A missing header results in a bodyless 401 HTTP response. An invalid token results in a bodyless 403 HTTP response. A failed authorization process results in a bodyless 403 HTTP response. Errors are logged to stdout.

If you need custom extraction, parsing, authorization or error handling, have a look at authorizeBiscuitWith.

getAuthorizedBiscuit :: Request -> Maybe (AuthorizedBiscuit OpenOrSealed)

Retrieve the result of the successful authorization from the request context. It is meant to be used in conjunction with the authorizeBiscuit' (or the authorizeBiscuitWith) middleware.

authorizeBiscuitWith :: AuthorizationConfig e -> Middleware

Given a way to extract a token from a request, parse it, authorized it and handle errors, generate a middleware that will extract a biscuit token from incoming requests, parse it, verify its signature and authorize it. Requests without an authorized biscuit are rejected, and the authorized biscuit is added to the request context. The underlying application will only receive requests where the whole authorization process succeeded. If you want to only parse tokens and delegate actual authorization to the underlying application, have a look at parseBiscuit (or parseBiscuitWith).

If you don’t need custom extraction, parsing, authorization, or error handling logic, have a look at authorizeBiscuit'.

data AuthorizationConfig e

Configuration for authorizeBiscuitWith.

Constructors

AuthorizationConfig

Fields

• extractToken :: Request -> IO (Either e ByteString)

  How to extract a token from a request

• parseToken :: ByteString -> IO (Either e (Biscuit OpenOrSealed Verified))

  How to parse a token from the extracted serialized bytestring

• authorizeToken :: Request -> Biscuit OpenOrSealed Verified -> IO (Either e (AuthorizedBiscuit OpenOrSealed))

  How to authorize a token

• handleError :: e -> IO Response

  How to handle errors (this does not allow recovery)

defaultAuthorizationConfig :: PublicKey -> (Request -> IO Authorizer) -> AuthorizationConfig BiscuitError

Default behaviour for token extraction, parsing and authorization.

• Extract the token as a bearer token from the Authorization header;
• Parse the token as URL-safe base64 strings, using the provided public key;
• Authorize the request with the generated authorizer;
• Errors are logged to stdout;
• Missing tokens are rejected with a bodyless 401 HTTP response;
• Parsing errors are rejected with a bodyless 403 HTTP response.
• Authorization errors are rejected with a bodyless 403 HTTP response.

Helpers

defaultExtractToken :: Request -> Maybe ByteString

Extract a token from the Authorization header, stripping the Bearer prefix.

defaultHandleError :: BiscuitError -> IO Response

Generate HTTP responses based on authorization errors. Errors are logged to stdout.

• Missing tokens result in a 401 bodyless response;
• Parsing errors result in a 403 bodyless response;
• Authorization errors result in a 403 bodyless response.