Using AmService Calls within ForgeRock IG for Policy Enforcement (PEP) Mode

AmService in ForgeRock IG is a powerful feature that allows you to leverage OpenAM’s capabilities directly within your identity gateway. Specifically, using AmService for Policy Enforcement Point (PEP) mode lets you enforce access control policies defined in OpenAM, ensuring that only authorized requests reach your protected resources. This setup is crucial for maintaining security while providing seamless access management.

What is AmService in ForgeRock IG?

AmService is a service in ForgeRock IG that acts as a bridge between IG and OpenAM. It provides access to various OpenAM functionalities, including authentication, session management, and most importantly, policy enforcement. By integrating AmService with IG, you can offload policy evaluation to OpenAM, which simplifies your security architecture and centralizes policy management.

How do you configure AmService for PEP Mode?

To use AmService for policy enforcement, you need to set up routes and handlers in IG’s configuration files. Here’s a step-by-step guide to get you started.

Step 1: Define the AmService

First, define the AmService in your IG configuration. This involves specifying the URL of your OpenAM instance and any necessary credentials.

{
  "name": "amService",
  "$schema": "#/definitions/org.forgerock.openig.services.AmService",
  "openam": {
    "url": "https://openam.example.com/openam",
    "realm": "/",
    "client": {
      "id": "your-client-id",
      "secret": "your-client-secret"
    }
  }
}

Step 2: Create a Policy Enforcement Filter

Next, create a filter that uses the AmService to evaluate policies. This filter will intercept incoming requests and check if they comply with the defined policies in OpenAM.

{
  "name": "policyEnforcementFilter",
  "$schema": "#/definitions/org.forgerock.openig.filter.PolicyEnforcementFilter",
  "service": "amService",
  "configuration": {
    "application": "your-application-name",
    "resource": "${request.uri}",
    "environment": {
      "method": "${request.method}",
      "headers": "${request.headers}"
    }
  }
}

Step 3: Configure Routes

Finally, configure routes in IG to use the policy enforcement filter. This ensures that all requests to protected resources pass through the policy evaluation process.

{
  "name": "protectedRoute",
  "$schema": "#/definitions/org.forgerock.openig.heap.Route",
  "baseUri": "http://backend.example.com",
  "condition": "${matches(request.uri.path, '^/protected')}",
  "handler": "ReverseProxyHandler",
  "filters": [
    "policyEnforcementFilter"
  ]
}

Quick Reference

• amService - Defines the connection to OpenAM.
• policyEnforcementFilter - Evaluates policies using AmService.
• protectedRoute - Route configuration that applies the policy filter.

What are the security considerations for using AmService in PEP Mode?

Security is paramount when dealing with policy enforcement. Here are some key considerations:

• Secure Communication: Ensure that the communication between IG and OpenAM is encrypted using HTTPS.
• Credential Management: Never hard-code credentials in configuration files. Use secure vaults or environment variables.
• Response Validation: Always validate responses from OpenAM to prevent injection attacks.

Common Pitfalls and Solutions

Pitfall: Incorrect Configuration

Symptom

Requests are being denied even though they should be allowed.

Solution

Double-check your policy configurations in OpenAM and ensure that the application and resource fields in the policy enforcement filter match those in OpenAM.

Pitfall: Performance Issues

Symptom

Increased latency in request processing.

Solution

Optimize your policy configurations in OpenAM to reduce evaluation time. Also, consider caching policy decisions in IG to minimize repeated evaluations.

Pitfall: Security Vulnerabilities

Symptom

Unauthorized access despite policy enforcement.

Solution

Regularly audit your policy configurations and ensure that all sensitive data is encrypted. Implement logging and monitoring to detect and respond to suspicious activities.

Example Scenario

Let’s walk through a real-world example to illustrate how AmService can be used for policy enforcement in PEP mode.

Scenario Overview

You have a web application that requires user authentication and authorization. You want to use OpenAM to manage policies and enforce them using ForgeRock IG.

Step 1: Set Up OpenAM Policies

Create policies in OpenAM that define what actions users can perform on different resources. For example, you might have a policy that allows users with the admin role to access /admin endpoints.

Step 2: Configure AmService in IG

Define the AmService in your IG configuration file with the appropriate OpenAM URL and client credentials.

{
  "name": "amService",
  "$schema": "#/definitions/org.forgerock.openig.services.AmService",
  "openam": {
    "url": "https://openam.example.com/openam",
    "realm": "/",
    "client": {
      "id": "webapp-client",
      "secret": "secure-client-secret"
    }
  }
}

Step 3: Create a Policy Enforcement Filter

Create a filter that uses the AmService to evaluate policies based on the request URI and method.

{
  "name": "policyEnforcementFilter",
  "$schema": "#/definitions/org.forgerock.openig.filter.PolicyEnforcementFilter",
  "service": "amService",
  "configuration": {
    "application": "webapp",
    "resource": "${request.uri}",
    "environment": {
      "method": "${request.method}",
      "headers": "${request.headers}"
    }
  }
}

Step 4: Configure Routes

Set up routes in IG to apply the policy enforcement filter to protected resources.

{
  "name": "adminRoute",
  "$schema": "#/definitions/org.forgerock.openig.heap.Route",
  "baseUri": "http://backend.example.com",
  "condition": "${matches(request.uri.path, '^/admin')}",
  "handler": "ReverseProxyHandler",
  "filters": [
    "policyEnforcementFilter"
  ]
}

Testing the Setup

Send a request to a protected endpoint to verify that policy enforcement is working correctly.

The request is denied because the user does not have the necessary permissions.

Implementing AmService for policy enforcement in ForgeRock IG can significantly enhance your security posture. By following the steps outlined in this guide, you can ensure that only authorized requests reach your protected resources. That’s it. Simple, secure, works.