**** 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.
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:
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:
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.
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.
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.