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, refer to 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 admin UI, the
ssoadm command, and the REST API.
To access the centralized web agent configuration, on the AM admin UI go to REALMS > Realm Name > Applications > Agents > Web > Agent Name.
Configure properties that are not present in the AM admin UI as custom properties, on the Advanced tab of the console. For a list of property names, refer to 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, refer to 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 admin UI, 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, refer to 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, refer to Single sign-on in AM’s Authentication and SSO guide.
- FQDN check
When FQDN checking is enabled, the agent can redirect requests to different domains, depending on the hostname of the request. For more information, refer to FQDN checking.
- Not-enforced rules check
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.
For more information, refer to Not-enforced rules.
1-2: 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.
3: AM’s authentication service verifies the client credentials and creates a valid OIDC JWT, with session information.
4: AM sends the client a self-submitting form with the OIDC JWT.
5: The client posts the self-submitting form to the agent endpoint, and the Web Agent consumes it.
6: The agent contacts AM to validate the session contained in the ID token.
7: AM validates the session.
1: The agent contacts AM’s policy service, requesting a decision about whether the client is authorized to access the resource.
2: AM’s policy service returns
3: The agent writes the policy decision to the audit log.
4: 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.
5: The client accesses the resource.
The agent profile realm is the AM realm in which the agent profile is stored. The agent profile stores a set of configuration properties that define the behavior of the agent.
During agent installation, the installer prompts for the agent profile realm, and populates the property Agent Profile Realm in the bootstrap properties file. By default, the agent profile realm is set to the top-level realm.
The agent profile realm can be different to the user realm and policy evaluation realm. Groups of agents can use the same agent profile realm, which can be separate from the user realm and policy evaluation realm.
For information about creating agent profiles in the top-level realm or other realms, refer to Create agent profiles.
The policy evaluation realm is the realm that the agent uses to request policy decisions from AM. In most circumstances, the policy evaluation realm is the same as the user realm.
In AM, only the top-level realm has a default policy set, called iPlanetAMWebAgentService. If you use a policy evaluation realm that is in a subrealm of the top-level realm, you must also define a policy set and policies in the equivalent realm in AM.
The user realm is the realm in which a user is authenticated. In most circumstances, the user evaluation realm is the same as the policy evaluation realm.
By default, users authenticate to AM in the top-level realm, however, the agent can authenticate users in different realms depending on the request domain, path, or resource.
When a user logs out, the agent maintains the user realm. The agent obtains the
realm info from the JWT, if one is available, or by calling
the user logs out, the stored realm is passed to the logout endpoint automatically.
The first time an authenticated user requests a resource from the agent, the agent establishes the user realm from the session. It permanently associates the realm with the session in the session cache. When the session ends, the agent automatically passes the realm to the logout endpoint.
For more information about changing the user realm, refer to Login redirect.
On startup, Web Agent uses the following properties to obtain a session from AM:
The agent session lifetime is defined by the AM version and configuration, and is essentially indefinite.
For the security of your deployment, set the agent session lifetime as described in Manage Web Agent sessions.
If you clear agent sessions in the AM admin UI, you can accidentally kill an active agent session. If this happens, the agent detects that its session has expired and automatically obtains a new one.