Faster docs

ForgeRock Logo One of the things you have asked for is to see large documents load faster on the ForgeRock BackStage docs site. We recently switched from publishing HTML documentation through the BackStage single-page app to publishing separate, static HTML with JavaScript to provide BackStage features.

This allows browsers to use progressive rendering, and start laying out the page before everything has been loaded and styled. The result is that large documents feel faster in your browser.

If you have bookmarks to published HTML, notice that we have dropped the per-chapter view of published docs. Each document is now a single HTML page. So instead of a link to /docs/product/version/book/chapter#section, target /docs/product/version/book/#section. Also notice that we have consolidated documentation sets to make information easier to find, with only one set per major or minor release. Generally this means that you only have to read one set of release notes, no matter what maintenance version you have right now.

The latest docs are the ones for version 5 of the platform:

We still publish all the same docs as before, including docs for software that is beyond the end of its service life. Please check out the updated site. Open issues there for any problems you notice.

ForgeRock welcomes Nabil Maynard

Late welcome to Nabil Maynard who joined the ForgeRock documentation team this past Monday.

Nabil has started working on the identity management documentation. He’s digging into his new full-time job as a writer.

Nabil brings solid technical experience and understanding of how server software works, having been a QA professional for years at places like Dropbox. So much of writing good documentation for ForgeRock software depends on throughly understanding what the software does, how it can be broken, and what you should do to make it work correctly. Nabil’s contributions will surely help you get deeper into ForgeRock’s identity management software.

ForgeRock welcomes Gina Cariaga

Late welcome to Gina Cariaga who joined the ForgeRock documentation team this spring.

Gina has strong experience writing about access management and directory services. Her formal background in training, mixed with her hands-on success with the kind of documentation we do at ForgeRock make a great combination.

Gina’s initial work at ForgeRock has included putting together a guide to getting started with the ForgeRock platform for IoT architects and developers. Gina is continuing to write on using ForgeRock’s identity and access management capabilities in the IoT space, and much more.

ForgeRock Identity Platform 5.0 docs

ForgeRock Logo By now you have probably read the news about the ForgeRock Identity Platform 5.0 release.

This major platform update comes with many documentation changes and improvements:

Hope you have no trouble finding what you need.

We’re hiring

ForgeRock still has open positions in many locations. One of those is for a writer based in our Vancouver, WA office (across the river from Portland, OR).

Be forewarned. This is challenging, hands-on technical writing and reverse engineering work. If you are looking for a gig where you can remain in your comfort zone, skip this one.

On the other hand, if you feel that most things worth doing are tough in the beginning, take a closer look and apply for the job.

ForgeRock 3.2.2 doc tools released

ForgeRock Logo ForgeRock doc tools 3.2.2 were released today.

This is a maintenance release, compatible with earlier 3.2.x releases.

ForgeRock doc tools 3.2.2 includes the following components:

  • forgerock-doc-maven-plugin
  • forgerock-doc-common-content
  • forgerock-doc-default-branding

This release resolves bugs and includes several improvements. For details, see the release notes.

Big thanks once again for enhancements, for identifying problems, and for help debugging.

Thanks to Chris Lee, Cristina Herraz, Joanne Henry, Lana Frost, Lori Goldman, David Goldsmith, Gene Hirayama, and Mike Jang for fixes, improvements, testing and bug reports.

Thanks also to the ForgeRock BackStage team for their help and continued improvements to release documentation.

OpenAM: New topic-based documentation

ForgeRock LogoOpenAM’s capabilities have grown significantly in the last few releases, with the result that even the product docs outgrew the old organization. Thanks to Chris Lee, Cristina Herraz, David Goldsmith, and Gene Hirayama, the draft docs are now arranged to make it easier to find just what you are looking for.

Instead of a guide-based doc set, what you see now are topic-oriented categories that bring you right to the features you want to use:

  • Try OpenAM (up and running quickly, ready for evaluation)
  • Access Management (authentication and single sign-on, authorization, RADIUS)
  • Federation (OAuth 2.0, OpenID Connect 1.0, SAML, STS)
  • User Services (self-registration, self-serve account and password management, self-serve sharing using UMA)
  • Installation and Maintenance (plan, install, set up, upgrade, and maintain access management services)
  • Extensibility (REST APIs, Java APIs and SPIs, C SDK)
  • Policy Agents (for enforcing policy on web sites and in Java web applications)

Each guide is written so that you find everything about a topic in one place. Are you focused on centralizing access policies for authorization? Read the Authorization Guide. Interested in granting access to account info for modern mobile and web applications using OpenID Connect? See the OpenID Connect 1.0 Guide. Participating in a federation of SAML 2 providers? Check out the SAML 2.0 Guide.

Those of you who knew the old layout intimately are probably going to wonder, “Where did you move my stuff?” In fact, there is a guide for that, too. Having Trouble Finding Something? indicates where your stuff went, with tables of correspondence from each section in the old layout to the topic in the new layout.

Great to see this leap forward towards a topic-based documentation set for OpenAM!

OpenDJ: Configuration over REST

ForgeRock LogoIn recent builds of OpenDJ directory server, the REST to LDAP configuration changed quite a bit… for the better.

The draft release notes tell only part of the story:

The changes let you configure multiple endpoints each with multiple versions, resource type inheritance, subresource definitions, and protection with OAuth 2.0. This version of REST to LDAP also brings many minor improvements.

A really cool “minor” improvement is that you can now configure OpenDJ directory server over HTTP. In the draft Admin Guide, you can also find a procedure titled, To Set Up REST Access to Administrative Data.

tl;dr—Directory administrators can configure the server over REST through the /admin/config endpoint, and can read monitoring info under the /admin/monitor endpoint.

Important note: Before you go wild writing a whole new OpenDJ web-based console as a single-page app, keep in mind that the REST to LDAP implementation is still an Evolving interface, so incompatible changes can happen even in minor releases.

Here’s one example using /admin/config:

#
# This example demonstrates 
# using the /admin/config endpoint
# to create a password policy
# as a directory administrator
# who is also a regular user.
# 
# This requires a nightly build or release 
# from no earlier than late June 2016.
# 
# In order to get this working,
# first set up OpenDJ directory server
# with data from Example.ldif,
# and enable the HTTP connection handler.
#

#
# Give Kirsten Vaughan the right
# to read/write the server configuration.
# This command updates privileges, 
# which are explained in the Admin Guide:
#
/path/to/opendj/bin/ldapmodify \
 --port 1389 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password
dn: uid=kvaughan,ou=People,dc=example,dc=com
changetype: modify
add: ds-privilege-name
ds-privilege-name: config-read
-
add: ds-privilege-name
ds-privilege-name: config-write

#
# Give Kirsten access to write password policies.
# This command adds a global ACI.
# Global ACIs are explained in the Admin Guide:
#
/path/to/opendj/bin/dsconfig \
 set-access-control-handler-prop \
 --port 4444 \
 --hostname opendj.example.com \
 --bindDN "cn=Directory Manager" \
 --bindPassword "password" \
 --add global-aci:"(target=\"ldap:///cn=Password Policies,cn=config\")(targetscope=\"subtree\")(targetattr=\"*\")(version 3.0; acl \"Manage password policies\"; allow (all) userdn=\"ldap:///uid=kvaughan,ou=People,dc=example,dc=com\";)" \
 --trustAll \
 --no-prompt

#
# Server config-based password policies
# are under the container entry
# /admin/config/password-policies.
# This corresponds to 
# cn=Password Policies,cn=config in LDAP.
#
# The following are standard common REST operations.
# Common REST is explained and demonstrated
# in the OpenDJ Server Dev Guide.
#
# In production, of course,
# use HTTPS (as described in the Admin Guide).
#

#
# Add a new password policy:
#
curl \
 --user kvaughan:bribery \
 --request POST \
 --header "Content-Type: application/json" \
 --data '{
    "_id": "New Account Password Policy",
    "_schema": "password-policy",
    "password-attribute": "userPassword",
    "force-change-on-add": true,
    "default-password-storage-scheme": "Salted SHA-1"
}' http://opendj.example.com:8080/admin/config/password-policies

#
# Read the new password policy:
#
# curl --user kvaughan:bribery http://opendj.example.com:8080/admin/config/password-policies/New%20Account%20Password%20Policy

#
# An exercise for the reader:
# Figure out how to set a user's pwd policy over REST.
#

If you have not yet learned how to use commons REST and OpenDJ REST to LDAP, have a look at the Server Dev Guide chapter, Performing RESTful Operations.

ForgeRock repos and mirrors

ForgeRock LogoYou might already know that ForgeRock’s platform is built on open source software. We have been using Stash, now BitBucket, to host the git repos and to manage the review process.

If you want to read the code or the doc source code, you will find the canonical copies on that server. For example—there are more repos on the server, but here are some of the most popular links:

If you want to contribute a patch or a feature, sign up, login, and follow the development process. That process involves working on https://stash.forgerock.org/.

You will also find read-only mirrors (and other goodies) at GitHub, under https://github.com/ForgeRock:

Either server is fine if you just want to read the code or clone a repo.