ForgeRock in the Enterprise: Architecture, Deployment, and Security Hardening Guide

Overview

ForgeRock is an enterprise-grade identity and access management platform used for workforce, customer, and partner identity use cases. Organizations adopt it to centralize authentication, enforce adaptive access policies, support standards such as OAuth 2.0, OpenID Connect, SAML, and SCIM, and scale identity services across hybrid and multi-cloud environments.

Its core value is flexibility: enterprises can build modern single sign-on, API authorization, identity lifecycle workflows, and passwordless journeys while integrating with legacy directories and modern applications. ForgeRock is especially common where high scale, custom authentication trees, and regulatory control are required.

Architecture

A typical ForgeRock deployment includes Access Management for authentication and authorization, Identity Management for provisioning and lifecycle workflows, Directory Services for identity data storage, and Identity Gateway for policy enforcement at the application edge.

[Users] ---- 1. authenticate ----> [ForgeRock AM]
[ForgeRock AM] ---- 2. token / session ----> [Apps]
[HR System] ---- 3. identities ----> [ForgeRock IDM]
[ForgeRock IDM] ---- 4. sync ----> [ForgeRock DS]
[Apps] ---- 5. policy check ----> [ForgeRock IG]
[ForgeRock IG] ---- 6. validate token ----> [ForgeRock AM]
[ForgeRock AM] ---- 7. read/write ----> [ForgeRock DS]

Core components

• AM: authentication trees, federation, session management, OAuth 2.0 and OIDC.
• IDM: provisioning, reconciliation, managed objects, workflows.
• DS: LDAP-based identity store, replication, indexing, high availability.
• IG: reverse proxy and policy enforcement point for apps and APIs.

Deployment models

• Self-managed on VMs or Kubernetes.
• Hybrid with cloud-hosted apps and on-prem DS.
• Multi-region active-active for customer identity workloads.

Data flow

1. User reaches an application protected by IG or integrated directly with AM.
2. AM executes an authentication tree and issues a session or token.
3. Applications validate tokens locally or through introspection.
4. IDM provisions or updates identities in DS and connected systems.

Implementation Guide

1. Prepare DNS and TLS certificates for am.example.com, idm.example.com, and ig.example.com.
2. Deploy DS and create a base backend.
3. Install AM and point it to DS for configuration and identity stores.
4. Install IDM and configure repository, mappings, and connectors.
5. Deploy IG in front of a test application.
6. Register an OAuth 2.0 client and validate OIDC login.

Example commands

helm repo add forgerock https://storage.googleapis.com/forgerock-charts
helm repo update
kubectl create namespace forgerock
helm install ds-idrepo forgerock/ds -n forgerock --set image.tag=7.4.0
helm install am forgerock/am -n forgerock --set image.tag=7.4.0
helm install idm forgerock/idm -n forgerock --set image.tag=7.4.0
helm install ig forgerock/ig -n forgerock --set image.tag=7.4.0

Create an AM OAuth 2.0 client using Amster:

./amster <<'EOF'
connect http://am.example.com/am -k /path/to/keystore.jceks changeit
create OAuth2Client --realm / --body '{"coreOAuth2ClientConfig":{"clientName":["webapp"],"redirectUris":["https://app.example.com/callback"]},"advancedOAuth2ClientConfig":{"grantTypes":["authorization_code","refresh_token"],"tokenEndpointAuthMethod":"client_secret_basic"}}'
EOF

Minimal IG route:

kind: Route
name: protected-app
baseURI: https://app.internal.example.com
condition: ${matches(request.uri.path, '^/app')}
heap:
  - name: OAuth2ResourceServerFilter
    type: OAuth2ResourceServerFilter
    config:
      accessTokenResolver:
        type: TokenIntrospectionAccessTokenResolver
        config:
          amService: ForgeRockAM
          providerHandler: ClientHandler
          clientId: ig-resource-server
          clientSecretId: ig.rs.secret
handler:
  type: Chain
  config:
    filters:
      - OAuth2ResourceServerFilter
    handler: ReverseProxyHandler

Code Examples

1. DS bootstrap LDIF

cat > base.ldif <<'EOF'
dn: ou=people,dc=example,dc=com
objectClass: top
objectClass: organizationalUnit
ou: people
EOF
ldapmodify -h ds-idrepo.forgerock.svc -p 1389 -D "cn=Directory Manager" -w 'Password123' -a -f base.ldif

2. AM service configuration

{
  "realm": "/",
  "session": {
    "maxSessionTime": 120,
    "maxIdleTime": 30
  },
  "authentication": {
    "treesEnabled": true,
    "adaptiveRisk": true
  }
}

3. Token test with Python

import requests
r = requests.post("https://am.example.com/am/oauth2/access_token", data={"grant_type":"client_credentials"}, auth=("api-client","SuperSecretValue"), verify=True)
print(r.status_code)
print(r.json())

Security Hardening

• Enforce TLS 1.2+ everywhere and use HSTS on IG endpoints.
• Store secrets in Kubernetes Secrets integrated with a vault, not in route files.
• Enable DS replication over TLS and restrict LDAP admin access by network policy.
• Use signed and encrypted OIDC tokens where required by regulation.
• Separate admin realms, operator accounts, and application service accounts.
• Enable audit logging for AM authentication events, IDM reconciliation, and IG policy decisions.
• Rotate OAuth client secrets and signing keys on a defined schedule.

Comparison

Troubleshooting

Error 1: AM cannot reach DS

Log sample:

2026-03-14T09:22:11.481Z ERROR amAuth OAuth2Provider failed to initialize LDAP connection: javax.naming.CommunicationException: ds-idrepo.forgerock.svc:1389 [Root exception is java.net.ConnectException: Connection refused]

Fix: Verify DS service endpoints, network policy, and AM LDAP connection settings. Confirm kubectl get svc -n forgerock and test connectivity from the AM pod.

Error 2: IG token introspection failure

Log sample:

2026-03-14T09:31:44.902Z WARN  ig.router OAuth2ResourceServerFilter access token validation failed: 401 Unauthorized from https://am.example.com/am/oauth2/introspect

Fix: Check clientId, secret mapping, AM client permissions, and clock synchronization between IG and AM.

Error 3: IDM reconciliation mapping error

Log sample:

2026-03-14T09:40:03.117Z ERROR org.forgerock.openidm.recon Reconciliation failed for mapping managedUser_systemLdapAccounts: java.lang.NullPointerException at org.forgerock.openidm.mapping.impl.PropertyMappingStage

Fix: Review mapping scripts for null handling, validate source attributes, and run a dry reconciliation with debug logging enabled.

Best Practices

Do

• Use separate DS backends for config, CTS, and identity data in larger deployments.
• Design authentication trees per use case, for example stronger MFA for admins than for customers.
• Put IG close to applications to reduce latency for token validation.
• Load test login and token endpoints before production cutover.

Don't

• Do not reuse admin credentials for application integrations.
• Do not disable certificate validation in IG or Python automation.
• Do not keep default session settings for internet-facing customer deployments.
• Do not skip index tuning in DS when storing large identity populations.