1# Authentication in Servant
3Once you've established the basic routes and semantics of your API, it's time
4to consider protecting parts of it. Authentication and authorization are broad
5and nuanced topics; as servant began to explore this space we started small
6with one of HTTP's earliest authentication schemes: [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication).
8Servant `0.5` shipped with out-of-the-box support for Basic Authentication.
9However, we recognize that every web application is its own beautiful snowflake
10and are offering experimental support for generalized or ad-hoc authentication.
12In this tutorial we'll build two APIs. One protecting certain routes with Basic
13Authentication and another protecting the same routes with a custom, in-house
16## Basic Authentication
18When protecting endpoints with basic authentication, we need to specify two
211. The **realm** of authentication as per the Basic Authentication spec.
222. The datatype returned by the server after authentication is verified. This
23is usually a `User` or `Customer` datatype.
25With those two items in mind, *servant* provides the following combinator:
28data BasicAuth (realm :: Symbol) (userData :: *)
31You can use this combinator to protect an API as follows:
34{-# LANGUAGE DataKinds #-}
35{-# LANGUAGE DeriveGeneric #-}
36{-# LANGUAGE FlexibleContexts #-}
37{-# LANGUAGE FlexibleInstances #-}
38{-# LANGUAGE MultiParamTypeClasses #-}
39{-# LANGUAGE OverloadedStrings #-}
40{-# LANGUAGE ScopedTypeVariables #-}
41{-# LANGUAGE TypeFamilies #-}
42{-# LANGUAGE TypeOperators #-}
43{-# LANGUAGE UndecidableInstances #-}
45module Authentication where
47import Data.Aeson (ToJSON)
48import Data.ByteString (ByteString)
49import Data.Map (Map, fromList)
50import qualified Data.Map as Map
51import Data.Proxy (Proxy (Proxy))
52import Data.Text (Text)
53import GHC.Generics (Generic)
54import Network.Wai (Request, requestHeaders)
55import Network.Wai.Handler.Warp (run)
56import Servant.API ((:<|>) ((:<|>)), (:>), BasicAuth,
58import Servant.API.BasicAuth (BasicAuthData (BasicAuthData))
59import Servant.API.Experimental.Auth (AuthProtect)
60import Servant (throwError)
61import Servant.Server (BasicAuthCheck (BasicAuthCheck),
62 BasicAuthResult( Authorized
65 Context ((:.), EmptyContext),
66 err401, err403, errBody, Server,
67 serveWithContext, Handler)
68import Servant.Server.Experimental.Auth (AuthHandler, AuthServerData,
70import Servant.Server.Experimental.Auth()
71import Web.Cookie (parseCookies)
73-- | private data that needs protection
74newtype PrivateData = PrivateData { ssshhh :: Text }
75 deriving (Eq, Show, Generic)
77instance ToJSON PrivateData
79-- | public data that anyone can use.
80newtype PublicData = PublicData { somedata :: Text }
81 deriving (Eq, Show, Generic)
83instance ToJSON PublicData
85-- | A user we'll grab from the database when we authenticate someone
86newtype User = User { userName :: Text }
89-- | a type to wrap our public api
90type PublicAPI = Get '[JSON] [PublicData]
92-- | a type to wrap our private api
93type PrivateAPI = Get '[JSON] PrivateData
96type BasicAPI = "public" :> PublicAPI
97 :<|> "private" :> BasicAuth "foo-realm" User :> PrivateAPI
99-- | a value holding a proxy of our API type
100basicAuthApi :: Proxy BasicAPI
104You can see that we've prefixed our public API with "public" and our private
105API with "private." Additionally, the private parts of our API use the
106`BasicAuth` combinator to protect them under a Basic Authentication scheme (the
107realm for this authentication is `"foo-realm"`).
109Unfortunately we're not done. When someone makes a request to our `"private"`
110API, we're going to need to provide to servant the logic for validating
111usernames and passwords. This adds a certain conceptual wrinkle in servant's
112design that we'll briefly discuss. If you want the **TL;DR**: we supply a lookup
113function to servant's new `Context` primitive.
115Until now, all of servant's API combinators extracted information from a request
116or dictated the structure of a response (e.g. a `Capture` param is pulled from
117the request path). Now consider an API resource protected by basic
118authentication. Once the required `WWW-Authenticate` header is checked, we need
119to verify the username and password. But how? One solution would be to force an
120API author to provide a function of type `BasicAuthData -> Handler User`
121and servant should use this function to authenticate a request. Unfortunately
122this didn't work prior to `0.5` because all of servant's machinery was
123engineered around the idea that each combinator can extract information from
124only the request. We cannot extract the function
125`BasicAuthData -> Handler User` from a request! Are we doomed?
127Servant `0.5` introduced `Context` to handle this. The type machinery is beyond
128the scope of this tutorial, but the idea is simple: provide some data to the
129`serve` function, and that data is propagated to the functions that handle each
130combinator. Using `Context`, we can supply a function of type
131`BasicAuthData -> Handler User` to the `BasicAuth` combinator
132handler. This will allow the handler to check authentication and return a `User`
133to downstream handlers if successful.
135In practice we wrap `BasicAuthData -> Handler User` into a slightly
136different function to better capture the semantics of basic authentication:
139-- | The result of authentication/authorization
140data BasicAuthResult usr
145 deriving (Eq, Show, Read, Generic, Typeable, Functor)
147-- | Datatype wrapping a function used to check authentication.
148newtype BasicAuthCheck usr = BasicAuthCheck
149 { unBasicAuthCheck :: BasicAuthData
150 -> IO (BasicAuthResult usr)
152 deriving (Generic, Typeable, Functor)
155We now use this datatype to supply servant with a method to authenticate
156requests. In this simple example the only valid username and password is
157`"servant"` and `"server"`, respectively, but in a real, production application
158you might do some database lookup here.
161-- | 'BasicAuthCheck' holds the handler we'll use to verify a username and password.
162authCheck :: BasicAuthCheck User
164 let check (BasicAuthData username password) =
165 if username == "servant" && password == "server"
166 then return (Authorized (User "servant"))
167 else return Unauthorized
168 in BasicAuthCheck check
171And now we create the `Context` used by servant to find `BasicAuthCheck`:
174-- | We need to supply our handlers with the right Context. In this case,
175-- Basic Authentication requires a Context Entry with the 'BasicAuthCheck' value
176-- tagged with "foo-tag" This context is then supplied to 'server' and threaded
177-- to the BasicAuth HasServer handlers.
178basicAuthServerContext :: Context (BasicAuthCheck User ': '[])
179basicAuthServerContext = authCheck :. EmptyContext
182We're now ready to write our `server` method that will tie everything together:
185-- | an implementation of our server. Here is where we pass all the handlers to our endpoints.
186-- In particular, for the BasicAuth protected handler, we need to supply a function
187-- that takes 'User' as an argument.
188basicAuthServer :: Server BasicAPI
190 let publicAPIHandler = return [PublicData "foo", PublicData "bar"]
191 privateAPIHandler (user :: User) = return (PrivateData (userName user))
192 in publicAPIHandler :<|> privateAPIHandler
195Finally, our main method and a sample session working with our server:
199basicAuthMain :: IO ()
200basicAuthMain = run 8080 (serveWithContext basicAuthApi
201 basicAuthServerContext
207$ curl -XGET localhost:8080/public
208[{"somedata":"foo"},{"somedata":"bar"}
210$ curl -iXGET localhost:8080/private
211HTTP/1.1 401 Unauthorized
212transfer-encoding: chunked
213Date: Thu, 07 Jan 2016 22:36:38 GMT
215WWW-Authenticate: Basic realm="foo-realm"
217$ curl -iXGET localhost:8080/private -H "Authorization: Basic c2VydmFudDpzZXJ2ZXI="
219transfer-encoding: chunked
220Date: Thu, 07 Jan 2016 22:37:58 GMT
222Content-Type: application/json
227## Generalized Authentication
229Sometimes your server's authentication scheme doesn't quite fit with the
230standards (or perhaps servant hasn't rolled-out support for that new, fancy
231authentication scheme). For such a scenario, servant `0.5` provides easy and
232simple experimental support to roll your own authentication.
234Why experimental? We worked on the design for authentication for a long time. We
235really struggled to find a nice, type-safe niche in the design space. In fact,
236`Context` came out of this work, and while it really fit for schemes like Basic
237and JWT, it wasn't enough to fully support something like OAuth or HMAC, which
238have flows, roles, and other fancy ceremonies. Further, we weren't sure *how*
241So, in typical startup fashion, we developed an MVP of 'generalized auth' and
242released it in an experimental module, with the hope of getting feedback from you!
243So, if you're reading this or using generalized auth support, please give us
246### What is Generalized Authentication?
248**TL;DR**: you throw a tagged `AuthProtect` combinator in front of the
249endpoints you want protected and then supply a function `Request -> Handler a`,
250where `a` is the type of your choice representing the data returned by
251successful authentication - e.g., a `User` or, in our example below, `Account`.
252This function is run anytime a request matches a protected endpoint. It
253precisely solves the "I just need to protect these endpoints with a function
254that does some complicated business logic" and nothing more. Behind the scenes
255we use a type family instance (`AuthServerData`) and `Context` to accomplish
258### Generalized Authentication in Action
260Let's implement a trivial authentication scheme. We will protect our API by
261looking for a cookie named `"servant-auth-cookie"`. This cookie's value will
262contain a key from which we can lookup an `Account`.
265-- | An account type that we "fetch from the database" after
266-- performing authentication
267newtype Account = Account { unAccount :: Text }
269-- | A (pure) database mapping keys to accounts.
270database :: Map ByteString Account
271database = fromList [ ("key1", Account "Anne Briggs")
272 , ("key2", Account "Bruce Cockburn")
273 , ("key3", Account "Ghédalia Tazartès")
276-- | A method that, when given a password, will return an Account.
277-- This is our bespoke (and bad) authentication logic.
278lookupAccount :: ByteString -> Handler Account
279lookupAccount key = case Map.lookup key database of
280 Nothing -> throwError (err403 { errBody = "Invalid Cookie" })
281 Just usr -> return usr
284For generalized authentication, servant exposes the `AuthHandler` type,
285which is used to wrap the `Request -> Handler Account` logic. Let's
286create a value of type `AuthHandler Request Account` using the above `lookupAccount`
287method (note: we depend upon [`cookie`](https://hackage.haskell.org/package/cookie)'s
288`parseCookies` for this):
292--- | The auth handler wraps a function from Request -> Handler Account.
293--- We look for a token in the request headers that we expect to be in the cookie.
294--- The token is then passed to our `lookupAccount` function.
295authHandler :: AuthHandler Request Account
296authHandler = mkAuthHandler handler
298 maybeToEither e = maybe (Left e) Right
299 throw401 msg = throwError $ err401 { errBody = msg }
300 handler req = either throw401 lookupAccount $ do
301 cookie <- maybeToEither "Missing cookie header" $ lookup "cookie" $ requestHeaders req
302 maybeToEither "Missing token in cookie" $ lookup "servant-auth-cookie" $ parseCookies cookie
305Let's now protect our API with our new, bespoke authentication scheme. We'll
306re-use the endpoints from our Basic Authentication example.
309-- | Our API, with auth-protection
310type AuthGenAPI = "private" :> AuthProtect "cookie-auth" :> PrivateAPI
311 :<|> "public" :> PublicAPI
313-- | A value holding our type-level API
314genAuthAPI :: Proxy AuthGenAPI
318Now we need to bring everything together for the server. We have the
319`AuthHandler Request Account` value and an `AuthProtected` endpoint. To bind these
320together, we need to provide a [Type Family](https://downloads.haskell.org/~ghc/8.8.1/docs/html/users_guide/glasgow_exts.html#type-families)
321instance that tells the `HasServer` instance that our `Context` will supply a
322`Account` (via `AuthHandler Request Account`) and that downstream combinators will
323have access to this `Account` value (or an error will be thrown if authentication
328-- | We need to specify the data returned after authentication
329type instance AuthServerData (AuthProtect "cookie-auth") = Account
332Note that we specify the type-level tag `"cookie-auth"` when defining the type
333family instance. This allows us to have multiple authentication schemes
334protecting a single API.
336We now construct the `Context` for our server, allowing us to instantiate a
337value of type `Server AuthGenAPI`, in addition to the server value:
340-- | The context that will be made available to request handlers. We supply the
341-- "cookie-auth"-tagged request handler defined above, so that the 'HasServer' instance
342-- of 'AuthProtect' can extract the handler and run it on the request.
343genAuthServerContext :: Context (AuthHandler Request Account ': '[])
344genAuthServerContext = authHandler :. EmptyContext
346-- | Our API, where we provide all the author-supplied handlers for each end
347-- point. Note that 'privateDataFunc' is a function that takes 'Account' as an
348-- argument. We don't worry about the authentication instrumentation here,
349-- that is taken care of by supplying context
350genAuthServer :: Server AuthGenAPI
352 let privateDataFunc (Account name) =
353 return (PrivateData ("this is a secret: " <> name))
354 publicData = return [PublicData "this is a public piece of data"]
355 in privateDataFunc :<|> publicData
358We're now ready to start our server (and provide a sample session)!
363genAuthMain = run 8080 (serveWithContext genAuthAPI genAuthServerContext genAuthServer)
367$ curl -XGET localhost:8080/private
370$ curl -XGET localhost:8080/private -H "Cookie: servant-auth-cookie=key3"
371[{"ssshhh":"this is a secret: Ghédalia Tazartès"}]
373$ curl -XGET localhost:8080/private -H "Cookie: servant-auth-cookie=bad-key"
376$ curl -XGET localhost:8080/public
377[{"somedata":"this is a public piece of data"}]
383Creating a generalized, ad-hoc authentication scheme was fairly straight
3861. use the `AuthProtect` combinator to protect your API.
3872. choose an application-specific data type used by your server when
388authentication is successful (in our case this was `Account`).
3893. Create a value of `AuthHandler Request Account` which encapsulates the
390authentication logic (`Request -> Handler Account`). This function
391will be executed every time a request matches a protected route.
3924. Provide an instance of the `AuthServerData` type family, specifying your
393application-specific data type returned when authentication is successful (in
394our case this was `Account`).
3981. The module `Servant.Server.Experimental.Auth` contains an orphan `HasServer`
399instance for the `AuthProtect` combinator. You may be get orphan instance
400warnings when using this.
4012. Generalized authentication requires the `UndecidableInstances` extension.
403## Client-side Authentication
405### Basic Authentication
407As of `0.5`, *servant-client* comes with support for basic authentication!
408Endpoints protected by Basic Authentication will require a value of type
409`BasicAuthData` to complete the request.
411You can find more comprehensive Basic Authentication example in the [Cookbook](../cookbook/basic-auth/BasicAuth.html).
413### Generalized Authentication
415Servant `0.5` also shipped with support for generalized authentication. Similar
416to the server-side support, clients need to supply an instance of the
417`AuthClientData` type family specifying the datatype the client will use to
418marshal an unauthenticated request into an authenticated request. Generally,
422import Servant.Common.Req (Req, addHeader)
424-- | The datatype we'll use to authenticate a request. If we were wrapping
425-- something like OAuth, this might be a Bearer token.
426type instance AuthClientData (AuthProtect "cookie-auth") = String
428-- | A method to authenticate a request
429authenticateReq :: String -> Req -> Req
430authenticateReq s req = addHeader "my-bespoke-header" s req
433Now, if the client method for our protected endpoint was `getProtected`, then
434we could perform authenticated requests as follows:
437-- | one could curry this to make it simpler to work with.
438result = runExceptT (getProtected (mkAuthenticateReq "secret" authenticateReq))
keysesc to close
- j k
- move down, up
- enter
- open
- esc
- back, or up a level
- 1 2 3 4
- readme, files, commits, refs
- /
- filter
- y
- copy the clone command
- c
- compare the chosen commit with another (or shift-click both)
- ?
- show or hide this list