cemerick.friend — com.cemerick/friend 0.2.3

*default-scheme-ports* clj deprecated

*identity* clj

A threadlocal reference to the value of (identity request).

This is fundamentally here only to support authorize and its derivatives. In general, you should not touch this; use the identity function to obtain the identity associated with a Ring request, or e.g. (current-authentication request) to obtain the current authentication from a Ring request or response.

anonymous? clj

Returns true only if the provided request/response has no identity. Equivalent to (complement current-authentication).

auth? clj

(auth? x)

Returns true only if the argument is an authentication map (i.e. has a (type) of ::auth).

authenticate clj

(authenticate ring-handler auth-config)

authenticate-request clj

(authenticate-request request config)

Returns response if there is one. Otherwise returns a map with :friend/handler-map key which contains a map to be called with a ring handler.

authenticate-response clj

(authenticate-response response request)

Adds to the response's :session for responses with a :friend/ensure-identity-request key.

authenticated clj macro

(authenticated & body)

Macro that only allows the evaluation of the given body of code if the current user is authenticated. Otherwise, control will be thrown up to the unauthorized-handler configured in the authenticate middleware.

The exception that causes this change in control flow carries a map of data describing the authorization failure; you can optionally provide an auxiliary map that is merged to it as the first form of the body of code wrapped by authenticated.

authorize clj macro

(authorize roles & [authz-failure-map? & body])

Macro that only allows the evaluation of the given body of code if the currently-identified user agent has a role that isa? one of the roles in the provided set. Otherwise, control will be thrown up to the unauthorized-handler configured in the authenticate middleware.

The exception that causes this change in control flow carries a map of data describing the authorization failure (see throw-unauthorized). You can optionally provide an auxiliary map that is merged to it as the first form of the body of code wrapped by authorize, e.g.:

(authorize #{::user :some.ns/admin} {:op-name "descriptive name for secured operation"}

Note that this macro depends upon the identity var being bound to the current user's authentications. This will work fine in e.g. agent sends and futures and such, but will fall down in places where binding conveyance doesn't apply (e.g. lazy sequences, direct java.lang.Thread usages, etc).

authorize-hook clj

(authorize-hook roles f & args)

Authorization function suitable for use as a hook with robert-hooke library. This allows you to place access controls around a function defined in code you don't control.

e.g.

(add-hook #'restricted-function (partial #{::admin} authorize-hook))

Like authorize, this depends upon identity being bound appropriately.

authorized? clj

(authorized? roles identity)

Returns the first value in the :roles of the current authentication in the given identity map that isa? one of the required roles. Returns nil otherwise, indicating that the identity is not authorized for the set of required roles. If :roles is a fn, it will be executed with no args and assumed to return a collection of roles.

current-authentication clj

(current-authentication)

(current-authentication identity-or-ring-map)

Returns the authentication associated with either the current in-flight request, or the provided Ring request or response map.

Providing the Ring request map explicitly is strongly encouraged, to avoid any funny-business related to the dynamic binding of *identity*.

default-unauthenticated-handler clj

(default-unauthenticated-handler request)

handler-request clj

(handler-request handler {:keys [catch-handler request auth]})

Calls handler with appropriate binding and error catching and returns a response.

identity clj

(identity m)

Returns the identity associated with the given request or response. This will either be nil (for an anonymous user/session) or a map containing:

:current - the name of the current authentication, must be a key into the map in the :authentications slot :authentications - a map with values of authentication maps keyed by their :identity.

logout clj

(logout handler)

Ring middleware that modifies the response to drop all retained authentications.

logout* clj

(logout* response)

Removes any Friend identity from the response's :session. Assumes that the request's :session has already been added to the response (doing otherwise will likely result in the Friend identity being added back into the final response).

merge-authentication clj

(merge-authentication m auth)

requires-scheme clj deprecated

(requires-scheme handler scheme)

(requires-scheme handler
                 scheme
                 scheme-mapping
                 &
                 {:keys [status] :or {status 302}})

DEPRECATED. Use https://github.com/ring-clojure/ring-ssl instead, perhaps via https://github.com/ring-clojure/ring-defaults.

Ring middleware that requires that the given handler be accessed using the specified scheme (:http or :https), a.k.a. channel security. Will use the optional map of scheme -> port numbers to determine the port to redirect to (defaults defined in default-scheme-ports).

(requires-scheme ring-handler :https)

...will redirect an http request to the same uri, but with an https scheme and default 443 port.

(requires-scheme ring-handler :https {:https 8443})

...will redirect an http request to the same uri, but with an https scheme and to port 8443.

By default, a 302 (found) redirect will be performed. For SEO reasons a 301 (moved permanently) redirect may be preferable, in which case the the actual status code to use can be specified with the :status option.

requires-scheme-with-proxy clj deprecated

(requires-scheme-with-proxy handler scheme)

(requires-scheme-with-proxy handler
                            scheme
                            scheme-mapping
                            &
                            {:keys [status] :or {status 302}})

DEPRECATED. Use https://github.com/ring-clojure/ring-ssl instead, perhaps via https://github.com/ring-clojure/ring-defaults.

Ring middleware similar to friend/requires-scheme that should be able to handle things like load balancers in Amazon's elastic beanstalk and heroku in addition to other load balancers and reverse proxies that use x-forwarded-proto and thus don't set :scheme in the request map properly. Do not use if your application server is directly facing the internet as these headers are very easy to forge.

throw-unauthorized clj

(throw-unauthorized identity authorization-info)

Throws a slingshot stone (see slingshot.slingshot/throw+) containing the [authorization-info] map, in addition to these slots:

:cemerick.friend/type - the type of authorization failure that has occurred, defaults to :unauthorized :cemerick.friend/identity - the current identity, defaults to the provided [identity] argument

Provided the stone is thrown within the context of an authenticate middleware, handling of the original request will be delegated to its unauthorized-handler or the unauthenticated-handler as appropriate, with the slingshot stone's map assoc'ed into the request map under :cemerick.friend/authorization-failure.

wrap-authorize clj

(wrap-authorize handler roles)

Ring middleware that only passes a request to the given handler if the identity in the request has a role that isa? one of the roles in the provided set. Otherwise, the request will be handled by the unauthorized-handler configured in the authenticate middleware.

Tip: make sure your authorization middleware is applied within your routing layer! Otherwise, authorization failures could occur simply because of the ordering of your routes, or on 404 requests. Using something like Compojure's context makes such arrangements easy to maintain.