API

Public APIs

node-openam-agent exposes most of its core functionality to let you access all sorts of OpenAM features.

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...)

OpenAMClient class

getServerInfo()

Gets the results of /json/serverinfo/* and mixes them in to PolicyAgent.serverInfo

authenticate(username, password, realm, service, module, noSession)

Sends an authentication request to OpenAM. Returns Promise. The module argument overrides service. The default realm is /. If noSession is true, the credentials will be validated but no session will be created.

logout(sessionId)

Sends a logout request to OpenAM to to destroy the session identified by sessionId. Returns Promise.

validateSession(sessionId)

Validates a given sessionId against OpenAM. Returns Promise.

getLoginUrl(req)

Returns an OpenAM login URL with the goto query parameter set to the original URL in req (req must be an instance of IncomingRequest). Returns String.

getPolicyDecision(params, sessionId, cookieName)

Gets policy decisions from OpenAM for params. params must be a well formatted OpenAM policy request object:

params = {
    resources: [
        '/foo',
        '/bar'
    ],
    application: 'my-app',
    subject: {
        ssoToken: '...'
    },
    environment: {}
}

It needs a valid sessionId and cookieName in order to make the request. (The user to whom the session belongs needs to have the REST calls for policy evaluation privilege in OpenAM. Returns Promise.

sessionServiceRequest(requestSet)

Sends requestSet to the SessionService. requestSet must be a properly formatted XML document. Returns Promise.

validateAccessToken(accessToken, realm)

Validates the OAuth2 access_token in the specified realm. Returns Promise.

getProfile(userId, realm, agentSessionId, cookieName)

Gets a user's profile (requires an agent or admin session).

Params:

• userId: the uid of the user whose profile to get
• realm: the realm of the user
• agentSessionId: a valid session ID with permissions to read user identities from the specified realm
• cookieName: name of the OpenAM session cookie

PolicyAgent class

PolicyAgent(config)

The constructor function, whose argument should be an object of config options (listed below).

var config = {
    serverUrl: 'http://openam.example.com:8080/openam',
    appUrl: 'http://app.example.com:8080',
    notificationRoute: '/',
    notificationsEnabled: true,
    username: 'my-agent',
    password: 'changeit',
    realm: '/',
    logLevel: 'info'
};

var agent = new PolicyAgent(config);

Config options

• serverUrl: The deployment URI of the OpenAM server, e.g. http://openam.example.com:8080/openam,

• appUrl: The root URL of the application, e.g. http://app.example.com:8080.

• notificationsEnabled: If enabled, the agent will cache sessions and register a change listener for them in OpenAM. Cached sessions will not be revalidated against OpenAM. The notifications middleware has be added to the express application for notifications to work (adds an /agent/notifications endpoint which can receive notifications from OpenAM).

• notificationRoute: The route to which the notifications middleware is attached.

  app.use('/foo/bar/baz', agent.notifications);
  app.listen(8080);

  In the above case the notificationRoute should be /foo/bar/baz. Notifications will be sent to http://app.example.com:8080/foo/bar/baz/agent/notifications.

• username: The agent's username in OpenAM

• password: The agent's password in OpenAM

• realm: Name of the realm in OpenAM in which the agent profile exists. Default: /

• errorPage: Callback function; If present, the function's return value will be sent as an error page, otherwise the default error template will be used.

  config = {
      ...
      errorPage: function (status, message, details) {
          return '<html><body><h1>' + status + ' - '  + message + '</h1></body></html>'
      }
      ...
  }

• logger: winston Logger A winstonjs logger instance. If falsy, a new Console logger is created.

• logLevel: logging level see winston's documentation Default: error. Only used when logger is falsy.

id

Short random ID that lets you differentiate agents in logs, etc.

config

The config object passed to the constructor.

serverInfo

A Promise returned by getServerInfo(). Once resolved, the response is mixed into the serverInfo object.

agentSession

Originally an empty Promise (haha). Whenever a certain client request needs an agent session, the agent will get authenticated and agentSession will become a Promise returned by authenticateAgent(). Once resolved, the response is mixed into the agentSession object.

openAMClient

An instance of OpenAMClient.

notifications

An instance of NotificationHandler that also serves as an EventEmitter. Events are emitted when notifications are received.

notifications.routes

Express middleware that has a single route: /agent/notifications.

Events

• session: a session service notification is received. Callbacks will be called with a session argument.

authenticateAgent()

Authenticates the policy agent using the credentials in the config object. Returns Promise.

validateSession(sessionId)

Validates a given sessionId against OpenAM and adds a session listener if valid. Returns Promise.

getUserProfile(userId, realm)

Fetches the user profile for a give UID.

getPolicyDecision(params)

Gets policy decisions from OpenAM for the req.originalUrl resource and the application name specified in the agent config (req must be an instance of IncomingRequest). Returns Promise.

registerSessionListener(sessionId)

Constructs a RequestSet document containing a AddSessionListener node for sessionId, and sends it to the SessionService. Returns Promise.