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.

constructor(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
});

constructor(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

constructor(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.

constructor(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)