Web Agents 5.10.3

About Web Agent

Web Agent is an Access Management add-on component that operates as a Policy Enforcement Point (PEP) or policy agent for applications deployed in a web server.

Web Agents intercept inbound requests to applications. Depending on the filter mode configuration, Web Agents interact with AM to:

  • Ensure that clients provide appropriate authentication.

  • Enforce AM resource-based policies.

    For information about how to enforce user authentication only, see Web Agent Single Sign-on (SSO) Only Mode.

This chapter covers how Web Agent works and how it protects applications.

Agent components

Web Agent includes the following main components:

Agent Modules

Intercepts and processes inbound requests to protected resources.

Native Shared Libraries

Enables agents to interact with AM.

Agent Profile

The agent profile is not strictly part of Web Agent, but plays an important part in the agent operation. It contains a set of configuration properties that define the agent behavior.

The following image shows the Web Agent components when the agent profile is stored in the AM configuration store:

Web Agent Components

Configuration location

Web Agent configuration properties determine the behavior of the agent. AM stores configuration properties either centrally or locally:

Centralized configuration

AM stores the agent properties in the AM configuration store. Storing the agent configuration centrally allows you to configure your agents using the AM console, the ssoadm command, and the REST API.

To access the centralized web agent configuration, on the AM console go to Realms > Realm Name > Applications > Agents > Web > Agent Name.

Configure properties that are not present in the AM console as custom properties, on the Advanced tab of the console. For a list of property names, see the Properties reference.

When properties and value pairs are defined as custom properties, they take precedence for that property. Therefore, to prevent configuration errors, do not configure a property as a custom property if it has a UI counterpart.

For more information about creating centrally-stored agent profiles, see Creating Agent Profiles.

Local configuration (agent.conf)

The Web Agent installer creates the following file to store agent bootstrap and configuration properties: /web_agents/agent_type/instances/agent_nnn/config/agent.conf

The installer populates agent.conf with enough information to make the agent start. To manage the configuration, edit agent.conf to add properties, remove properties, and change values. You cannot update agent.conf using the AM console, the ssoadm command, or the REST API.

The agent.conf file must contain at least the following properties:

# Bootstrap properties
com.sun.identity.agents.config.organization.name = /
com.sun.identity.agents.config.username = ApacheAgentProfile
com.sun.identity.agents.config.password = o7OuvnaDnQ==
com.sun.identity.agents.config.key = OGM...Yg=
com.sun.identity.agents.config.naming.url = https://am.example.com:8443/am

# Configuration properties
com.sun.identity.agents.config.repository.location = local
org.forgerock.openam.agents.config.jwt.name = am-auth-jwt
com.sun.identity.agents.config.cdsso.redirect.uri = agent/cdsso-oauth2
org.forgerock.openam.agents.config.policy.evaluation.application = iPlanetAMWebAgentService
org.forgerock.openam.agents.config.policy.evaluation.realm = /
com.sun.identity.agents.config.polling.interval = 60
com.sun.identity.agents.config.sso.cache.polling.interval = 3
com.sun.identity.agents.config.policy.cache.polling.interval = 3
com.sun.identity.agents.config.cookie.name = iPlanetDirectoryPro
com.sun.identity.agents.config.debug.file.size = 0
com.sun.identity.agents.config.local.logfile = /web_agents/agent_type/instances/agent_name/logs/debug/debug.log
com.sun.identity.agents.config.local.audit.logfile = /web_agents/agent_type/instances/agent_name/logs/audit/audit.log
com.sun.identity.agents.config.debug.level = Error

The properties are provided with an example value. For information about each of these properties, see the Properties reference.

Request process flow

When a client requests access to an application resource, the Web Agent intercepts the request. AM then validates the identity of the client, and their authorization to access the protected resource.

The following simplified data flow occurs when an unauthenticated client requests a resource protected by a Web Agent and AM. The flow assumes that requests must meet the requirements of an AM policy. For a detailed diagram, see Single sign-on in AM’s Authentication and single sign-on guide.

web-agent-process-flow.puml

  1. An unauthenticated client attempts to access a resource, and the agent intercepts the inbound request.

  2. The agent evaluates whether the requested resource or the client IP address matches a not-enforced rule..

  3. Alternate flow. The requested resource or the client IP address matches a not-enforced rule. The agent allows access to the resource.

  4. Alternate flow. The client receives a response from www.example.com. The flow ends.

  5. The requested resource or the client IP address does not match a not-enforced rule. The agent redirects the client to log in to AM.

  6. The client authenticates to AM.

    During client authentication, and to protect against reply attacks, the agent issues a pre-authentication cookie, named agent-authn-tx. The agent uses the cookie to track the authentication request to AM, and deletes it immediately after authentication.

    Depending on the configuration, the agent can either issue a single cookie to track all concurrent authentication requests, or one cookie for each request.

    The pre-authentication cookie expires after 5 minutes, or after the time specified in Profile Attributes Cookie Maxage.

    If POST data preservation is enabled, the request expires after the time specified in POST Data Entries Cache Period, which is by default 10 minutes. In this case, consider increasing Profile Attributes Cookie Maxage to at least 10 minutes.

  7. AM’s authentication service verifies the client credentials and creates a valid OpenID Connect (OIDC) JSON Web Token (JWT) with session information.

  8. AM sends the client a self-submitting form with the OIDC JWT.

  9. The client posts the self-submitting form to the agent endpoint, and the Web Agent consumes it.

  10. The agent contacts AM to validate the session contained in the ID token.

  11. AM validates the session.

  12. The agent contacts AM’s policy service, requesting a decision about whether the client is authorized to access the resource.

  13. AM’s policy service returns ALLOW.

  14. The agent writes the policy decision to the audit log.

  15. The agent enforces the policy decision. Because the Policy Service returned ALLOW, the agent performs a pass-through operation to return the resource to the client.

  16. The client accesses the resource.