# Security Handler

Getting Started | API | Elements | Actions | Validators | Handlers | Configuration Options | About

## Table of Contents

- 1 Security Handler

## 1 Security Handler

The security handler provides a mechanism for determining whether or not the client user has access to a particular resource. In particular, it can be used for injecting HTTP Authentication headers, or for being customized to your own app's authentication system, like checking cookies to automatically log in a returning user.

### Behavior Functions

##### `init(Config, State)`

Initialize the Security Handler. Like the Route Handler, the majority of the work done in the security handler will happen here, or at least will start here.

It's typical to check for headers, cookies, or other settings here, and for possibly loading paths and their required settings.

- Return Value - `{ok, NewState}`

##### `finish(Config, State)`

Clean up the handler

- Return Value - `{ok, NewState}`

### Simplest Example - A security handler that lets everything through

The default security handler for Nitrogen is extremely simple and allows all requests through. The text of that handler is here:

    -module (default_security_handler).
    -behaviour (security_handler).
    -export ([
        init/2,
        finish/2
    ]).

    init(_Config, State) ->
        % By default, let all requests through. If we wanted to impose
        % security, then check the page module (via wf:page_module()),
        % and if the user doesn't have access, then set a new page module and path info,
        % via wf_context:page_module(Module), wf_context:path_info(PathInfo).
        {ok, State}.

    finish(_Config, State) ->
        {ok, State}.

### Cookie-based Authentication Example

As an example, you could automatically log in a user based on a cookie inside the security handler. This example assumes you'll check an authentication cookie stored with your login table within a database, providing a `db_login` module for interacting with the user table. It assumes the existance of a `db_login:loginid_from_cookie/1` function which takes an a `Cookie` and returns a `Loginid` or `undefined`.

    -module (bracketpal_security_handler).
    -behaviour (security_handler).
    -export ([
        init/2,
        finish/2
    ]).

    init(_Config, State) ->
        attempt_cookie_login(),
        {ok, State}.

    finish(_Config, State) ->
        {ok, State}.

    %% PRIVATE FUNCTIONS %%

    %% First, let's check to see if we've already tried to log in this user using
    %% cookies. If we have, then we don't want to keep trying, and hitting the
    %% database every time we load a page when we already know that it won't
    %% authenticate

    attempt_cookie_login() ->
        attempt_cookie_login(session).

    attempt_cookie_login(session) ->
        %% Have we already attempted a cookie login?
        %% If so, then skip it
        %% If not, let's try to authenticate with the cookie
        case wf:session_default(cookie_login_attempted,false) of
            false -> attempt_cookie_login(cookie);
            _ -> do_nothing
        end;
    attempt_cookie_login(cookie) ->
        %% Let's read the authentication token from our "quicklogin" cookie
        case wf:cookie(quicklogin) of
            undefined ->
                %% The cookie is undefined, so obviously there's nothing to log in
                do_nothing;
            Cookie ->
                %% Let's check our database to see if we have a user that's
                %% associated with our authentication cookie
                case db_login:loginid_from_cookie(Cookie) of
                    undefined ->
                      %% No user associated with that token, so let's just do nothing
                      do_nothing;
                    Loginid ->
                      %% Yes! We have a login associated with that cookie, so let's
                      %% Set use the Nitrogen user handler to set the loginid
                      wf:user(Loginid)
                end,

                %% Finally, we've now attempted to do a cookie login, so let's set
                %% a session variable so we don't try doing the cookie login again
                %% for this session
                wf:session(cookie_login_attempted,true)
        end.

### An HTTP Auth Example

Nitrogen also provides a simple HTTP Auth security handler for those interested in employing some HTTP auth-type user verification (courtesy of Torbjorn Tornkvist).

The full text of this can be viewed on Github

### See Also

- Handler Overview

Date: 2012-10-18 03:24:13 CDT

Author: Jesse Gumm (@jessegumm)

Org version 7.8.02 with Emacs version 23

Validate XHTML 1.0

## Comments

Note:To specify code blocks, just use the generic code block syntax:

    <pre><code>your code here</code></pre>

comments powered by Disqus