Using the ForgeRock AM API Explorer

ForgeRock Logo 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:

AM API explorer.png

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:

AM browse API explorer.png

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

AM try sessions endpoint.png

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:

AM Swagger UI.png

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:

AM Swagger Editor.png

For more information, see Introducing the API Explorer. For details about authenticating to use the APIs outside the console, see Authentication and Logout.

Advertisements

About REST APIs and API Descriptors

ForgeRock Logo 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

ForgeRock Logo 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 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.

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!

ForgeRock Common Audit

ForgeRock LogoCommon 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:

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

ForgeRock LogoPerhaps 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:

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