Building a simple Basic HTTP Authentication Interceptor

Introduction

In this recipe we will create a simple interceptor that will be in charge of challenging users with HTTP Basic Authentication. It features the usage of all the new RESTful methods in our Request Context that will make this interceptor really straightforward. We will start by knowing that this interceptor will need a security service to verify security, so we will also touch on this.

The Interceptor

Our simple security interceptor will be intercepting at preProcess so all incoming requests are inspected for security. Remember that I will also be putting best practices in place and will be creating some unit tests and mocking for all classes. So check out our interceptor:

/**
* Intercepts with HTTP Basic Authentication
*/
component {

    // Security Service
    property name="securityService" inject="id:SecurityService";


    void function configure(){
    }

    void function preProcess(event,struct interceptData){

        // Verify Incoming Headers to see if we are authorizing already or we are already Authorized
        if( !securityService.isLoggedIn() OR len( event.getHTTPHeader("Authorization","") ) ){

            // Verify incoming authorization
            var credentials = event.getHTTPBasicCredentials();
            if( securityService.authorize(credentials.username, credentials.password) ){
                // we are secured woot woot!
                return;
            };

            // Not secure!
            event.setHTTPHeader(name="WWW-Authenticate",value="basic realm=""Please enter your username and password for our Cool App!""");

            // secured content data and skip event execution
            event.renderData(data="<h1>Unathorized Access<p>Content Requires Authentication</p>",statusCode="401",statusText="Unauthorized")
                .noExecution();
        }

    }

}

As you can see it relies on a SecurityService model object that is being wired via:

// Security Service
property name="securityService" inject="id:SecurityService";

Then we check if a user is logged in or not and if not we either verify their incoming HTTP basic credentials or if none, we challenge them by setting up some cool headers and bypass event execution:

// Verify Incoming Headers to see if we are authorizing already or we are already Authorized
if( !securityService.isLoggedIn() OR len( event.getHTTPHeader("Authorization","") ) ){

    // Verify incoming authorization
    var credentials = event.getHTTPBasicCredentials();
    if( securityService.authorize(credentials.username, credentials.password) ){
        // we are secured woot woot!
        return;
    };

    // Not secure!
    event.setHTTPHeader(name="WWW-Authenticate",value="basic realm=""Please enter your username and password for our Cool App!""");

    // secured content data and skip event execution
    event.renderData(data="<h1>Unathorized Access<p>Content Requires Authentication</p>",statusCode="401",statusText="Unauthorized")
        .noExecution();
}

The renderData() is essential in not only setting the 401 status codes but also concatenating to a noExecution() method so it bypasses any event as we want to secure them.

Interceptor Test

So to make sure this works, here is our Interceptor Test Case with all possibilities for our Security Interceptor.

component extends="coldbox.system.testing.BaseInterceptorTest" interceptor="simpleMVC.interceptors.SimpleSecurity"{

    function setup(){
        super.setup();
        // mock security service
        mockSecurityService = getMockBox().createEmptyMock("simpleMVC.model.SecurityService");
        // inject mock into interceptor
        interceptor.$property("securityService","variables",mockSecurityService);
    }

    function testPreProcess(){
        var mockEvent = getMockRequestContext();

        // TEST A
        // test already logged in and mock authorize so we can see if it was called
        mockSecurityService.$("isLoggedIn",true).$("authorize",false);
        // call interceptor
        interceptor.preProcess(mockEvent,{});
        // verify nothing called
        assertTrue( mockSecurityService.$never("authorize") );

        // TEST B
        // test NOT logged in and NO credentials, so just challenge
        mockSecurityService.$("isLoggedIn",false).$("authorize",false);
        // mock incoming headers and no auth credentials
        mockEvent.$("getHTTPHeader").$args("Authorization").$results("")
            .$("getHTTPBasicCredentials",{username="",password=""})
            .$("setHTTPHeader");
        // call interceptor
        interceptor.preProcess(mockEvent,{});
        // verify authorize called once
        assertTrue( mockSecurityService.$once("authorize") );
        // Assert Set Header
        AssertTrue( mockEvent.$once("setHTTPHeader") );
        // assert renderdata
        assertEquals( "401", mockEvent.getRenderData().statusCode );

        // TEST C
        // Test NOT logged in With basic credentials that are valid
        mockSecurityService.$("isLoggedIn",false).$("authorize",true);
        // reset mocks for testing
        mockEvent.$("getHTTPBasicCredentials",{username="luis",password="luis"})
            .$("setHTTPHeader");
        // call interceptor
        interceptor.preProcess(mockEvent,{});
        // Assert header never called.
        AssertTrue( mockEvent.$never("setHTTPHeader") );
    }


}

As you can see from our A,B, anc C tests that we use MockBox to mock the security service, the request context and methods so we can build our interceptor without knowledge of other parts.

Security Service

Now that we have our interceptor built and fully tested, let's build the security service.

component accessors="true" singleton{

    // Dependencies
    property name="sessionStorage"     inject="coldbox:plugin:SessionStorage";

    /**
    * Constructor
    */
    public SecurityService function init(){

        variables.username = "luis";
        variables.password = "coldbox";

        return this;
    }

    /**
    * Authorize with basic auth
    */
    function authorize(username,password){

        // Validate Credentials, we can do better here
        if( variables.username eq username AND variables.password eq password ){
            // Set simple validation
            sessionStorage.setVar("userAuthorized",  true );
            return true;
        }

        return false;
    }

    /**
    * Checks if user already logged in or not.
    */
    function isLoggedIn(){
        if( sessionStorage.getVar("userAuthorized","false") ){
            return true;
        }
        return false;
    }

}

We use a simple auth with luis and coldbox as the password. Of course, you would get fancy and store these in a database and have a nice object model around it. For this purposes was having a simple 1 time username and password. We also use the SessionStorage plugin in order to interact with the session scope with extra pizass and the most important thing: We can mock it!

Security Service Test

component extends="coldbox.system.testing.BaseModelTest" model="simpleMVC.model.SecurityService"{

    function setup(){
        super.setup();
        // init model
        model.init();
        // mock dependency
        mockSession = getMockBox().createEmptyMock("coldbox.system.plugins.SessionStorage");
        model.$property("sessionStorage","variables",mockSession);
    }

    function testauthorize(){

        // A: Invalid
        mockSession.$("setVar");
        r = model.authorize("invalid","invalid");
        assertFalse( r );
        assertTrue( mockSession.$never("setVar") );

        // B: Valid
        mockSession.$("setVar");
        r = model.authorize("luis","coldbox");
        assertTrue( r );
        assertTrue( mockSession.$once("setVar") );


    }

    function testIsLoggedIn(){

        // A: Invalid
        mockSession.$("getVar",false);
        assertFalse( model.isLoggedIn() );

        // B: Valid
        mockSession.$("getVar",true);
        assertTrue( model.isLoggedIn() );
    }

}

Again, you can see that now we use our BaseModelTest case and continue to use mocks for our dependencies.

Interceptor Declaration

Open your Coldbox.cfc configuration file and add it.

//Register interceptors as an array, we need order
interceptors = [
    //SES
    {class="coldbox.system.interceptors.SES"},
    // Security
    { class="interceptors.SimpleSecurity" }
];

We just add our Simple Security interceptor and reinit your application and you should be now using simple security.