Common REST and ForgeRock: Architecture Deployment Considerations

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 –

Derek Small


President & CEO


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

  1. register their accounts,
  2. update their profiles and credentials,
  3. use their accounts as a point of reference for identity federation, and
  4. register/reach to other services in the federation.

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.

Solution Architecture for Discussion

Figure 1. The IAM solution architecture

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:

  • OpenDJ 2.6
  • OpenIDM 2.1
  • OpenAM 11

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:

  1. How do we decide which ForgeRock tool to employ to achieve this kind of registration use case?
  2. How do we decide between the using the OpenDJ REST API versus the use of the REST API for OpenIDM?

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.