The goal of this guide is to describe a recipe of how to configure OpenIG to connect to Connect.gov, test and then integrate with existing agency applications.
The following solution is some sample configuration for OpenIG that is known to work with Connect.gov (http://www.connect.gov) For details of OpenIG and how to install please go here: (http://docs.forgerock.org/en/index.html?product=openig&version=3.0.0)
In short the prerequisites are:
- Java Development Kit 6, 7, or 8. ForgeRock recommends the most recent update to ensure you have the latest security fixes.
- Apache Tomcat 7
At some point to actually be able to invoke the services provided by Connect.gov, correspondence and formal on-boarding process with them will need to occur. Details of that are out of scope of this paper but contact information for Connect.gov should be found on their site. Feel free to test out OpenIG on it's own merit prior to that on-boarding, just be aware that the FederalConnect config will until that process has been completed and the artifacts exchanged from them are also copied to the OpenIG configuration folders as detailed below.
|Table of Contents|
ForgeRock FederalConnect solution is comprised of OpenIG product and preconfigured Connect.gov settings to provide rapid deployment relative to general purpose integration efforts. In addition to providing SAML requests and response on behalf of agency applications, thereby insulating application owners and developers from the complexity of SAML, ForgeRock solution also provides automated routing and attribute injection. This provides applications standard mechanisms to request and consume identity data from the Connect.gov service without needing to retrofit applications to support SAML or become locked into vendor specific APIs. This solution leverages HTTP/HTML only from an application integration perspective, eliminating proprietary from the equation and of course supporting SAML and FICAM standards as part of the preconfigured templates.
Where Connect.gov provides a consistent service on behalf of the user regardless of complexity of CSP/IDP ecosystem, ForgeRock provides a consistent Connect.Gov[SAML] service on behalf of Agency Applications, regardless of how many applications that want to participate with the Connect.gov service.
Step 1: Downloads
Download prerequisites on to a operating system such as Windows or LINUX.
- Java JDK: http://www.oracle.com/technetwork/java/javase/overview/index.html
- Apache Tomcat: http://tomcat.apache.org/download-70.cgi
- OpenIG 3.0 or 3.1: https://backstage.forgerock.com/#!/downloads/OpenIG
- Download the FederalConnect samples and tester app here: https://github.com/sjarosz/federalconnect
Step 2: Installation
- After Tomcat is installed it needs to be prepared for OpenIG. Details of that are here: http://docs.forgerock.org/en/openig/3.0.0/gateway-guide/index/chap-install.html#configure-container
- Now install OpenIG into Tomcat. Name the OpenIG.war file to ROOT.war and copy into the Tomcat webapps folder. Additional details here: http://docs.forgerock.org/en/openig/3.0.0/gateway-guide/index/chap-install.html#install
- Now install the FederalConnect into Tomcat. a) Copy the testerapp file to Tomcat webapps folder. b) Copy the OpenIG config files to existing OpenIG config folder
Step 3: Launch FederalConnect Validator
Point browser to Tomcat instance (ex. http://host.domain.com:8080/federalconnect) Where the URI component federalconnect corresponds to the .war file name that was deployed into Tomcat.
You should see a page similar to the following:
At this point your metadata is ready to exchange to Connect.gov, however the digital certificates in the metadata should be hardened for production. (Out of scope of this doc).
To share the metadata with Connect.gov, click on the <show> link next to the SP EntityID. (for example, https://myhost.mydomain.gov/federalconnect/saml2/jsp/exportmetadata.jsp) This will reveal the configured metadata and the URL link in the browser can be sent to them or the contents copied and sent to them per their instructions.
The configured IDP (Connect.gov) metadata is only at this point a template and will not work. Before actual testing can occur, live metadata must first be obtained from Connect.gov and copied into the OpenIG SAML folder
Step 4: After Connect.gov on-boarding has completed
Rename the SAML2 metadata sent from Connect.gov to connect.gov and place into OpenIG/SAML folder. $HOME/.openig/SAML on Linux, Mac OS X, and UNIX systems, and %appdata%\OpenIG\SAML on Windows systems.
Relaunch the FederalConnect validator in the browser and attempt the test links for LOA1-4. These should now:
- redirect to Connect.gov service,
- allow login to accounts (assuming user has credentials at IDPs),
- allow user to grant consent of attribute sharing,
- return to tester application with attributes displayed.
Step 5: Integrate with Agency Application
With the validator in place application integration is very simple.
In addition to the configured URL exposing a fedletconnect URI endpoint, the solution is an active proxy to agency applications. This proxy will inject the asserted values from the SAML exchange on behalf of agency applications in the form of standard HTTP_HEADERS. From a developer or application owner's perspective, this means that their application need not know how to speak SAML or be tied to a vendor specific set of SAML APIs. Rather the application can:
- request LOA 1-4 authentication just by providing the proper URL
- consume the end result by looking at HTTP_HEADERS
This means application integration is simply a proxy configuration and application making proper calls. Call mechanics that are not tied to any vendor (including ForgeRock) or require the application be built to understand SAML.
There is an included sample application that is protected VIA this proxy mechanism and configured as an OpenIG route. To add more applications just add additional OpenIG routes. Details here: http://openig.forgerock.org/doc/webhelp/gateway-guide/routing-route-setup.html