Intelligent Authn and more

ForgeRock Access Management (AM) 6.5 brings many new features and improvements: support for standard Web Authentication (WebAuthn), more built-in intelligent authentication nodes, support for secret stores including keystores, file-based stores, and HSMs, as well as CTS and OAuth 2.0/OpenID Connect enhancements.

The AM 6.5 docs are the best yet. Highlights:

• The new Authentication Node Developer’s Guide shows you how to develop and maintain your own intelligent authentication nodes in Java for use alongside built-in nodes and third-party nodes from the marketplace. (New to authentication nodes and trees? In a nutshell, AM 6 and later let you use decision trees to create authentication journeys that best fit any use case. For more, start with this blog.)
• The OAuth 2.0 Guide for 6.5 has improved a lot, making it easier to understand and use OAuth 2.0 features in AM (even if you haven’t read all the RFCs ;-). The guide now helps you decide quickly which flow to use for your case. The descriptions and instructions for flows have been reworked for you to find what you need fast.
• The AM 6.5 docs release includes 40 improvements and new features and over 100 fixes and updates, many in response to questions from readers. So please continue to send your feedback, which you can do directly from the docs as you read them. (Click at the top right to start.)

DevOps docs leap forward

The ForgeRock DevOps docs for 6.5 add a lot beyond version 6. Not only do the 6.5 DevOps Developer’s Guide (formerly DevOps Guide) and Quick Start Guide cover everything they addressed in 6, you now get much more guidance:

• The Start Here roadmap gives you an overview of all docs.
• The Release Notes bring you up to date quickly from the previous release.
• The CDM Cookbooks bring you the Cloud Deployment Model, a recipe for common use of the ForgeRock Identity Platform in a DevOps environment. At present, ForgeRock publishes cookbooks for Google’s cloud and Amazon’s cloud, relying on Kubernetes for orchestration in both clouds. Make sure you read through to the Benchmarking chapter, where you will learn what it cost ForgeRock to run sample deployments in the real world.
• The Site Reliability Guides cover how to customize and run the deployments in the cloud of your choice.

Congratulations to everyone in the cloud deployment team on an impressive release, and especially to Gina, David, and Shankar for a great doc set!

Documenting ForgeRock DS HTTP APIs

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

ForgeRock DS directory servers do not enable the CREST APIs to directory data by default, since you must first adapt the REST to LDAP mapping for your data. To get started with REST to LDAP, see To Set Up REST Access to User Data.

In the end, make sure that the API is enabled before trying to read its descriptor. For example, you can enable the default /api endpoint with the following command (adapted for your installation):

/path/to/opendj/bin/dsconfig \
 set-http-endpoint-prop \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --endpoint-name /api \
 --set enabled:true \
 --no-prompt \
 --trustAll

The ForgeRock DS product does not currently include an API explorer, but you can get the OpenAPI-format API descriptor for any or all CREST endpoints. You pass the _api query string parameter to the endpoint. The resulting OpenAPI descriptor is a JSON document. Get available CREST APIs for directory data with a request to the /api endpoint:

curl -o ds.json -u kvaughan:bribery http://localhost:8080/api?_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 ds.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 Working With REST API Documentation.

Documenting ForgeRock IG HTTP APIs

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

The ForgeRock IG product does not currently include an API explorer, but you can get the OpenAPI-format API descriptor for any or all endpoints. You pass the _api query string parameter to the endpoint. The resulting OpenAPI descriptor is a JSON document. For example, you can start IG in development mode as described in Starting IG, and then get all available APIs with a request to the /openig/api endpoint:

curl -o ig.json http://localhost:8080/openig/api?_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 ig.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 Understanding IG APIs With API Descriptors.

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.

Using the ForgeRock AM API Explorer

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

The ForgeRock AM 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 AM API explorer from the question mark menu in the console:

By default, there are many APIs published in the top-level realm. A simple one that you can try right away when logged in as AmAdmin is an action on the /sessions endpoint. Click /sessions in the left menu, scroll down, and click /sessions#1.2_query_id_all:

Next, scroll to and click the Try it out! button:

Notice that the API explorer displays everything but the AM SSO details that your browser is using to authenticate with your AmAdmin session.

Suppose you want to get the OpenAPI-format API descriptor for the /sessions endpoint. You pass the _api query string parameter to the endpoint. The resulting OpenAPI descriptor is a JSON document:

curl -o sessions-api.json http://openam.example.com:8080/openam/json/sessions?_api

To try out the result, download and install Swagger UI, then move the JSON document into the Swagger UI directory.

For example, copy the Swagger UI dist folder into the same Apache Tomcat server used by OpenAM, add the descriptor, and restart Tomcat:

unzip swagger-ui-version.zip
cp -r swagger-ui-version/dist /path/to/tomcat/webapps/swagger-ui
mv sessions-api.json /path/to/tomcat/webapps/swagger-ui/
/path/to/tomcat/bin/shutdown.sh
/path/to/tomcat/bin/startup.sh

Now browse http://openam.example.com:8080/swagger-ui/ with http://openam.example.com:8080/swagger-ui/sessions-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 Introducing the API Explorer. For details about authenticating to use the APIs outside the console, see Authentication and Logout.

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 Laetitia Ellison

Late welcome to Laetitia Ellison, who joined the ForgeRock documentation team in February.

Laetitia works with the access management team, and has started out on AM documentation.

Laetitia might be the only member of the team who has a hereditary connection to technical writing. She comes to ForgeRock with a background in writing about customer engagement software, and also technical support. Laetitia brings great energy and enthusiasm to the team, and has really hit the ground running.

ForgeRock welcomes Shankar Raman

Welcome to Shankar Raman, who joins the ForgeRock documentation team today.

Shankar is starting with platform and deployment documentation, where many of you have been asking us to do more.

Shankar comes to the team from curriculum development, having worked for years as an instructor, writer, and course developer at Oracle on everything from the DB, to middleware, to Fusion Applications. Shankar’s understanding of the deployment problem space and what architects and deployers must know to build solutions will help him make your lives, or at least your jobs, a bit easier. Looking forward to that!

Faster docs

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:

• Platform modules, DevOps, IoT: https://backstage.forgerock.com/docs/platform/5
• Access Management: https://backstage.forgerock.com/docs/am/5.1, https://backstage.forgerock.com/docs/amster/5
• Directory Services: https://backstage.forgerock.com/docs/ds/5
• Identity Management: https://backstage.forgerock.com/docs/idm/5
• Identity Gateway: https://backstage.forgerock.com/docs/ig/5

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.