Securing your (micro) services with ForgeRock Identity Microservices

Written by Javed Shah

Please note that the EA program for Microservices has ended. The code provided 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.

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

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.


Helpful Links

Microservices Docs