-
Notifications
You must be signed in to change notification settings - Fork 12
Concepts
A Policy Agent is an application that enforces access control decisions provided by OpenAM. The agent is usually a filter inside the resource server that sits between the request and the resource. When a request comes in, the agent gets decisions from OpenAM and allows or denies the resource to be delivered to the requester.
node-openam-agent uses express middleware functions to filter requests. Given the flexible structure of express middleware, the various agent features can be used in many ways to protect resources (unlike with other policy agent implementations where only a single policy agent instance can be used for the entire app server).
The agent uses a library to OpenAM. This library is a lightweight OpenAM client that uses the latest stable REST APIs in OpenAM.
An agent is an instance of the PolicyAgent class. It will need some configuration (username, password, cache settings etc.) The agent is an object that has all the logic and privileges to fetch access control decisions from OpenAM.
You can create several PolicyAgent instances for the same application – this allows you to use different OpenAM servers for different routes in your app (or different cache settings, etc.).
Shields are a unique concept to this agent implementation and provide various strategies for getting and enforcing access control decisions. Other existing agent implementations are only capable of getting decisions based on the user's session cookie. However, times have changed and OpenAM now provides alternative ways to get decisions (e.g. OAuth2 and JWT).
With shields, you can use different decision techniques for different routes, depending on what makes the most sense. For HTML resources you may want to go down the classic route and use cookies as a means to get decisions and redirect users to OpenAM if their session is invalid. However, you may have certain routes that are only used asynchronously from a rich web application (typically JSON resources) – for these you wouldn't want to return a 302 response, but a 401 instead, and let the client app handle the error response. You can also have other resources that weren't meant to be consumed in a browser, but perhaps a native mobile application instead – in such cases you can take advantage of OAuth2 authorization.
This agent is meant to be more deeply integrated into the protected application as other agents. The idea is to provide flexibility and ease of access within the code of your app, rather than centralizing the configuration in OpenAM.
The point of Shield concept is to make the agent extensible. Feel free to inherit the "abstract" Shield class and write your own shield that uses OpenAM in a way that is best for your application.