Contributors: Sandeep Chaturvedi, Rob Jackson, Derek Small
The following report has been prepared by Nulli – Identity Solution Architects for use by our peers, customers, partners and Identity and Access Management teams interested in learning more about deploying the ForgeRock Identity Relationship Management stack with the REST API.
ForgeRock products OpenIDM, OpenAM, OpenDJ provide their users with unparalleled flexibility
Common REST and ForgeRock: Architecture Deployment Considerations
June 09, 2014
Version: 1.0
Audience and Distribution Information
This report has been prepared by Nulli – Identity Solution Architects for use by our peers, customers, partners and Identity and Access Management teams interested in learning more about deploying the ForgeRock Identity Relationship Management stack with the REST API.
Document Status
This document is deemed to be open for public disclosure or distribution.
Contents and figures subject to change at any time as we continue to refine the information upon which this report is written.
About Nulli
Nulli Identity Solution Architects is a leading Human Information and Identity Management Integrator providing successful outcomes to organizations architecting, designing, implementing and supporting Identity and Human Capital initiatives. “It’s about People”, the Nulli motto, defines how Nulli focuses on the value of people and the need to maintain a person centric approach to Human Information and Identity Management applications.
Nulli Core Values
We provide successful outcomes for our clients, our partners and ourselves by adhering to our values of Integrity, Knowledge and Partnership. Our development of the content of this report was completed with our values being upheld.
Nulli – Contacts – www.nulli.com
Derek Small
+1.403.648.0901
President & CEO
Background
ForgeRock products OpenIDM, OpenAM, OpenDJ provide their users with unparalleled flexibility in terms of customizing user Identity and Access Management (IAM) experience. ForgeRock provides the opportunity to do away with inflexible GUIs by exposing endpoints for most identity functions – allowing implementors a chance to deliver only the functionality and features to satisfy solution requirements. This paper explores a recent customer deployment by Nulli to identify security, business, and technical concerns about exposing the ForgeRock Common REST (CREST) Interface to external AJAX clients. Its goal is to provide insight into the tips and techniques associated with implementing a solution of this architecture.
The solution requirements include design and implementation of a highly performant, highly available, and scalable digital identity provider service that allows system users to
Integration of AJAX and REST Web architecture styles is an effective approach to address these requirements.
The benefits of AJAX/REST integration. Introduced in 2000 by Roy Fielding, the Representational State Transfer (REST) provides an architectural protocol for hypermedia applications to take advantage of Web properties. With the growth in the Web’s usage however, applications have become more immersive to provide rich personalized application experiences. Letting the REST processing for these applications be mostly server side creates a complex environment. Moving processes to the server leads to the violation of REST constraints, especially server-statelessness and thus failure in achieving reliability and scalability. A mitigation methodology for this situation is to leverage the use of Asynchronous JavaScript and XML (AJAX). AJAX helps reduce the server-side complexity by allowing most of the UI and application logic to reside in the browser. This AJAX/REST combination promises to support the creation of desired immersive Web applications with benefits such as server robustness, scalability, and balanced processing between client and server.
The IAM solution architecture for such an approach is depicted in Figure 1. A session is initiated by a user browsing to the service provider page at which point the web-server sends the associated AJAX code to the browser. The AJAX code executes in the browser and is responsible for the translation of the user’s input into REST calls submitted to the ForgeRock IAM components, and is also responsible for converting REST responses into human consumable or UI-convenient formats.
Other constraints we were trying to address included provisioning marketing events that would trigger high volume registrations simultaneously with very high volume authentication, authorization and federation with n-Service Providers and Relying Parties. Nulli’s architecture definition was formulated based on the technical requirement for client browser based processing for business logic leveraging AJAX with the ForgeRock IAM CREST interface. Nulli’s solution architecture relies on the ForgeRock stack and standard supporting middleware components such as reverse-proxies and load balancers as well as the use of a middle-tier application server to provide customization of communication/validation messages whenever appropriate. The middle-tier application server sits between the User Interface (UI) and the IAM stack and provides Nulli developed “wrappers” for the REST service requests/responses that make them easy to consume by target endpoints in the process tree.
The browser initiated AJAX REST calls could be sent directly to OpenAM and OpenIDM thanks to the CREST API. This solution however utilizes a middle-tier wrapper that helps address some business-logic and security related concerns with the current version of the ForgeRock stack. The addition of the custom middle-tier adds some complexity and possibly increases overhead. Nulli developed a series of techniques for reducing, if not eliminating, the complexity and have created a best practices model to minimize the chance of performance being impacted due to our adopted approach. Nulli Identity Solution Architects will update this paper once we have representative data of performance from the production deployment of the solution.
This architecture was developed with the current stable versions of the ForgeRock software at the time designed:
Considerations and Objectives
The following enumerates various considerations that were of interest during this particular deployment. These considerations are in no way complete but rather ones the authors believe are of particular significance while architecting a REST based ForgeRock deployment.
Performance Considerations
Middle-tier! To be or not to be:
We applied a middle-tier layer to provide common wrapped REST calls that allowed for a simplified set of access calls for the UI/UX teams. This addition of a middle-tier adds to the traffic on the network but it is not anticipated to be a significant overhead and should be readily managed. Throughput might even improve by allowing the middle-tier to make internal queries to OpenAM and OpenIDM when completing validation or lookup of data for policy decisions during registration use cases and verification. If performance becomes a concern we can scale up the application servers to support performance demands as we assess load management during stress testing prior to moving to production. This interface to this middle tier is still implemented in REST, continues to be stateless, and still resembles the ForgeRock CREST API.
Unverified user handling! OpenIDM or OpenAM:
The ForgeRock IAM products, utilizing their common REST API are all capable of dealing with user registration use cases. In one use case, the business might want users to complete their registration through a two step process. After the initial registration of stub data we wanted to have the user verify this data and this registration process as being originated with them and not a “bot”. The user will complete the second step by clicking on a verification link received via email after their initial registration is saved. This verification link is time limited and associated with the new account. If the verification is not clicked on and thus verified prior to the time limit then the initial registration is deleted with the assumption being that the user registered in error or wasn’t interested enough to complete the process. The use case is broadly described as follows: During the initial creation or registration process, the user enters an “unverified” state and stays in this state until they receive and click on the registration verification link sent to them via their supplied email address.
A couple of questions that arise from this type of two-step registration use case are:
The use of each of these products has its own set of pros and cons to consider with respect to achieving the business requirements and satisfying the technical constraints of the client infrastructure. Initially we considered relying on the use of OpenIDM to maintain the unverified user accounts in the multi-step verification process. We considered this approach as it appeared that it might be a good idea to leave unverified user accounts only in the OpenIDM repository in order to avoid creation of orphan accounts in the directory and to minimize the management of related calls in OpenDJ. We also considered using OpenDJ as the single point of storage for unverified accounts and thus allow OpenAM to authenticate unverified users during the multi-step registration to allow them to complete the process using only the OpenAM toolset.
Our Decision. Utilizing the database storage system contained in OpenIDM meant that we had to rely on bringing into the team database expertise in support of redundancy of the data across geographically dispersed data centres. We also would need to support the use of the OpenIDM authentication process whereas we wanted to rely on the OpenAM application as the authority for all authentication processes. Taking into account our client’s business requirements, we chose to use OpenAM as the only resource for authentication and hence to store unverified accounts in OpenDJ. This utilizes OpenDJ’s highly scalable and performant multi-master replication to keep separate instances in sync.
Business Requirement Considerations
Registration form submission – Two-step vs one-step:
The two-step registration process followed this basic flow of: user fills out the registration form, submits, receives an email confirmation of registration, reads terms & conditions, confirms account registration by clicking on verification link contained in the email. This two-step process could introduce a complexity to the system in peak volume registration moments such as during the case when User1 is reading terms and conditions while User2 registers User1’s username and completes the two-step registration just before User1. Different use cases were proposed to handle this scenario which would either add complexity to the UI code or add load to the IAM stack. We finally decided to use a one-step registration that was based on a form that contained Terms and Conditions and registration tombstone data and thus avoid unnecessary complexity and this peak volume registration concern.
Security Considerations
In this section, we enumerate some of the security challenges about using RESTful services and discuss how we address them in our case study. This study takes into account OWASP’s best security practices on using RESTful services.
Authentication and Session Management: As REST is server-stateless, the OpenIDM REST interface requires users to send their credentials as URL parameters for each request made to the backend. To avoid cleartext transfer of credentials, the given architecture allows the browser to pass user’s proof-of-authentication as an SSL-encrypted cookie and takes advantage of the middle-tier server to find credentials from the token and convert the browser’s request to an OpenIDM REST call.
Authorization and anti-framing: It is difficult to distinguish legitimate clients from malicious ones when it comes to anonymous service requests, which do not provide any user credentials. Suggested OWASP guidelines include client-side SSL and CAPTCHA. While the former is not applicable in our case, our solution adopts CAPTCHA verification in the required places to address this issue. This is further boosted by another layer of protection offered by the load balancing appliances.
Protecting HTTP methods and actions: OpenIDM REST interface allows access to backend resources via HTTP methods and actions. It also allows for role-based access control to protect such resource against unauthorized access. We use this service and create a access whitelist by following the minimum privilege principle. In addition, for the most of endpoint URLs, we only allow REST calls from the middle-tier server thanks to its involvement in the designed architecture.
In some cases, the same action can be performed via multiple REST endpoints. Some are more resource-focused (utilizing HTTP verbs with resource specifically defined in the path), while some are more general using only POST, and allow the resource and/or action to be defined in the JSON payload. We avoided the use when possible of the generalized POSTs as they allow for more ambiguity and could potentially be used to inject unintended actions.
Input validation and output encoding: Sanitizing input and output data to and from the IAM stack is one of the essential security requirements from any IAM solution. Failing to validate input data may cause tampering and leakage of the system internal state, and lack of output data encoding may result in revealing sensitive information to a potentially untrusted user. Thankfully, OpenIDM and OpenAM both provide OOTB mechanisms to check input and output data and to make sure they are safe. This leaves us to be responsible only for business-level requirements of user data validations which is done by the middle-tier JSON libraries, during user registration.
Protecting against XSS, Injection, and CSRF attacks: Protection against XSS and injection attacks relies on applying input validation and the minimum privileges principle, which we have already considered above. The CSRF attack risk however needs to be tackled differently. The CSRF attack makes a victim browser send a malicious HTTP request to the server. This attack succeeds if (1) the browser has a valid session, and (2) the malicious HTTP request is a valid REST call. Hence, to mitigate the risk, we (1) use short-term session cookies, and (2) use unpredictable GUIDs for OpenIDM managed user endpoints. We believe that these two features drastically decrease the CSRF attack risk without sacrificing the performance. Besides, we are also investigating the possibility of adding the SSOtoken hash to the URL to further avoid receiving malicious but valid HTTP requests. The security of the system will be further investigated in the penetration testing process.
Final Thoughts
These are just a few identity patterns that Nulli Identity Solution Architects address on behalf of our clients who rely on us to bring a balanced approach to achieve their business goals. Remember that there is more than one way to achieve your goal using the same set of ForgeRock IRM tools. Each client scenario is going to have differing registration requirements and as such Nulli is prepared to assist our clients to review the use cases identified by the our clients and also provide them with use cases they might overlook in the process. Nulli is pleased to share this brief overview of a few Identity use cases required to successfully deploy a resilient Identity Relationship Management infrastructure.
