Getting Started

Install with npm

npm install openam-agent

How to use in your Express app

• Create an agent profile in OpenAM (a 2.2 agent profile is enough since we only need a username and password, no server side config).

• Set up the express app and the agent:

var express = require('express'),
    openam = require('openam-agent');

var app = express(),
    agent = new openam.PolicyAgent({
        serverUrl: 'http://openam.example.com:8080/openam',
        appUrl: 'http://app.example.com:8080',
        notificationRoute: '/',
        notificationsEnabled: true,
        username: 'my-agent',
        password: 'changeit',
        realm: '/'
    });

app.use(agent.shield(new CookieShield()));

The agent can use implementations of the Shield class to protect resources. A shield can execute any code and then call success() or fail(). The abstract Shield class can be extended to introduce new agent features.

Shields

Built in Shield implementations:

• CookieShield: enforces a valid SSOToken in a cookie set by OpenAM
• OAuth2Shield: enforces a valid OAuth2 token (provided by OpenAM)
• BasicAuthShield: enforces a valid basic auth header (validates credentials against OpenAM)
• PolicyShield: enforces OpenAM policies for a certain entitlement application

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

var oauth2Shield = new openam.OAuth2Shield();
app.use('/api/for/mobile/devices', agent.shield(oauth2Shield), function (req, res, next) {
    // your route handler code here
});

var basicAuthShield = new openam.BasicAuthShield();
app.use('/api/for/challenged/clients', agent.shield(basicAuthShield), function (req, res, next) {
    // your route handler code here
});

var policyShield = new openam.PolicyShield('my-app');
app.use('/very/secure', agent.shield(policyShield), function (req, res, next) {
    // your route handler code here
});

Notifications

The agent can register session change listeners. It has a notifications middleware you can attach to your app:

app.use(agent.notifications);

It emits a session event if a session notification is received from OpenAM.

agent.notifications.on('session', function (session) {
    console.log('server - session changed!');
});

If notifications are enabled, sessions will be cached by CookieShield. Otherwise, sessions will be validated upon every request.

Logging

The PolicyAgent uses winstonjs for logging. If no logger instance is provided in the config, the agent will create its own logger. In this case, you can specify a log level in the config using with the logLevel property.

Each agent instance has a random ID. The logger created by the agent always logs this ID. E.g.:

If you're using your own logger instance, it's recommended that you override its log method to include the agent's id