What’s new
Web Agent 2024.11
Web Agent 2024.11 is a minor release that introduces new features, functional enhancements, and fixes.
Request handling
We’ve made changes to the Web Agent to improve the security of handling requests from upstream Java servers.
The agent now rejects unsafe uses of path parameters with an HTTP 400
in the following scenarios:
-
The request contains one or more
%2F
or%2f
(encoded forward slash) characters in the path parameters. -
The request contains one or more
%5C
or%5c
(encoded backslash) characters in the path parameters on a Windows server. -
The request includes empty path segments or dot path segments with path parameters. Some example unsafe uses include:
-
/;/
-
/..;
-
/.;
-
/..;parameter/
Legitimate uses of
;
as a path parameter are still permitted. For example, the agent won’t reject this request with thejessionid
parameter:/segment1/segment2/;jsessionid=1234
-
Path parameters (also known as matrix parameters) are used by J2EE and Spring-based Java servers in URL paths. |
Learn more in Path traversal attempts.
Agent authentication to Advanced Identity Cloud and AM
Web Agent authenticates to Advanced Identity Cloud and AM using a non-configurable authentication module or the Agent
authentication journey if it exists.
A new AM_AGENT_AUTH_MODE installation environment variable controls which authentication method the agent uses. By default, the agent authenticates using the Agent
journey but falls back to using the deprecated authentication module if authentication fails. This behavior is unchanged from earlier agent versions.
A new Agent Authentication Mode property allows the authentication method to be changed post-installation.
If you use PingAM 7.3 or 7.4 and experience issues with session quotas, set this property or environment variable to 2
to always authenticate using the authentication module.
The default fallback mode is deprecated and will be removed in the next release. The default will change to always authenticate using the Agent journey.
|
Include userId in audit logs
We’ve made changes to audit logging in the Web Agent to output the userId
field in the audit logs.
Providing the /access/userId
field is allowlisted
(which it is by default), the userId
field is now included in the audit event logs.
It is populated with the value of the universalId
attribute retrieved from the session by default. For example:
"userId":"id=demo,ou=user,dc=example,dc=com"
The following new properties provide additional control over how the universal ID is retrieved:
The user field is currently incorrectly output in the audit logs.
This output is deprecated and the user field will be removed from audit logs in the next release.
|
Web Agent 2024.9
Web Agent 2024.9 is a minor release that introduces new features, functional enhancements, and fixes.
Prometheus monitoring
To improve monitoring in the agent, a Prometheus monitoring endpoint is now available at /agent/metrics
. You can access this endpoint to return Prometheus metrics relevant to your deployment.
Learn more in Monitor services.
JWT signature validation
A new Validate JWT Signature Locally property controls how the JWT signature is validated. By default, the property is set to 0
, which doesn’t change JWT signature validatation.
Set this property to 1
to validate the JWT signature locally.
When the JWT signature is validated locally, there is an expected performance impact. |
TLSv1.3 security protocol
The TLS 1.3 security protocol can now be disabled if required by adding -TLSv1.3
to the Security Protocol List.
TLS key logging
TLS key logging is now available for troubleshooting TLS issues between the agent and AM. When enabled, TLS session keys are logged to an SSL key log file.
To troubleshoot TLS issues, enable TLS key logging using one of the following options:
-
The new Enable TLS key logging property.
-
The new AM_SSL_KEYLOG_ENABLE installation environment variable.
Then configure the new AM_SSL_KEYLOG_FILE environment variable to specify the name of the SSL key log file.
Learn more in TLS key logging.
Web Agent 2024.6
Web Agent 2024.6 is a minor release that introduces new features, functional enhancements, and fixes.
Overrides for request protocol, host, and port
In certain circumstances, the new property Disable Override Request URL Port, Host, or Protocol facilitates access to the agent by bypassing load balancers.
Audit
The new property Audit Path as Full URL is available to manage how the agent includes an HTTP request path in an audit log.
Web Agent 2024.3
Web Agent 2024.3 is a major release that introduces new features, functional enhancements, and fixes.
Hardened security of agent secrets
Because of the hardened security of agent secrets, drop-in software update to this release isn’t possible. Upgrade to this release from an earlier release is a major upgrade. Learn more in Upgrade.
- Strengthened encryption of agent secrets
-
The
agentadmin --k
command now generates a base64-encoded 256-bit random key.The
agentadmin --p
command now generates AES-256-GCM encrypted ciphertext.The
agentadmin --V
command now verifies that the agent can decrypt the ciphertext.
- Runtime encryption and decryption of on-disk agent secrets
-
At runtime, the agent decrypts the agent credentials and then generates a one-time symmetric encryption key to re-encrypt the credentials.
This feature creates crypto material at runtime. In previous releases, crypto material was created and stored only on-disk.
- Encryption key and ciphertext removed from bootstrap configuration file
-
The encryption key and ciphertext are stored in new agent configuration files,
agent-key.conf
andagent-password.conf
. The following properties are removed fromagent.conf
:For more information, refer to Agent configuration.
- Log of decryption errors for agent profile password
-
If the agent can’t decrypt the password in Agent Profile Password a message is now written to the logs.
- Use of the secret service in PingOne Advanced Identity Cloud and AM
-
With PingOne Advanced Identity Cloud and from AM 7.5, the agent profile password can optionally be managed through the identity provider’s secret service. If the identity provider finds a matching secret in a secret store, it uses that secret instead of the hard-coded agent password.
Learn more from Create an agent profile in PingOne Advanced Identity Cloud and Create agent profiles in AM.
Flexibility when client IP validation fails
A new property
Client IP Validation Failure Response
is available to force logout when
Client IP Validation is true
and the IP address of an
authenticated request doesn’t originate from the IP address used for authentication.
In previous releases, the agent could only return an HTTP 403 Forbidden.
Warnings for TLS certificates validation
When
Server Certificate Trust
is set to true
, the agent trusts any server certificate. Validation of the
installation with
agentadmin
now returns a warning to set the property to false
in production environments.
ISAPI Web Agent
The ISAPI Web Agent is now supported. Learn more from Install IIS and ISAPI Web Agent.
Key rotation with the agentadmin
command
The
agentadmin
command now provides an option for key rotation. Learn more in
Rotate keys.
Web Agent 2023.11
Web Agent 2023.11 is a minor release that introduces new features, functional enhancements, and fixes.
Hardened security of agent responses with JavaScript
All agent responses that contain JavaScript are now protected by a Content-Security-Policy header.
Examples of responses protected by this change include:
-
HTML forms returned by the agent during POST data preservation
-
Preserved browser fragments returned by the agent during authentication
Deployment with Docker
A Dockerfile is now provided to deploy Apache Web Agent to extend and protect an application. For more information, refer to Deploy Web Agent with Docker.
Web Agent 2023.9
Web Agent 2023.9 is a minor release that introduces new features, functional enhancements, and fixes.
Supported platforms
Web Agent 2023.9 supports the following additional platforms:
-
IBM HTTP Server 8.5 for Linux
-
Red Hat JBoss Core Services for Red Hat Enterprise Linux
-
NGINX Plus R30
For more information, refer to Supported operating systems and web servers Web Agent 2023.9.
Web Agent 2023.6
Web Agent 2023.6 is a minor release that introduces new features, functional enhancements, and fixes.
Use Apache Web Agent with Apache directives
Apache Web Agent can now be configured with the following Apache directives, globally or independently for different server locations:
-
AmAgent
to switch the agent on or off -
AmAuthProvider
to use Apache as the policy enforcement point
For more information, refer to Configure Apache Web Agent.
Authentication of Web Agent to PingOne Advanced Identity Cloud and AM
Web Agent agents are automatically authenticated to PingOne Advanced Identity Cloud and AM by a non-configurable authentication module. Authentication chains and modules are deprecated and replaced by nodes, trees, and journeys.
You can now authenticate Web Agent to PingOne Advanced Identity Cloud and AM 7.3 with a journey. The procedure is currently optional, but will be required when authentication chains and modules are removed in a future release.
For more information, refer to Authenticate agents to PingOne Advanced Identity Cloud and Authenticate agents to AM.
Management of agent credentials
An encryption key in agent.conf
is used to decrypt credentials for the agent
profile, the SSL certificate, and the HTTP proxy. By default, the agent caches
the encryption key. A new property Disable Caching of Agent Profile Password Encryption Key
is available to disable caching and require the agent to securely wipe the
encryption key after it is read.
Use the agentadmin --V
command to verify that the agent can decrypt the credentials
correctly.
Web Agent 2023.3
Web Agent 2023.3 is a major release that introduces new features, functional enhancements, and fixes.
Remove HTTP Server header in IIS
In IIS, the agent can now remove the Server
header from all responses.
To enable the feature, set the Remove IIS HTTP Server Header
property to true
.
Web Agent 5.10.2
Remove HTTP Server header in IIS
In IIS, the agent can now remove the Server
header from all responses.
To enable the feature, set the
Remove IIS HTTP Server Header property
(org.forgerock.agents.config.iis.headers.server.disable
) to true
.
Web Agent 5.10.1
Limit the number of debug log files
To help manage the amount of stored data, the new property Maximum Number of Debug Log Files is now available to limit the number of debug log files that the agent stores after file rotation.
Web Agent 5.10
Matching FQDNs to URL patterns
The wildcard *
can now be used in
FQDN Virtual Host Map.
to match a domain name. Use this feature to pass requests with
dynamically allocated hostnames, for example, in Kubernetes deployments, without
redirecting them to another domain.
For more information, see FQDN checking.
Authorization flow for single page applications using Javascript
Authorization flow for applications using Javascript is a new property to enable callbacks into JavaScript applications, after an authentication or transactional authorization journey.
The property provides support for single page applications (SPAs) that use embedded login or authorization dialogs within iframes or embedded tags.
This feature is in Technology Preview, as defined in Release levels and interface stability, for use only with assistance from Ping Identity.
Current limitations:
-
The property cannot be set in
agent.conf
. Set it in the Advanced tab of the AM console. -
The feature might require configuration changes to on-prem AM servers.
-
The feature does not work with the PingOne Advanced Identity Cloud, unless the service is accessed through a reverse proxy on the application site.
Apache built-in modules available for authentication
Use Built-in Apache HTTPD Authentication Directives
is a new property to enable Apache Web Agent to use built-in Apache
authentication directives, such as AuthName
, FilesMatch
, and Require
for
specified not-enforced URLs.
In previous releases, use of built-in Apache authentication directives was not supported. The agent replaced authentication functionality provided by Apache.
POST data preservation: use a single agent profile for multiple agent instances
In previous releases, to correctly configure POST data preservation, a separate agent profile was required in AM for each agent instance. From this release, a single agent profile can be used for multiple agent instance.
Use this feature for scalable deployments, where resources are dynamically created or destroyed.
URI fragments persisted in custom login mode
When the value of
Enable Custom Login Mode
is 2
, URI fragments were previously lost during login. From this release,
URI fragments in the browser are not lost after the custom login procedure.
Pre-authentication cookies expire immediately after authentication
In previous releases, the pre-authentication cookie, agent-authn-tx
, expired
when it reached the age configured by
Profile Attributes Cookie Maxage.
From this release, the pre-authentication cookie expires when the first of the
following events occur:
-
Authentication completes successfully
-
It reaches the age configured by Profile Attributes Cookie Maxage
Expiring the cookie immediately after authentication reduces the amount of used header space, and prevents authentication errors and errors in applications that set headers.