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.
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 configuration properties determine the behavior of the agent. AM stores configuration properties either centrally or locally:
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.
The Web Agent installer creates the following file to store agent bootstrap
and configuration properties:
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.
agent.conf file must contain at least the following
# 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.
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.
An unauthenticated client attempts to access a resource, and the agent intercepts the inbound request.
The agent evaluates whether the requested resource or the client IP address matches a not-enforced rule..
Alternate flow. The requested resource or the client IP address matches a not-enforced rule. The agent allows access to the resource.
Alternate flow. The client receives a response from
www.example.com. The flow ends.
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.
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.
AM’s authentication service verifies the client credentials and creates a valid OpenID Connect (OIDC) JSON Web Token (JWT) with session information.
AM sends the client a self-submitting form with the OIDC JWT.
The client posts the self-submitting form to the agent endpoint, and the Web Agent consumes it.
The agent contacts AM to validate the session contained in the ID token.
AM validates the session.
The agent contacts AM’s policy service, requesting a decision about whether the client is authorized to access the resource.
AM’s policy service returns
The agent writes the policy decision to the audit log.
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.
The client accesses the resource.