Lambda Island

Buddy is a popular security library for implementing authentication and authorization. In this episode you’ll learn what the difference is, and how to implement password based authentication for a simple Ring app.

Transcript

Buddy is a collection of security libraries for Clojure. It contains cryptographic functions, utilities to implement authentication and authorization, and facilities for encryption and message signing.

In this episode I’ll show you how to use Buddy to implement authentication in a typical Ring application. Buddy is split into four packages. buddy-auth provides authentication and authorization. You also need buddy-hashers so you don’t have to store passwords in plain text.

buddy-sign provides cryptographic message signing, I won’t cover that one. buddy-core contains utilities used by the other three. It’s pulled in automatically by the others, so you don’t have to include it.

(defproject booklog "0.1.0-SNAPSHOT"
  :description "Keep track of the books you read,
                a sample project to demonstrate Buddy."

  :url "https://github.com/lambdaisland/booklog"

  :dependencies [,,,
                 [buddy/buddy-auth "1.4.1"]
                 [buddy/buddy-hashers "1.2.0"]
                 ;;[buddy/buddy-sign "1.4.0"]
                 ;;[buddy/buddy-core "1.2.0"]
                 ])

This episode uses the Booklog example app, you can find it on Github. The starting point for this episode is the ep28-start branch.

To launch the app, open a REPL and use the (run) function. This starts the system with all the necessary components.

You can reload all namespaces and restart all components to get a clean slate again with (reset).

user> (run)
user> (reset)

This app is based on the Chestnut application template, and uses Ring and Compojure for routing, Hiccup for templating, and Spicerack for peristance. The different parts are tied together using Component.

First let’s start by defining some terms. Authentication means verifying that “you are who you say you are”. It comes from the greek αὐϑεντικός, meaning “genuine”, which has the same root as the word “author”.

In practice you authenticate incoming requests by verifying some form of identification. This could be login information, a session cookie, or a secret token.

Authentication /ɑːˌθen.t̬əˈkeɪ.ʃən/

From Latin auctorizare, from Greek αὐϑεντικός (authentikos): “genuine”

to prove that something is real, true, or what people say it is

Authorization means giving permission. It is related to the word authority. It answers the question “is this operation allowed?”. This could be based on authentication: if Li is an admin but Jenny isn’t, then some requests will be ok when Li sends them, but they’ll be rejected when coming from Jenny.

But authorization can also use other criteria. When building microservices it’s common to only accept requests from a specific range of IP addresses. Media companies often restrict their content to certain regions, so-called geoblocking.

Authorization /ˌɑː.θɚ.əˈzeɪ.ʃən/

From Latin auctorizo, to approve

giving someone permission to do something

This episode will only cover the authentication part of Buddy, I’ll cover authorization some other time.

Authentication can be done in many ways, so buddy provides a pluggable system through protocols. The IAuthentication protocol has two methods: -parse and -authenticate. -parse is responsible for pulling the identifying information from the current request, for instance from an authentication header or token parameter. This data is passed on to -authenticate, so it can be verified.

If authentication succeeds then authenticate should return something that identitifies the current user, like a username. If it fails then it returns nil.

(ns buddy.auth.protocols
  "Main authentication and authorization abstractions
  defined as protocols.")

(defprotocol IAuthentication
  "Protocol that defines unified workflow steps for
  all authentication backends."
  (-parse [_ request]
    "Parse token from the request. If it returns `nil`
    the `authenticate` phase will be skipped and the
    handler will be called directly.")
  (-authenticate [_ request data]
    "Given a request and parsed data (from previous step),
    try to authenticate this data.

    If this method returns not nil value, the request
    will be considered authenticated and the value will
    be attached to request under `:identity` attribute."))

There’s also an IAuthorization protocol with a single -handle-unauthorized method, which gets called when a a route signals that the user is unauthorized to do whatever it is they’re trying to do, either because the user isn’t authenticated yet, or because they are authenticated but don’t have the required permissions.

(defprotocol IAuthorization
  "Protocol that defines unified workflow steps for
  authorization exceptions."
  (-handle-unauthorized [_ request metadata]
    "This function is executed when a `NotAuthorizedException`
    exception is intercepted by authorization wrapper.

    It should return a valid ring response."))

A record that implements these two protocols is called an “auth backend”. You can implement one yourself, but Buddy already contains backends for common use cases. You can find them in the buddy.auth.backends namespace.

The session backend is the most useful one for typical web applications, so this is the one covered in this episode. You can pass it certain options, or use the defaults.

(require '[buddy.auth.backends :as backends])

;; Session based auth

(backends/session)               ; uses defaults: {:authfn identity}

(backends/session {:authfn
                   (fn [data]
                     data)

                   :unauthorized-handler
                   (fn [request metadata]
                     ,,,)})

If you’re building APIs then the HTTP Basic Authentication, JSON Web Tokens, or generic Token backends might be more suitable.

Note that JSON Web Tokens are not suitable as a session mechanism, and you are better off just sticking with cookies, even if you’re building a JavaScript one-page-app. I’ll provide a link to an article that describes the issues.

All backends take a map with options, although for some you can omit it to use the default values.

(require '[buddy.auth.backends :as backends])

;; HTTP Basic Auth
(backends/basic)
(backends/basic {:realm "My app"
                 :authfn (fn [req {:keys [username password]}]
                           (if (= [username password] ["arne" "abc123"])
                             arne))
                 :unauthorized-handler (fn [req metadata] ,,,)})

;; Session based auth
(backends/session {:authfn (fn [data]
                             data)
                   :unauthorized-handler (fn [req metadata])})

;; Signed JWT
(backends/jws {:secret "some-long-string"
               :authfn (fn [unparsed-token]
                         unparsed-token)
               :unauthorized-handler (fn [req metadata])
               :options {}
               :token-name "Token"
               :on-error (fn [req exception]
                           (println "JWT signature check failed"))})

;; Encrypted JWT
(backends/jwe {,,,})

;; Generic Token Backend
(backends/token {:authfn (fn [req token])
                 :unauthorized-handler (fn [req metadata])
                 :token-name "Token"})

You use these backends through the wrap-authentication ring middleware, found in buddy.auth.middleware. Also require the backends namespace. Now add the middleware to the middleware stack, passing it the session backend. You can give it multiple backends as well, in which case each one in turn will get a chance to authenticate a given request.

Make sure you place the middleware before wrap-defaults. Among other things wrap-defaults makes sure session data persists from request to request. Since the session backend needs access to the session it needs to sit above, or “inside” wrap-defaults.

The middleware will take care of calling the backend’s -parse and -authenticate methods. If authentication succeeds, then the backend returns a value that uniquely identifies the current user back to the middleware, something like a username or unique id, which the middleware places in the Ring request map under :identity. That way you can easily check it in your code.

(ns booklog.application
  (:gen-class)
  (:require ,,,
            [buddy.auth.backends :as buddy-backends]
            [buddy.auth.middleware :refer [wrap-authentication]]
            ,,,))

(defn app-system []
  (component/system-map
   ,,,
   :middleware (new-middleware {:middleware [wrap-render-views
                                             [wrap-authentication (buddy-backends/session)]
                                             [wrap-defaults site-defaults]
                                             wrap-with-logger
                                             wrap-gzip
                                             prone/wrap-exceptions]})
   ,,,))

To work with the session backend you need to provide your own login mechanism. When a user succesfully logs in you put the user’s identity in the session map. This session map will be carried on from request to request thanks to the session middleware.

Upon each request Buddy will call the session backend. This backend looks for an :identity key in the session, and if found passes it on to be used as the :identity in the Ring request map.

(require '[buddy.auth.middleware :refer [wrap-authentication]]
         '[buddy.auth.backends :as backends])

(defn ring-handler [req]
  {:status 200
   :body {:got-request req}})

(let [backend (backends/session)
      handler (-> ring-handler
                  (wrap-authentication backend))
      request {:session {:identity "arne"}}]
  (handler request))

;;=> {:status 200
;;    :body {:got-request {:session {:identity "arne"}
;;                         :identity "arne"}}}

You can pass an extra “authfn” to the session backend so you can look up the user’s details. I’ve added a map here as a sort of ad hoc users database. The authfn function takes the username and uses that to look up the user’s details. Now these become available in the request map, so you can access them easily, and they’re always up to date.

(require '[buddy.auth.backends :as buddy-backends])
(require '[buddy.auth.middleware :refer [wrap-authentication]])

(def users {"arne" {:name "Arne Brasseur"
                    :username "arne"}})

(let [backend (buddy-backends/session {:authfn (fn [u] (get users u))})
      handler (-> (fn [req] {:status 200
                             :body {:request req}})
                  (wrap-authentication backend))
      request {:session {:identity "arne"}}]
  (handler request))

;;=>
{:status 200
 :body {:request {:session {:identity "arne"}
                  :identity {:name "Arne Brasseur"
                             :username "arne"}}}}

Each request the session backend will look up the user’s identity in the session, but first it needs to get in there. That part is still up to you. When the user logs in and their credentials check out, then you can add the identity to the session. The session backend will do the rest.

So let’s implement the login form. Add two routes: a GET route to serve up the form, and a POST route to handle the form submission.

(defn auth-routes [endpoint]
  (routes
   (GET "/login" []
     ,,,)

   (POST "/login" []
     ,,,)))

I’ve already prepared the views, these are just functions that return Hiccup. render is a helper function that renders the view and returns a Ring response. Let’s also give it a title, this will show up as title on the browser tab.

(defn auth-routes [endpoint]
  (routes
   (GET "/login" []
     (render :view login-view
             :data {:layout/title "Login"}))


   (POST "/login" []
     ,,,)))

This is what that looks like, but when you submit it you get a 404, because the POST route returns nil. Let’s fix that next.

Destruture the request map to get the incoming username and password parameters.

As a first iteration use a hardcoded username and password. It never hurts to do something like this just to see if everything works so far.

(defn auth-routes [endpoint]
  (routes

   (GET "/login" _ ,,,)

   (POST "/login" [username password]
     (if (and (= username "admin") (= password "trustno1"))
       ,,,
       ,,,))))

Next you need to update the session map to actually log the user in, you can add this :as req to the Compojure destructuring form to get the request map, and from there you can get to the session.

Now log the user in by adding an :identity to the session map. You will have to add this updated session map to the ring response so it will be updated for future requests.

Next you redirect the user to the home page, add the new session, and also add a friendly message welcoming the user. This relies on the wrap-flash middleware, which is part of ring.middleware.defaults. It lets you pass some values on to the next request, so the message will show up after the redirect.

(defn auth-routes [endpoint]
  (routes

   (GET "/login" _
     (render :view login-view
             :data {:layout/title "Login"}))

   (POST "/login" [username password :as req]
     (if (and (= username "admin") (= password "trustno1"))
       (let [next-session (assoc (:session req) :identity username)]
         (-> (redirect "/")
             (assoc :session next-session)
             (flash-message "Login successful, welcome back!")))))
   ))

If the credentials don’t match then you should show the login form again with an error message so the user knows what’s going on. Pass the username back to the view so it gets prefilled.

(defn auth-routes [endpoint]
  (routes

   (GET "/login" _
     (render :view login-view
             :data {:layout/title "Login"}))

   (POST "/login" [username password :as req]
     (if (and (= username "admin") (= password "trustno1"))
       (let [next-session (assoc (:session req) :identity username)]
         (-> (redirect "/")
             (assoc :session next-session)
             (flash-message "Login successful, welcome back!")))
       (render :view login-view
               :data {:layout/title "Login"
                      :layout/message "Login failed, please check your password."
                      :user/username username})))))

So far so good, you’re using the wrap-authentication middleware with the session backend, and you have some login routes that work together with the backend so people can log in and stay logged in.

The username and password are still hard coded, but we’ll address that next, by adding a way for people to register.

Let’s first consider how to store these user details. You need a way to check the password, but you can’t just store the password in the database. Instead you should store something different that still allows you to verify the password.

This is where a hashing function comes in handy. It turns the password into an unrecognizable sequence of bytes called a hash. When the user logs in you compare the stored hash with a hash computed from the submitted password. If the password is the same then the hashes will also match.

You should’t use just any hashing functions though. It needs to be a modern one with no known flaws, it needs the right runtime characteristics to protect you from timing attacks, and it should use a method of salting so that, in case a breach happens, the attackers can’t use rainbow tables on the data.

I won’t explain what all of that means exactly. If you have some time it’s a good idea to read up on these things, but luckily Buddy provides good defaults, so you are less likely to get this wrong.

The required functionality is provided in the buddy-hashers package, in the buddy.hashers namespace, as a pair of two functions: derive, and check.

hashers/derive takes a password and returns the password hash, in particular it returns a string containing the encryption algorithm, the salt, the number of iterations performed by the algorithm, and the password hash itself. This value is now safe to store in the database. Even if an attacker gets hold of it it will be nearly impossible to find out the original password, provided it is long enough to prohibit a brute force attack.

(hashers/derive "trustno1")
;;=> "bcrypt+sha512$02f85c2ded57bb4d46b6547a268f2693$12$9a52bb16806562b9b0450659331c7da80731e1441f218451"

(-> (hashers/derive "trustno1")
    (str/split  #"\$"))
;;=>
["bcrypt+sha512"                                    ; encryption
 "5f8dc902b11de2aa17e67ecb0f76713f"                 ; salt
 "12"                                               ; iterations
 "622891a3aed90cea118b3ed791b96e27818389bddf9e5a9b" ; hashed password
 ]

So you can’t get the original password back from this hash, that’s the whole point, but given the hash and a password the user entered, you can check if it matches the original. This is done with hashers/check.

(hashers/check "trustno1" (hashers/derive "trustno1"))
;;=> true

So now that you know how to safely store passwords, let’s add two new routes, one renders a form that allows people to register, and the other handles the form submission.

As a database I’m using Spicerack, a Clojure wrapper around MapDB. Instead of tables Spicerack provides mutable hashmaps which are stored to disk. You can stick arbitrary Clojure values in them including nested vectors, maps, or sets, making it a great choice for quick prototyping.

The auth-routes function receives an endpoint component, which in turn contains the Spicerack component. From there you can get to the actual database. Open the “users” hashmap in an outer let block, so you can access users inside the routes. This users hashmap will just be a mapping from username to password hash.

(defn auth-routes [{:keys [spicerack] :as endpoint}]
  (let [users (sr/open-hashmap (:db spicerack) "users")]
    (routes
     ,,,

     (GET "/register" _
       ,,,)

     (POST "/register" [username password]
       ,,,))))

The GET route is pretty similar to the one used to log in, so just copy the render call and update the view function and page title.

(defn auth-routes [{:keys [spicerack] :as endpoint}]
  (let [users (sr/open-hashmap (:db spicerack) "users")]
    (routes
     ,,,

     (GET "/register" _
       (render :view register-view
               :data {:layout/title "Register"}))

     (POST "/register" [username password]
       ,,,))))

To handle the form submission, first get the username and password again from the incoming parameters, and then look up the username in the users table.

If the username is already taken then render the form again with an error message, and with the username prefilled.

(defn auth-routes [{:keys [spicerack] :as endpoint}]
  (let [users (sr/open-hashmap (:db spicerack) "users")]
    (routes
     ,,,

     (POST "/register" [username password]
       (if (get users username)
         (render :view register-view
                 :data {:layout/title "Register"
                        :layout/message "Username is already taken"
                        :user/username username})
         (do
           (sr/put! users username (hashers/derive password))
           (-> (redirect "/login")
               (flash-message "Thanks for registering, please log in"))))))))

If it’s not there then it’s time to register the user. Put a new entry in the Spicerack users hashmap, with as key the username, and as value the hash derived from the password. Finally point the user to the login page and ask them to log in. You could also log the user in directly, maybe that’s a good exercise to try yourself.

(defn auth-routes [{:keys [spicerack] :as endpoint}]
  (let [users (sr/open-hashmap (:db spicerack) "users")]
    (routes
     ,,,

     (POST "/register" [username password]
       (if (get users username)
         (render :view register-view
                 :data {:layout/title "Register"
                        :layout/message "Username is already taken"
                        :user/username username})
         (do
           (sr/put! users username (hashers/derive password))
           (-> (redirect "/login")
               (flash-message "Thanks for registering, please log in"))))))))

The login route is still using a hard coded password, but now that’s easy to change. Look up the submitted username in the users map, so you get the hashed password back, which you can check against the submitted password with hashers/check.

(if (hashers/check password (get users username))
  ,,,
  ,,,)

There’s one more thing you should change here, when logging a user in you should make sure they get a new session key. This will protect you against session fixation attacks. You do this by adding this bit of metadata to the updated session map.

This will cause the session identifier that is sent to the browser to change.

(let [next-session (-> (assoc (:session req) :identity username)
                       (with-meta {:recreate true}))] ,,, )

And that’s it, now a user can register and log in. All that’s missing is a way to log out again.

So add one more route which redirects back to the homepage. By setting :session to nil in the response map the session middleware will effectively delete all session data, so that after logging out we have a clean slate again.

(GET "/logout" _
  (-> (redirect "/")
      (assoc :session nil)
      (flash-message "You have been logged out")))

You should have a good understanding of how authorization with Buddy works. I didn’t cover the other auth backends in detail, but you can find example code for each of them in the Buddy documentation. Also make sure to check out the show notes for more info and some suggested reading material.

Authentication with Buddy