Securing your (micro)services with ForgeRock Identity Microservices

****  Please note that the EA program for Microservices has ended. The code in this post is not supported by ForgeRock.  ****

ForgeRock Identity Microservices

ForgeRock released in Q4 2017, an Early Access (aka beta) program for three key Identity Microservices within a compact, single-purpose code set for consumer-scale deployments. For companies who are deploying stateless Microservices architectures, these microservices offer a micro-gateway enabled solution that enables service trust, policy-enforced identity propagation and even OAuth2-based delegation. The stateless architecture of FR Identity Microservices allows for implementing a sidecar-friendly microgateway deployment pattern.

I blogged about it here. The sign up form is here. The kubernetes/docker artifacts for evaluation purposes are in this github repository.

The Stateless Microservices

OAuth2 Token Issuance

Enables service to service authentication using client-credential grant type. These “bearer” tokens facilitate trust down the call chain.

Simple use example is shown here in a sequence diagram:

We currently support RSA, EC, and HMAC signing, with the following algorithms:

  • HS256
  • HS384
  • HS512
  • RS256
  • ES256
  • ES384
  • ES512

Token Validation

Supports introspection of OAuth2 / OIDC tokens issued by an OAuth2 AS as well as native AM tokens. Token validations performed using either configured keys, or lookup via JWK URI for issuer and kid verification.

One or more Token Introspection API implementations can be configured by setting the value to a comma-separated list of implementation names. Each implementation is given a chance to handle the token, in given order, until an implementation successfully handles the token. An error response occurs if no implementation successfully introspects a given token.

The following implementations are provided:

  • json : Configured by a JSON file.
  • openam : Proxies introspect calls to ForgeRock Access Management.

Several powerful validation and introspection use cases that enhance microservices security can be covered with this microservice. Examples follow.

Sequence diagram for validating machine-to-machine stateless bearer tokens:

Sequence for validating OpenAM issued ssotoken:

Sequence for validating OpenAM issued stateful access token:

We are not done yet.. sequence diagram for validation and introspection of an OIDC token is shown here:

Token Exchange

Supports exchanging stateless OAuth2 access tokens and native AM tokens for hybrid tokens that grant specific entitlements per resourceor audience requested. Implements the draft OAuth2 token-exchange specification. Offers no-fuss declarative (“local”) policy enforcement inside the pod without needing to “call home” for identity data. Also provides policy based entitlement decisions by calling out to ForgeRock Access Management.

The Token-Exchange Policy is a pluggable service which determines whether or not a given token exchange may proceed. The service also determines what audience, scope, and so forth the generated token will have. The following implementations are provided:

  • json (default) : Configured by a JSON file.
  • jwt : Simply returns a JWT for any token that can be introspected.
  • openam : Uses a ForgeRock Access Management Policy Set.

A sequence diagram showing token exchange flow using an ssotoken with OpenAM policy validation:

This more involved “delegation” model with token exchange and OpenAM policy is covered in this blog post:

Feature Comparison and Dependency Chart

ForgeRock Identity Microservice



Will work with any OAuth2/OIDC Provider or Policy Engine?
Authentication Yes OAuth2 client credential grant No
Token Validation Yes ssotoken introspection Yes No
Token Validation Yes stateless JWT introspection No
Token Validation Yes stateful access_token introspection Yes (by proxy) Yes (by proxy)
Token Validation Yes id_token introspection No (if importing signer), Yes (if using jwk uri) Yes
Token Exchange Yes Exchange opaque AM access token with a JWT Yes Yes (by proxy)
Token Exchange Yes Exchange stateless AM access token with a JWT No Yes
Token Exchange Yes exchange token with audience restriction using JSON policy No
Token Exchange Yes exchange token and add delegate using JSON policy No
Token Exchange Yes exchange token with audience restriction using Open Policy Agent server No
Token Exchange Yes exchange token and add delegate using Open Policy Agent server No
Token Exchange Yes exchange token with audience restriction using AM policy Yes Yes
Token Exchange Yes exchange token and add delegate using AM policy Yes Yes
Authorization (specification) scheduled for 9/18 (estimated) decentralized authorization using custom pluggable policy backend No

Cloud and Platform

Docker and Kubernetes

Docker images for evaluation are available publicly on ForgeRock Bintray. I have created a github repository to evaluate the evaluation images and provided the needed kubernetes artifacts as well. The yaml files include environment variables necessary for configuring each microservice. These environment variables map to configuration fields that are read by each microservice on startup.

Metrics and Prometheus Integration

The microservices are instrumented to publish basic request metrics and a Prometheus endpoint is also provided, which is convenient for monitoring published metrics.

Audit Tracking

Each incoming HTTP request is assigned a transaction ID, for audit logging purposes, which by default is a UUID. ForgeRock Microservices like other products support propagation of a transaction ID between point-to-point service calls.

Cloud Foundry

The standard binary in Zip format is also directly deploy-able to Cloud Foundry, and will get recognized by the Cloud Foundry Java build pack as a “dist zip” format.

Client Credential Repository

ForgeRock Identity Microservices support Cassandra, MongoDB, any LDAP v3 including ForgeRock Directory Services.


Comments are closed.

  1. Scott Heger 5 years ago


  2. ytheva 4 years ago

    Are the Identity Microservices officially launched by Forgerock? I can not see any documentation in the backstage?

©2022 ForgeRock - we provide an identity and access platform to secure every online relationship for the enterprise market, educational sector and even entire countries. Click to view our privacy policy and terms of use.

Log in with your credentials

Forgot your details?