Shield

• Shield class
• CookieShield class
• PolicyShield class
• OAuth2Shield class
• BasicAuthShield class

Shield class

Abstract class. Implement your own Shield and plug it into the agent. It's really simple:

// shield implementation 

var util = require('util'),
    openamAgent = require('openam-agent');
    
function MyShield(options) {
    this.options = options;
}

util.inherits(MyShield, Shield);

MyShield.prototype.evaluate = function (req, success, fail) {
    var sessionKey, sessionData;
    if (this.options.foo) {
        // do something
        sessionKey = 'foo';
        sessionData = 'bar';
        success(sessionKey, sessionData);
    } else {
        // failure
        fail(401, 'Unauthorized', 'Missing Foo...');
    }
};

// including it in the express app 

app.use(agent.shield(new MyShield({foo: 'bar'})));

CookieShield class

This shield checks if the request contains a session cookie and validates it against OpenAM. The session is cached if notifications are enabled, otherwise it's re-validated for every request.

CookieShield(params)

The constructor function can be called with a params object or a string (whose value will be used to override the default cookie name). Available options:

• cookieName: overrides the cookie name that was retrieved from OpenAM with PolicyAgent.getServerInfo()
• noRedirect: if true, the agent will not redirect to OpenAM's login page for authentication, only return a 401 response
• getProfiles: Boolean. If true, the agent will fetch and cache the user's profile when validating the session. Default: false
• passThrough: Boolean. If true, the shield will not enforce valid sessions. This is useful in conjunction with getProfiles:true when a route is public but you want fetch identity information for any logged in users. Default: false

PolicyShield class

This shield fetches policy decisions from OpenAM for the requested path, specified application name and current user. It requires a valid session cookie. Typically used in a chain with CookieShield:

var cookieShield = new openam.CookieShield();
var policyShield = new openam.PolicyShield('my-app');

app.use('/some/protected/route', agent.shield(cookieShield), agent.shield(policyShield), function (req, res, next) {
    // your route handler code here
});

PolicyShield(applicationName)

The constructor function can be called with an applicationName argument whose value will be used as the application name when fetching policy decisions. Default: iPlanetAMWebAgentService;

OAuth2Shield class

This Shield implementation validates an OAuth2 access_token issued by OpenAM, using OpenAM's /oauth2/tokeninfo service. The access_token must be sent in an Authorization header:

curl -H 'Authorization Bearer 2dcaac7a-8ce1-4e62-8b3a-0d0b9949cc98' http://app.example.com:8080/mobile

OAUth2Shield(realm)

realm is the OpenAM realm in which the token should validated (default: /).

BasicAuthShield class

This shield will enforce basic auth. Credentials will be checked against OpenAM.

BasicAuthShield(params)

Available params:

• realm: name of the realm in OpenAM to which the suer should be authenticated (default: /)
• service: chain/service name used for authentication
• module: module name used for authentication (overrides service)

NotificationHandler class

Returns an object that can be used to manage notifications. Used internally by PolicyAgent.

router

An instance of express.Router. It can be used as a middleware for your express application. It adds a single route: /agent/notifications which can be used to receive notifications from OpenAM. When a notification is received, its contents will be parsed and handled by one of the handler functions.

sessionNotification()

Notification handler for session notifications. When a session notification is received, it will emit a session event. CookieShield instances listen on this event to delete any destroyed cookies from the agent's session cache.

app.use(agent.notifications.router);
agent.notifications.on('session', function (session) {
    console.log('server - session changed: %s', JSON.stringify(session));
});

(more notification handlers are coming soon...)