Using the ForgeRock IDM API Explorer

This post is part of a series about how to get live reference documentation for ForgeRock REST APIs.

The ForgeRock IDM web-based console includes an API explorer.

The API explorer lets you try out the CREST HTTP APIs as you are building your service. You access the IDM API explorer from the question mark menu in the console. IDM makes many categories of endpoints available. The following example shows the Health category expanded:

You can quickly try out one of the API calls. For example, expand /health/memory, and then click the Try it out and Execute buttons:

Notice that the API explorer displays everything but the credentials needed to access the REST API.

You can also get the OpenAPI-format API descriptor for the /health endpoint. You pass the _api query string parameter to the endpoint. The resulting OpenAPI descriptor is a JSON document:

curl -u openidm-admin:openidm-admin -o health-api.json http://localhost:8080/openidm/health?_api

To try out the result, download and install Swagger UI, then move the JSON document into the Swagger UI directory. You can then browse the Swagger UI with health-api.json as the descriptor:

The API descriptor that you load from the server no doubt does not exactly match what you need to publish in your live documentation. Use the Swagger Editor to adapt it to your needs:

For more information, see API Explorer.

About REST APIs and API Descriptors

This post briefly describes the types of HTTP APIs available through the ForgeRock platform, and which ones come with live reference documentation.

The following categories of HTTP APIs are available in the ForgeRock platform:

ForgeRock Common REST (CREST) APIs

ForgeRock Common REST provides a framework for HTTP APIs. Each of the component products in the platform uses CREST to build APIs that do CRUDPAQ operations in the same ways.

ForgeRock platform component products generate live reference documentation in a standard format (Swagger, which has been standardized as OpenAPI) for CREST APIs. This is done through a mechanism referred to as API descriptors. You can use this documentation to try out the CREST APIs.

Standard HTTP APIs such as OAuth 2.0

Standard HTTP APIs are defined by organizations like the IETF for OAuth 2.0, the Kantara Initiative for UMA, and the OpenID Connect Working Group. These APIs have their own implementations and do not use CREST. They are documented where they are used in the product documentation.

The canonical documentation is the specifications for the standards. At present, the ForgeRock platform components do not generate live documentation for these standard APIs.

Non-RESTful, Challenge-Response HTTP APIs

Some APIs, such as the authentication API used in ForgeRock AM and the user self-service API used in ForgeRock IDM are not fully RESTful. Instead, they use challenge-response mechanisms that have the developer return to the same endpoint with different payloads during a session.

These APIs are documented in the product documentation.

The ForgeRock API reference documentation published with the product docs is, necessarily, abstract. It does not provide you a sandbox to try out the APIs. Unlike a SaaS, with its fixed configuration, the ForgeRock platform components are highly configurable. ForgeRock HTTP APIs depend on how you decide to configure each service.

Live Reference Documentation

It is your software deployment or SaaS, built with the ForgeRock platform, that publishes concrete APIs.

You can capture the OpenAPI-format docs, and edit them to correspond to the APIs you actually want to publish. A browser-based, third-party application, Swagger UI, makes it easy to set up a front end to a sandbox service so your developers can try out your APIs.

Note that you still need to protect the endpoints. In particular, prevent developers from using the endpoints you do not want to publish.

The following posts in this series will look at how to work with the APIs when developing your configuration, and how to get the OpenAPI-format descriptors to publish live API documentation for your developers.

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 Identity Platform 5.0 docs

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:

• Access Management docs are now arranged to make it much easier for you to find all the details about new features and specific capabilities (User Self Service, OAuth 2.0, SSO, Authorization, and more). Since long-time readers who know where everything was might find this disconcerting at first, we also included a map to the new doc set. Don’t forget to check out Amster, too, which is new, and lets you do configuration as (file-based) artifacts.
• Identity Management is covered with the same titles as the previous platform update, but a lot of new features that make integration easier. (Integrated social identity provider support, better system connector support, additional audit event handlers, HSM support, etc.)
• Directory Services now has a Security Guide covering all the features for protecting your deployment, a new configuration reference, a bunch of smaller doc improvements, and full coverage of new features (LDAP proxy, native JSON syntax, tools improvements, documented HSM support, and so on).
• Identity Gateway docs now include a Deployment Guide aimed at those of you working in DevOps environments. They also cover all the new features, from the developer Studio to SSO filters and everything in between.
• Platform docs make their first appearance in the update. Try the DevOps examples, which point to a more cloud-friendly way of deploying the platform. And if you are new to ForgeRock software, start with the platform guide that maps the functional modules to the documentation that describes them.

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 Common Audit

Common Audit is another new feature of the ForgeRock platform.

Common Audit is part of the platform-wide infrastructure: a framework to handle audit events using common audit event handlers that are plugged in to the individual products. The handlers record events, logging them for example into files, relational databases, or syslog. Because handlers are pluggable, new handlers can be added to interoperate with your systems that store and analyze audit data.

Each audit event is identified by a unique transaction ID. The IDs can be communicated across the products and recorded for each local event. The transaction ID is the means to track requests as they traverse the platform.

In the current platform, configuring handlers depends on the product. So there are several places in the docs to read about how to configure Common Audit:

• OpenAM: Configuring Audit Logging
• OpenDJ: Common ForgeRock Logs
• OpenIDM: Using Audit Logs
• OpenIG: Audit Events and Logging

In addition, if you want to get the source code for Common Audit, or are interested in trying out new handlers and developments, you can find it on the ForgeRock Stash server. Right now it is in the forgerock-audit git repository. (To access most code on the ForgeRock Stash server, sign in with your ForgeRock credentials. You can sign up if you have not done so.)

What’s new in the ForgeRock platform release

Perhaps you have read yesterday’s news about ForgeRock launching the updated identity platform.

Those of us who spent the last year working on this update are proud of all the new capabilities, from the integration achieved with common components to the depth and breadth of new features across all the products in the platform.

Looking for detailed lists of what’s new? Here are some quick links to each of the products’ release notes:

• What’s New in OpenAM 13
• What’s New in OpenDJ 3
• What’s New in OpenIDM 4
• What’s New in OpenIG 4

I’ll drill down on some of those in future posts.

OpenIDM: Trying the new Admin UI

One of the cool features in the upcoming release of OpenIDM is the new Admin UI. Jake Feasel demonstrated this to several people last week. It already looks like a major improvement for newbies over editing configuration files.

If like me you have been out of the loop for a while, it is reassuring to see that OpenIDM still installs a dream when you are just getting started. Download, unzip, and ./startup.sh.

Here is how you might start OpenIDM with an existing sample. This uses sample2, which is one-way synchronization with OpenDJ. You are not required to start with the samples, but they can quickly bootstrap your evaluation, without requiring you to read much doc or to think through the initial configuration.

$ cd /path/to && mv ~/Downloads/openidm . && cd openidm
$ ./startup.sh -p samples/sample2
Executing ./startup.sh...
Using OPENIDM_HOME:   /path/to/openidm
Using PROJECT_HOME:   /path/to/openidm/samples/sample2
Using OPENIDM_OPTS:   -Xmx1024m -Xms1024m
Using LOGGING_CONFIG: -Djava.util.logging.config.file=/path/to/openidm/samples/sample2/conf/logging.properties
Using boot properties at /path/to/openidm/samples/sample2/conf/boot/boot.properties
OpenIDM version "3.1.0-RC3-SNAPSHOT" (revision: 4297) jenkins-OpenIDM-3746 null
-> OpenIDM ready

OpenIDM’s web based UI is ready for HTTPS out of the box, but it seems you can still use HTTP for evaluation.

For example, you can visit http://localhost:8080/openidmui/ and login as openidm-admin:openidm-admin.

OpenIDM’s UI helps prevent default passwords by prompting you to change your password the first time you login.

You find the Admin UI at http://localhost:8080/admin/. This shows the view when running with the sample2 configuration.

The new Admin UI offers a wizard-like approach to setting up provisioning. If you follow sample2, set up OpenDJ with some sample data before you get started. The sample comes with a mapping from OpenDJ accounts to managed/user.

The sample also comes with a configuration for what to do in different situations during synchronization. Most of the policies are defaults.

To run reconciliation and synchronize your source and target, either click the Reconcile Now or schedule reconciliation on the Sync Tab of the Mappings page. When reconciliation completes, you should have a bunch of new managed users. If you schedule reconciliation, subsequent runs might not encounter any changes.

Click the User View link at the upper left of the page and then the Users tab to view all your managed users.

When you change a mapped attribute in the source, in this case OpenDJ, reconciliation updates it in the target, in this case the managed/user. For example, Babs Jensen’s original mail address is bjensen@example.com.

After changing the mail address in OpenDJ to babs.jensen@example.com, reconciliation updates her corresponding managed/user in OpenIDM’s repo. Refreshing the page after reconciliation, you can see the change.

The OpenIDM Admin UI is quite a leap forward, and promises to make it much easier for all of us to create and edit resources and mappings, and to arrange and schedule synchronization. Hats off to the OpenIDM team!

Searching ForgeRock Community Sites

Someone said it is hard to find the search box on the *.forgerock.org community sites. Also, the searches were scoped too narrowly to look in the mailing lists.

Before the changes the search box is tucked away in the left menu, and scoped to site:<project>.forgerock.org.

OpenDJ Before: Search box in left menu

The new, improved version has a more obvious search box. Searches now cover everything at site:forgerock.org.

OpenAM After: Search box top right, now with colors

ForgeRock welcomes Lana Frost

Welcome to Lana Frost who joined the ForgeRock documentation team Monday. Glad you decided to work for ForgeRock, Lana.

Lana has worked as Lead Writer at Sun Microsystems on the Directory Services team, and more recently at Oracle. While helping other writers meet their deadlines and keeping the projects on track, she also wrote a big share of the directory documentation herself. Furthermore, Lana was instrumental in setting up the rigorous documentation review process that first lifted the quality of the directory documentation, and was later adopted by other middleware documentation teams.

Lana will help with OpenDJ docs at ForgeRock. Her main focus however is the leadership role for identity documentation with the OpenIDM and OpenICF projects. Good news for the ForgeRock directory and identity communities!