Preface

This guide shows you how to install ForgeRock Access Management Java agents, as well as how to integrate with ForgeRock Access Management. Read the Release Notes before you get started.

This guide is written for anyone installing Java agents to interface with supported Java web application containers.

About ForgeRock Identity Platform™ Software

ForgeRock Identity Platform™ serves as the basis for our simple and comprehensive Identity and Access Management solution. We help our customers deepen their relationships with their customers, and improve the productivity and connectivity of their employees and partners. For more information about ForgeRock and about the platform, see https://www.forgerock.com.

Chapter 1. Introducing Java Agents

A Java agent is an Access Management add-on component that operates as a Policy Enforcement Point (PEP) or policy agent for applications deployed on a Java container.

This chapter covers how Java agents work and how their features can protect your applications.

1.1. Java Agent Components

Java agents comprise two main components; the agent filter and the agent application:

Agent Filter. Intercepts inbound client requests to a resource and processes them based on the filter mode of operation.

Agent Application. Deployed as agentapp.war, it is required for authentication and the cross-domain single sign-on (CDSSO) flow.

The following components are not strictly part of the Java agent, but they play an important part in the agent's operation:

AM SDKs. Provide a set of APIs required to interact with AM.

Agent Profile. Contains a set of configuration properties that define the agent's behavior. The agent profile can be stored in AM's configuration store or as a text file local to the agent installation.

The following picture illustrates the Java agent's components when the agent profile is stored in the AM configuration store:

AM stores the Java agent properties in the AM configuration store. Storing the agent configuration centrally allows you to configure your agents by using the AM console, the ssoadm command, and the REST API. This is the default configuration location mode.

The Java agent installer creates the /path/to/java_agents/agent_type/agent_instance/OpenSSOAgentConfiguration.properties file to store configuration properties locally. To manage the configuration, edit the file to add properties, remove properties, and change values. You cannot update this file using the AM console, the ssoadm command, or the REST API.

Bootstrap properties

Bootstrap properties enable Java agents to connect to an AM instance. These properties are required regardless of whether the configuration properties are stored centrally in AM or locally on the agent installation.

The agent installer creates the /path/to/java_agents/agent_type/agent_instance/config/OpenSSOAgentBootstrap.properties file, which contains the bootstrap properties.

For more information on setting the Location of Agent Configuration Repository, see Profile Properties.

1.3. Request Process Flow

Suppose you wanted to withdraw money from your bank account using an ATM. The ATM would not allow you to access your account unless you identified yourself to the bank with your card and PIN number. For a joint account, you may also require additional authorization to access the funds.

Java agents work on a similar premise. When a client requests access to an application resource, the Java agent intercepts the request. Then, AM validates the identity of the client as well as their authorization to access the protected resource.

The following sequence diagram shows the flow that occurs when an unauthenticated client requests a resource protected by a Java agent and AM. The diagram assumes that the filter mode is set to ALL and is simplified [1] to show only the relevant steps in the flow.

Java Agent Process Flow

An unauthenticated client attempts to access a resource at www.example.com. The agent filter intercepts the inbound request.

Java agents evaluate whether the requested resource or the client IP address matches any rule contained in the not-enforced lists.

Alternate Flow. The requested resource or the client IP address matches a not-enforced rule. The Java 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 Java agent redirects the client to log in to AM.

The first time the Java agent receives a request for a resource, it needs to evaluate if the request is for a protected resource or for a not-enforced resource. To make this decision, the agent tries to match the request with the patterns specified in the not-enforced lists.

The Java agent evaluates every rule in the lists in order until it finds the first match. It does not process any other rule, even though a rule further down the list might provide a better match. Because of this, place your most specific rules at or near the beginning of the list.

To speed up future requests, the Java agent caches whether the resource hit or miss any not-enforced rule. Therefore, if a request for the same resource reaches the agent again, the agent checks the result of the rules evaluation in the cache instead of running the rules again.

If no rule matches, the Java agent decides whether to grant access or defer to AM based on the configuration of the Invert Not-Enforced IPs and the Invert Not-Enforced URIs properties. See the following table for an analysis of the possibilities.

Not-Enforced Default Access for Non-Matching Requests

Not-Enforced Client IP List Property

Not-Enforced URIs Property

Outcome

Inverted?

No

No

Defer to AM

Inverted?

Yes

Yes

Grant access

Inverted?

Yes

No

Defer to AM

Inverted?

No

Yes

Defer to AM

In the preceding table, if the Not-Enforced Client IP List and Not-Enforced URIs properties are not inverted (the Not-Enforced IP Invert List and Invert Not-Enforced URIs properties are set to false), the Java agent defers any unmatched request to AM for authorization.

Not-Enforced lists support wildcards, regular expressions, and the possibility of specify HTTP methods for fine-tuning the rules.

1.4.2. Notification System

AM can notify Java agents of configuration and session state changes through WebSockets. Java agents can subscribe to up to three notification feeds:

Configuration Notifications. When the administrator makes a change to a hot-swappable Java agent configuration property, AM sends a notification to the agent to reread the agent profile from AM.

Configuration notifications are applicable when you store the agent profile in AM's configuration data store. For more information about enabling configuration notifications, see Profile Properties.

Session Notifications. When a client logs out or a CTS-based session expires, AM sends a notification to the Java agent to remove that entry from the session cache. For more information about enabling session notifications, see Session Client Service Properties.

Policy Notifications. When an administrator changes a policy, AM sends a notification to the Java agent to flush the policy cache. For more information about enabling policy notifications, see Policy Client Service Properties.

Enabling notifications affects the validity of the Java agent caches. For more information, see "Caching Capabilities".

Note

Ensure that load balancers and reverse proxies configured in your environment support WebSockets.

1.4.3. Attribute Fetch Modes

Java agents provide the capability to fetch and inject user information into HTTP headers, request objects, and cookies and pass them on to the protected client applications. The client applications can then personalize content using these attributes in their web pages or responses.

Specifically, you can configure the type of attributes to be fetched and the associated mappings for the attributes names used on AM to those values used in the containers. The Java agent securely fetches the user and session data from the authenticated user as well as policy response attributes.

1.4.4. Login Attempt Limits

When the client does not present a valid SSO token, the Java agent will redirect the user to the login URL configured in AM. The Java agent can be configured to limit the login attempts made to the Java agent to mitigate any redirect loops that may result in an error page presented to the end-user.

You can use the com.sun.identity.agents.config.login.attempt.limit property to specify a non-zero value for the number of login attempts. For example, if the property is set to 3, then the Java agent will block the access request to the protected resource on the fourth login request.

You can also limit the number of redirections the Java agent can take for a single browser session by setting the com.sun.identity.agents.config.redirect.attempt.limit.

1.4.5. FQDN Checking

Java agents require that clients accessing protected resources use valid URLs with fully qualified domain names (FQDNs). If invalid URLs are referenced, policy evaluation can fail as the FQDN will not match the requested URL, leading to blocked access to the resource. Misconfigured URLs can also result in incorrect policy evaluation for subsequent access requests.

There are cases where clients may specify resource URLs that differ from the FQDNs stored in AM policies; for example, in load balanced and virtual host environments. To handle these cases, the Java agent supports FQDN Checking properties: FQDN Default and FQDN Virtual Host Map properties.

The FQDN Default property specifies the default URL with valid hostname. The property ensures that the Java agent can redirect to a URL with a valid hostname should it discover an invalid URL in the client request.

The FQDN Virtual Host Map property stores map keys and their corresponding values, allowing invalid URLs, load balanced URLs, and virtual host URLs to be correctly mapped to valid URLs. Each entry in the Map has precedence over the FQDN Default setting, so that if no valid URLs exist in the FQDN Virtual Host Map property, the Java agent redirects to the value specified in the FQDN Default property.

If you want the Java agent to redirect to a URL other than the one specified in the FQDN Default property, then it is good practice to include any anticipated invalid URLs in the FQDN Virtual Host Map property and map it to a valid URL.

1.4.6. Cookie Reset Properties

AM provides cookie reset properties that the Java agent carries out prior to redirecting the client to a login page for authentication.

Cookie reset is typically used when multiple parallel authentication mechanisms are in play with the Java agent and another authentication system. The Java agent can reset the cookies set by the other mechanism before redirecting the client to a login page.

The cookie reset properties include a name list specifying all of the cookies that will reset, a domain map specifying the domains set for each cookie, and a path map specifying the path from which the cookie will be reset.

If you have enabled attribute fetching using cookies to retrieve user data, it is good practice to use cookie reset, which will reset once you want to access an enforced URL without a valid session.

1.4.7. Cross-Domain Single Sign-On

Cross-domain single sign-on (CDSSO) is an AM capability that lets users access multiple independent services from a single login session, using the Java agent to transfer a validated session ID on a single DNS domain or across domains.

Without AM's CDSSO, single sign-on cannot be implemented across domains; the session cookie from one domain would not be accessible from another domain. For example, in a configuration where the AM server (openam.example.com) is in a different DNS domain than the Java agent (myapp.website.com), single sign-on would not be possible.

Java agents work in CDSSO mode by default, regardless of the DNS domain of the AM servers and the DNS domain of the agents.

1.4.8. POST Data Preservation

Java agents can preserve HTML form data submitted as an HTTP POST by unauthenticated clients.

At a high level, when an unauthenticated client posts HTML form data to a protected resource, the Java agent stores the data in its cache and redirects the client to the login screen. Upon successful authentication, the agent recovers the data stores in the cache and autosubmits it to the protected resource.

Consider enabling POST data preservation if users or clients in your environment submit large amounts of data, such as blog posts and wiki pages, and their sessions are short-lived.

Java agents guarantee the integrity of the data and the authenticity of the client as follows:

Each unauthenticated form POST to a protected resource generates a random unique identifier as the dummy internal endpoint from which the client recovers the POST data after authentication. This identifier is then placed into an encrypted cookie and provided to the client.

During authentication, the client is provided with a one-time code placed in a different cookie that is also stored with the POST data in the cache. If the client cannot provide the code (because the cookie is missing) or the code differs from the one stored with the POST data, the Java agent denies access to the endpoint.

To mitigate against DoS attacks, manage the time the data lives in the cache and the size of the cache itself, either by limiting the total number of entries it can hold or the total size of the data held.

1.4.9. Continuous Security

Because Java agents are the first point of contact between users and your business applications, they can collect inbound login requests' cookie and header information which an AM server-side authorization script can then process.

For example, you may decide that only incoming requests containing the InternalNetwork cookie can access intranet resources outside working hours.

1.4.10. Redirection and Conditional Redirection

Java agents provide the capability to redirect users to a specific AM instance, an AM site, or a website other than AM. You can also redirect users based on the incoming request URL. Conditional redirection is available for login and logout requests.

For example, you can configure the Java agent such that any login request made from the france.example.com domain is redirected to the openam.france.example.com AM site. You can also configure the Java agent to redirect any user to a specific page after logout.

You may also decide to configure conditional login redirection to specify the realm to which users must authenticate.

1.4.10.1. Default Redirection Login Mode

By default, Java Agents 5.x and AM use OpenID Connect (OIDC) JSON web tokens (JWT) for authentication. Unauthenticated users are redirected to the oauth2/authorize endpoint. This endpoint invokes both the XUI and other endpoints within AM, such as:

oauth2/authorize

json/authenticate

json/sessions

json/serverinfo

XUI/*

Unauthenticated users must be able to reach, at least, AM's oauth2/authorize endpoint.

When configuring the default redirection login mode, consider the following points:

Ensure that the Allow Custom Login Mode property is disabled (org.forgerock.openam.agents.config.allow.custom.login is set to false).

1.4.10.2. Custom Redirection Login Mode

When this property is set to true, the agent expects the custom login page to set an SSO token in the user's browser after authentication. The agent will present the SSO token to AM, which would then convert it into an OIDC JWT.

Use the custom redirection login mode when:

Your environment has customized login pages that expect user sessions to be stored in SSO tokens instead of in OIDC JWTs.

Your environment is configured so the users cannot access the AM servers directly.

Your environment is configured so the custom login pages are not part of AM's XUI.

Note

You should use the default redirection login mode when designing new environments. The custom redirection login mode is meant as an aid to support environments upgrading from earlier versions of the agents.

When configuring the custom redirection login mode, consider the following points:

Ensure that the Allow Custom Login Mode property is enabled (the org.forgerock.openam.agents.config.allow.custom.login property is set to true).

Configure the public AM URL in the org.forgerock.agents.public.am.url bootstrap property if the custom pages are in a network that can only access AM using a proxy, a firewall, or any other technology that remaps the AM URL to one accessible by the custom login pages.

Consider an example where the traffic between AM and the agent happens through the example-internal.com network, but the custom login pages are on the example-external.com domain. In this case, you would configure https://openam.example-external.com:8443/openam as the public AM URL.

The agent receives a request to access a page from an unauthorized user.

The agent checks the custom login redirection mode properties:

If configured, the agent redirects the user to the custom login page specified by the AM Login URL property.

If not configured, the agent matches the request with the domains and URLs specified by the org.forgerock.openam.agents.config.conditional.custom.login.url property, and redirects the user to the appropriate custom login page.

During the redirection process, the agent appends a goto parameter and a nonce to the request.

The user logs in to the custom login page.

The custom login page sets an SSO token in AM's session cookie (by default, iPlanetDirectoryPro) in the user's browser and redirects back to the agent using the goto parameter provided.

If the agent is unable to access AM's session cookie, or if the session cookie contains an invalid SSO token, the login process will fail.

The agent contacts AM to log the user in to the appropriate realm and convert the SSO token into an OIDC JWT.

1.4.11. Caching Capabilities

Java agents allocate memory from the Java heap space in the web container to the following caches:

Configuration Cache

When a Java agent with centralized configuration starts up, it makes a call to AM to retrieve a copy of the Java agent profile and stores it in the cache. The information stored in the cache is valid until one of the following events occurs:

AM notifies the Java agent of changes to hot-swappable Java agent configuration properties. The agent flushes the configuration cache and rereads the agent profile from AM.

The Java agent restarts.

The Java agent rereads the configuration from AM or from local files at the frequency specified by the com.sun.identity.agents.config.load.interval property.

If notifications and the com.sun.identity.agents.config.load.interval property are disabled, cached configuration remains valid until the Java agent restarts.

Session Cache

After authentication, AM presents the client with a JWT containing session information. The agent stores part of that session information in the cache. A session stored in the session cache is valid until one of the following events occurs:

The session contained in the JWT expires.

The client logs out from AM, and session notifications are enabled.

The session reaches the expiration time specified by the org.forgerock.openam.agents.config.active.session.cache.ttl.minutes property.

Policy Decision Cache

When a client attempts to access a protected resource, the Java agent checks whether there is a policy decision cached for the resource:

If the client's session is valid, the Java agent requests a policy decision from AM and then enforces it.

If the client's session is not valid, the Java agent redirects the client to AM for authentication regardless of why the session is invalid. The agent does not specify the reason why the client needs to authenticate.

Once the client authenticates, the Java agent requests policy decision to AM and enforces it.

Policy decisions are valid in the cache until one of the following events occur:

Session and Policy Validity in Cache

Event

What is invalidated?

Session contained in the JWT expires

Session and policy decisions related to the session

Client logs out from AM (and session notifications are enabled)

Session and policy decisions related to the session

Policy decision reaches the expiration time specified by the com.sun.identity.agents.polling.interval property

Important

A Java agent that loses connectivity to AM cannot request policy decisions. Therefore, the Java agent denies access to inbound requests that do not have a policy decision cached until the connection is restored.

Not-Enforced Lists Hit and Miss Caches

The first time the Java agent receives a request for a resource, it matches the request and the client's IP address against the rules specified in the not-enforced lists.

Java agents maintain a hit cache and a miss cache for each of the not-enforced lists specified in "Not-Enforced Lists". To speed up future requests, the agent stores whether the resource hit or missed not-enforced rules in the corresponding caches. Therefore, if a request for the same resource reaches the agent again, the agent replays the result of the rules' evaluation stored in the caches instead of re-evaluating the request.

Entries stored in the hit and miss caches do not expire unless AM notifies the agent about configuration changes in the not-enforced lists properties.

When POST data preservation is enabled, the Java agent caches HTML form data submitted as an HTTP POST by unauthenticated clients.

The POST data expires either when the client recovers the information from the cache or after the time interval specified by the com.sun.identity.agents.config.postdata.preserve.cache.entry.ttl property.

Decoding JWTs into JSON objects is a CPU-intensive operation. To reduce the amount of processing required on each request, Java agents cache decoded JWTs.

When a Java agent receives a request for a resource, it passes the JWT through a fast hashing algorithm that creates a 128-bit hash unique for that JWT. Then the agent determines if the hash is in the JWT cache. One of the following scenarios occur:

The hash is in the cache. The Java agent retrieves the decoded JWT from the cache and continues processing the request.

The hash is not in the cache. The Java agent decodes the JWT and stores it and its hash in the cache. Then it continues processing the request.

JWTs in the cache expire after the time interval specified by the org.forgerock.openam.agents.config.jwt.cache.ttl.minutes property.

1.4.12. Query Parameter Handling

By default, Java agents consider any query parameters to be part of the URL, and insert the entire string into the policy decision cache. For example, the agent will insert each of the following URLs in the cache, even though the root URL is the same:

Applications adding new parameters to the URL on every request would fill the Java agent's policy cache without actually using it, which in turn causes the agent to request policy decision to AM each time.

To prevent this behavior, Java agents can be configured to either retain nominated URL parameters (for example, to remove all but those that are added as part of the policy evaluation) or to discard them (for example, to remove all parameters added by the angular.js framework).

To retain nominated query parameters, configure one of the following properties:

2.1. Downloading and Unzipping Java Agents

Navigate to the ForgeRock BackStage website and choose the agent to download based on your version, architecture, and operating system requirements. Remember to verify the checksum of the downloaded file against the checksum posted on the download page.

Unzip the file in the directory where you plan to store the Java agent's configuration and log files. The following directories are extracted:

AM communicates all authentication and authorization information to Java agents using OpenID Connect (OIDC) JSON web tokens (JWT). To secure the integrity of the JSON payload (outlined in the JSON Web Algorithm specification RFC 7518), AM and the Java agent support signing the tokens for communication with the RS256 algorithm.

AM also uses an HMAC signing key to protect requested ACR claims values between sending the user to the authentication endpoint, and returning from successful authentication.

By default, AM uses a demo key and an autogenerated secret for these purposes. For production environments, perform the steps in one of the following procedures to create new key aliases and configure them in AM:

Configure the new RSA key alias in the am.global.services.oauth2.oidc.agent.idtoken.signing secret ID.

Configure the new HMAC secret in the am.services.oauth2.jwt.authenticity.signing secret ID.

Note that you may already have a secret configured for this secret ID, since it is also used for signing certain OpenID Connect ID tokens and remote consent requests. For more information, see Secret ID Mapping Defaults in the ForgeRock Access Management Setup and Maintenance Guide.

Save your changes.

For more information about secret stores, see the chapter Setting Up Secret Stores of the ForgeRock Access Management Setup and Maintenance Guide.

No further configuration is required in the agents.

2.3. Creating Agent Profiles

A Java agent requires a profile to connect to and communicate with AM, regardless of whether it is stored centrally in AM or on the agent installation.

To Create an Agent Profile in AM Using the Console

Create an agent profile using the AM console by performing the following steps:

In the AM console, navigate to Realms > Realm Name > Applications > Agents > Java, and then select the Add Java Agent button in the Agent tab.

Complete the web form using the following hints:

Agent ID

The ID of the agent profile. This ID is used during the agent installation.

Agent URL

The URL the Java agent protects, such as http://www.example.com:8080/agentapp.

In centralized configuration mode, the Agent URL is used to populate the agent profile for services, such as notifications.

Server URL

The full URL to an AM instance. If AM is deployed in a site configuration (behind a load balancer), enter the site URL.

In centralized configuration mode, Server URL is used to populate the agent profile for use with as login, logout, naming, and cross-domain SSO.

Password

The password the agent uses to authenticate to AM. Use this password when installing an agent.

To Create an Agent Profile Using the ssoadm Command

You can create an agent profile in AM using the ssoadm command-line tool. You do so by specifying the agent properties either as a list of attributes, or by using an agent properties file as shown below.

Perform the following steps to create an agent profile using the ssoadm command:

Select New in the Group table, and provide a name for the group and the URL to the AM server in which to store the profile.

After creating the group profile, you can select the link to the new group profile to fine-tune the configuration.

Inherit group settings by selecting your agent profile, and then selecting the group name in the Group drop-down list near the top of the profile page.

You can then adjust inheritance by clicking Inheritance Settings on the AM Services agent profile tab.

2.3.1. Delegating Agent Profile Creation

If you want to create agent profiles when installing Java agents, then you need the credentials of an AM user who can read and write agent profiles.

You can use the AM administrator account when creating agent profiles. If you delegate agent installation, then you might not want to share AM administrator credentials with everyone who installs Java agents.

To Create Agent Administrators for a Realm

Follow these steps to create agent administrator users for a realm:

In the AM console, navigate to Realms > Realm Name > Subjects.

Under Group click New... and create a group for agent administrators.

Switch to the Privileges tab for the realm, and click the name of the group you created.

Select Read and write access to all configured agents, and then Save your work.

Return to the Subjects tab, and under User create as many agent administrator users as needed.

For each agent administrator user, edit the user profile.

Under the Group tab of the user profile, add the user to agent profile administrator group, and then Save your work.

Provide each system administrator who installs Java agents with their agent administrator credentials.

When installing the Java agent with the --custom-install option, the system administrator can choose the option to create the profile during installation, and then provide the agent administrator user name and the path to a read-only file containing the agent administrator password. For silent installs, you can add the --acceptLicense option to auto-accept the software license agreement.

2.4. Supporting Load Balancers and Reverse Proxies Between AM and the Agents

When your environment has reverse proxies or load balancers configured between the agents and AM, you must perform additional configuration in both AM and your environment before installing the agents.

Failure to do so may cause the agent installation to fail, or it may compromise the agent's functionality.

When working with AM and agents, the most common deployment scenario is to configure a load balancer and a reverse proxy between the clients and the agents, and another load balancer and reverse proxy between the agent and an AM site, as shown in the following diagram:

Java Agents in Environments with Load Balancers and Reverse Proxies

Usually, you want to anonymize client traffic as it gets into your network by using a reverse proxy, then balance the load among different application servers and agents.

AM sites are usually deployed behind a load balancer so the load can be spread among different instances. A reverse proxy may be deployed in front of the AM site to protect its APIs, too.

Note that the reverse proxy and the load balancer may be the same entity. In very complex environments, there may be more than the depicted load balancers and reverse proxies deployed in the network.

In any case, when installing Java agents in an environment with load balancers or reverse proxies, you must consider the communication between the clients and the Java agents, and between the agents and the AM servers.

3.1. Regarding Communication Between AM and Agents

Before attempting to install Java agents in an environment where AM is behind a load balancer, reverse proxy, or both, consider the following points:

Agent's IP Address and/or FQDN

When a load balancer or a reverse proxy is configured between AM and the Java agents, the agents' IP addresses and FQDNs are concealed by the load balancer/reverse proxy's own IP or FQDN. As a result, AM cannot determine the agents' base URL as expected.

This could cause trouble during the installation process and also hinder functionality such as redirection using the goto parameter.

Therefore, you must configure the following:

The load balancer or reverse proxy, to forward the agents' IP address and/or FQDN in a header.

Note

A load balancer or reverse proxy conceals the AM instances' IP addresses and FQDNs. When installing Java agents, use the load balancer or reverse proxy IP address or FQDN as the point of contact for the AM site.

AM Sessions and Session Stickiness

When Java agents communicate with an AM site that is behind a load balancer, you can improve policy evaluation performance by setting up AM's sticky cookie (by default, amlbcookie) to the AM's server ID. For more information, see Configuring Site Sticky Load Balancing in the ForgeRock Access Management Installation Guide.

Important

When configuring multiple agents behind a load balancer or reverse proxy, you must take into consideration whether you use one or multiple agent profiles, since it impacts sticky load balancer requirements:

If the agents are configured with multiple agent profiles you must configure sticky load balancing. This is because the agent profile name is contained in the OpenID Connect JWT the agent and AM use to communicate. Without session stickiness, there is no way to make sure that the appropriate JWT ends in the appropriate Java agent instance.

If multiple agents are configured with the same agent profile, you can decide whether to configure sticky load balancing or not depending on other requirements of your environment.

WebSockets

Your load balancers and reverse proxies must support the WebSocket protocol for communication between the Java agents and the AM servers.

For more information, refer to the load balancer or proxy documentation.

This property allows AM to retrieve the base URL from the Forwarded header field in the HTTP request. The Forwarded HTTP header field is standardized and specified in RFC 7239.

Context path: AM's deployment uri. For example, /openam.

Leave the rest of the fields empty.

Tip

For more information about the Base URL Source service, see Base URL Source in the ForgeRock Access Management Reference.

Save your changes.

3.2. Regarding Communication Between Clients and Agents

When your environment has load balancers or reverse proxies between clients and agents, you must consider the following points:

Client's IP Address and/or FQDNs

When configuring Java agents behind a load balancer or reverse proxy, the clients' IP addresses and FQDNs are hidden by the load balancer's IP or FQDN, which results in agents not being able to determine the clients' base URLs.

Therefore, you must configure the load balancer or reverse proxy to forward the client's IP address and/or the client's FQDN in a header. Failure to do so will will prevent the agent from performing policy evaluation, and applying not-enforced and conditional login/logout rules.

When the protected Java containers and their agents are behind a load balancer or reverse proxy, it is imperative that the agent is configured to match the load balancer FQDN, port, and protocol.

Failure to do so would make the agent to return HTTP 403 errors when clients request access to resources.

There are two use-cases:

The load balancer or reverse proxy forwards requests and responses between clients and protected Java containers only. In this case, ports and protocols configured in the Java container match those on the load balancer or reverse proxy, but FQDNs do not.

The load balancer or reverse proxy also performs SSL offloading, terminating the SSL traffic and converting the requests reaching the Java container to HTTP. This reduces the load on the protected containers, since the processing of the public key is usually done by a hardware accelerator.

3.2.1. Matching Protected Java Container Ports, Protocols, and FQDNs

When the protocol and port configured on the load balancer or reverse proxy differ from those configured on the protected Java container, you must override them in the Java agent configuration. The following diagram illustrates this scenario:

When the protocol and port configured on the load balancer or reverse proxy match those configured on the protected Java container, you must map the agent host name to the load balancer or reverse proxy host name. The following diagram illustrates this scenario:

Use the alternate Java agent URL properties to override the agent protocol, host, and port with that of the load balancer or reverse proxy.

Important

The Java agent configuration for SSL offloading has the side effect of preventing FQDN checking and mapping. As a result, URL rewriting and redirection does not work correctly when the Java agent is accessed directly and not through the load balancer or proxy. This should not be a problem for client traffic, but potentially could be an issue for applications accessing the protected container directly, from behind the load balancer.

This procedure explains how to do so for a centralized Java agent profile configured in the AM console. The steps also mention the properties for Java agent profiles that rely on local, file-based configurations:

Log in to the AM console as an administrative user with rights to modify the Java agent profile.

This procedure explains how to do so for a centralized Java agent profile configured in the AM console. The steps also mention the properties for Java agent profiles that rely on local, file-based configurations:

Log in to the AM console as an administrative user with rights to modify the Java agent profile.

The equivalent property setting is com.sun.identity.agents.config.fqdn.check.enable=true.

Set the FQDN Default field to the fully qualified domain name of the load balancer or proxy, such as lb.example.com, rather than the protected container FQDN where the Java agent is installed.

The equivalent property setting is com.sun.identity.agents.config.fqdn.default=lb.example.com.

Append the FQDN of the load balancer or proxy to the Agent Root URL for CDSSO field.

The equivalent property setting is sunIdentityServerDeviceKeyValue[n]=lb.example.com.

Map the load balancer or proxy FQDN to the FQDN where the Java agent is installed in the FQDN Virtual Host Map key-pair map. For example, set the key agent.example.com (protected Java container) and a value lb.example.com (load balancer or proxy).

The equivalent property setting is com.sun.identity.agents.config.fqdn.mapping[agent.example.com]=lb.example.com.

This procedure explains how to configure the client identification properties for a centralized Java agent profile configured in the AM console. The steps also mention the properties for Java agent profiles that rely on local, file-based configurations:

Log in to the AM console with a user that has permissions to modify the Java agent profile.

(Optional) In the Client IP Address Header field, configure the name of the header containing the IP address of the client. For example, X-Forwarded-For.

Configure this property if your AM policies are IP address-based, you configured the agent for not-enforced IP rules, or if you configured the agent to take any decision based on the client's IP address.

The equivalent property setting is com.sun.identity.agents.config.client.ip.header=X-Forwarded-For.

(Optional) In the Client Hostname Header field, configure the name of the header containing the FQDN of the client. For example, X-Forwarded-Host.

Configure this property if your AM policies are URL-based, you configured the agent for not-enforced URL rules, or if you configured the agent to take any decision based on the client's URL.

The equivalent property setting is com.sun.identity.agents.config.client.hostname.header=X-Forwarded-Host.

When configuring POST data preservation behind a load balancer or a reverse proxy, you must configure both your load balancer/reverse proxy and the Java agents for session stickiness.

This procedure explains how to configure the client identification properties for a centralized Java agent profile configured in the AM console. The steps also mention the properties for Java agent profiles that rely on local, file-based configurations:

To Configure POST Data Preservation Stickiness Properties

Log in to the AM console with a user that has permissions to modify the Java agent profile.

Decide whether the Java agent should create a cookie or append a string to the URL to assist with sticky load balancing.

In the PDP Stickysession mode drop-down menu, configure one of the following options:

Cookie. The Java agent will create a cookie for POST data preservation session stickiness. The contents of the cookie is configured in the next step.

URL. The Java agent will append to the URL a string specified in the next step.

The equivalent property setting is com.sun.identity.agents.config.postdata.preserve.stickysession.mode=[Cookie|URL].

In the PDP Stickysession key-value field, configure a key-pair value separated by the = character.

For example, specifying lb=myserver either sets a cookie called lb with myserver as a value, or appends lb=myserver to the URL query string.

The equivalent property setting is com.sun.identity.agents.config.postdata.preserve.stickysession.value=lb=myserver.

Save your changes.

Configure your load balancer or reverse proxy to ensure session stickiness when the cookie or URL query parameter are present.

Chapter 4. Installing Java Agents

Install Java agents in web application containers to police access to your web sites, web applications, and resources. Java agents depend on AM for all authentication and authorization decisions. The primary responsibility of Java agents is to enforce what AM decides in a way that is unobtrusive to the user.

When installing Java agents, consider the following points:

Configurations where AM and the Java agent are installed in the same container are not supported.

A single Java agent installation can hold multiple agent instances. Therefore, install only one Java agent per application server and configure as many agent instances as you require. Installing more than one Java agent in an application server is not supported.

The following table contains a list of sections containing information to install Java agents on supported platforms:

4.1.1. Before You Install

Consider the following points before installing the Tomcat Java agent:

Install Tomcat before you install the agent.

All of the Tomcat scripts must be present in the $CATALINA_HOME/bin directory. The Tomcat Windows executable installer does not include the scripts, for example. If the scripts are not present in your installation, copy the contents of the bin directory from a .zip download of Tomcat of the same version as the one you installed.

Install a supported version of the Java runtime environment, as described in "Java Requirements" in the Release Notes. Set the JAVA_HOME environment variable accordingly. The agent installer requires Java.

$ echo $JAVA_HOME/path/to/java

4.1.2. Installing the Tomcat Java Agent

Complete the following procedures to install the Tomcat Java Agent:

To Complete Pre-Installation Tasks

Perform the following steps to create the configuration required by the Java agent before installing it:

Configure AM to protect the cross-domain single sign-on (CDSSO) session cookie from hijacking. For more information, see Implementing Cross-Domain Single Sign-On in the ForgeRock Access Management Authentication and Single Sign-On Guide.

When you run the command, you will be prompted to read and accept the software license agreement for the agent installation. You can suppress the license agreement prompt by including the --acceptLicence parameter. The inclusion of the option indicates that you have read and accepted the terms stated in the license. To view the license agreement, open <server-root>/legal-notices/license.txt.

Enter the path to the Tomcat configuration folder. For example, /path/to/apache-tomcat/conf.

Enter the complete path to the directory which is used by Tomcat Server to
store its configuration Files. This directory uniquely identifies the
Tomcat Server instance that is secured by this Agent.
[ ? : Help, ! : Exit ]
Enter the Tomcat Server Config Directory Path
[/opt/apache-tomcat-6.0.14/conf]: /path/to/apache-tomcat/conf

To balance agent connections to an AM site, configure the URL of the load balancer in front of the AM site.

Note

If your environment has a reverse proxy configured between AM and the agent, set the AM URL to the proxy URL instead. For example, https://proxy.example.com:443/openam. For more information about setting up the environment for reverse proxies, see "Configuring Apache HTTP Server as a Reverse Proxy Example".

Upon successful completion, the installer adds the agent configuration to the Tomcat configuration, and also set up the configuration and log directories for the agent.

Take note of the configuration files and log locations.

Each agent instance that you install on the system has its own numbered configuration and logs directory. The first agent's configuration and logs are thus located under the directory java_agents/tomcat_agent/Agent_001/:

config/OpenSSOAgentBootstrap.properties

Used to bootstrap the agent, allowing it to connect to AM and download its configuration.

config/OpenSSOAgentConfiguration.properties

Only used if you configured the agent to use local configuration.

logs/audit/

Operational audit log directory, only used if remote logging to AM is disabled.

(Optional) If you have a policy configured, you can test your agent installation. For example, try to browse to a resource that your agent protects. You should be redirected to AM to authenticate, for example, as user demo, password changeit. After you authenticate, AM then redirects you back to the resource you tried to access.

4.1.3. Installing the Tomcat Java Agent Silently

To install the Tomcat Java agent silently you must create a response file containing the installation parameters, and then provide it to the agentadmin command.

To balance agent connections to an AM site, set the AM_SERVER_URL variable as the URL of the load balancer in front of the AM site.

Note

If your environment has a reverse proxy configured between AM and the agent, set the AM URL to the proxy URL instead. For example, https://proxy.example.com:443/openam. For more information about setting up the environment for reverse proxies, see "Configuring Apache HTTP Server as a Reverse Proxy Example".

You can also create this file automatically when installing the agent by running the agentadmin command with the --saveResponse option. For example:

$ agentadmin --install --saveResponse response-file

Complete the following procedures to install the Tomcat Java agent silently:

To Complete Pre-Installation Tasks

Perform the following steps to create the configuration required by the Java agent before installing it:

Configure AM to protect the cross-domain single sign-on (CDSSO) session cookie from hijacking. For more information, see Implementing Cross-Domain Single Sign-On in the ForgeRock Access Management Authentication and Single Sign-On Guide.

Install a supported version of the Java runtime environment, as described in "Java Requirements" in the Release Notes. Set the JAVA_HOME environment variable accordingly. The agent installer requires Java.

$ echo $JAVA_HOME/path/to/java

4.2.2. Installing the JBoss Java Agent

Complete the following procedures to install the JBoss Java agent:

To Complete Pre-Installation Tasks

Perform the following steps to create the configuration required by the Java agent before installing it:

Configure AM to protect the cross-domain single sign-on (CDSSO) session cookie from hijacking. For more information, see Implementing Cross-Domain Single Sign-On in the ForgeRock Access Management Authentication and Single Sign-On Guide.

When you run the command, you will be prompted to read and accept the software license agreement for the agent installation. You can suppress the license agreement prompt by including the --acceptLicence parameter. The inclusion of the option indicates that you have read and accepted the terms stated in the license. To view the license agreement, open <server-root>/legal-notices/license.txt.

Enter the path to the JBoss installation directory. For example, /path/to/jboss.

Enter the complete path to the home directory of the JBoss instance.
[ ? : Help, ! : Exit ]
Enter the path to the JBoss installation: /path/to/jboss

Enter the JBoss deployment mode. Supported modes are domain, which allows you to manage multiple server instances from a single control point, or standalone, which is a single JBoss instance.

Enter the name of the deployment mode of the JBoss installation that you wish
to use with this agent. Supported values are: domain, standalone.
[ ? : Help, < : Back, ! : Exit ]
Enter the deployment mode of JBoss [standalone]: standalone

To balance agent connections to an AM site, configure the URL of the load balancer in front of the AM site.

Note

If your environment has a reverse proxy configured between AM and the agent, set the AM URL to the proxy URL instead. For example, https://proxy.example.com:443/openam. For more information about setting up the environment for reverse proxies, see "Configuring Apache HTTP Server as a Reverse Proxy Example".

Upon successful completion, the installer updates the JBoss configuration, adds the Java agent application under JBOSS_HOME/server/standalone/deployments, and also sets up configuration and log directories for the Java agent.

Take note of the configuration files and log locations.

Each Java agent instance that you install on the system has its own numbered configuration and logs directory. The first Java agent instance configuration files and logs are thus located under the directory java_agents/jboss_agent/Agent_001/:

config/OpenSSOAgentBootstrap.properties

Used to bootstrap the Java agent, allowing it to connect to AM and download its configuration.

config/OpenSSOAgentConfiguration.properties

Only used if you configured the Java agent to use local configuration.

logs/audit/

Operational audit log directory, only used if remote logging to AM is disabled.

(Optional) If you responded domain to the Enter the name of the deployment mode question during the installation process, you must manually deploy the java_agents/jboss_agent/etc/agentapp.war file to JBoss.

The reason manual deployment is required when running JBoss in domain mode is that the agent installer uses auto-deployment capabilities provided by the JBoss deployment scanner. The deployment scanner is used only in standalone mode. When running JBoss in standalone mode, it is not necessary to manually deploy the agentapp.war file.

(Optional) If you have a policy configured, you can test your agent installation. For example, try to browse to a resource that your agent protects. You should be redirected to AM to authenticate, for example, as user demo, password changeit. After you authenticate, AM then redirects you back to the resource you tried to access.

4.2.3. Installing the JBoss Java Agent Silently

To install the JBoss Java agent silently, you must create a response file containing the installation parameters that you will then provide to the agentadmin command.

The following is an example of the response file to install the agent when JBoss is configured in standalone mode:

The INSTALL_PROFILE_NAME variable is only used when the INSTANCE_NAME is set to domain, and it specifies the name of the JBoss domain profile.

To balance agent connections to an AM site, set the AM_SERVER_URL variable as the URL of the load balancer in front of the AM site.

Note

If your environment has a reverse proxy configured between AM and the agent, set the AM URL to the proxy URL instead. For example, https://proxy.example.com:443/openam. For more information about setting up the environment for reverse proxies, see "Configuring Apache HTTP Server as a Reverse Proxy Example".

You can also create this file automatically when installing the agent by running the agentadmin command with the --saveResponse option. For example:

$ agentadmin --install --saveResponse response-file

Complete the following procedures to install the JBoss Java agent silently:

To Complete Pre-Installation Tasks

Perform the following steps to create the configuration required by the Java agent before installing it:

Configure AM to protect the cross-domain single sign-on (CDSSO) session cookie from hijacking. For more information, see Implementing Cross-Domain Single Sign-On in the ForgeRock Access Management Authentication and Single Sign-On Guide.

Run the agentadmin command with the --useResponse option. For example:

$ agentadmin --install --acceptLicense --useResponse response-file

To protect an application in the container, configure the agent filter.

If you configured the GLOBAL_MODULE variable as false in the response file, add the following line to the META-INF/MANIFEST.MF file of the application:

Dependencies: org.forgerock.openam.agent

If you configured the INSTANCE_NAME variable as domain in the response file, you must manually deploy the java_agents/jboss_agent/etc/agentapp.war file to JBoss.

The reason manual deployment is required when running JBoss in domain mode is that the agent installer uses auto-deployment capabilities provided by the JBoss deployment scanner. The deployment scanner is used only in standalone mode. When running JBoss in standalone mode, it is not necessary to manually deploy the agentapp.war file.

Install a supported version of the Java runtime environment, as described in "Java Requirements" in the Release Notes. Set the JAVA_HOME environment variable accordingly. The agent installer requires Java.

$ echo $JAVA_HOME/path/to/java

Command-line examples in this chapter show Jetty accessed remotely. If you are following the examples and have issues accessing Jetty remotely, you might have to change filter settings in the deployment descriptor file, such as /path/to/jetty/webapps/test/WEB-INF/web.xml, as shown in the following example:

Configure AM to protect the cross-domain single sign-on (CDSSO) session cookie from hijacking. For more information, see Implementing Cross-Domain Single Sign-On in the ForgeRock Access Management Authentication and Single Sign-On Guide.

When you run the command, you will be prompted to read and accept the software license agreement for the agent installation. You can suppress the license agreement prompt by including the --acceptLicence parameter. The inclusion of the option indicates that you have read and accepted the terms stated in the license. To view the license agreement, open <server-root>/legal-notices/license.txt.

Enter the path to the Jetty configuration directory. For example, /path/to/jetty/etc.

Enter the complete path to the directory which is used by Jetty Server to store
its configuration Files. This directory uniquely identifies the Jetty
Server instance that is secured by this Agent.
[ ? : Help, ! : Exit ]
Enter the Jetty Server Config Directory Path [/opt/jetty/etc]: /path/to/jetty/etc

Enter the path to the Jetty root directory. For example, /path/to/jetty.

To balance agent connections to an AM site, configure the URL of the load balancer in front of the AM site.

Note

If your environment has a reverse proxy configured between AM and the agent, set the AM URL to the proxy URL instead. For example, https://proxy.example.com:443/openam. For more information about setting up the environment for reverse proxies, see "Configuring Apache HTTP Server as a Reverse Proxy Example".

Upon successful completion, the installer updates Jetty's start.jar to reference the agent, sets up the agent web application, and also sets up configuration and log directories for the agent.

Take note of the configuration files and log locations.

Each agent instance that you install on the system has its own numbered configuration and logs directory. The first agent's configuration and logs are thus located under the directory java_agents/jetty_agent/Agent_001/:

config/OpenSSOAgentBootstrap.properties

Used to bootstrap the Java agent, allowing the agent to connect to AM and download its configuration.

config/OpenSSOAgentConfiguration.properties

Only used if you configured the Java agent to use local configuration.

logs/audit/

Operational audit log directory, only used if remote logging to AM is disabled.

To protect an application in the container, configure the agent filter.

(Optional) If you have a policy configured, you can test the agent installation. For example, try to browse to a resource that your agent protects. You should be redirected to AM to authenticate, for example, as user demo, password changeit. After you authenticate, AM then redirects you back to the resource you tried to access.

4.3.3. Installing the Jetty Java Agent Silently

To install the Jetty Java agent silently, you must create a response file contanining the installation parameters and then provide it to the agentadmin command.

To balance agent connections to an AM site, set the AM_SERVER_URL variable as the URL of the load balancer in front of the AM site.

Note

If your environment has a reverse proxy configured between AM and the agent, set the AM URL to the proxy URL instead. For example, https://proxy.example.com:443/openam. For more information about setting up the environment for reverse proxies, see "Configuring Apache HTTP Server as a Reverse Proxy Example".

You can also create this file automatically when installing the Java agent by running the agentadmin command with the --saveResponse option. For example:

$ agentadmin --install --saveResponse response-file

Complete the following procedures to install the Jetty Java agent silently:

To Complete Pre-Installation Tasks

Perform the following steps to create the configuration required by the Java agent before installing it:

Configure AM to protect the cross-domain single sign-on (CDSSO) session cookie from hijacking. For more information, see Implementing Cross-Domain Single Sign-On in the ForgeRock Access Management Authentication and Single Sign-On Guide.

4.4.1. Before You Install

Consider the following points before installing the WebLogic Java agent:

Install WebLogic before you install the agent.

Install a supported version of the Java runtime environment, as described in "Java Requirements" in the Release Notes. Set the JAVA_HOME environment variable accordingly. The agent installer requires Java.

$ echo $JAVA_HOME/path/to/java

4.4.2. Installing the WebLogic Java Agent

Complete the following procedures to install the WebLogic Java agent:

To Complete Pre-Installation Tasks

Perform the following steps to create the configuration required by the Java agent before installing it:

Configure AM to protect the cross-domain single sign-on (CDSSO) session cookie from hijacking. For more information, see Implementing Cross-Domain Single Sign-On in the ForgeRock Access Management Authentication and Single Sign-On Guide.

When you run the command, you will be prompted to read and accept the software license agreement for the agent installation. You can suppress the license agreement prompt by including the --acceptLicence parameter. The inclusion of the option indicates that you have read and accepted the terms stated in the license. To view the license agreement, open <server-root>/legal-notices/license.txt.

Enter the path to the startWebLogic.sh file of the WebLogic domain where you want to install the agent. For example, /Oracle_Home/user_projects/domains/base_domain/startWebLogic.sh.

Enter the path to the location of the script used to start the WebLogic domain.
Please ensure that the agent is first installed on the admin server instance
before installing on any managed server instance.
[ ? : Help, ! : Exit ]
Enter the Startup script location
[/usr/local/bea/user_projects/domains/base_domain/startWebLogic.sh]: /Oracle_Home/user_projects/domains/base_domain/startWebLogic.sh

Enter the path to the WebLogic installation directory. For example, /path/to/weblogic.

To balance agent connections to an AM site, configure the URL of the load balancer in front of the AM site.

Note

If your environment has a reverse proxy configured between AM and the agent, set the AM URL to the proxy URL instead. For example, https://proxy.example.com:443/openam. For more information about setting up the environment for reverse proxies, see "Configuring Apache HTTP Server as a Reverse Proxy Example".

Each agent instance that you install on the system has its own numbered configuration and logs directory. The first agent's configuration and logs are thus located under the directory java_agents/weblogic_agent/Agent_001/:

config/OpenSSOAgentBootstrap.properties

Used to bootstrap the Java agent, allowing the agent to connect to AM and download its configuration.

config/OpenSSOAgentConfiguration.properties

Only used if you configured the Java agent to use local configuration.

logs/audit/

Operational audit log directory, only used if remote logging to AM is disabled.

The agent requires sourcing before it will work properly. There are two ways to source:

Manually source the file containing the agent environment settings for WebLogic before starting the application server.

$ . /path/to/setAgentEnv_AdminServer.sh

Or edit the startWebLogic.sh script to set the sourcing needed for the agent, by adding these lines after the code block shown. Add the setAgentEnv_AdminServer.sh line to the following location in the file. The drawback to this approach is that it could be overwritten, as noted in the file:

$ cat /path/to/startWebLogic.sh...
# Any changes to this script may be lost when adding extensions to this
# configuration.
DOMAIN_HOME="/opt/Oracle/Middleware/user_projects/domains/base_domain"
. /path/to/setAgentEnv_AdminServer.sh
${DOMAIN_HOME}/bin/startWebLogic.sh $*

To protect an application in the container, configure the agent filter.

(Optional) If you have a policy configured, you can test your agent installation. For example, try to browse to a resource that your agent protects. You should be redirected to AM to authenticate, for example, as user demo, password changeit. After you authenticate, AM then redirects you back to the resource you tried to access.

4.4.3. Installing the WebLogic Java Agent Silently

To install the WebLogic Java agent silently, you must create a response file containing the installation parameters that you will then provide to the agentadmin command.

To balance agent connections to an AM site, set the AM_SERVER_URL variable as the URL of the load balancer in front of the AM site.

Note

If your environment has a reverse proxy configured between AM and the agent, set the AM URL to the proxy URL instead. For example, https://proxy.example.com:443/openam. For more information about setting up the environment for reverse proxies, see "Configuring Apache HTTP Server as a Reverse Proxy Example".

You can also create this file automatically when installing the Java agent by running the agentadmin command with the --saveResponse option. For example:

$ agentadmin --install --saveResponse response-file

Complete the following procedures to install the WebLogic Java agent silently:

To Complete Pre-Installation Tasks

Perform the following steps to create the configuration required by the Java agent before installing it:

Configure AM to protect the cross-domain single sign-on (CDSSO) session cookie from hijacking. For more information, see Implementing Cross-Domain Single Sign-On in the ForgeRock Access Management Authentication and Single Sign-On Guide.

Run the agentadmin command with the --useResponse option. For example:

$ agentadmin --install --acceptLicense --useResponse response-file

The agent requires sourcing before it will work properly. There are two ways to source:

Manually source the file containing the agent environment settings for WebLogic before starting the application server.

$ . /path/to/setAgentEnv_AdminServer.sh

Or edit the startWebLogic.sh script to set the sourcing needed for the agent, by adding these lines after the code block shown. Add the setAgentEnv_AdminServer.sh line to the following location in the file. The drawback to this approach is that it could be overwritten, as noted in the file:

$ cat /path/to/startWebLogic.sh...
# Any changes to this script may be lost when adding extensions to this
# configuration.
DOMAIN_HOME="/opt/Oracle/Middleware/user_projects/domains/base_domain"
. /path/to/setAgentEnv_AdminServer.sh
${DOMAIN_HOME}/bin/startWebLogic.sh $*

4.5.1. Before You Install

Consider the following points before installing the WebSphere Java agent:

Install WebSphere before you install the agent.

Install a supported version of the Java runtime environment, as described in "Java Requirements" in the Release Notes. Set the JAVA_HOME environment variable accordingly. The agent installer requires Java.

$ echo $JAVA_HOME/path/to/java

If you are using IBM Java, perform the following procedure:

To Install With IBM Java

The WebSphere Java agent runs with IBM Java. To install the agent using IBM Java on platforms other than AIX, you must change the agentadmin script to use the IBM Java Cryptography Extensions (JCE).

Note that line breaks and continuation marker (\) characters have been manually added to the following examples to aid display in the documentation. These are not required when editing the script.

Open the file bin/agentadmin for editing.

Edit the line that calls the AdminToolLauncher jar file to move the $AGENT_OPTS environment variable before the classpath is set:

Configure AM to protect the cross-domain single sign-on (CDSSO) session cookie from hijacking. For more information, see Implementing Cross-Domain Single Sign-On in the ForgeRock Access Management Authentication and Single Sign-On Guide.

When you run the command, you will be prompted to read and accept the software license agreement for the agent installation. You can suppress the license agreement prompt by including the --acceptLicence parameter. The inclusion of the option indicates that you have read and accepted the terms stated in the license. To view the license agreement, open <server-root>/legal-notices/license.txt.

Enter the path to the configuration directory of the server instance for the WebSphere node. For example, /path/to/WebSphere/AppServer/profiles/AppServ01/config/cells/DefaultCell01/nodes/DefaultNode01/servers/server1.

To balance agent connections to an AM site, configure the URL of the load balancer in front of the AM site.

Note

If your environment has a reverse proxy configured between AM and the agent, set the AM URL to the proxy URL instead. For example, https://proxy.example.com:443/openam. For more information about setting up the environment for reverse proxies, see "Configuring Apache HTTP Server as a Reverse Proxy Example".

Upon successful completion, the installer updates the WebSphere configuration, copies the agent libraries to WebSphere's external library directory, and also sets up configuration and log directories for the agent.

Take note of the configuration files and log locations.

Each agent instance that you install on the system has its own numbered configuration and logs directory. The first agent's configuration and logs are thus located under the directory java_agents/websphere_agent/Agent_001/:

config/OpenSSOAgentBootstrap.properties

Used to bootstrap the Java agent, allowing the agent to connect to AM and download its configuration.

config/OpenSSOAgentConfiguration.properties

Only used if you configured the Java agent to use local configuration.

logs/audit/

Operational audit log directory, only used if remote logging to AM is disabled.

To protect an application in the container, configure the agent filter.

(Optional) If you have a policy configured, you can test your agent installation. For example, try to browse to a resource that your agent protects. You should be redirected to AM to authenticate, for example, as user demo, password changeit. After you authenticate, AM then redirects you back to the resource you tried to access.

4.5.3. Installing the WebSphere Java Agent Silently

To install the WebSphere Java agent silently, you must create a response file containing the installation parameters that you will then provide to the agentadmin command.

To balance agent connections to an AM site, set the AM_SERVER_URL variable as the URL of the load balancer in front of the AM site.

Note

If your environment has a reverse proxy configured between AM and the agent, set the AM URL to the proxy URL instead. For example, https://proxy.example.com:443/openam. For more information about setting up the environment for reverse proxies, see "Configuring Apache HTTP Server as a Reverse Proxy Example".

You can also create this file automatically when installing the Java agent by running the agentadmin command with the --saveResponse option. For example:

$ agentadmin --install --saveResponse response-file

Complete the following procedure to install the WebSphere Java agent silently:

To Complete Pre-Installation Tasks

Perform the following steps to create the configuration required by the Java agent before installing it:

Configure AM to protect the cross-domain single sign-on (CDSSO) session cookie from hijacking. For more information, see Implementing Cross-Domain Single Sign-On in the ForgeRock Access Management Authentication and Single Sign-On Guide.

To protect an application in the container, configure the agent filter.

(Optional) If you have a policy configured, you can test your agent installation. For example, try to browse to a resource that your agent protects. You should be redirected to AM to authenticate, for example, as user demo, password changeit. After you authenticate, AM then redirects you back to the resource you tried to access.

4.5.4. Notes About WebSphere Network Deployment

When using WebSphere Application Server Network Deployment, you must install WebSphere Java agents on the Deployment Manager, on each Node Agent, and on each Application Server. Installation requires that you stop and then restart the Deployment Manager, each Node Agent, and each Application Server in the Network Deployment.

Before installation, synchronize each server configuration with the profile saved by the Deployment Manager using the syncNode command. After agent installation, copy the server configuration for each node stored in server.xml to the corresponding Deployment Manager profile. After you have synchronized the configurations, you must restart the Deployment Manager for the Network Deployment.

Chapter 5. Post-Installation Tasks

This chapter covers tasks to perform after installing Java agents in your environment. The following table contains a list of the tasks:

Task

Section

Configure the agent filter and mode of operation. You must configure the agent filter to protect your applications

On the Global tab, change the mode in the Agent Filter Mode (com.sun.identity.agents.config.filter.mode) property:

To set the global filter mode, enter the mode name in the Value field, for example SSO_ONLY, and then click Add.

To override the filter mode for a particular context path, enter the name of the context path in the Key field, for example BankApp, enter the mode name in the Value field, for example URL_POLICY, and then click Add.

Setting the Agent Filter Mode

Save your changes.

5.2. Configuring Audit Logging

Java agents support logging audit events for security, troubleshooting, and regulatory compliance. You can store agent audit event logs in the following ways:

Remotely. Log audit events to the audit event handler configured in the AM realm. In a site comprised of several AM servers, Java agents write audit logs to the AM server that satisfies the agent's request for client authentication or resource authorization.

Java agents cannot log audit events remotely if:

AM's Audit Logging Service is disabled.

No audit event handler is configured in the realm where the agent is configured.

All audit event handlers configured in the realm where the agent is configured are disabled.

For more information about audit logging in AM, see the chapter Setting Up Audit Logging in the ForgeRock Access Management Setup and Maintenance Guide.

Note

Local audit logs do not have an _id attribute, which is an internal AM id.

The audit log format adheres to the log structure shared across the ForgeRock Identity Platform. For more information about the audit log format, see the section Audit Logging File Format in the ForgeRock Access Management Setup and Maintenance Guide.

In the Audit Access Type property (com.sun.identity.agents.config.audit.accesstype), select the type of messages to log. For example, select LOG_ALL to log access allowed and access denied events.

In the Audit Log Location property (com.sun.identity.agents.config.log.disposition), select whether to write the audit logs locally to the agent installation (LOCAL), remotely to AM (REMOTE), or to both places (ALL). For example, keep REMOTE to log audit events to the AM instances.

(Optional) If you chose to log audit messages locally, enable the Rotate Local Audit Log property (com.sun.identity.agents.config.local.log.rotate) to rotate the audit log files upon reaching a maximum size.

(Optional) If you enabled the Rotate Local Audit Log property (com.sun.identity.agents.config.local.log.size), specify the maximum size of the audit log files in the Local Audit Log Rotation Size property.

5.3. Configuring Performance Monitoring

This section covers how to monitor the performance of Java agents.

You can monitor the performance of agents through the following interfaces:

Prometheus Monitoring

Prometheus is third-party software used for gathering and processing monitoring data.

You can configure Java agents to expose an endpoint which Prometheus scrapes to obtain performance metrics from your protected applications.

Configure Prometheus to monitor the metrics endpoint exposed by the agent by using the prometheus.yml configuration file. For more information on configuring Prometheus, see the Prometheus configuration documentation.

Tip

Prometheus provides monitoring and processing for the information provided by Java agents, but further analysis and visualization may be desired. In this case, you can use tools such as Grafana to create customized charts and graphs based on the information collected by Prometheus.

Common REST and Prometheus performance metrics are provided by an endpoint configured in the protected application's web.xml file. The endpoint must be accessible to the REST client or Prometheus server that will be making use of the performance data.

To configure an agent instance to expose the endpoint for metrics, perform the following steps:

For each protected application that will expose metrics, edit the application's web.xml file.

5.4. Configuring Java Agents for SSL Communication

For security reasons, your environment may require that your Java agents communicate with AM over SSL. To configure the agents, perform the steps in the following procedure:

To Configure Java Agents for SSL Communication

Import a CA certificate in the JDK truststore, usually $JAVA_HOME/jre/lib/security/cacerts. The certificate should be either the same one configured for SSL purposes in the container where AM is installed, or one signed with the same CA root certificate. For example:

Note

For backward-compatibility purposes, you can also provide the truststore and the password to the agent by specifying them as Java properties in the container's start-up sequence. For example, add them to Tomcat's $CATALINA_OPS variable instead of specifying them in the OpenSSOAgentBootstrap.properties file:

When your environment has reverse proxies or load balancers configured between the agents and the clients, you must perform additional configuration in the agents to account for the anonymization of both the clients and the agents.

Failure to do so may cause policy evaluation and other agent features to fail.

For example, to remove an old Tomcat Java agent, see "Removing the Tomcat Java Agent". If the uninstall process has changed, refer to the version of the Java Agent Guide that corresponds to your Java agent.

The installer creates new OpenSSOAgentConfiguration.properties and OpenSSOAgentBootstrap.properties files containing adequate properties for the particular agent version.

Review the agent configuration:

If the agent configuration is stored in the AM configuration store, review the Release Notes and the ForgeRock Access Management Release Notes to check what is new and possible changes to AM and the agent. Then, adjust the agent configuration if required using the AM console.

If the agent configuration is stored locally, review the OpenSSOAgentConfiguration.properties file. Use the backed-up copy of the configuration file for guidance, and the Release Notes and the ForgeRock Access Management Release Notes to check what is new and possible changes to AM and the agent. Then, update the file manually to contain the properties required for your environment.

The OpenSSOAgentBootstrap.properties file created by the installer already contain bootstrap properties relevant to the new version of the agent.

7.1. Removing the Tomcat Java Agent

Run the agentadmin command with the --listAgents option to output a list of installed agent instances. For example:

$ agentadmin --listAgents
The following agents are configured on this Application Server.
The following are the details for agent Agent_001 :-
Tomcat Server Config Directory: /path/to/apache-tomcat/conf

Make a note of the agent configuration details of the instance you want to remove.

Run the agentadmin command with the --uninstall option.

$ agentadmin --uninstall

Enter the path of the Tomcat installation directory. For example, /path/to/apache-tomcat/conf.

Enter the complete path to the directory which is used by Tomcat Server to
store its configuration Files. This directory uniquely identifies the
Tomcat Server instance that is secured by this Agent.
[ ? : Help, ! : Exit ]
Enter the Tomcat Server Config Directory Path
[/opt/apache-tomcat-6.0.14/conf]: /path/to/apache-tomcat/conf

Review a summary of your responses and select an action to continue: uninstall, go back a step, start over, or exit:

7.2. Removing the JBoss Java Agent

Run the agentadmin command with the --listAgents option to output a list of installed agent instances. For example:

$ agentadmin --listAgents
The following agents are configured on this Application Server.
The following are the details for agent Agent_001 :-
JBoss home directory: /path/to/jboss
JBoss domain profile name: null
JBoss deployment mode: standalone

Make a note of the agent configuration details of the instance you want to remove.

Run the agentadmin command with the --uninstall option.

$ agentadmin --uninstall

Enter the path to the JBoss installation directory. For example, /path/to/jboss.

Enter the complete path to the home directory of the JBoss instance.
[ ? : Help, ! : Exit ]
Enter the path to the JBoss installation: /path/to/jboss

Enter the deployment mode of the JBoss installation to uninstall. Possible values are domain or standalone.

Enter the name of the deployment mode of the JBoss installation that you wish
to use with this agent. Supported values are: domain, standalone.
[ ? : Help, < : Back, ! : Exit ]
Enter the deployment mode of JBoss [standalone]: standalone

Review a summary of your responses and select an action to continue: uninstall, go back a step, start over, or exit:

7.3. Removing the Jetty Java Agent

Run the agentadmin command with the --listAgents options to output a list of installed agent instances. For example:

$ ./agentadmin --listAgents
The following agents are configured on this Application Server.
The following are the details for agent Agent_001 :-
Jetty Server Config Directory:
/path/to/jetty/etc

Make a note of the agent configuration details of the instance you want to remove.

Run the agentadmin command with the --uninstall option.

$ agentadmin --uninstall

Enter the path of the Jetty configuration directory. For example, /path/to/jetty/etc.

Enter the complete path to the directory which is used by Jetty Server to store
its configuration Files. This directory uniquely identifies the Jetty
Server instance that is secured by this Agent.
[ ? : Help, ! : Exit ]
Enter the Jetty Server Config Directory Path [/opt/jetty/etc]: /path/to/jetty/etc

Review a summary of your responses and select an action to continue: uninstall, go back a step, start over, or exit:

7.4. Removing the WebLogic Java Agent

Run the agentadmin with the --listAgents option to output a list of installed agent instances. For example:

The following agents are configured on this Application Server.
The following are the details for agent Agent_001 :-
WebLogic Server instance name: AdminServer
Startup script location:
/Oracle_Home/user_projects/domains/base_domain/startWebLogic.sh

Make a note of the agent configuration details of the instance you want to remove.

Run the agentadmin with the --uninstall option.

$ agentadmin --uninstall

Enter the path to the startWebLogic.sh file of the WebLogic domain where you want to install the agent. For example, /Oracle_Home/user_projects/domains/base_domain/startWebLogic.sh.

Enter the path to the location of the script used to start the WebLogic domain.
Please ensure that the agent is first installed on the admin server instance
before installing on any managed server instance.
[ ? : Help, ! : Exit ]
Enter the Startup script location
[/usr/local/bea/user_projects/domains/base_domain/startWebLogic.sh]: /Oracle_Home/user_projects/domains/base_domain/startWebLogic.sh

7.5. Removing the WebSphere Java Agent

Run the agentadmin command with the --listAgents option to output a list of installed agent instances. For example:

The following agents are configured on this Application Server.
The following are the details for agent Agent_001 :-
WebSphere Install Root Directory: /path/to/WebSphere/AppServer
Instance Server name: server1
Instance Config Directory:
/path/to/WebSphere/AppServer/profiles/AppServ01/config/cells/DefaultCell01/nodes/DefaultNode01/servers/server1

Make a note of the agent configuration details of the instance you want to remove.

Run the agentadmin command with the --uninstall option:

$ agentadmin --uninstall

Enter the path to the configuration directory of the server instance for the WebSphere node. For example, /path/to/WebSphere/AppServer/profiles/AppServ01/config/cells/DefaultCell01/nodes/DefaultNode01/servers/server1.

Chapter 8. Troubleshooting

This chapter offers solutions to issues that may occur during installation of AM Java agents.

Solutions to Common Issues

Q:

I am trying to install a Java agent, connecting to AM over HTTPS, and seeing the following error:

AM server URL: https://openam.example.com:8443/openam
WARNING: Unable to connect to OpenAM server URL. Please specify the
correct OpenAM server URL by hitting the Back button (<) or if the OpenAM
server URL is not started and you want to start it later, please proceed with
the installation.
If OpenAM server is SSL enabled and the root CA certificate for the OpenAM
server certificate has been not imported into installer JVMs key store (see
installer-logs/debug/Agent.log for detailed exception), import the root
CA certificate and restart the installer; or continue installation without
verifying OpenAM server URL.

What should I do?

A:

The Java platform includes certificates from many certificate authorities (CAs). If, however, you run your own CA, or you use self-signed certificates for HTTPS on the web application container where you run AM, then the agentadmin command cannot trust the certificate presented during connection to AM, and so cannot complete installation correctly.

After setting up the web application container where you run AM to use HTTPS, get the certificate to trust in a certificate file. The certificate you want is that of the CA who signed the container certificate, or the certificate itself if the container certificate is self-signed.

Copy the certificate file to the system where you plan to install the Java agent. Import the certificate into a trust store that you will use during Java agent installation. If you import the certificate into the default trust store for the Java platform, then the agentadmin command can recognize it without additional configuration.

Export and import of self-signed certificates is demonstrated in the ForgeRock Access Management Install Guide section Using Self-Signed Certificates.

Q:

I am trying to install the WebSphere Java agent on Linux. The system has IBM Java. When I run agentadmin --install, the script fails to encrypt the password from the password file, ending with this message:

In this case, the redirection loop happens because the client-based (stateless) session cookie is surpassing the maximum supported browser header size. Since the cookie is incomplete, AM cannot validate it.

To ensure the session cookie does not surpass the browser supported size, configure either signing and compression or encryption and compression.

I have upgraded my agent and I see the following message in the Java agent log:

redirect_uri_mismatch. The redirection URI provided does not match a pre-registered value.

What should I do?

A:

Java agents 5.6 only accept requests sent to the URL specified by the Agent Root URL for CDSSO property. For example, http://agent.example.com:8080/.

As a security measure, Java agents prevent you from accessing the agent on URLs not defined in the Agent Root URL for CDSSO property. Add entries to this property when:

Configuring the Alternative Agent Protocol (com.sun.identity.agents.config.agent.protocol) property to access the agent through different protocols. For example, http://agent.example.com/ and https://agent.example.com/.

Configuring the Alternative Agent Host Name (com.sun.identity.agents.config.agent.host) property to access the agent through different virtual host names. For example, http://agent.example.com/ and http://internal.example.com/.

Configuring the Alternative Agent Port Name (com.sun.identity.agents.config.agent.port) property to access the agent through different ports. For example, http://agent.example.com/ and http://agent.example.com:8080/.

Q:

After installing a Java agent on WebSphere, accessing a URL for a folder in a protected application such as http://openam.example.com:9080/test/ results in Error 404: SRVE0190E: File not found: {0}, and redirection fails. What should I do to work around this problem?

A:

Perform the following steps to work around the problem, by setting the WebSphere custom property com.ibm.ws.webcontainer.invokeFiltersCompatibility=true:

Chapter 9. Reference

9.1. Configuring Java Agent Properties

When you create the agent profile, you can choose whether to store the agent configuration in AM's configuration store or locally to the agent installation [3]. This section covers centralized configuration, indicating the corresponding properties for use in a local configuration file where applicable. [4]

After changing properties specified as "Hot-swap: no", you must restart the container where the Java agent is installed for the changes to take effect.

9.1.1. Configuring Bootstrap Properties

These properties are set in the config/OpenSSOAgentBootstrap.properties file.

am.encryption.pwd

When using an encrypted password, set this to the encryption key used to encrypt the agent profile password.

com.iplanet.am.naming.url

This property does not apply to Java Agents 5.6.

com.iplanet.am.service.secret

When using a plain text password, set this to the password for the agent profile, and leave am.encryption.pwd blank.

When using an encrypted password, set this to the encrypted version of the password for the agent profile. Use the command ./agentadmin --encrypt agentInstancepasswordFile to get the encrypted version.

Default: not set

org.forgerock.agents.public.am.url

Specifies the full URL of AM when it is behind a proxy during the custom login redirection flow. For example, protocol://public_am_fqdn:port/openam.

Use this property both of the following points are true:

Your environment uses custom login pages (non-OIDC-compliant flows), and the custom login pages are not in the same domain as the agent.

Your custom login pages are in a network that can only access AM using a proxy, a firewall, or any other technology that remaps the AM URL to one accessible by the custom login pages.

Consider an example where the traffic between AM and the agent happens through the example-internal.com network, but the custom login pages are on the example-external.com domain. The traffic between the custom pages and AM is translated from am.example-internal.com into am.example-external.com.

You would configure https://am.example-external.com:8443/openam as the public AM URL.

The default value is a combination of the values of the com.iplanet.am.server.host, com.iplanet.am.server.port, com.iplanet.am.server.protocol, and com.iplanet.am.services.deploymentDescriptor properties.

com.iplanet.am.services.deploymentDescriptor

Specifies the URI under which AM is deployed, such as /openam.

Default: not set

com.iplanet.services.debug.directory

Specifies the full path of the directory where the Java agent writes debug log files.

For assigning the Java agent to a previously configured group in order to inherit selected properties from the group.

Password

Specifies the password used when creating the password file and when installing the Java agent.

If you change this password, you must modify manually the password of the bootstrap property com.iplanet.am.service.secret. For more information, see "Configuring Bootstrap Properties".

Status

Specifies the status of the agent configuration.

Agent Notification URL

This property does not apply to Java Agents 5.6, although it may appear in the AM console.

When creating an agent profile, the AM console configures a default value for this property to maintain compatibility with earlier versions of the Java agent. The default value can be safely removed.

Property: com.sun.identity.client.notification.url

Location of Agent Configuration Repository

Specifies whether the Java agent configuration runs in local or centralized mode. For background information on these modes, see "Configuration Location".

To configure local mode, make sure the com.sun.identity.agents.config.repository.location=local is in the bootstrap properties file.

Note

At startup, the agent always reads the bootstrap properties file, and then the configuration properties file [5]. The agent's behavior then depends entirely on the value of the com.sun.identity.agents.config.repository.location property.

If the property is set to LOCAL, the agent will use all of the properties it has retrieved and continue working.

If the property is set to CENTRALIZED or is not defined at all, the agent will ignore all values from the configuration properties file, and while retaining the retrieved bootstrap properties, download its configuration from AM.

To revert to centralized mode, remove the com.sun.identity.agents.config.repository.location property in the bootstrap file, and then restart the agent's container.

Default: centralized

Property: com.sun.identity.agents.config.repository.location

Configuration Reload Interval

Specifies the time interval in seconds after which the Java agent reloads the agent profile. The behavior of this property is determined by the agent profile's configuration location:

Centralized configuration. The Java agent reloads the configuration from AM.

Local configuration. The Java agent reloads the configuration from the local files if the local files have been modified.

Tip

Notifications ensure that Java agents with centralized configuration reload the configuration when the administrator makes a change to a hot-swappable configuration property. Enable this property if notifications are disabled or if the Java agent stores its configuration locally.

Set the property to 0 to disable it.

Default: 0

Property: com.sun.identity.agents.config.load.interval

Hot-swap: yes

Agent Configuration Change Notification

Specifies whether AM sends a notification to the Java agent to reread the agent profile after a change to a hot-swappable property. This property only applies when you store the agent profile in AM's configuration data store.

Default: true

Property: com.sun.identity.agents.config.change.notification.enable

Hot-swap: no

Web Socket Connection Interval

Specifies the time in minutes after which Java agents reopen their WebSocket connection to AM. This property helps ensure a balanced distribution of connections across the AM servers on the site.

Specifies the name of the cookie that holds the OpenID Connect JSON web token (JWT) on the user's browser.

Before changing the name of this cookie, consider the following points:

This cookie is only used by the Java agent and is never presented to AM.

The name of this cookie must be unique across the set of cookies the user's browser receives, since some browsers behave in unexpected ways when receiving several cookies with the same name. For example, you should not set the JWT cookie name to iPlanetDirectoryPro, which is the default name of AM's session cookie.

Specifies whether the agent should convert SSO tokens (iPlanetDirectoryPro cookies) into OpenID Connect JWTs, to make them compliant with the agent's default login redirection mode.

Set this property when your end users access resources protected by both Java Agents 3.5.x (which use SSO tokens) and 5.x (which use OpenID Connect JWTs). Converting the SSO token to a JWT will ensure a seamless experience to the user without additional redirection or re-authentication.

When this property is enabled, the agent makes a request to AM to exchange the SSO token for a JWT.

Tip

The client application is responsible for appending the JWT to subsequent calls to protected resources. Failure to do so will cause the agent to request additional JWTs from AM.

Specifies how long to cache the results of exchanging an SSO token for a JWT, in minutes.

The returned JWT is cached against the relevant SSO token. If the same SSO token is presented in the future, but before the cache expires, the agent does not need to request a new JWT from AM. Instead, it retrieves the correct JWT from its cache.

Specifies the maximum number of entries allowed when caching the results of exchanging an SSO token for a JWT, in minutes.

If the maximum number of records is reached, the oldest records in the cache are overwritten.

Default: 100

Property: org.forgerock.agents.sso.exchange.cache.size

Agent Root URL for CDSSO

The Java agent root URL for CDSSO. The valid value is in the format protocol://hostname:port/ where protocol represents the protocol used, such as http or https, hostname represents the host name of the system where the Java agent resides, and port represents the port number on which the Java agent is installed. The slash following the port number is required.

If the server where the Java agent is installed has virtual host names, add URLs with the virtual host names to this list as well. AM checks that goto URLs match one of the Java agent root URLs for CDSSO.

Default: agent-root-URL

Property: sunIdentityServerDeviceKeyValue[n]

General Properties

Agent Filter Mode

Specifies the agent filter's mode of operation. The mode can be set to one of the following values:

Specifies the time interval, in minutes, the agent will wait before making a call to AM to refresh a the session's idle timeout.

Sessions in AM have an idle timeout after which they expire. In general, when users access protected resources through an agent, the agent requests a policy decision on behalf of that user, which resets the idle timeout.

When the agent does not need to reach out to AM frequently, for example, when policy evaluation is already cached, sessions may unexpectedly expire in AM due to idle timeout before the user has finished accessing the application.

Agents make one call per active user session at the end of the time interval, provided that the user is actively accessing the application or site. If the user does not access the application during the configured window interval time, the agent will not make the call to AM at the end of the interval. Eventually, if the user is inactive for enough time, AM will log them out when the session reaches its idle timeout.

Configuring the idle timeout window to a short value, such as one minute, achieves a good balance between making additional calls to AM and providing a good user experience.

Increase this value only if the performance impact of making an extra call to AM every minute is noticeable enough in your environment.

Default: 1

Property: org.forgerock.agents.idle.time.window.minutes

Hot-swap: yes

HTTP Session Binding

When enabled, the Java agent invalidates the HTTP session upon login failure, when the user has no SSO session, or when the principal user name does not match the SSO user name.

Default: true

Property: com.sun.identity.agents.config.httpsession.binding

Login Attempt Limit

When set to a value other than zero, this defines the maximum number of failed login attempts allowed during a single browser session, after which the Java agent blocks requests from the user.

Default: 0

Property: com.sun.identity.agents.config.login.attempt.limit

Custom Response Header

Specifies the custom headers the Java agent sets for the client. The key is the header name. The value is the header value. For example, com.sun.identity.agents.config.response.header[Cache-Control]=no-cache.

ALL. Log audit event messages to the audit event handler configured in the AM realm and locally to the agent installation.

Default: REMOTE

Property: com.sun.identity.agents.config.log.disposition

Hot-swap: yes

Remote Log File Name

This property does not apply to Java Agents 5.6, although it may appear in the AM console.

Property: com.sun.identity.agents.config.remote.logfile

Rotate Local Audit Log

When enabled, rotate local audit log files that have reached the size specified by the Local Audit Log Rotation Size property.

Default: false

Property: com.sun.identity.agents.config.local.log.rotate

Hot-swap: yes

Local Audit Log Rotation Size

Specifies the maximum size in bytes of the local audit log files. When audit log rotation is enabled, the Java agent rotates the log file when it reaches this size.

Default: 52428800

Property: com.sun.identity.agents.config.local.log.size

Hot-swap: yes

Fully Qualified Domain Name Checking Properties

FQDN Check

Enables checking of FQDN default value and FQDN map values.

Default: false

Property: com.sun.identity.agents.config.fqdn.check.enable

FQDN Default

FQDN users should use to access resources.

This property ensures that when users access protected resources on the web server without specifying the FQDN, the Java agent can redirect the users to URLs containing the correct FQDN.

Note

If you add any FQDN to this property, you must also add it to the Agent Root URL for CDSSO property.

Default: agent-root-URL

Property: com.sun.identity.agents.config.fqdn.default

FQDN Virtual Host Map

Maps virtual, invalid, or partial hostnames, and IP addresses to the FQDN to access protected resources. The property allows Java agents to redirect users to the FQDN and receive cookies belonging to the domain. It also ensures that invalid FQDN values that can cause the application server to become unusable or render resources inaccessible get properly mapped to the FQDN.

The property accepts an invalid_hostname and a validN Map Key value. The invalid_hostname maps an invalid or a partial hostname, or an IP address to a FQDN. The validN (where N = 1, 2, 3 ...) Map Key maps virtual hostnames to a FQDN.

For example, to map the partial hostname myserver to myserver.mydomain.example, enter myserver in the Map Key field, enter myserver.mydomain.example in the Corresponding Map Value field and then click Add. This corresponds to:

To address a server as xyz.hostname.com, when the actual name of the server is abc.hostname.com, enter valid1 in the Map Key field, enter xyz.hostname.example in the Corresponding Map Value field and then click Add. This corresponds to:

If you have multiple virtual servers rst.hostname.com, uvw.hostname.com, and xyz.hostname.com pointing to the same actual server abc.hostname.com and each virtual server has its own policies defined, the properties can be defined as:

Specifies the list of absolute URIs corresponding to a protected application's web.xmlform-login-page element, such as /myApp/jsp/login.jsp.

Default: not set

Property: com.sun.identity.agents.config.login.form

Login Error URI

Specifies the list of absolute URIs corresponding to a protected application's web.xmlform-error-page element, such as /myApp/jsp/error.jsp.

Default: not set

Property: com.sun.identity.agents.config.login.error.uri

Use Internal Login

When enabled, the Java agent uses the internal default content file for the login.

Default: true

Property: com.sun.identity.agents.config.login.use.internal

Login Content File Name

Full path name to the file containing custom login content when Use Internal Login is enabled.

Default: FormLoginContent.txt

Property: com.sun.identity.agents.config.login.content.file

Logout Processing Properties

Application Logout Handler

This property does not apply to Java Agents 5.6, although it may appear in the AM console.

Property: com.sun.identity.agents.config.logout.application.handler

Application Logout URI

Specifies request URIs that indicate logout events. The key is the web application name. The value is the application logout URI.

To set a global logout URI for applications without other logout URIs defined, leave the key empty and set the value to the global logout URI, /logout.jsp.

To set a logout URI for a specific application, set the key to the name of the application, and the value to the application logout page.

Default: not set

Property: com.sun.identity.agents.config.logout.uri

Logout Request Parameter

Specifies parameters in the HTTP request that indicate logout events. The key is the web application name. The value is the logout request parameter.

To set a global logout request parameter for applications without other logout request parameters defined, leave the key empty and set the value to the global logout request parameter, logoutparam.

To set a logout request parameter for a specific application, set the key to the name of the application, and the value to the application logout request parameter, such as logoutparam.

Default: not set

Property: com.sun.identity.agents.config.logout.request.param

Logout Introspect Enabled

When enabled, the Java agent checks the HTTP request body to locate the Logout Request Parameter you set.

Default: disabled

Property: com.sun.identity.agents.config.logout.introspect.enabled

Logout Entry URI

Specifies the URIs to return after successful logout and subsequent authentication. The key is the web application name. The value is the URI to return.

To set a global logout entry URI for applications without other logout entry URIs defined, leave the key empty and set the value to the global logout entry URI, /welcome.html.

To set a logout entry URI for a specific application, set the key to the name of the application, and the value to the application logout entry URI, such as /myApp/welcome.html.

Default: not set

Property: com.sun.identity.agents.config.logout.entry.uri

Access Denied URI Processing Properties

Resource Access Denied URI

Specifies the URIs of custom pages to return when access is denied. The key is the web application name. The value is the custom URI.

To set a global custom access denied URI for applications without other custom access denied URIs defined, leave the key empty and set the value to the global custom access denied URI, /sample/accessdenied.html.

To set a custom access denied URI for a specific application, set the key to the name of the application, and the value to the application access denied URI, such as /myApp/accessdenied.html.

Default: not set

Property: com.sun.identity.agents.config.access.denied.uri

Not-Enforced Processing Properties

Not-Enforced Compound Rules Separator

Specifies a delimiter for the not-enforced compound rules. The delimiter can be a single character or a string. For example, setting the delimiter to && allows compound rules to be specified as:

If the URI contains spaces or other reserved characters, you must percent-encode (often referred to as URL encoding) them. For example, /my%20public%20app/.

To fine-tune the not-enforced URI list, the Java agent supports inverting rules, and using regular expressions and wildcards. You can also filter based on HTTP methods, and cookie and header values:

Inverting Rules

Not-enforced URI rules can be inverted either by rule or by property:

By rule. Invert any rule in the Not-Enforced URIs property by preceding it with the keyword NOT, separated by a space (blank) character. In the following example, the agent will defer to AM any request of a .jpg file in the /private URI:

NOT /private/*.jpg

By property. Invert all the rules in the Not-Enforced URIs property by setting the Invert Not-Enforced URIs property to true.

For finer control over the filtering of not-enforced URI rules, you can create rules that use wildcards or regular expressions, and that filter HTTP methods, cookie values, and headers.

Wildcards

Not-Enforced URI rules support two types of wildcards:

The * wildcard matches all characters except the question mark ? character. It cannot be escaped, and spans multiple levels in a URI. For example:

/images/*
/*.jsp?locale=*

Multiple forward slashes do not match a single forward slash, so * matches mult/iple/dirs, yet mult/*/dirs does not match mult/dirs.

The -*- wildcard matches all characters except the forward slash / and the question mark ? character. It cannot be escaped. Because it does not match the / character, the -*- wildcard does not span multiple levels in a URI. For example:

/css/-*-

When using wildcards on not-enforced URI rules, consider the following points:

The use of the * and -*- wildcards in the same rule is not supported. However, you can use them in different rules in the same list. For example:

/css/-*-
/images/*

Multiple wildcards in the query parameter section of a not-enforced URI rule will match the parameters in any order that they might appear in a resource URI. For example:

/customers/*?*member_level=*location=*

The not-enforced URI rule above will apply to any resource URI that contains a member_level and location query parameter, in any order. In this example, the following requests would be not-enforced:

To use regular expressions in a not-enforced URI rule, add the keyword REGEX followed by a blank (space) character before the URI to match. For example:

REGEX https?://www\.example\.com/([^/])+/.*\.jpg

When using regular expressions in a not-enforced URI list, consider the following points:

The use of 'classic' wildcards and regular expressions in the same rule is not supported.

If an invalid regular expression is specified in a rule, the rule is dropped and an error message will show in the logs.

HTTP Methods

Specify not-enforced HTTP methods by adding one of the following keywords: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS, and TRACE.

By default, if no HTTP method is specified for a particular rule, all methods are not-enforced for that rule. For example, the following rule does not enforce every supported HTTP method for any file contained in /public:

/public/*

To specify which methods should not be enforced, add a comma-delimited list of methods followed by a blank (space) character before the URL to match. For example:

Methods can be inverted by adding an exclamation mark ! character in front of them. For example, all methods but POST are not enforced in the following example:

!POST /public/*

Unrecognized keywords in a rule are ignored and do not invalidate the rest of the rule.

Cookie Values

You can create not-enforced rules that only apply when the incoming request has a named cookie, with a specified value.

The syntax for specifying rules that apply to cookies with a specified value is as follows:

COOKIE(Name/Value/Modifiers) Not Enforced URIs

Where:

Name

Specifies the name of the cookie to inspect for the specified value.

The name of the cookie is case-sensitive.

Value

Specifies a string to look for in the value field of the specified cookie.

Modifiers

Specify one or more of the following optional modifiers to alter the method for looking up the value:

i

Perform a case-insensitive comparison.

r

Treat the string specified in Value as a regular expression.

For example, to allow access to all resources in /private/admin/images/ when there is a cookie named login_result (case-sensitive) present on the request that has a value VALID, ignoring case, specify a rule similar to the following:

COOKIE(login_result/VALID/i) /private/admin/images/*

You can combine cookie filters with other filters, such as HTTP methods.

For example, the following rule allows GET, POST, and PUT HTTP requests to HTML resources in the /other/records/ folder, providing that there is a cookie named internal (case-sensitive) present, and it has a value that matches the regular expression .*ID - that is; strings that end with ID - ignoring case:

GET,POST,COOKIE(internal/.*ID/ri),PUT /other/records/*.html

Note that combining a HEADER and COOKIE expression in the same rule implies a logical AND is applied, such that both expressions must match in order to apply. To apply the rules as a logical OR, create two separate rules.

Header Values

You can create not-enforced rules that only apply when the incoming request has a named header, with a specified value.

The syntax for specifying rules that apply to headers with a specified value is as follows:

HEADER(Name/Value/Modifiers) Not Enforced URIs

Where:

Name

Specifies the name of the header to inspect for the specified value.

The name of the header is not case-sensitive.

Value

Specifies a string to look for in the value field of the specified header.

Modifiers

Specify one or more of the following optional modifiers to alter the method for looking up the value:

i

Perform a case-insensitive string comparison.

r

Treat the string specified in Value as a regular expression.

For example, to allow access to all TXT files in /yearly/2019/ when there is a header named ID present on the request that has a value validated, ignoring case, specify a rule similar to the following:

HEADER(ID/validated/i) /yearly/2019/*.txt

You can combine cookie filters with other filters, such as HTTP methods.

For example, the following rule allows GET, POST, and PUT HTTP requests to HTML resources in the /other/records/ folder, providing that there is a header named internal present, and it has a value that matches the regular expression .*ID - that is; strings that end with ID - ignoring case:

GET,POST,HEADER(internal/.*ID/ri),PUT /other/records/*.html

Note that combining a HEADER and COOKIE expression in the same rule implies a logical AND is applied, such that both expressions must match in order to apply. To apply the rules as a logical OR, create two separate rules.

Compound Not-Enforced Rules

Compound not-enforced rules allow you to combine not-enforced URI and IP rules in a single rule. They can be configured either in the Not-Enforced URIs or the Not-Enforced Client IP List properties.

The format for compound rules requires the IP rule or list of IP rules, a delimiter, by default the horizontal line | character, and the URI rule or list of URI rules. Blank (space) characters around the delimiter are optional. For example:

192.168.1.1-192.168.4.3 | /images/*

In the example, the agent will not enforce any HTTP requests coming from the ip range 192.168.1.1-192.168.4.3 to any file (*) in the /images URI.

When configuring compound rules, consider the following points:

Keywords, such as HTTP methods, NOT, and REGEX, are required at the beginning of the compound rule, and affect both the IP and the URI rules. For example:

GET,POST 192.168.1.1-192.168.4.3 | /images/*

In the preceding example, the agent will not enforce GET and POST HTTP requests coming from the ip range 192.168.1.1-192.168.4.3 to any file (*) in the /images URI.

NOT,!POST 192.168.1.* | /private/*

In the preceding example, the agent will defer to AM (NOT keyword) any request done to all supported HTTP methods but POST (!) coming from any ip address in the 192.168.1 subnet to any file (*) in the /private URI.

When working with the REGEX keyword, ensure both sides of the rule can be parsed as a regular expression. For example:

POST,REGEX 192\.168\.10\.(10|\d) && \/images\/([^/])+\.*\.jpg

Note that the delimiter in the previous example is &&. This is because the | character can lead to invalid regular expressions. To configure a different delimiter, see the Not-Enforced Compound Rules Multi-Value Separator property in Not-Enforced Processing Properties.

When dealing with compound rules, the agent caches hits and misses for each resource accessed. IP and URI not-enforced lists have a property each to enable or disable their caches; for compound rules, caching is enabled if either the IP or URI not-enforced cache is enabled. The size of its cache has the size of the larger of the two IP or URI cache sizes.

When caching is enabled, this limits the number of not-enforced URIs cached.

Default: 10000

Property: com.sun.identity.agents.config.notenforced.uri.cache.size

Refresh Session Idle Time

When set to true, the agent resets the CTS-based session idle time when granting access to a not-enforced URI, prolonging the time before the user must authenticate again. This setting has no effect on users with client-based (stateless) sessions.

By rule. Invert any rule in the Not-Enforced Client IP List property by preceding it with the keyword NOT, separated by a space (blank) character. In the following example, the agent will defer to AM any request from the network specified by the 192.168.1.0/24 CIDR notation:

NOT 192.168.1.0/24

By property. Invert all the rules in the Not-Enforced Client IP List property by setting the Not-Enforced IP Invert List to true.

Wildcards, Regular Expressions, and HTTP Methods

For finer control over the filtering of not-enforced IP rules, use wildcards, regular expressions, HTTP methods, cookie values, and headers:

Wildcards

The * wildcard matches all characters except the question mark ? character, and cannot be escaped. For example:

To use regular expressions in a not-enforced IP rule, add the keyword REGEX followed by a blank (space) character before the URI to match. For example:

REGEX 192\.168\.10\.\d+

When using regular expressions in a not-enforced IP list, consider the following points:

The use of wildcards and regular expressions in the same rule is not supported.

The use of netmask CIDR notation or ip address ranges and regular expressions is not supported. However, you can create a regular expression that matches a range of IP addresses, such as:

REGEX 192\.168\.10\.(10|\d)

If an invalid regular expression is specified in a rule, the rule is dropped and an error message will show in the logs.

HTTP Methods

Specify not-enforced HTTP methods by adding one of the following keywords: GET,HEAD, POST, PUT, PATCH, DELETE, OPTIONS, and TRACE.

By default, if no HTTP method is specified for a particular rule, all methods are not-enforced for that rule. For example, the following rule does not enforce every supported HTTP method for the ips specified by 192.168.10.*:

192.168.10.*

To specify which methods should not be not-enforced, add a comma-delimited list of methods followed by a blank (space) character before the URL to match. For example:

Methods can be inverted by adding an exclamation point ! character in front of them. For example, all methods but POST are enforced in the following example:

!POST 192.168.1.0/24

Unrecognized keywords in a rule are ignored and do not invalidate the rest of the rule.

Cookie Values

You can create not-enforced rules that only apply when the incoming request has a named cookie, with a specified value.

The syntax for specifying rules that apply to cookies with a specified value is as follows:

COOKIE(Name/Value/Modifiers) Not Enforced IPs

Where:

Name

Specifies the name of the cookie to inspect for the specified value.

The name of the cookie is case-sensitive.

Value

Specifies a string to look for in the value field of the specified cookie.

Modifiers

Specify one or more of the following optional modifiers to alter the method for looking up the value:

i

Perform a case-insensitive comparison.

r

Treat the string specified in Value as a regular expression.

For example, to allow access from 192.168.* when there is a cookie named login_result (case-sensitive) present on the request that has a value VALID, ignoring case, specify a rule similar to the following:

COOKIE(login_result/VALID/i) 192.168.*

You can combine cookie filters with other filters, such as HTTP methods.

For example, the following rule allows GET, POST, and PUT HTTP requests from the client IP range 192.168.*, providing that there is a cookie named internal (case-sensitive) present, and it has a value that matches the regular expression .*ID - that is; strings that end with ID - ignoring case:

GET,POST,COOKIE(internal/.*ID/ri),PUT 192.168.*

Note that combining a HEADER and COOKIE expression in the same rule implies a logical AND is applied, such that both expressions must match in order to apply. To apply the rules as a logical OR, create two separate rules.

Header Values

You can create not-enforced rules that only apply when the incoming request has a named header, with a specified value.

The syntax for specifying rules that apply to headers with a specified value is as follows:

HEADER(Name/Value/Modifiers) Not Enforced IPs

Where:

Name

Specifies the name of the header to inspect for the specified value.

The name of the header is not case-sensitive.

Value

Specifies a string to look for in the value field of the specified header.

Modifiers

Specify one or more of the following optional modifiers to alter the method for looking up the value:

i

Perform a case-insensitive string comparison.

r

Treat the string specified in Value as a regular expression.

For example, to allow access to the IP range 192.168.* when there is a header named ID present on the request that has a value validated, ignoring case, specify a rule similar to the following:

HEADER(ID/validated/i) 192.168.*

You can combine cookie filters with other filters, such as HTTP methods.

For example, the following rule allows GET, POST, and PUT HTTP requests from the IP address range 192.168.*, providing that there is a header named internal present, and it has a value that matches the regular expression .*ID - that is; strings that end with ID - ignoring case:

GET,POST,HEADER(internal/.*ID/ri),PUT 192.168.*

Note that combining a HEADER and COOKIE expression in the same rule implies a logical AND is applied, such that both expressions must match in order to apply. To apply the rules as a logical OR, create two separate rules.

Compound Not-Enforced Rules

Compound not-enforced rules allow you to combine not-enforced URI and IP rules in a single rule. They can be configured either in the Not-Enforced URIs or the Not-Enforced Client IP List properties.

The format for compound rules requires the IP rule or list of IP rules, a delimiter, by default the horizontal line | character, and the URI rule or list of URI rules. Blank (space) characters around the delimiter are optional. For example:

192.168.1.1-192.168.4.3 | /images/*

In the example, the agent will not enforce any HTTP requests coming from the ip range 192.168.1.1-192.168.4.3 to any file (*) in the /images URI.

When configuring compound rules, consider the following points:

Keywords, such as HTTP methods, NOT, and REGEX, are required at the beginning of the compound rule, and affect both the IP and the URI rules. For example:

GET,POST 192.168.1.1-192.168.4.3 | /images/*

In the preceding example, the agent will not enforce GET and POST HTTP requests coming from the ip range 192.168.1.1-192.168.4.3 to any file (*) in the /images URI.

NOT,!POST 192.168.1.* | /private/*

In the preceding example, the agent will defer to AM (NOT keyword) any request done to all supported HTTP methods but POST (!) coming from any ip address in the 192.168.1 subnet to any file (*) in the /private URI.

When working with the REGEX keyword, ensure both sides of the rule can be parsed as a regular expression. For example:

POST,REGEX 192\.168\.10\.(10|\d) && \/images\/([^/])+\.*\.jpg

Note that the delimiter in the previous example is &&. This is because the | character can lead to invalid regular expressions. To configure a different delimiter, see the Not-Enforced Compound Rules Multi-Value Separator property in Not-Enforced Processing Properties.

When dealing with compound rules, the agent caches hits and misses for each resource accessed. IP and URI not-enforced lists have a property each to enable or disable their caches; for compound rules, caching is enabled if either the IP or URI not-enforced cache is enabled. The size of its cache has the size of the larger of the two IP or URI cache sizes.

When caching is enabled, this limits the number of not-enforced addresses cached.

Default: 10000

Property: com.sun.identity.agents.config.notenforced.ip.cache.size

Profile Attributes Processing Properties

Profile Attribute Fetch Mode

When set to HTTP_COOKIE or HTTP_HEADER, profile attributes are introduced into the cookie or the headers, respectively. When set to REQUEST_ATTRIBUTE, profile attributes are part of the HTTP request.

Property: com.sun.identity.agents.config.profile.attribute.fetch.mode

Profile Attribute Mapping

Maps the profile attributes to HTTP headers for the currently authenticated user. Map Keys are attribute names, and Map Values are HTTP header names. The user profile can be stored in LDAP or any other arbitrary data store.

To populate the value of profile attribute CN under CUSTOM-Common-Name: enter CN in the Map Key field, and enter CUSTOM-Common-Name in the Corresponding Map Value field. This corresponds to com.sun.identity.agents.config.profile.attribute.mapping[cn]=CUSTOM-Common-Name.

In most cases, in a destination application where an HTTP header name shows up as a request header, it is prefixed by HTTP_, lower case letters become upper case, and hyphens (-) become underscores (_). For example, common-name becomes HTTP_COMMON_NAME.

Property: com.sun.identity.agents.config.profile.attribute.mapping

Response Attributes Processing Properties

Response Attribute Fetch Mode

When set to HTTP_COOKIE or HTTP_HEADER, response attributes are introduced into the cookie or the headers, respectively. When set to REQUEST_ATTRIBUTE, response attributes are part of the HTTP request.

Maps the policy response attributes to HTTP headers for the currently authenticated user. The response attribute is the attribute in the policy response to be fetched.

To populate the value of response attribute uid under CUSTOM-User-Name: enter uid in the Map Key field, and enter CUSTOM-User-Name in the Corresponding Map Value field. This corresponds to com.sun.identity.agents.config.response.attribute.mapping[uid]=Custom-User-Name.

In most cases, in a destination application where an HTTP header name shows up as a request header, it is prefixed by HTTP_, lower case letters become upper case, and hyphens (-) become underscores (_). For example, response-attr-one becomes HTTP_RESPONSE_ATTR_ONE.

Property: com.sun.identity.agents.config.response.attribute.mapping

Common Attributes Fetching Processing Properties

Cookie Separator Character

Specifies the separator for multiple values of the same attribute when it is set as a cookie.

Default: |

Property: com.sun.identity.agents.config.attribute.cookie.separator

Fetch Attribute Date Format

Specifies the java.text.SimpleDateFormat of date attribute values used when an attribute is set in an HTTP header.

Default: EEE, d MMM yyyy hh:mm:ss z.

Property: com.sun.identity.agents.config.attribute.date.format

Attribute Cookie Encode

When enabled, attribute values are URL-encoded before being set as a cookie.

Default: true

Property: com.sun.identity.agents.config.attribute.cookie.encode

Session Attributes Processing Properties

Session Attribute Fetch Mode

When set to HTTP_COOKIE or HTTP_HEADER, session attributes are introduced into the cookie or the headers, respectively. When set to REQUEST_ATTRIBUTE, session attributes are part of the HTTP request.

Property: com.sun.identity.agents.config.session.attribute.fetch.mode

Session Attribute Mapping

Maps session attributes to HTTP headers for the currently authenticated user. The session attribute is the attribute in the session to be fetched.

To populate the value of session attribute UserToken under CUSTOM-userid: enter UserToken in the Map Key field, and enter CUSTOM-userid in the Corresponding Map Value field. This corresponds to com.sun.identity.agents.config.session.attribute.mapping[UserToken]=CUSTOM-userid.

In most cases, in a destination application where an HTTP header name shows up as a request header, it is prefixed by HTTP_, lower case letters become upper case, and hyphens (-) become underscores (_). For example, success-url becomes HTTP_SUCCESS_URL.

Property: com.sun.identity.agents.config.session.attribute.mapping

Privilege Attributes Processing Properties

The following properties do not apply to Java Agents 5.6, although they may appear in the AM console:

Specifies a list of query parameters to be removed from a URL for policy decision and caching purposes. The property has the format [Domain/path] | parameter[,parameter...] with no spaces between values. Specify values as follows:

Domain/path

Specifies the incoming request URL. It can take the following values:

A domain. For example, example.com.

When you specify a domain, Java agents match both the domain itself and its subdomains. For example, example.com matches mydomain.example.com and www.example.com.

Domains can also include path information, for example, example.com/market, but cannot specify ports.

A subdomain. For example, mydomain.example.com.

When you specify a subdomain, Java agents match the domain, the subdomain, and any sub-subdomain. For example, mydomain.example.com matches true.mydomain.example.com, too.

Subdomains can include path information, for example, mydomain.example.com/secure, but cannot specify ports.

A path. For example, /myapp.

No value, in which case nothing is specified before the | character and the rule applies to every incoming request.

Note

It is possible to specify both the Request-Header and Domain/path login formats in an incoming request via the agent properties. If both formats are specified, the Request-Header entries are applied first. If none of the headers in the incoming request match, the Domain/path entries will be applied.

parameter[,parameter...]

Specifies a comma-separated list of query parameters to remove from the incoming request URL.

Consider the following constraints when constructing the list of parameters:

Add a comma (,) character at the beginning or the end of the list to remove all unnamed parameters. For example, myapp.example.com/customers|,lang would match both lang and any unnamed parameters.

Add the asterisk (*) character to the list to remove all parameters, including unnamed ones.

The remaining parameters (those that do not match the list of parameters) are sorted alphabetically.

For example, an incoming URL request such as http://myapp.example.com/customers?country=uk&=bristol&lang=en_GB&area=1343456 that matches a rule such as myapp.example.com/customers|,lang, will be cached by the agent as http://myapp.example.com/customers?area=1343456&country=uk, where both lang and the unnamed parameter are removed and the rest of the parameters are sorted alphabetically.

Specifies a list of regular expressions the agent uses to match query parameters to be removed from a URL for policy decision and caching purposes. The property has the format [Domain/path] | regular_expression[,regular_expression...] with no spaces between values. Specify values as follows:

Domain/path

Specifies the incoming request URL. It can take the following values:

A domain. For example, example.com.

When you specify a domain, Java agents match both the domain itself and its subdomains. For example, example.com matches mydomain.example.com and www.example.com.

Domains can also include path information, for example, example.com/market, but cannot specify ports.

A subdomain. For example, mydomain.example.com.

When you specify a subdomain, Java agents match the domain, the subdomain, and any sub-subdomain. For example, mydomain.example.com matches true.mydomain.example.com, too.

Subdomains can include path information, for example, mydomain.example.com/secure, but cannot specify ports.

A path. For example, /myapp.

No value, in which case nothing is specified before the | character and the rule applies to every incoming request.

Note

It is possible to specify both the Request-Header and Domain/path login formats in an incoming request via the agent properties. If both formats are specified, the Request-Header entries are applied first. If none of the headers in the incoming request match, the Domain/path entries will be applied.

regular_expression[,regular_expression...]

Specifies a comma-separated list of regular expressions the agent uses to match query parameters to be removed from the incoming request URL.

Consider the following constraints when constructing your list of regular expressions:

Add a comma (,) character at the beginning or the end of the list to remove all unnamed parameters. For example, myapp.example.com/customers|,lang would match both lang and any unnamed parameters.

For example, an incoming URL request such as http://myapp.example.com/customers?country=uk&=bristol&lang=en_GB&area=1343456 that matches a rule such as myapp.example.com/customers|,coun.*?, will be cached by the agent as http://myapp.example.com/customers?=bristol&lang=en_GB, where both country and unnamed parameter are removed and the remaining parameters are sorted alphabetically.

Specifies a list of query parameters to be retained for policy decision and caching purposes. The property has the format [Domain/path] | parameter[,parameter...] with no spaces between values. Specify values as follows:

Domain/path

Specifies the incoming request URL. It can take the following values:

A domain. For example, example.com.

When you specify a domain, Java agents match both the domain itself and its subdomains. For example, example.com matches mydomain.example.com and www.example.com.

Domains can also include path information, for example, example.com/market, but cannot specify ports.

A subdomain. For example, mydomain.example.com.

When you specify a subdomain, Java agents match the domain, the subdomain, and any sub-subdomain. For example, mydomain.example.com matches true.mydomain.example.com, too.

Subdomains can include path information, for example, mydomain.example.com/secure, but cannot specify ports.

A path. For example, /myapp.

No value, in which case nothing is specified before the | character and the rule applies to every incoming request.

Note

It is possible to specify both the Request-Header and Domain/path login formats in an incoming request via the agent properties. If both formats are specified, the Request-Header entries are applied first. If none of the headers in the incoming request match, the Domain/path entries will be applied.

parameter[,parameter...]

Specifies a comma-separated list of query parameters to retain from the incoming request URL.

Consider the following constraints when constructing the list of parameters:

Add a comma (,) character at the beginning or the end of the list to retain all unnamed parameters. For example, myapp.example.com/customers|,lang would match both lang and any unnamed parameters.

Add the asterisk (*) character to the list to retain all parameters, including unnamed ones.

The remaining parameters (those that match the list of parameters) are sorted alphabetically.

For example, an incoming URL request such as http://myapp.example.com/customers?country=uk&=bristol&lang=en_GB&area=1343456 that matches a rule such as myapp.example.com/customers|,lang, will be cached by the agent as http://myapp.example.com/customers?=bristol&lang=en_GB, where both lang and the unnamed parameter are retained and sorted alphabetically.

Specifies a list of regular expressions the agent uses to match query parameters to be retained for policy decision and caching purposes. The property has the format [Domain/path] | regular_expression[,regular_expression...] with no spaces between values. Specify values as follows:

Domain/path

Specifies the incoming request URL. It can take the following values:

A domain. For example, example.com.

When you specify a domain, Java agents match both the domain itself and its subdomains. For example, example.com matches mydomain.example.com and www.example.com.

Domains can also include path information, for example, example.com/market, but cannot specify ports.

A subdomain. For example, mydomain.example.com.

When you specify a subdomain, Java agents match the domain, the subdomain, and any sub-subdomain. For example, mydomain.example.com matches true.mydomain.example.com, too.

Subdomains can include path information, for example, mydomain.example.com/secure, but cannot specify ports.

A path. For example, /myapp.

No value, in which case nothing is specified before the | character and the rule applies to every incoming request.

Note

It is possible to specify both the Request-Header and Domain/path login formats in an incoming request via the agent properties. If both formats are specified, the Request-Header entries are applied first. If none of the headers in the incoming request match, the Domain/path entries will be applied.

regular_expression[,regular_expression...]

Specifies a comma-separated list of regular expressions the agent uses to match query parameters to be retained from the incoming request URL.

Consider the following constraints when constructing your list of regular expressions:

Add a comma (,) character at the beginning or the end of the list to retain all unnamed parameters. For example, myapp.example.com/customers|,lang would match both lang and any unnamed parameters.

For example, an incoming URL request such as http://myapp.example.com/customers?country=uk&=bristol&lang=en_GB&area=1343456 that matches a rule such as myapp.example.com/customers|,coun.*?, will be cached by the agent as http://myapp.example.com/customers?=bristol,country=uk, where both country and the unnamed parameter are retained and sorted alphabetically.

Important

The login URL has the format URL[?realm=realm_name?parameter1=value1&...], where:

URL is the custom login page to where the agent redirects the unauthenticated user.

[?realm=realm_name&parameter1=value1&...] specifies optional parameters that the agent will pass to the custom login page, for example, the AM realm where the user should log to.

You do not need to specify the realm in the login URL if any of the following conditions is true:

The custom login page itself sets the realm parameter, for example, because it lets the user choose it. In this case, you must ensure the custom login page always returns a realm parameter to the agent.

The realm that the agent is logging the user into has DNS aliases configured in AM.

AM logs the user into the realm whose DNS alias matches the incoming request URL. For example, an inbound request from the http://marketplace.example.com URL logs in the marketplace realm if the realm alias is set to marketplace.example.com.

The users should always log in to the Top Level Realm.

Even if you decide to specify the realm by default, this parameter can be overwritten by the custom login page if, for example, the user can choose the realm for authentication.

You can specify as many parameters your custom login pages require.

Example:

https://login.example.com/login.jsp?realm=marketplace&param1=value1

In some versions of AM you may be able to configure more than one value for this property, but only the first value is honored.

Important

When the agent redirects the user to the custom login page, it appends a goto parameter (as configured in the com.sun.identity.agents.config.redirect.param property) with the agent's CDSSO endpoint and a nonce parameter.

The following is an example of a redirection from the agent to a custom login page:

Note that the goto parameter is URL encoded. If the realm parameter is configured in the redirection rule, it is also appended to the goto parameter.

Once the user has logged in, the custom login page must redirect back to the agent. To avoid redirection loops and login failures, consider the following constraints:

You must ensure that the custom login page redirects back to the agent using the URL contained in the goto parameter, and that the request contains the nonce parameter.

You must set the realm parameter in the redirection request to the agent if the users should not log in to AM's Top Level Realm.

For example, you could use the realm specified in the redirection request from the agent to the custom login pages (if configured in the conditional redirection rule), or the custom login page can let the user chose to which realm authenticate to.

The following is an example of a redirection from a custom login page to the agent:

There is one exception; if the realm where the agent should log the user in to has DNS alias configured, AM will log in the user to the realm whose DNS alias matches the incoming request URL. For example, an inbound request from the http://marketplace.example.com URL will be logged in to the marketplace realm if the realm alias is set to marketplace.example.com, whether there is a realm parameter or not.

Default: AM_URL/AM_URI/UI/Login

Property: com.sun.identity.agents.config.login.url

Hot-swap: Yes

OpenAM Conditional Login URL

Conditionally redirect users based on the incoming request header or URL. If the incoming request URL matches a specified request header or domain name, the Java agent redirects the request to an specific URL. That specific URL can be an AM instance, site, or a different website.

Important

When redirecting incoming login requests to a custom login page, you must add it to either the not-enforced IP or URI lists.

If the FQDN Check property (com.sun.identity.agents.config.fqdn.check.enable) is enabled, the Java agent iterates through the list of URLs until it finds an appropriate redirect URL that matches the FQDN check values. Otherwise, the Java agent redirects the user to the URL configured in the conditional redirect rules.

Conditional redirects have the format [Request-Header:value|Domain/path]|[URL][?realm=value&module=value2&service=value3], with no spaces between values. Specify values in conditional redirects as follows:

Request-Header

Specifies the HTTP request header, which can take the following format:

A specific case-insensitive HTTP request header, followed by a colon ':', then its value without line breaks. For example, X-Source:LAN.

If the header is defined but with no value, then any value is acceptable. For example, X-realm1:.

The agent processes any rule in alphabetical order starting with header name, then header values in alphabetical order, and then request headers with zero-length values (i.e., no value).

Domain/path

Specifies the incoming request URL. It can take the following values:

A domain. For example, example.com.

When you specify a domain, Java agents match both the domain itself and its subdomains. For example, example.com matches mydomain.example.com and www.example.com.

Domains can also include path information, for example, example.com/market, but cannot specify ports.

A subdomain. For example, mydomain.example.com.

When you specify a subdomain, Java agents match the domain, the subdomain, and any sub-subdomain. For example, mydomain.example.com matches true.mydomain.example.com, too.

Subdomains can include path information, for example, mydomain.example.com/secure, but cannot specify ports.

A path. For example, /myapp.

No value, in which case nothing is specified before the | character and the rule applies to every incoming request.

Note

It is possible to specify both the Request-Header and Domain/path login formats in an incoming request via the agent properties. If both formats are specified, the Request-Header entries are applied first. If none of the headers in the incoming request match, the Domain/path entries will be applied.

URL

Specifies the URL to which redirect incoming login requests. The URL may be an AM instance, an AM site, or a website other than AM.

When redirecting to AM, specify the URL of an AM instance or site in the format protocol://FQDN[:port]/URI/oauth2/authorize, where the port is optional if it is 80 or 443. For example, https://openam.example.com/openam/oauth2/authorize.

When redirecting to a website other than AM, specify a URL in the format protocol://FQDN[:port]/URI, where the port is optional if it is 80 or 443. For example, https://myweb.example.com/authApp.

If the redirection URL is not specified, the Java agent redirects the request to the AM instance or site specified by the following bootstrap properties:

Specifies the AM realm into which the agent logs users. For example, ?realm=marketplace.

You do not need to specify the realm in the login URL if any of the following conditions is true:

The custom login page itself sets the realm parameter, for example, because it lets the user choose it. In this case, you must ensure the custom login page always returns a realm parameter to the agent.

The realm that the agent is logging the user into has DNS aliases configured in AM.

AM logs the user into the realm whose DNS alias matches the incoming request URL. For example, an inbound request from the http://marketplace.example.com URL logs in the marketplace realm if the realm alias is set to marketplace.example.com.

The users should always log in to the Top Level Realm.

Even if you decide to specify the realm by default, this parameter can be overwritten by the custom login page if, for example, the user can choose the realm for authentication.

&module=value2&service=value3&param1=value1...

Specifies parameters that can be added to the URL, such as:

module, which specifies the authentication module the user authenticates against. For example, ?module=myAuthModule.

service, which specifies an authentication chain or tree the user authenticates against. For example, ?service=myAuthChain.

Any other parameters your custom login pages require.

Chain parameters with an & character, for example, realm=value&service=value.

Important

Java agent requests contain a number of parameters required by AM's oauth2/authorize endpoint. You must ensure that the custom login page redirects back to the agent using the URL contained in the goto parameter, and that the request contains the following parameters:

Failure to maintain these parameters when redirecting to AM may cause unexpected problems, such as redirect loops.

You must also set the realm parameter in the redirection request made to the agent if users should not log in to AM's Top Level Realm.

For example, you could use the realm specified in the redirection request from the agent to the custom login pages (if configured in the conditional redirection rule), or the custom login page can let the user chose to which realm authenticate to, and then pass the realm parameter to the redirection to the agent.

There is one exception; if the realm where the agent should log in the user has DNS alias configured, AM will log in the user to the realm whose DNS alias matches the incoming request URL. For example, an inbound request from the http://marketplace.example.com URL will be logged in the marketplace realm if the realm alias is set to marketplace.example.com.

Examples using the Request-Header Format

The following examples use the request headers format to set redirection to the conditional login URL. The first example redirects the user only if the HTTP header contains the field X-Source with the value LAN. The second example redirects the user only if the HTTP header contains the field X-Source with the value extranet. The third example redirects the user if the HTTP header contains the field X-Realm1 with any value.

Important

Be careful when specifying request headers with no values as it may lead to unexpected results.

Rules are applied in alphabetical order of header name, then sub-sorted by alphabetical order of header value. Zero length value always sorts last. For example, if you specify a redirection with an X-Source header with value A and another redirection with the header X-Domain with no value, any incoming request with the X-Domain header triggers before the X-Source, due to alphabetical header precedence.

The following examples use the Domain/Path format to set redirection to the conditional login URL. The first example redirects the user if the parent domain is example.com. The second example redirects the user if the FQDN is myapp.domain.com. The third example redirects the user if the domain and path match sales.example.com/marketplace. The last example redirects the user for any incoming request.

Conditionally redirect users based on the incoming request header or URL. If the incoming request URL matches a specified request header or domain name, the Java agent redirects the request to an specific URL. That specific URL can be an AM instance, site, or a different website.

Important

When redirecting incoming login requests to a custom login page, you must add it to either the not-enforced IP or URI lists.

Use this property only if the AM Login URL (com.sun.identity.agents.config.login.url) is empty.

If the FQDN Check property (com.sun.identity.agents.config.fqdn.check.enable) is enabled, the Java agent iterates through the list of URLs until it finds an appropriate redirect URL that matches the FQDN check values. Otherwise, the Java agent redirects the user to the URL configured in the conditional redirect rules.

Conditional redirects have the format [Request-Header:value|Domain/path]|[URL?realm=value&parameter1=value1...], with no spaces between values. Specify values in conditional redirects as follows:

Request-Header

Specifies the HTTP request header, which can take the following format:

A specific case-insensitive HTTP request header, followed by a colon ':', then its value without line breaks. For example, X-Source:LAN.

If the header is defined but with no value, then any value is acceptable. For example, X-realm1:.

The agent processes any rule in alphabetical order starting with header name, then header values in alphabetical order, and then request headers with zero-length values (i.e., no value).

Domain/path

Specifies the incoming request URL. It can take the following values:

A domain. For example, example.com.

When you specify a domain, Java agents match both the domain itself and its subdomains. For example, example.com matches mydomain.example.com and www.example.com.

Domains can also include path information, for example, example.com/market, but cannot specify ports.

A subdomain. For example, mydomain.example.com.

When you specify a subdomain, Java agents match the domain, the subdomain, and any sub-subdomain. For example, mydomain.example.com matches true.mydomain.example.com, too.

Subdomains can include path information, for example, mydomain.example.com/secure, but cannot specify ports.

A path. For example, /myapp.

No value, in which case nothing is specified before the | character and the rule applies to every incoming request.

Note

It is possible to specify both the Request-Header and Domain/path login formats in an incoming request via the agent properties. If both formats are specified, the Request-Header entries are applied first. If none of the headers in the incoming request match, the Domain/path entries will be applied.

URL

Specifies the URL to which redirect incoming login requests. The URL may be an AM instance, an AM site, or a website other than AM.

Specify a URL in the format protocol://FQDN[:port]/URI, where the port is optional if it is 80 or 443. For example:

Specifies the AM realm into which the agent logs the users. For example, ?realm=marketplace.

When redirecting to AM's XUI, use an ampersand (&) character instead of a question mark (?) character. For example, https://openam.example.com:8443/openam/XUI/#login/&realm=marketplace

You do not need to specify the realm in the login URL if any of the following conditions is true:

The custom login page itself sets the realm parameter, for example, because it lets the user choose it. In this case, you must ensure the custom login page always returns a realm parameter to the agent.

The realm that the agent is logging the user into has DNS aliases configured in AM.

AM logs the user into the realm whose DNS alias matches the incoming request URL. For example, an inbound request from the http://marketplace.example.com URL logs in the marketplace realm if the realm alias is set to marketplace.example.com.

The users should always log in to the Top Level Realm.

Even if you decide to specify the realm by default, this parameter can be overwritten by the custom login page if, for example, the user can choose the realm for authentication.

&parameter1=value1...

Specifies parameters that can be added to the URL. You can add as many parameters as your custom login pages need.

Chain parameters with an & character, for example, realm=value&parameter1=value1&parameter2=value2.

Important

When the agent redirects the user to the custom login page, it appends a goto parameter (as configured in the com.sun.identity.agents.config.redirect.param property) with the agent's CDSSO endpoint and a nonce parameter.

The following is an example of a redirection from the agent to a custom login page:

Note that the goto parameter is URL encoded. If the realm parameter is configured in the redirection rule, it is also appended to the goto parameter.

Once the user has logged in, the custom login page must redirect back to the agent. To avoid redirection loops and login failures, consider the following constraints:

You must ensure that the custom login page redirects back to the agent using the URL contained in the goto parameter, and that the request contains the nonce parameter.

You must set the realm parameter in the redirection request to the agent if the users should not log in to AM's Top Level Realm.

For example, you could use the realm specified in the redirection request from the agent to the custom login pages (if configured in the conditional redirection rule), or the custom login page can let the user chose to which realm authenticate to.

The following is an example of a redirection from a custom login page to the agent:

There is one exception; if the realm where the agent should log the user in to has DNS alias configured, AM will log in the user to the realm whose DNS alias matches the incoming request URL. For example, an inbound request from the http://marketplace.example.com URL will be logged in to the marketplace realm if the realm alias is set to marketplace.example.com, whether there is a realm parameter or not.

Examples using the Request-Header Format

The following examples use the request headers format to set redirection to the custom login URL. The first example triggers only if the HTTP header contains the field X-Domain with the value A. The second example redirects the user if the HTTP header contains the field X-Domain with the any value.

Important

Be careful when specifying request headers with no values as it may lead to unexpected results.

Rules are applied in alphabetical order of header name, then sub-sorted by alphabetical order of header value. Zero length value always sorts last. For example, if you specify a redirection with an X-Source header with value A and another redirection with the header X-Domain with no value, any incoming request with the X-Domain header triggers before the X-Source, due to alphabetical header precedence.

The following examples use the Domain/Path format to set redirection to the custom login URL. The first example redirects the user if the parent domain is example.com. The second example redirects the user if the FQDN is myapp.domain.com. The third example redirects the user if the domain and path match sales.example.com/marketplace. The last example redirects the user for any incoming request.

This property does not apply to Java Agents 5.6, although it may appear in the AM console.

Property: com.sun.identity.agents.config.login.url.prioritized

Login URL Probe

This property does not apply to Java Agents 5.6, although it may appear in the AM console.

Property: com.sun.identity.agents.config.login.url.probe.enabled

Login URL Probe Timeout

This property does not apply to Java Agents 5.6, although it may appear in the AM console.

Property: com.sun.identity.agents.config.login.url.probe.timeout

Logout URL Properties

OpenAM Logout URL

This property does not apply to Java Agents 5.6, although it may appear in the AM console.

Property: com.sun.identity.agents.config.logout.url

OpenAM Conditional Logout URL

Conditionally redirect users based on the incoming request header or URL. If the incoming request URL matches a request header or specified domain name, the Java agent redirects the request to an specific URL. That specific URL can be an AM instance, site, or a different website.

If the FQDN Check property (com.sun.identity.agents.config.fqdn.check.enable) is enabled, the Java agent iterates through the list of URLs until it finds an appropriate redirect URL that matches the FQDN check values. Otherwise, the Java agent redirects the user to the URL configured in the conditional redirect rules.

Conditional redirects have the format [Requester-Header:value|Domain/path]|[URL][?realm=value], with no spaces between values. Specify values in conditional redirects as follows:

Request-Header

Specifies the HTTP request header, which can take the following format:

A specific case-insensitive HTTP request header, followed by a colon ':', then its value without line breaks. For example, X-Source:LAN.

The agent processes any rule in alphabetical order starting with header name, and then header values in alphabetical order.

Domain/path

Specifies the incoming request URL. It can take the following values:

A domain. For example, example.com.

When you specify a domain, Java agents match both the domain itself and its subdomains. For example, example.com matches mydomain.example.com and www.example.com.

Domains can also include path information, for example, example.com/market, but cannot specify ports.

A subdomain. For example, mydomain.example.com.

When you specify a subdomain, Java agents match the domain, the subdomain, and any sub-subdomain. For example, mydomain.example.com matches true.mydomain.example.com, too.

Subdomains can include path information, for example, mydomain.example.com/secure, but cannot specify ports.

A path. For example, /myapp.

No value, in which case nothing is specified before the | character and the rule applies to every incoming request.

Note

It is possible to specify both the Request-Header and Domain/path login formats in an incoming request via the agent properties. If both formats are specified, the Request-Header entries are applied first. If none of the headers in the incoming request match, the Domain/path entries will be applied.

URL

Specifies the URL to which redirect incoming logout requests. The URL may be an AM instance, an AM site, or a website other than AM.

When redirecting to AM, specify the URL of an AM instance or site in the format protocol://FQDN[:port]/URI/oauth2/authorize, where the port is optional if it is 80 or 443. For example, https://openam.example.com/openam/oauth2/authorize.

When redirecting to a website other than AM, specify a URL in the format protocol://FQDN[:port]/URI, where the port is optional if it is 80 or 443. For example, https://myweb.example.com/authApp.

If the redirection URL is not specified, the Java agent redirects the request to the AM instance or site specified by the following bootstrap properties:

Specifies the realm the user should log out from. For example, realm=marketplace.

The realm can also be specified in the URL. For example, if the user should log out from the /customers realm, construct the URL as https://openam.example.com/openam/oauth2/realms/root/realms/customers/authorize and do not add the realm parameter.

Examples using the Request-Header Format

The following examples use the request headers format to set redirection to the conditional logout URL. The first example redirects the user only if the HTTP header contains the field X-Source with the value LAN. The second example redirects the user only if the HTTP header contains the field X-Source with the value extranet.

The following examples use the Domain/Path format to set redirection to the conditional logout URL. The first example redirects the user if the parent domain is example.com. The second example redirects the user if the domain and path match sales.example.com/marketplace. The last example redirects the user for any incoming request.

Specifies the time interval in minutes after which an active session expires in the Java agent's cache. The session cache holds information about logged in users, such as session properties and profile attributes.

If the value is not set, the Java agent sets the property to five times the value of the com.sun.identity.agents.polling.interval property.

Specifies the name of the file containing the content to handle requests on the wrong port when port checking is enabled.

Default: PortCheckContent.txt

Property: com.sun.identity.agents.config.port.check.file

Port Check Setting

Specifies which ports correspond to which protocols. The Java agent uses the map when handling requests with invalid port numbers during port checking.

Default: 8080 http

Property: com.sun.identity.agents.config.port.check.setting

Bypass Principal List Properties

Bypass Principal List

This property does not apply to Java Agents 5.6, although it may appear in the AM console.

Property: com.sun.identity.agents.config.bypass.principal

Agent Password Encryptor Properties

Encryption Provider

Specifies the class the agent uses for encryption and decryption purposes, for example, org.forgerock.openam.shared.security.crypto.AESWrapEncryption.

Default: com.iplanet.services.util.JCEEncryption

Property: com.iplanet.security.encryptor

Ignore Path Info Properties

Ignore Path Info in Request URL

When enabled, strip the path information from the request URL while doing not-enforced list checks and URL policy evaluation. This property is designed to prevent a user from accessing a URI by appending the matching pattern in the policy or not-enforced list.

For example, if the not-enforced list includes /*.gif, then stripping path info from the request URL prevents access to http://host/index.html by using http://host/index.html?hack.gif.

Default: false

Property: com.sun.identity.agents.config.ignore.path.info

Deprecated Agent Properties

Goto Parameter Name

Allows you to rename the goto parameter. The Java agent appends the requested URL to the renamed parameter during redirection. Rename the parameter when your application requires a parameter other than goto.

Consider the following example:

com.sun.identity.agents.config.redirect.param=goto2

A valid redirection URL using the goto2 parameter may look similar to the following:

In this example, the URL appended to the goto2 parameter is the URL that the user tried to access when the Java agent redirected the request to the accessDenied.html page. Note that you configure the access denied page using the Access Denied URI Processing (com.sun.identity.agents.config.access.denied.uri) property.

Default: goto

Property: com.sun.identity.agents.config.redirect.param

Legacy User Agent Support Enable

When enabled, provide support for legacy browsers.

Default: false

Property: com.sun.identity.agents.config.legacy.support.enable

Legacy User Agent List

List of header values that identify legacy browsers. Entries can use the wildcard character, *.

If the Java agent is behind a proxy or load balancer, then the Java agent can get client IP and host name values from the proxy or load balancer. For proxies and load balancers that support providing the client IP and host name in HTTP headers, you can use the following properties.

When multiple proxies or load balancers sit in the request path, the header values can include a comma-separated list of values with the first value representing the client, as in client,next-proxy,first-proxy.

Client IP Address Header

HTTP header name that holds the IP address of the client.

If the Java agent is behind a proxy or load balancer, then the Java agent can get client IP address values from the proxy or load balancer. Use this property if the proxy or load balancer supports providing the IP address in an HTTP header.

Default: not set

Property: com.sun.identity.agents.config.client.ip.header

Client Hostname Header

HTTP header name that holds the hostname of the client.

If the Java agent is behind a proxy or load balancer, then the Java agent can get client host name values from the proxy or load balancer. Use this property if the proxy or load balancer supports providing the host name in an HTTP header.

When multiple proxies or load balancers sit in the request path, the header values can include a comma-separated list of values with the first value representing the client, as in client,next-proxy,first-proxy.

Default: not set

Property: com.sun.identity.agents.config.client.hostname.header

Web Service Processing Properties

The following properties do not apply to Java Agents 5.6, although they may appear in the AM console:

Specifies a list of application-specific URIs if the referenced Post Data Preservation entry cannot be found in the local cache because it has exceeded its POST entry TTL. Either the Java agent redirects to a URI in this list, or it shows an HTTP 403 Forbidden error.

Specifies the maximum number of entries to hold in the PDP cache. Old entries in the cache are discarded if the cache reaches the maximum number of entries.

Limiting the amount of entries in the PDP cache mitigates against DoS attacks. If a malicious user posts a large amount of information to the cache, the cache will grow to the maximum number of entries rather than consume all available memory.

Specifies the maximum size of the PDP cache in megabytes. Old entries in the cache are discarded if the cache reaches the maximum size.

Limiting the size of the PDP cache mitigates against DoS attacks. If a malicious user posts a large amount of information to the cache, the cache will grow to the maximum size rather than consume all available memory.

Note

If both PDP Cache Maximum Size and PDP Cache Maximum Number of Entries properties are set, the PDP Cache Maximum Number of Entries property is ignored.

Specifies which agent profiles the agent authenticator can read in the realm.

Agent Root URL for CDSSO

Specifies the list of agent root URLs for CDSSO. The valid value is in the format protocol://hostname:port/ where protocol represents the protocol used, such as http or https, hostname represents the host name of the system where the agent resides, and port represents the port number on which the agent is installed. The slash following the port number is required.

If your agent system also has virtual host names, add URLs with the virtual host names to this list as well. AM checks that goto URLs match one of the agent root URLs for CDSSO.

When using the Common REST interface, the Timer metric type has the following fields:

Field

Description

_id

The metric ID.

_type

The metric type.

count

The number of events recorded for this metric.

total

The sum of the durations recorded for this metric.

min

The minimum duration recorded for this metric.

max

The maximum duration recorded for this metric.

mean

The mean average duration recorded for this metric.

stddev

The standard deviation of durations recorded for this metric.

duration_units

The units used for measuring the durations in the metric.

p50

50% of the durations recorded are at or below this value.

p75

75% of the durations recorded are at or below this value.

p95

95% of the durations recorded are at or below this value.

p98

98% of the durations recorded are at or below this value.

p99

99% of the durations recorded are at or below this value.

p999

99.9% of the durations recorded are at or below this value.

m1_rate

The one-minute average rate.

m5_rate

The five-minute average rate.

m15_rate

The fifteen-minute average rate.

mean_rate

The average rate.

rate_units

The units used for measuring the rate of the metric.

Note

Duration-based values, such as min, max, and p50, are weighted towards newer data. By representing approximately the last five minutes of data, the timers make it easier to see recent changes in behavior, rather than a uniform average of recordings since the server was started.

The following is an example of the requests.granted.not-enforced metric from the Common REST endpoint:

The Prometheus endpoint does not provide rate-based statistics, as rates can be calculated from the time-series data.

When using the Prometheus interface, the Timer metric type has the following fields:

Field

Description

# TYPE

The metric ID, and type. Note that the Timer metric type is reported as a Summary type. Formatted as a comment.

_count

The number of events recorded.

_total

The sum of the durations recorded.

{quantile="0.5"}

50% of the durations are at or below this value.

{quantile="0.75"}

75% of the durations are at or below this value.

{quantile="0.95"}

95% of the durations are at or below this value.

{quantile="0.98"}

98% of the durations are at or below this value.

{quantile="0.99"}

99% of the durations are at or below this value.

{quantile="0.999"}

99.9% of the durations are at or below this value.

Note

Duration-based quantile values are weighted towards newer data. By representing approximately the last five minutes of data, the timers make it easier to see recent changes in behavior, rather than a uniform average of recordings since the server was started.

The following is an example of the ja_requests{access=granted,decision=allowed-by-policy} metric from the Prometheus endpoint:

9.3.2.4. JVM Metrics

Tip

To get the metric name used by Prometheus, prepend ja_ to the names below, and replace period (.) and hyphen (-) characters with underscore (_) characters. For example, the jvm.available-cpus metric is named ja_jvm_available_cpus in Prometheus.

Use this option to install in silent mode by specifying all the responses in the file-name file. When this option is used, agentadmin runs in non-interactive mode.

--saveResponse

Use this option to save all the supplied responses to the file-name file.

--acceptLicense

Auto-accepts the software license agreement. If this option is present on the command line with the --install or --custom-install option, the license agreement prompt is suppressed and the agent installation continues. To view the license agreement, open <server-root>/legal-notices/license.txt.

Use this option to uninstall in silent mode by specifying all the responses in the file-name file. When this option is used, agentadmin runs in non-interactive mode.

--saveResponse

Use this option to save all the supplied responses to the file-name file.

--version

Displays the version information.

--uninstallAll

Uninstalls all the agent instances.

--listAgents

Displays details of all the configured agents.

--agentInfo

Displays details of the agent corresponding to the specified agent-id.

Example: agentadmin --agentInfo agent_001

--encrypt

Encrypts a given string.

Usage: agentadmin --encrypt agent-instancepassword-file

agent-instance

Agent instance identifier. The encryption functionality requires the use of agent instance specific encryption key present in its configuration file.

password-file

File containing the password to encrypt.

--getEncryptKey

Generates an agent encryption key.

9.5. Configuring Apache HTTP Server as a Reverse Proxy Example

This section demonstrates a possible configuration of Apache as a reverse proxy between AM and the agent, but you can use any reverse proxy that supports the WebSocket protocol.

Reverse Proxy Configured Between the Agent and AM

Note that the communication protocol changes from HTTPS to HTTP.

To Configure Apache as a Reverse Proxy Example

This procedure demonstrates how to configure Apache as a reverse proxy between an agent and a single AM instance. Refer to the Apache documentation to configure Apache for load balancing and any other requirement for your environment:

RequestHeader. Set this directive to https or http depending on the proxy configuration. If the proxy is configured for https, as in the example depicted in the diagram above, set the directive to https. Otherwise, set it to http.

In a future step you will configure AM to recognize the forwarded header and use it in the goto parameter for redirecting back to the agent after authentication.

ProxyPass. Set this directive to allow WebSocket traffic between AM and the agent.

If you have HTTPS configured between the proxy and AM, set the directive to use the wss protocol instead of ws.

ProxyPass. Set this directive to allow HTTP traffic between AM and the agent.

ProxyPassReverseCookieDomain. Set this directive to rewrite the domain string in Set-Cookie headers in the format internal domain (AM's domain) public domain (proxy's domain).

ProxyPassReverse. Set this directive to the same value configured for the ProxyPass directive.

For more information about configuring Apache as a reverse proxy, refer to the Apache documentation.

Restart the reverse proxy instance.

Configure AM to recover the forwarded header you configured in the reverse proxy. Also, review other configurations that may be required in an environment that uses reverse proxies. For more information, see "Regarding Communication Between AM and Agents"

[5] These files are /path/to/java_agents/agent_type/agent_instance/config/OpenSSOAgentBootstrap.properties and /path/to/java_agents/agent_type/agent_instance/OpenSSOAgentConfiguration.properties, respectively.

Appendix A. Getting Support

ForgeRock provides support services, professional services, training through ForgeRock University, and partner services to assist you in setting up and maintaining your deployments. For a general overview of these services, see https://www.forgerock.com.

ForgeRock has staff members around the globe who support our international customers and partners. For details on ForgeRock's support offering, including support plans and service level agreements (SLAs), visit https://www.forgerock.com/support.

ForgeRock publishes comprehensive documentation online:

The ForgeRock Knowledge Base offers a large and increasing number of up-to-date, practical articles that help you deploy and manage ForgeRock software.

While many articles are visible to community members, ForgeRock customers have access to much more, including advanced information for customers using ForgeRock software in a mission-critical capacity.

ForgeRock product documentation, such as this document, aims to be technically accurate and complete with respect to the software documented. It is visible to everyone and covers all product features and examples of how to use them.

Glossary

Access control

Control to grant or to deny access to a resource.

Account lockout

The act of making an account temporarily or permanently inactive after successive authentication failures.

Actions

Defined as part of policies, these verbs indicate what authorized identities can do to resources.

Advice

In the context of a policy decision denying access, a hint to the policy enforcement point about remedial action to take that could result in a decision allowing access.

Agent administrator

User having privileges only to read and write agent profile configuration information, typically created to delegate agent profile creation to the user installing a web or Java agent.

Agent authenticator

Entity with read-only access to multiple agent profiles defined in the same realm; allows an agent to read web service profiles.

Application

In general terms, a service exposing protected resources.

In the context of AM policies, the application is a template that constrains the policies that govern access to protected resources. An application can have zero or more policies.

Application type

Application types act as templates for creating policy applications.

Application types define a preset list of actions and functional logic, such as policy lookup and resource comparator logic.

Access control that is based on attributes of a user, such as how old a user is or whether the user is a paying customer.

Authentication

The act of confirming the identity of a principal.

Authentication chaining

A series of authentication modules configured together which a principal must negotiate as configured in order to authenticate successfully.

Authentication level

Positive integer associated with an authentication module, usually used to require success with more stringent authentication measures when requesting resources requiring special protection.

Authentication module

AM authentication unit that handles one way of obtaining and verifying credentials.

Authorization

The act of determining whether to grant or to deny a principal access to a resource.

Authorization Server

In OAuth 2.0, issues access tokens to the client after authenticating a resource owner and confirming that the owner authorizes the client to access the protected resource. AM can play this role in the OAuth 2.0 authorization framework.

Auto-federation

Arrangement to federate a principal's identity automatically based on a common attribute value shared across the principal's profiles at different providers.

Bulk federation

Batch job permanently federating user profiles between a service provider and an identity provider based on a list of matched user identifiers that exist on both providers.

Circle of trust

Group of providers, including at least one identity provider, who have agreed to trust each other to participate in a SAML v2.0 provider federation.

Client

In OAuth 2.0, requests protected web resources on behalf of the resource owner given the owner's authorization. AM can play this role in the OAuth 2.0 authorization framework.

Client-based OAuth 2.0 tokens

After a successful OAuth 2.0 grant flow, AM returns a token to the client. This differs from CTS-based OAuth 2.0 tokens, where AM returns a reference to token to the client.

Client-based sessions

AM sessions for which AM returns session state to the client after each request, and require it to be passed in with the subsequent request. For browser-based clients, AM sets a cookie in the browser that contains the session information.

For browser-based clients, AM sets a cookie in the browser that contains the session state. When the browser transmits the cookie back to AM, AM decodes the session state from the cookie.

Conditions

Defined as part of policies, these determine the circumstances under which which a policy applies.

Environmental conditions reflect circumstances like the client IP address, time of day, how the subject authenticated, or the authentication level achieved.

Subject conditions reflect characteristics of the subject like whether the subject authenticated, the identity of the subject, or claims in the subject's JWT.

Configuration datastore

LDAP directory service holding AM configuration data.

Cross-domain single sign-on (CDSSO)

AM capability allowing single sign-on across different DNS domains.

CTS-based OAuth 2.0 tokens

After a successful OAuth 2.0 grant flow, AM returns a reference to the token to the client, rather than the token itself. This differs from client-based OAuth 2.0 tokens, where AM returns the entire token to the client.

CTS-based sessions

AM sessions that reside in the Core Token Service's token store. CTS-based sessions might also be cached in memory on one or more AM servers. AM tracks these sessions in order to handle events like logout and timeout, to permit session constraints, and to notify applications involved in SSO when a session ends.

Delegation

Granting users administrative privileges with AM.

Entitlement

Decision that defines which resource names can and cannot be accessed for a given identity in the context of a particular application, which actions are allowed and which are denied, and any related advice and attributes.

Extended metadata

Federation configuration information specific to AM.

Extensible Access Control Markup Language (XACML)

Standard, XML-based access control policy language, including a processing model for making authorization decisions based on policies.

Federation

Standardized means for aggregating identities, sharing authentication and authorization data information between trusted providers, and allowing principals to access services across different providers without authenticating repeatedly.

Fedlet

Service provider application capable of participating in a circle of trust and allowing federation without installing all of AM on the service provider side; AM lets you create Java Fedlets.

Hot swappable

Refers to configuration properties for which changes can take effect without restarting the container where AM runs.

Identity

Set of data that uniquely describes a person or a thing such as a device or an application.

Identity federation

Linking of a principal's identity across multiple providers.

Identity provider (IdP)

Entity that produces assertions about a principal (such as how and when a principal authenticated, or that the principal's profile has a specified attribute value).

Identity repository

Data store holding user profiles and group information; different identity repositories can be defined for different realms.

Java agent

Java web application installed in a web container that acts as a policy enforcement point, filtering requests to other applications in the container with policies based on application resource URLs.

Metadata

Federation configuration information for a provider.

Policy

Set of rules that define who is granted access to a protected resource when, how, and under what conditions.

Policy agent

Java, web, or custom agent that intercepts requests for resources, directs principals to AM for authentication, and enforces policy decisions from AM.

Policy Administration Point (PAP)

Entity that manages and stores policy definitions.

Policy Decision Point (PDP)

Entity that evaluates access rights and then issues authorization decisions.

Policy Enforcement Point (PEP)

Entity that intercepts a request for a resource and then enforces policy decisions from a PDP.

Policy Information Point (PIP)

Entity that provides extra information, such as user profile attributes that a PDP needs in order to make a decision.

Principal

Represents an entity that has been authenticated (such as a user, a device, or an application), and thus is distinguished from other entities.

When a Subject successfully authenticates, AM associates the Subject with the Principal.

Privilege

In the context of delegated administration, a set of administrative tasks that can be performed by specified identities in a given realm.

Provider federation

Agreement among providers to participate in a circle of trust.

Realm

AM unit for organizing configuration and identity information.

Realms can be used for example when different parts of an organization have different applications and identity stores, and when different organizations use the same AM deployment.

Administrators can delegate realm administration. The administrator assigns administrative privileges to users, allowing them to perform administrative tasks within the realm.

Resource

Something a user can access over the network such as a web page.

Defined as part of policies, these can include wildcards in order to match multiple actual resources.

Resource owner

In OAuth 2.0, entity who can authorize access to protected web resources, such as an end user.

Resource server

In OAuth 2.0, server hosting protected web resources, capable of handling access tokens to respond to requests for such resources.

Response attributes

Defined as part of policies, these allow AM to return additional information in the form of "attributes" with the response to a policy decision.

Role based access control (RBAC)

Access control that is based on whether a user has been granted a set of permissions (a role).

Security Assertion Markup Language (SAML)

Standard, XML-based language for exchanging authentication and authorization data between identity providers and service providers.

Service provider (SP)

Entity that consumes assertions about a principal (and provides a service that the principal is trying to access).

Authentication Session

The interval while the user or entity is authenticating to AM.

Session

The interval that starts after the user has authenticated and ends when the user logs out, or when their session is terminated. For browser-based clients, AM manages user sessions across one or more applications by setting a session cookie. See also CTS-based sessions and Client-based sessions.

Session high availability

Capability that lets any AM server in a clustered deployment access shared, persistent information about users' sessions from the CTS token store. The user does not need to log in again unless the entire deployment goes down.

Session token

Unique identifier issued by AM after successful authentication. For a CTS-based sessions, the session token is used to track a principal's session.

Single log out (SLO)

Capability allowing a principal to end a session once, thereby ending her session across multiple applications.

Single sign-on (SSO)

Capability allowing a principal to authenticate once and gain access to multiple applications without authenticating again.

Site

Group of AM servers configured the same way, accessed through a load balancer layer. The load balancer handles failover to provide service-level availability.

The load balancer can also be used to protect AM services.

Standard metadata

Standard federation configuration information that you can share with other access management software.

Stateless Service

Stateless services do not store any data locally to the service. When the service requires data to perform any action, it requests it from a data store. For example, a stateless authentication service stores session state for logged-in users in a database. This way, any server in the deployment can recover the session from the database and service requests for any user.