Basic HTTP Authentication Interceptor

Search…
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.
You can find the code for this recipe here: https://github.com/coldbox-samples/simple-auth​
Application Setup
Let's start building the app using CommandBox and installing all the necessary dependencies:
1
# create our folder
2
mkdir simple-auth --cd
3
# generate a coldbox app
4
coldbox create app "SimpleAuth"
5
# Install extra dependencies
6
install cbStorages
7
# Startup the server
8
server start
Copied!
Use [email protected] if using ColdBox Pre-Releases
Security Service
Let's build a simple security service to track users. Use CommandBox to generate the service model with two functions and let's mark it as a singleton:
1
coldbox create model SecurityService authorize,isLoggedIn singleton
Copied!
This will create the models/SecurityService and the companion unit tests. Let's fill them out:
Security Service Test
1
/**
2
* The base model test case will use the 'model' annotation as the instantiation path
3
* and then create it, prepare it for mocking and then place it in the variables scope as 'model'. It is your
4
* responsibility to update the model annotation instantiation path and init your model.
5
*/
6
component extends="coldbox.system.testing.BaseModelTest" model="models.SecurityService"{
7
​
8
    /*********************************** LIFE CYCLE Methods ***********************************/
9
​
10
    function beforeAll(){
11
        super.beforeAll();
12
​
13
        // setup the model
14
        super.setup();
15
​
16
        mockSession = createMock( "modules.cbstorages.models.SessionStorage" )
17
    }
18
​
19
    function afterAll(){
20
        super.afterAll();
21
    }
22
​
23
    /*********************************** BDD SUITES ***********************************/
24
​
25
    function run(){
26
​
27
        describe( "SecurityService Suite", function(){
28
​
29
            beforeEach(function( currentSpec ){
30
                model.init();
31
                model.setSessionStorage( mockSession );
32
            });
33
​
34
            it( "can be created (canary)", function(){
35
                expect( model ).toBeComponent();
36
            });
37
​
38
            it( "should authorize valid credentials", function(){
39
                mockSession.$( "set", mockSession );
40
                expect( model.authorize( "luis", "coldbox" ) ).toBeTrue();
41
            });
42
​
43
            it( "should not authorize invalid credentials ", function(){
44
                expect( model.authorize( "test", "test" ) ).toBeFalse();
45
            });
46
​
47
            it( "should verify if you are logged in", function(){
48
                mockSession.$( "get", true );
49
                expect( model.isLoggedIn() ).toBeTrue();
50
            });
51
​
52
            it( "should verify if you are NOT logged in", function(){
53
                mockSession.$( "get", false );
54
                expect( model.isLoggedIn() ).toBeFalse();
55
            });
56
​
57
        });
58
​
59
    }
60
​
61
}
Copied!
Security Service
1
component accessors="true" singleton{
2
​
3
    // Dependencies
4
    property name="sessionStorage" inject="[email protected]";
5
​
6
    /**
7
     * Constructor
8
     */
9
    function init(){
10
            // Mock Security For Now
11
        variables.username = "luis";
12
        variables.password = "coldbox";
13
​
14
        return this;
15
    }
16
​
17
    /**
18
     * Authorize with basic auth
19
     */
20
    function authorize( username, password ){
21
​
22
        // Validate Credentials, we can do better here
23
        if( variables.username eq username AND variables.password eq password ){
24
            // Set simple validation
25
            sessionStorage.set( "userAuthorized", true );
26
            return true;
27
        }
28
​
29
        return false;
30
    }
31
​
32
    /**
33
     * Checks if user already logged in or not.
34
     */
35
    function isLoggedIn(){
36
            return sessionStorage.get( "userAuthorized", "false" );
37
    }
38
​
39
}
Copied!
Please note that we are using a hard coded username and password, but you can connect this to any provider or db.
The Interceptor
Let's generate the interceptor now and listen to preProcess
1
coldbox create interceptor name="SimpleSecurity" points="preProcess"
Copied!
The preProcesslistener is to listen to all incoming requests are inspected for security. Please note that the unit test for this interceptor is also generated. Let's fill out the interceptor test first:
Interceptor Test
So to make sure this works, here is our Interceptor Test Case with all possibilities for our Security Interceptor.
1
component extends="coldbox.system.testing.BaseInterceptorTest" interceptor="interceptors.SimpleSecurity" {
2
​
3
    /*********************************** LIFE CYCLE Methods ***********************************/
4
​
5
    function beforeAll() {
6
        super.beforeAll();
7
​
8
        // mock security service
9
        mockSecurityService = createEmptyMock( "models.SecurityService" );
10
    }
11
​
12
    function afterAll() {
13
        super.afterAll();
14
    }
15
​
16
    /*********************************** BDD SUITES ***********************************/
17
​
18
    function run() {
19
        describe( "SimpleSecurity Interceptor Suite", function() {
20
            beforeEach( function( currentSpec ) {
21
                // Setup the interceptor target
22
                super.setup();
23
                // inject mock into interceptor
24
                interceptor.$property(
25
                    "securityService",
26
                    "variables",
27
                    mockSecurityService
28
                );
29
                mockEvent = getMockRequestContext();
30
            } );
31
​
32
            it( "can be created (canary)", function() {
33
                expect( interceptor ).toBeComponent();
34
            } );
35
​
36
            it( "can allow already logged in users", function() {
37
                // test already logged in and mock authorize so we can see if it was called
38
                mockSecurityService.$( "isLoggedIn", true ).$( "authorize", false );
39
                // call interceptor
40
                interceptor.preProcess( mockEvent, {} );
41
                // verify nothing called
42
                expect( mockSecurityService.$never( "authorize" ) ).toBeTrue();
43
            } );
44
​
45
            it( "will challenge if you are not logged in and you don't have the right credentials", function() {
46
                // test NOT logged in and NO credentials, so just challenge
47
                mockSecurityService.$( "isLoggedIn", false ).$( "authorize", false );
48
                // mock incoming headers and no auth credentials
49
                mockEvent
50
                    .$( "getHTTPHeader" )
51
                    .$args( "Authorization" )
52
                    .$results( "" )
53
                    .$( "getHTTPBasicCredentials", { username : "", password : "" } )
54
                    .$( "setHTTPHeader" );
55
                // call interceptor
56
                interceptor.preProcess( mockEvent, {} );
57
                // verify authorize called once
58
                expect( mockSecurityService.$once( "authorize" ) ).toBeTrue();
59
                // Assert Set Header
60
                expect( mockEvent.$once( "setHTTPHeader" ) ).toBeTrue();
61
                // assert renderdata
62
                expect( mockEvent.getRenderData().statusCode ).toBe( 401 );
63
            } );
64
​
65
            it( "should authorize if you are not logged in but have valid credentials", function() {
66
                // Test NOT logged in With basic credentials that are valid
67
                mockSecurityService.$( "isLoggedIn", false ).$( "authorize", true );
68
                // reset mocks for testing
69
                mockEvent
70
                    .$( "getHTTPBasicCredentials", { username : "luis", password : "luis" } )
71
                    .$( "setHTTPHeader" );
72
                // call interceptor
73
                interceptor.preProcess( mockEvent, {} );
74
                // Assert header never called.
75
                expect( mockEvent.$never( "setHTTPHeader" ) ).toBeTrue();
76
            } );
77
        } );
78
    }
79
​
80
}
Copied!
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.
Interceptor Code
interceptors/SimpleSecurity.cfc
1
/**
2
 * Intercepts with HTTP Basic Authentication
3
 */
4
component {
5
​
6
    // Security Service
7
    property name="securityService" inject="provider:SecurityService";
8
​
9
    void function configure(){}
10
​
11
    void function preProcess( event, interceptData, rc, prc ){
12
​
13
        // Verify Incoming Headers to see if we are authorizing already or we are already Authorized
14
        if( !securityService.isLoggedIn() OR len( event.getHTTPHeader( "Authorization", "" ) ) ){
15
​
16
            // Verify incoming authorization
17
            var credentials = event.getHTTPBasicCredentials();
18
            if( securityService.authorize(credentials.username, credentials.password) ){
19
                // we are secured woot woot!
20
                return;
21
            };
22
​
23
            // Not secure!
24
            event.setHTTPHeader(
25
                name     = "WWW-Authenticate",
26
                value     = "basic realm=""Please enter your username and password for our Cool App!"""
27
            );
28
​
29
            // secured content data and skip event execution
30
            event
31
                .renderData(
32
                    data         = "<h1>Unathorized Access<p>Content Requires Authentication</p>",
33
                    statusCode     = "401",
34
                    statusText     = "Unauthorized"
35
                )
36
                .noExecution();
37
        }
38
​
39
    }
40
​
41
}
Copied!
As you can see it relies on a SecurityService model object that is being wired via:
1
// Security Service
2
property name="securityService" inject="provider:SecurityService";
Copied!
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:
1
// Verify Incoming Headers to see if we are authorizing already or we are already Authorized
2
if( !securityService.isLoggedIn() OR len( event.getHTTPHeader("Authorization","") ) ){
3
​
4
    // Verify incoming authorization
5
    var credentials = event.getHTTPBasicCredentials();
6
    if( securityService.authorize(credentials.username, credentials.password) ){
7
        // we are secured woot woot!
8
        return;
9
    };
10
​
11
    // Not secure!
12
    event.setHTTPHeader(name="WWW-Authenticate",value="basic realm=""Please enter your username and password for our Cool App!""");
13
​
14
    // secured content data and skip event execution
15
    event.renderData(data="<h1>Unathorized Access<p>Content Requires Authentication</p>",statusCode="401",statusText="Unauthorized")
16
        .noExecution();
17
}
Copied!
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 Declaration
Open your Coldbox.cfc configuration file and add it.
1
//Register interceptors as an array, we need order
2
interceptors = [
3
    // Security
4
    { class="interceptors.SimpleSecurity" }
5
];
Copied!
Now reinit your app coldbox reinit and you are simple auth secured!
Why provider
You might have noticed the injection of the security service into the interceptor used a provider: DSL prefix, why? Well, global interceptors are created first, then modules are loaded, so if we don't use a provider to delay the injection, then the storages module might not be loaded yet.
Extra Credit
Now that the hard part is done, we encourage you to try and build the integration test for the application now. Please note that most likely you would NOT do the unit test for the interceptor if you do the integration portion in BDD Style.
Clearing the View Cache
Next - Digging Deeper
Scheduled Tasks
Last modified 1yr ago
Copy link
Contents
Introduction
Application Setup
Security Service
Security Service Test
Interceptor Declaration
Why provider
Extra Credit