State of Servant authentication

[tchoutri]

I took over the maintenance after a lot of help from @alpmestan when I needed to figure out servant-auth. I share the same experience as others of wasting countless hours, but I did put a lot of those hours back so that it's a tiny bit better nowadays.

Here's a short overview of incremental changes with the most impact:

• write tutorials for common use cases (this would solve most of newcomers as they can have a working version they can revert to - see Set-Cookie JWT - happens if there is cookie in request servant-auth#167)
• remove XSRF being required for GET requests Remove XSRF Cookie servant-auth#192
• Rewrite documentation servant-auth#129

Commonly requested features:

• BasicAuth support in client servant-auth#140
• authorization How to implement new authorization schemes servant-auth#119 Authorization versus Authentication servant-auth#73
• not requiring JWT for cookie auth Cookie Auth SEPARATE from JWT Auth? servant-auth#151

Last but not least, the plan is to port servant-auth to servant and deprecate the old auth: #805

These days I'm in brutal prioritization mode of scaling my business, so I can't do much maintenance but I do want to do everything I can for someone else to step up!

Originally posted by @domenkozar in haskell-servant/servant-auth#195 (comment)

[Siprj]

Having a nicer/simpler way of writing custom authentication handlers in servant-server is really compelling to me. In my daily job we had to create custom authentication combinator because the default one wasn't able to set cookies and the one from servant-auth didn't suit us either.

I would find useful some kind of combinator that would take the request as argument and returned user-defined data with the possibility to set cookies/header to the response.

[alpmestan]

For a long time now, both servant contributors and users have been annoyed by the fact that auth support has been essentially spread between the "generalized auth" machinery in the core servant packages, and the servant-auth packages. During all that time, I have been thinking that we ought to merge those two things (but lacked time and opportunity to execute), in a very precise way.

• servant-auth provides a simpler out-of-the-box experience but only supports a small number of authentication schemes, and doesn't provide a way to extend that set of schemes with new ones.
• the generalized auth stuffs in the core servant packages is essentially the opposite: you've got some general infrastructure for defining your own auth schemes and making use of them in APIs, but the out-of-the-box experience is not quite there and it doesn't come with common auth schemes pre-implemented - some auxiliary packages do use that and provide such implementations, but it's not in servant itself

What I think we would all love is the following: a single Auth (or AuthProtect or whatever) combinator that people could throw in front of one or more routes in their API types to auth-protect the said routes. We ideally should be able to specify one or more auth schemes to use to protect the routes, with (again ideally) a bunch of common ones being supported and implemented out of the box, while retaining the generalized auth's ability to define new ones, possibly using all sorts of pieces/bricks used to define the pre-implemented ones. All schemes (or even combinaison of schemes) would give users a "hook" of sorts to check credentials/tokens/etc (what we refer to as "auth check" in the current generalized auth business).

I do not have a concrete design in mind, but those requirements seem reasonable and in fact are bound to dictate a saner solution that the current ones. I'm not sure whether it's better to start from scratch, from servant-auth or from the generalized auth stuffs. I'd perhaps lean towards looking at what's missing from the generalized auth stuffs besides... a bunch of pre-implemented pieces for various auth schemes, and a way to combine them, since it's already extensible.

(It's harder to introduce extensibility after the fact to servant-auth than to tweak the generalized auth stuffs a bit, IMO.)

[tchoutri]

Here are the aspects to take into account when implementing this:

1. How are fetched the auth information (token, cookie, etc)

• This must be provided by our package, be canonical implementations, and should cover a variety of protocols.

2. Auth check: How is the token verified.

• This is given to us by the user.

3. How to handle success and failure of authentication

• Possibility of having a lenient/strict mode, where the request is denied if it fails in strict mode, and in lenient mode the handler is given a Maybe a so that authentication failure can be handled at the application level.

4. Login endpoint for third-party auth, can be an afterthought, not a hard requirement at the moment.
5. What should be the type representing an authenticated user, what the handler gets when a user is identified.

Currently, Generalised Authentication combines 1 & 2, and asks the user to it all by themselves. We could provide 1 and leave 2 to the user.

[tchoutri]

Here is a prototype design that would be nice to have

{-
## Example

type API
  =  Authenticate User (AuthCookie :> AuthHeader "X-Scrive-XToken")
  :> ToServantApi API'

type API
  = Authenticate (Maybe User) (AuthHeaders '["Token1", "Token2"])
  :> ToServantApi API'
-}

-- | These empty types can be provided by us or by external packages
data AuthCookie

data AuthHeader (name :: Symbol)

data AuthHeaders '[(name :: Symbol)]

-- | This class is provided by us and implemented by the providers of the above types (us, external packages)
class HasAuth input output | input -> output -- Implement this for the auth markers
  authenticate :: (MonadIO m) => a -> m b
  
instance HasAuth AuthCookie User
  authenticate = myFunThatTakesACookie

instance HasAuth (AuthHeader ["X-Token"]) User
  authenticate = myFunThatTakesTheContentOfTheseHeaders

instance HasAuth (AuthHeaders '["Token-1", "Token-2"]) (Maybe User) 
  authenticate = myFunThatTakesTwoHeaders

[Vlix]

* instance HasAuth (AuthHeader "X-Token") User where

I'd also like to help make the authenticating with servant better (see #1494 ), so I'll have a good think about this as well.

[Vlix]

Some brainstorming, just wrote it down, no idea if this would even compile.

-- | When the 'Lenient' mod is set, the handler will be passed the entire 'AuthResult val'
-- and the 'Context' needs a 'LenientAuthHandler'.
--
-- Otherwise, the 'Context' requires there to be a 'StrictAuthHandler' so that any failure of authentication results in a 'ServerError', and in case of success the handler will just receive the 'val'.
instance (
    HasServer api ctxs,
    HasContextEntry ctxs (AuthHandler (If (FoldLenient mods) Lenient Strict) auth val)
    ) => HasServer (Authenticate' mods auths val :> api) ctxs where
  type ServerT (Authenticate' mods auths val :> api) m =
    If (FoldLenient mods) (AuthResult val) val -> ServerT api m
  hoistServerWithContext _ pc nt s = hoistServerWithContext (Proxy @api) pc nt . s
  route _ context subserver = 
      route (Proxy @api) context $ subserver `addAuthCheck` authCheck
    where
      authCheck :: DelayedIO AuthResult
      authCheck :: withRequest $ \req -> liftIO $ do
        -- Somehow get to an AuthResult?
        authResult <- someHowCheckAuths
        case authHandler of
          LenientAuthHandler Nothing -> pure authResult
          LenientAuthHandler (Just check) ->
            maybe (pure authResult) delayedFailFatal $ check authResult
          StrictAuthHandler check ->
            either delayedFailFatal pure $ check authResult 

      authHandler :: AuthHandler (If (FoldLenient mods) Lenient Strict) auth val
      authHandler = getContextEntry context

data AuthHandler (mod :: k) auth val where
  LenientAuthHandler :: HasAuth auth val => Maybe (auth -> Maybe ServerError) -> AuthHandler Lenient auth val
  StrictAuthHandler :: HasAuth auth val => (auth -> Either ServerError val) -> AuthHandler Strict auth val

[divarvel]

Hi, speaking as a happy generalized auth user, i've never used servant-auth, and never had the need to come up with custom combinators, so here's my question:

is the generalized auth lacking expressivity in a way that makes it not suitable as a basic building block? (i've used it to build token-based auth and session auth mechanism without being limited (in servant-server).

If the generalized auth is indeed enough, would it make sense to provide high-level schemes based on it? I'd argue that the biggest issue with generalized auth right now is the lack of documentation and the Experimental module namespace.

To be completely honest, there is one limitation with the generalized auth system, in servant-client: there is no way to have effectful request signing. I've tried patching it, but that was a bit too big of a change for me to carry out.

Based on my experience (both on APIs and regular web apps), generalized auth is a solid base to build upon. DX could be improved with common schemes handled out of the box, and helpers abstracting away some common use-cases, that would make building on top of it less boilerplate-y

[tchoutri]

From what I am reading, it would seem that the optimal direction would be to iterate massively over generalised auth, get it out of Experimental, provide use-cases like:

On servant server

• BasicAuth
• Sessions with cookies (doable with @divarvel and I)
• JWT
• OAuth (?)

On servant client

• Enable effectful request signing

And then we can deprecate servant-auth and subsume its functionalities, provide migration guides (very important), and provide more documentation and guides with the new generalised auth schemes.

Indeed, it feels very "servant" to provide a maximum of informations at the type-level, but sometimes they are not actionable without a typeclass that provides term-level code. It would seem more efficient and direct to take a direction where we encode what we can at the type-level, and simplify API authoring for our end-users by doing the meat of things in the term level.

[alpmestan]

As stated before, I agree that generalized auth is a good starting point, that we need to tweak to make some of the improvements that we've discussed so far (separate "getting auth data" from "verify auth data", ability to easily combine several schemes, allow effectful things on the client side, maybe some others), while providing more schemes out of the box, along with their building blocks so that people can reuse them.