Agents and policies in AM/OpenAM

This books provides information on agents and their use in AM/OpenAM. It includes chapters on SSL and policies.


What versions of Policy Agents are compatible with AM/OpenAM?

The purpose of this article is to provide compatibility information between Policy Agents and AM/OpenAM versions. Also included is the supported Java® versions for each combination.

Policy Agents and AM/OpenAM compatibility

Caution

Web policy agents 4.x and JEE policy agents 3.5.x are not supported in AM 6.5; you will need to upgrade to the latest Agents 5 release ahead of upgrading to AM 6.5. 

Web policy agents

The following matrix indicates compatibility between AM/OpenAM and Web policy agent versions:

  Web Agents 5.x Web Policy Agents 4.x
AM 6.5.x Yes (5.0.1 or later) --
AM 6 Yes (5.0.1 or later) Yes *
AM 5.5 Yes Yes
AM 5 and 5.1.x -- Yes
OpenAM 13.x -- Yes
OpenAM 12.x -- Yes

* New Agents Profiles on AM 6 are not compatible with Web Agents 4.x by default and will require setting the AM Login URL and AM Logout URL to work with AM 6. Additionally, the experimental REST login mode that was introduced in Web Agents 4.1.0.30 will not work with AM 6.0.0.x. See How do I configure AM 6.0.0.x to work with older policy agents (Web 4.x and JEE 3.5.x)? for details. 

Java policy agents

The following matrix indicates compatibility between AM/OpenAM and Java policy agent versions:

  Java Agents 5.x JEE Policy Agents 3.5.x
AM 6.5.x Yes (5.0.1 or later) --
AM 6 Yes (5.0.1 or later) Yes *
AM 5.5 Yes Yes
AM 5 and 5.1.x -- Yes
OpenAM 13.x -- Yes
OpenAM 12.x -- Yes

* New Agents Profiles on AM 6 are not compatible with JEE Agents 3.5.x by default and will require setting the AM Login URL and AM Logout URL to work with AM 6. See How do I configure AM 6.0.0.x to work with older policy agents (Web 4.x and JEE 3.5.x)? for details.

Note

It is strongly recommended that you always upgrade to the latest maintenance releases for the specific versions of AM/OpenAM and Policy Agents you have deployed.

Java Compatability

Java 11

  • AM 6.5 and later.
  • Java Agents 5.6 and later.

Java 8

  • AM 5 and later; OpenAM 12.x and 13.x
  • JEE Policy Agents 3.5 and later

Java 7

  • AM 5.0 and 5.1.x; OpenAM 12.x and 13.x
  • JEE Policy Agents 3.5

Java 6

  • OpenAM 12.x
  • JEE Policy Agents 3.5

Software and Hardware requirements

AM/OpenAM

Web Policy Agents

Java EE Policy Agents

See Also

What versions of DS/OpenDJ are compatible with AM/OpenAM?

What operating systems are ForgeRock products supported on?

FAQ: Configuring Policy Agents in AM/OpenAM

Installing and configuring AM/OpenAM

Maintenance and Patch availability policy

ForgeRock End of Service Life (EOSL) policy

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I check that a Policy Agent (All versions) can connect to AM/OpenAM?

The purpose of this article is to provide information on checking that a Policy Agent can connect to AM/OpenAM. The information in this article serves various purposes, including: checking connectivity, checking credentials are correct, checking a valid policy agent profile exists and verifying the policy agent can authenticate to AM/OpenAM.

Checking that a policy agent can connect

You can perform a number of checks to confirm that a policy agent can connect to AM/OpenAM, depending on your requirements.

Agent debug logs

The agent debug log will show any exceptions where the policy agent cannot connect to AM/OpenAM. Some common error messages to look out for include:

  • The policy agent has timed out waiting for a response from the AM/OpenAM server: 
    Error 1188:3146f40 all: Connection::read(): NSPR Error while reading data:-5961
    
  • The policy agent's password is incorrect:
    Error 15840:7f4df0490760 AuthService: AuthService::processLoginStatus() Exception message=[invalid password] errorCode='103' templateName=login_failed_template.jsp
    
    You need to check that the password used to install the policy agent matches the password set in the policy agent's profile in AM/OpenAM.
  • The policy agent's name is incorrect or the policy agent profile does not exist in the top level realm:
    Error 11704:2b3eda287cf0 AuthService: AuthService::processLoginStatus() Exception message=[Application user ID is not valid.] errorCode='107' templateName=login_failed_template.jsp.
    You need to check the policy agent profile exists in the top level realm with the same name.
Note

You can also check the AM/OpenAM CoreSystem debug log, which will show any policy agent related exceptions where AM/OpenAM cannot connect to the policy agent.

Authentication

Note

For a policy agent to be able to authenticate, agent must be listed as an Identity Type (Realms > [Realm Name] > Authentication > Settings > General > Identity Types). It is included by default, but if it missing, you will see the following response: { "code": 401, "reason": "Unauthorized", "message": "User Requires Profile to Login" } and should re-add it.

You can make a REST call (from the server on which the policy agent is installed) to verify that the policy agent can authenticate to AM/OpenAM. For example:

  • AM 5 and later:
    $ curl -X POST -H "X-OpenAM-Username: webagentname" -H "X-OpenAM-Password: webagentpassword" -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.1" http://host1.example.com:8080/openam/json/realms/root/authenticate?authIndexType=module&authIndexValue=Application
    
  • Pre-AM 5:
    $ curl -X POST -H "X-OpenAM-Username: webagentname" -H "X-OpenAM-Password: webagentpassword" -H "Content-Type: application/json" http://host1.example.com:8080/openam/json/authenticate?authIndexType=module&authIndexValue=Application
    

If authentication is successful, you will receive a response that includes the tokenId that corresponds to the policy agent session and the URL to which the policy agent would normally be redirected. This response proves that the policy agent can connect to AM/OpenAM, their credentials are correct and a valid policy agent profile exists in AM/OpenAM.

See How do I check that an OAuth 2.0 client can connect to AM/OpenAM (All versions)? for information on checking that an OAuth2 client can connect.

Protected Resource

You can send a request to a URL that is protected by the policy agent. If the policy agent can connect to AM/OpenAM, you will be redirected to the login page.

See Also

How do I enable debug logging for troubleshooting Policy Agents (All versions)?

How do I check if AM/OpenAM (All versions) is up and running?

How do I check if a particular AM/OpenAM (All versions) instance is running?

How do I perform a heartbeat check against DS/OpenDJ (All versions)?

FAQ: Configuring Policy Agents in AM/OpenAM

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I set up a monitoring page for the load balancer in front of Web Policy Agents (All versions) for health checks?

The purpose of this article is to provide information on setting up a monitoring page for the load balancer in front of Web policy agents. Creating a monitoring page is best practice for health checking when you have a load balancer in front of your Web policy agents. This article assumes you have already configured your load balancer and policy agents.

Overview

Creating a monitoring page on the server being protected by the Web policy agent means you can eliminate the policy agent being involved in the load balancer's health check.

This monitoring page should be an unprotected resource and exist on the Not Enforced URL list. Even though the URL is on the Not Enforced URL list, the policy agent is still invoked each time the load balancer checks the monitoring page to determine whether the resource needs protecting or not; this means you can use this configuration to check if the policy agent is responding without the need for policy evaluation.

Creating a monitoring page

You can create a monitoring page as follows:

  1. Create a monitor.html file on one of the servers being protected by the Web policy agent. This file can simply contain the HTML tags; for example, you can use the printf command to create is as follows:
    $ printf '<HTML>\n</HTML>' > monitor.html
  2. Add the URL for this monitoring page to the Not Enforced URL list for this server:
    • AM 5 and later console: navigate to: Realms > [Realm Name] > Applications > Agents > Web > [Agent Name] > Application > Not Enforced URLs and add the URL for the monitoring page, for example:
      http://www.host1.example.com:8080/monitor.html 
    • OpenAM 13.x console: navigate to: Realms > [Realm Name] > Agents > Web > [Agent Name] > Application > Not Enforced URLs and add the URL for the monitoring page.
    • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Agents > Web > [Agent Name] > Application > Not Enforced URLs and add the URL for the monitoring page.
    • ssoadm: enter the following command:
      $ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a com.sun.identity.agents.config.notenforced.url[0]=[URL]
      replacing [realmname], [agentname], [adminID], [passwordfile] and [URL] with appropriate values.
  3. Repeat steps 1 and 2 on each server being protected by the Web policy agent.

The load balancer will now check the monitoring page URL, for example, http://www.host1.example.com:8080/monitor.html on each server to check if the server is up.

You can check this by navigating to the monitoring page URL and observing that you do not need to log in; if you check the agent debug log (when the debug level is set to All) you will see that the policy agent has been invoked to determine if the resource needs protecting and matches the URL on the Not Enforced URL list. For example:

2016-08-16 20:33:53.504    Debug 65819:7f22ec000950 all: in_not_enforced_list(http://host1.example.com:8080/monitor.html): matched 'http://host1.example.com:8080/monitor.html' entry in not-enforced list
2016-08-16 20:33:53.504    Debug 65819:7f22ec000950 all: in_not_enforced_list: Allowing access to http://host1.example.com:8080/monitor.html

See Also

How do I define a list of Not Enforce URLs that Web Policy Agents can ignore for authentication purposes in AM/OpenAM (All versions)?

How do I configure a Web Policy Agent (All versions) for SSL offloading?

FAQ: Configuring Policy Agents in AM/OpenAM

Agents and policies in AM/OpenAM

User Guide › Introducing Web Agents › Not-Enforced URL and Client IP Lists

User Guide › Introducing Web Agents › FQDN Checking

User Guide › Reference › Configuring Application Properties

User Guide › Reference › Configuring Global Properties

Related Training

N/A

Related Issue Tracker IDs

OPENAM-5693 (RFE: Web Agent to provide means of monitoring health and active state of Agent to AM communication )


How does Post Data Preservation work for Web agents (All versions)?

The purpose of this article is to provide information on Post Data Preservation (PDP) and how it affects the Web agent.

What is Post Data Preservation (PDP)

Enabling PDP tells the policy agent to save the data entered in a form when it is received by the policy agent without a valid authenticated session. This helps prevent data loss if a session times out before the user submits the form.

PDP data is preserved in a local file-based cache in the policy agent install directory/log. When using PDP with a Web policy agent, the user/browser must return to the same server that has the local cache containing the details being preserved or saved. If the follow up request ends up at a different server, it will not be able to retrieve the PDP data. 

There are two methods for ensuring the user returns to the original server: cookie or URI. This means the load balancer must use either the cookie being set or the URI being set to route the user back to the same server where they completed the form. See Post Data Preservation Properties for more details on the POST Data Preservation Cookie Name (com.sun.identity.agents.config.postdata.preserve.lbcookie) and Post Data Preservation URI Prefix (com.forgerock.agents.config.pdpuri.prefix) properties, which should be set appropriately.

There are a couple of different ways to send parameter data from one web page to another:

  • GET parameters: these are limited in size and can also be seen in the browser.
  • Data in the POST body: this allows for greater size and different formats of data to be sent. In some cases, this can result in a tremendous amount of data in the requests. For example, exampleform.html contains a form, which submits via POST to processform.php, which then retrieves the parameter data. This is the simplest possible scenario.

Observing data in the POST body

You can see the data in the example POST body snippet below (pdpForm) in an HTTP trace, for example:

                <html><body><form name="pdpForm" action="http://host1.example.com:8080/examples/servlets/servlet/RequestParamExample" method="POST"><input type="hidden" name="lastname" value="doe"/><input type="hidden" name="firstname" value="john"/></form><script type="text/javascript" language="javascript">document.pdpForm.submit();</script></body></html>

How do I enable debug logging for troubleshooting Policy Agents (All versions)? debugging in the policy agent will show the size of data that has been processed, and whether it is stored in-memory or in the file-based cache. Depending on processing speed, you may also be able to look in the logs directory. The output from a HTTP trace shows what has been received by the browser. The size information should match the content size in a working system.

Note

PDP has been improved in Web agents 5.x as detailed in the release notes: Important Changes to Existing Functionality (Changes to POST Data Preservation (PDP)).

PDP caveats in Web policy agents 4.x

There are some caveats around enabling PDP in Web policy agents 4.x as follows:

  • It only works with HTML form data in Web policy agents 4.0; this was extended to include arbitrary data in Web policy agent 4.1 (up to, and including patch 4.1.0-24) and finally, all restrictions were removed in Web policy agent 4.1.0-25 and later, which also allows file uploads etc.
  • For pre-4.1.0-25 versions of the Web policy agent: The headers of the original request are lost when the policy agent redirects to a dummy form, which submits the original data. For Web policy agent 4.1.0-25 and later, a new redirection mechanism results in the web browser resubmitting the original request including headers.

Complications

The following scenarios introduce complications to PDP:

  • Apache™ forwards on to PHP processing through FastCGI on a non-enforced URL.
  • Apache forwards on to PHP processing locally but PHP endpoint is enforced.
  • Apache forwards on to PHP processing through FastCGI on an enforced URL.
  • Apache forwards on to processing of the CGI requests on another application server such as WebSphere®, Tomcat™ for further processing. This may or may not be an enforced endpoint.
  • Any of these could also be using CDSSO.
  • There could also be advices involved, which would mean session upgrade is involved.

Troubleshooting

The following information is needed for troubleshooting purposes:

Known issues in Web agents 4.x

Note

The majority of these issues can be addressed by applying the Web policy agent 4.1.0-25 patch or later, which includes fixes for AMAGENTS-469 (Browser hang in PDP with agent 4.1 using mod_jk with a fileupload servlet). After applying AMAGENTS-469, PDP must be explicitly turned on for Web policy agent 4.1.0-25 to 4.1.0-29 if you use HTTP Post .

The following known issues exist with PDP in Web policy agents 4.x:

  • Cannot exclude specific URLs from POST data inspection. 
  • POST data not preserved when using the FastCGI module.
  • POST data files are not cleared by the policy agent.
  • POST body is truncated when uploading files.

Cannot exclude specific URLs from post data inspection

There is a known issue in Web policy agents 4.0, which prevents you from specifying URLs that should not go through POST data inspection: AMAGENTS-27 (WPA4 needs a configurable option to bypass POST data inspection). This issue is fixed in Web policy agents 4.1 with the introduction of a new configuration property that lets you control which URLs should be skipped by the POST inspector:

org.forgerock.agents.config.skip.post.url[0]=http*://*:*/postreader.jsp

You should add the same URL to the Not Enforced list too.

See Web Policy Agent Guide › Reference › Configuring Web Policy Agent Custom Properties for further information.

Note

You cannot/should not use this for everything as LARES POSTs still need to get through for CDSSO.

POST data not preserved when using the FastCGI module

There is a known issue in Web policy agents 4.x, which causes missing POST data if you are using the FastCGI module: AMAGENTS-322 - FastCGI module results in post data missing after processing with agent. This issue is fixed in Web policy agent 4.1.0-6 and later; there are two parts to this fix: a passive fix (which should be tested first) and an active fix, which is only initiated when you set the following new property to true:

org.forgerock.agents.config.lares.cookie.compatibility.mode=true

This new property can be added in the console by navigating as follows:

  • AM 5 and later console: navigate to: Realms > [Realm Name] > Applications > Agents > Web > [Agent Name] > Advanced > Custom Properties.
  • OpenAM 13.x console: navigate to: Realms > [Realm Name] > Agents > Web > [Agent Name] > Advanced > Custom Properties.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Agents > Web > [Agent Name] > Advanced > Custom Properties

This property reverts some of the logic so that POST data is not preserved in as many scenarios.

POST data files are not cleared by the policy agent

There is a known issue in Web policy agents 4.x, which stops the POST data files being automatically cleared: AMAGENTS-331 (with Agent 4.0.1-14 Post Data files are not getting cleared by agent). This issue is mostly resolved by AMAGENTS-322 (FastCGI module results in post data missing after processing with agent) (fixed in Web policy agent 4.1.0-6 and later;) but there is one outstanding use case where this issue can still occur as detailed in the comments section in AMAGENTS-331.

POST body is truncated when uploading files

There is a known issue in Web policy agents 4.0, which truncates data in the POST body when uploading files: AMAGENTS-47 (Agent truncates filtered HTTP POST body). This issue is fixed in Web policy agents 4.1 for files up to 4k in size. This fix also resolves OPENAM-2493 (POST Data Preservation makes error in a CDSSO environment for Apache and Varnish webagents).

See Also

Tips and feature insights for Web Policy Agents 4.x

How do I upgrade to Web Policy Agent 4.x from a previous version?

User Guide › Configuring Advanced Properties

User Guide › Supporting Load Balancers

Related Training

N/A

Related Issue Tracker IDs

AMAGENTS-668 (POST Data Preservation fails with (error: 18) if the web agent is installed in the separate disk from /tmp)

AMAGENTS-469 (Browser hang in PDP with agent 4.1 using mod_jk with a fileupload servlet)

AMAGENTS-459 (PDP of 5 bytes or less in one bucket results in post data loss)

AMAGENTS-322 (FastCGI module results in post data missing after processing with agent) 

AMAGENTS-331 (with Agent 4.0.1-14 Post Data files are not getting cleared by agent)

AMAGENTS-47 (Agent truncates filtered HTTP POST body)

AMAGENTS-27 (WPA4 needs a configurable option to bypass POST data inspection)

OPENAM-3727 (Varnish PA does not properly handle POST data preservation feature)

OPENAM-2493 (POST Data Preservation makes error in a CDSSO environment for Apache and Varnish webagents)


How do I silently remove a Web Policy Agent 4.x or 5.x?

The purpose of this article is to provide information on performing a silent, non-interactive removal of a Web Policy Agent.

Silently removing Web policy agents

If you uninstall a policy agent using the --r switch, you are prompted to confirm the removal by entering yes or y. You can prevent this prompt by echoing the answer and piping it to the agentadmin command.

For example, the following commands demonstrate uninstalling agent_1 depending on which operating system you are using:

  • Unix® or Linux® system:
    $ echo y | ./agentadmin --r agent_1
    
  • Microsoft® Windows®:
    C:\path\to\web_agents\agent_type\bin> echo y | agentadmin.exe --r agent_1

See Also

Tips and feature insights for Web Policy Agents 4.x

How do I upgrade to Web Policy Agent 4.x from a previous version?

FAQ: Configuring Policy Agents in AM/OpenAM

User Guide

Related Training

N/A

Related Issue Tracker IDs

AMAGENTS-582 (quiet remove option for yes/no prompts in WPA 5 install)


Installation


How do I configure AM 6.0.0.x to work with older policy agents (Web 4.x and JEE 3.5.x)?

The purpose of this article is to provide information on using Web and JEE policy agents with AM 6. This is a supported combination but requires setting the AM Login URL and AM Logout URL for new installs and new agent profiles. Otherwise, you will encounter "unable to find active OpenAM server URL" errors.

Configuring AM 6.0.0.x

Note

The experimental REST login mode that was introduced in Web Agents 4.1.0.30 will not work with AM 6.0.0.x. This feature is only officially supported with Web Agents 4.2. If you wish to use this login mode with Web Agents 4.x and AM 6.0.0.x, you must use Web Agents 4.2.

AM 6 introduced profile changes to support Agents 5, which removed the legacy login and logout URL property values required by older policy agents. If you try to use Web policy agents 4.x or JEE policy agents 3.5.x without setting these properties, you may encounter 403 Forbidden responses and will see the following error in the agent  debug.log:

2018-10-11 11:37:26.436 +1000   ERROR [0x7fe007f1c8c0:40] handle_exit(): unable to find active OpenAM server URL

New installs and new profiles

If you have a new install of AM 6 or add a new profile, you must populate the AM Login URL and AM Logout URL using either the console, REST or ssoadm:

  • Console: navigate to: Realms > [Realm Name] > Applications > Agents > [Web or Java] > [Agent Name] > AM Services and specify both the AM Login URL and AM Logout URL including the realm. The URL should be in the correct format, for example: 
    http://host1.example.com:8080/openam/XUI?realm=/#login/
  • REST: update the com.sun.identity.agents.config.login.url and com.sun.identity.agents.config.logout.url properties as described in How do I create and update an agent in AM/OpenAM (All versions) using the REST API?
  • ssoadm: enter the following command:
    $ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a com.sun.identity.agents.config.login.url[0]=[loginURL] com.sun.identity.agents.config.logout.url[0]=[logoutURL]
    replacing [realmname], [agentname], [adminID], [passwordfile], [loginURL] and [logoutURL] with appropriate values.

Upgrades

If you upgrade to AM 6, existing profiles will not be affected and older policy agents will work without any changes needed. 

Caution

Web policy agents 4.x and JEE policy agents 3.5.x are not supported in AM 6.5; you will need to upgrade to the latest Agents 5 release ahead of upgrading to AM 6.5.

See Also

What versions of Policy Agents are compatible with AM/OpenAM?

Best practice for upgrading to AM 6.x

Upgrading AM/OpenAM

Agents and policies in AM/OpenAM

Setup and Maintenance Guide › Creating Agent Profiles

Related Training

N/A

Related Issue Tracker IDs

AMAGENTS-2070 (AM_AGENT_REST_LOGIN does not work with AM 6)

OPENAM-13565 (agent 4 ft for ssl requires login.url set in profile when using with AM 6)

OPENAM-12666 (Agent OAuth 2 provider does not support custom login URLs)


Best practice for installing IIS Web Policy Agents (All versions)

The purpose of this article is to provide best practice advice on installing IIS Web Policy Agents.

Prerequisites

There are a number of things you should check before installing the IIS policy agents. In summary, these are:

  • All Application Development features are installed on the IIS web server. If you attempt to install the IIS policy agent without installing these features first, you will end up with empty debug directories and a non-working, non-registered IIS policy agent on your IIS web server.
  • The authentication method for IIS is set to anonymous.
  • All relevant configuration sections in the IIS Manager (under Site > Management > Configuration Editor) are unlocked. Typically, you will only need to unlock modules under the system.webServer configuration section (system.webServer/modules). If any required configuration sections are locked when you attempt the install, you will see the following error:  
    Creating configuration...
    AddElement failed, file MACHINE/WEBROOT/APPHOST/SITE1: The process cannot access the file because another process has locked a portion of the file.
    
  • The application pool should be set as the default Integrated mode rather than Classic mode. In Classic mode, you cannot share sessions between the policy agent and another .NET application, so Logon and Impersonation are not operative. Furthermore, IIS in Classic mode treats all modules as ISAPI extensions and request processing, including that of Post Data Preservation, is affected.
  • Both the site and nested web application must be on the same application pool for them both to be protected by the policy agent. If they are on different application pools, only the site will be protected.
  • IIS agent 5 and later: The value of the com.sun.identity.client.notification.url property has been removed; this is especially pertinent if the agent is configured for client-based sessions as you will encounter HTTP 403 errors when trying to access a protected resource if this property is populated.
  • IIS policy agents 4.0.x only: You do not have any mixed 32bit and 64bit application pools running on the IIS web server; the IIS 4.0.x policy agent does not support this type of mixed installation. IIS policy agents 4.1 and later do support 32-bit and 64-bit application pools on the same IIS environment.
  • IIS policy agents 4.0.x only: You have downloaded the correct IIS policy agent according to whether your Microsoft® Windows machine is 32bit or 64bit. This is not relevant to IIS policy agents 4.1 and later as there is now only one downloadable package that supports both 32-bit and 64-bit IIS application pools.

Install

You should then install the IIS policy agents per the documentation applicable to your version:

IIS agent 5.x

If you need to protect a parent application and a child application with different web agent configurations, you must install the web agent on the child application before installing the web agent in the parent. Trying to install a web agent on a child that is already protected will result in error.

IIS policy agent 4.x

In IIS policy agent 4.x, you should pay particular attention to the following:

  • IIS policy agents 4.x now use the agentadmin tool to install and configure the agent. This tool is located in the /path/to/policy_agent/bin directory. IIS7Admin.vbs script is for pre-4.x release only.  
  • You should read Tips and feature insights for Web Policy Agents 4.x in conjunction with the product documentation prior to installing and using the new web policy agents. 

Post-install

You should be consistent with running everything in 32bit mode or 64bit mode as appropriate. If you attempt to use a 64bit policy agent when running in 32bit mode (Enable 32-Bit Applications option set to 'true'), you will see the following error in the event logs:

The Module DLL 'D:\openam\web_agents\iis7_agent\bin\amiis7module.dll' could not be loaded due to a configuration problem. The current configuration only supports loading images built for a x86 processor architecture.

See Also

Tips and feature insights for Web Policy Agents 4.x

Web policy agents 4 install fails with messages such as send_session_request or Server returned HTTP response code

Installing Web policy agent 4.x or 5.x fails with a no ssl/library support error

Related Training

N/A

Related Issue Tracker IDs

OPENAM-3380 (IIS 7 Web Agent Requires installation of Windows Application Development Features)

OPENAM-6005 (IIS v7 Agent fails intermittently when connecting to authservice over SSL)


How do I install AM/OpenAM (All versions) with Apache Web Policy Agent on Red Hat Enterprise Linux or CentOS configured with SELinux?

The purpose of this article is to provide assistance if you want to install AM/OpenAM with Apache™ Web Policy Agent on a Red Hat® Enterprise Linux® (RHEL) or CentOS system configured with SELinux in Enforcing mode. It assumes the Policy Agent is installed on an Apache web server with AM/OpenAM running on Tomcat™ as the web container.

Preparing for a successful install

The following tools are used in this process:

  • SELinux troubleshooting tool - displays all the violations that have been logged to the /var/log/audit/audit.log file along with possible solutions. When SELinux is in Enforcing mode, all configured parameters are enforced and any violations are logged to the /var/log/audit/audit.log file.
  • GUI configuration tool - provides useful utilities for operating and managing SELinux, including restorecon. The restorecon utility enables you to restore a file's default SELinux security contexts.
Note

These are third-party tools that we suggest can be used for troubleshooting but are not supported by ForgeRock.

To prepare for a successful install:

  1. Install these tools using the following terminal command: 
    yum install setroubleshoot policycoreutils-gui
  2. Enable communication between Apache and Tomcat using the following terminal commands:
    # setsebool -P httpd_can_network_connect on
    # setsebool -P httpd_can_network_relay on
  3. Change the default SELinux type context for files in the directory with agent configuration files, such as /opt/web_agent, with the following command if installing the Apache Web Policy Agent:
    restorecon -v /opt/web_agents/apache22_agent/lib/*
  4. Identify and diagnose any other SELinux issues that may exist on your system using the following command:
    sealert -b /var/log/audit/audit.log
    The SELinux Alert Browser is displayed.
  5. Click Troubleshoot to display all the logged alerts along with suggested solutions.
  6. Implement the suggested solutions or similar to resolve all the logged alerts. You can now proceed to install AM/OpenAM and the Apache Web Policy Agent.
Note

You can use -a instead of -b in the sealert command to show a command line equivalent of the SELinux Alert Browser.

See Also

Permission denied when starting Apache Web Policy Agent on Red Hat Enterprise Linux or CentOS system configured with SELinux

OpenAM Web Policy Agent Release Notes › Limitations

Security-Enhanced Linux User Guide

SELinux

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I upgrade to Web Policy Agent 4.x from a previous version?

The purpose of this article is to provide information on upgrading to Web Policy Agent 4.x from a previous version. This process allows you to use the same agent configuration used previously.

Prerequisites

Note

As with any software upgrade, we strongly recommend testing the procedure in your own development environment first and ensuring you have up to date backups and recovery plans in case you encounter any issues. 

Before upgrading your Web policy agent, you should:

Upgrading to Web Policy Agent 4.x

Note

Please note the following:

  • You should upgrade to Web policy agent 4.2, which includes fixes to a number of known issues; you can download this from BackStage.
  • As part of the install process, you must uninstall the previous version of the web policy agent; Web policy agent 4 cannot coexist with a previous version.
  • If you are using a centralized configuration, Web policy agent 4.x will automatically be installed using the same agent configuration used previously.

You can upgrade your Web Policy Agent as follows:

  1. Copy the OpenSSOAgentConfiguration.properties file if you have a local configuration and want to retain your previous configuration.
  2. Uninstall the previous version of the web policy agent; Web policy agent 4 cannot coexist with a previous version. Uninstalling the web policy agent will not affect the policy agent profile in AM/OpenAM. After uninstalling the IIS 7 policy agent, follow the steps below in the Checking IIS Policy Agent is completely uninstalled section to ensure it is completely removed before you install the new policy agent.
  3. Install OpenSSL if the AM/OpenAM server you will be connecting to uses SSL and the operating system does not provide native openssl packages. You can download OpenSSL from: https://www.openssl.org/. If you are using Microsoft® Windows®, you can use the native Schannel for SSL communication as of Web policy agent 4.1; see OpenAM Web Policy Agent Release Notes › What's New in Web Policy Agents 4.1 › New Features in Web Policy Agents 4.1.0 for further information.
  4. Install the web policy agent 4.x using the documented procedure for your specific agent/version: 

Silent install

If you are performing a silent, non-interactive installation by running agentadmin --s, you can optionally add the --forceInstall option. This option forces the installer to proceed with the silent installation even if it cannot connect to the specified AM/OpenAM server during installation. If your install fails, you should try performing a silent non-interactive installation with this option added, for example:

  • Unix® or Linux® system:
    $ agentadmin --s --forceInstall
    
  • Microsoft Windows:
    C:\> agentadmin.exe --s --forceInstall
    

See How do I silently remove a Web Policy Agent 4.x or 5.x? for information on silently removing agents. 

Checking IIS Policy Agent is completely uninstalled

There is a known issue with the uninstaller for IIS 3.x agents where it can fail to completely uninstall the agent. You should follow these steps (using the IIS Manager or command line as preferred) to ensure the agent has been completely uninstalled prior to installing web agent 4.x or later 3.x releases:

Using IIS Manager

  1. Launch the IIS Manager.
  2. Expand the required Server node in the Connections pane, select Sites followed by the Site name.
  3. Click Modules under IIS to display the list of modules for the site.
  4. If the iis7agent module is listed, right-click on it and remove it. If it is not listed, proceed to the next step.
  5. Repeat steps 2 to 4 for each site.
  6. Select the Server name in the Connections pane.
  7. Click Modules under IIS to display the list of modules for the server.
  8. If the iis7agent module is listed, right-click on it and remove it. If it is not listed, proceed to the next step.
  9. Select the Configure Native modules option from the Actions pane whilst the Server > Modules configuration is displayed.
  10. If the iis7agent module is listed, select it and click Remove. If it is not listed, proceed to the next step. 
  11. Restart the IIS process or Microsoft Windows by running
    C:\> iisreset

Using the command line

  1. List the sites and modules using the following commands:
    C:\> appcmd.exe list sites
    C:\> appcmd.exe list modules
  2. Run the following command for the first site listed, replacing "Default Web Site/" with the site name:
    C:\> appcmd.exe list config "Default Web Site/" /section:globalModules
  3. Run the following commands if the iis7agent module is listed:
    C:\> appcmd.exe delete module /module.name:iis7agent /commit
    C:\> appcmd.exe uninstall  module /module.name:iis7agent /commit
  4. Repeat steps 2 and 3 for all the remaining sites that were listed in step 1.
  5. Restart the IIS process or Microsoft Windows by running
    C:\>iisreset
    

See Also

Tips and feature insights for Web Policy Agents 4.x

Best practice for installing IIS Web Policy Agents (All versions)

What versions of Policy Agents are compatible with AM/OpenAM?

Web Policy Agent 4.1 Guide › Removing Apache Web Policy Agents

Web Policy Agent 4.1 Guide › Managing IIS Web Policy Agents

OpenAM Web Policy Agent 4 User's Guide › Removing Apache Web Policy Agents

OpenAM Web Policy Agent 4 User's Guide › Removing IIS Web Policy Agents

OpenAM Web Policy Agent 3.x Installation Guide › Remove Apache 2.4 Web Policy Agent Software

OpenAM Web Policy Agent 3.x Installation Guide ›Remove Apache 2.2 Web Policy Agent

OpenAM Web Policy Agent 3.x Installation Guide › Remove IIS 7 Web Policy Agent Software

OpenAM Web Policy Agent 3.x Installation Guide › Remove IIS 6 Web Policy Agent Software

Related Training

N/A

Related Issue Tracker IDs

OPENAM-7452 (WPA4 agent might crash in configuration validation phase (silent install) )

OPENAM-8065 (WPA4 agentadmin installer fails in send_session_request when notifications are disabled in OpenAM)


Tips and feature insights for Web Policy Agents 4.x

The purpose of this article is to provide tips and feature insights introduced in Web Policy Agents 4.x It is recommended that you read this article prior to installing and using web policy agents 4.x. You should also refer to the product documentation.

Installation

Note

You should upgrade to Web policy agent 4.2, which includes fixes to a number of known issues; you can download this from BackStage.

The installation process for IIS web policy agents 4.x is different to previous versions. You should use the agentadmin tool to install and configure your IIS policy agents. This tool is located in the /path/to/policy_agent/bin directory. If you run agentadmin without any options (as an administrator), it will return a full list of possible commands. 

See Web Policy Agent Guide › Installing Web Policy Agents 4.2 in Microsoft IIS for further information on using agentadmin to install your IIS policy agents.

Note

See How do I upgrade to Web Policy Agent 4.x from a previous version? for information on upgrading from a previous version.

SSL

Web policy agents no longer include independent NSS/NSPR libraries for handling SSL.

If you use SSL between the the policy agent and AM/OpenAM, you should firstly ensure OpenSSL is available prior to installing the policy agent. See OpenAM Web Policy Agent 4 Release Notes › Important Changes to Existing Functionality for further information. If you are using Microsoft® Windows®, you can use the native Schannel for SSL communication as of Web policy agent 4.1; see Web Policy Agent Release Notes › New Features in 4.1 for further information.

Secondly, the approach needed to install the policy agent depends on your use case as follows:

  • HTTPS  only communication between the policy agent and AM/OpenAM server (without certificate authentication) - the agentadmin tool will handle this scenario without any additional setup as agentadmin trusts all available server certificates.
  • HTTPS only communication but with mutual ssl-auth enabled in AM/OpenAM (with certificate authentication) - you can use one of the following approaches:
    • Configure environment variables - you will need to configure the following environment variables in your operating system prior to installation:
      AM_SSL_KEY - path to a private key file (pem encoded)
      AM_SSL_PASSWORD - password for a private key (if set) 
      AM_SSL_CERT - path to a public key file (certificate; pem encoded)
      AM_SSL_CA - path to a CA certs file (pem encoded)
      Optionally, you can also set the following environment variables:
      AM_SSL_CIPHERS - cipher suites used in SSL handshake (similar to the SSLCipherSuite directive in mod_ssl)
      AM_SSL_OPTIONS  - disable SSL/TLS handling in OpenSSL for one or more versions (by using the following possible values: -SSLv3 -TLSv1 -TLSv1.1 -TLSv1.2) 
      
      The settings you specify are automatically transferred to the agent.conf file. You can then proceed with the installation.
    • Use the agentadmin tool - alternatively, you can use the --forceinstall option to install the policy agent.  
      agentadmin --forceInstall
      The following encryption properties (that correspond to the AM_SSL_ environment variables) can then be set in the agent.conf file after installation:
      com.forgerock.agents.config.cert.ca.file = AM_SSL_CA
      com.forgerock.agents.config.cert.file = AM_SSL_CERT
      com.forgerock.agents.config.cert.key = AM_SSL_KEY
      com.forgerock.agents.config.cert.key.password = AM_SSL_PASSWORD
      com.forgerock.agents.config.ciphers = AM_SSL_CIPHERS
      org.forgerock.agents.config.tls = AM_SSL_OPTIONS

Load balancers and reverse proxies

By default, both web policy agent 4.x and the agentadmin tool use long running connections with keep alives when communicating with AM/OpenAM (for login and policy processing). This can cause issues if there is a load balancer or reverse proxy between the policy agent and AM/OpenAM server.

If you use a load balancer or reverse proxy, you should add the following setting to the agent.conf file after installation:

org.forgerock.agents.config.keepalive.disable = true

This setting will switch off the long running socket connection and allow the connections to work as expected within a reverse proxy / load balanced environment.

New files and locations

The following new files have been introduced as part of the changes made for web policy agents 4.x:

Configuration and log files are now specific to the instance (each virtual host and IIS application will have its own instance). The relevant paths for these files are now as follows:

  • agent.conf - /path/to/policy_agent/instances/agent_n/config directory.
  • debug.log - /path/to/policy_agent/instances/agent_n/logs/debug directory.
  • audit.log - /path/to/policy_agent/instances/agent_n/logs/audit directory.

Shared Memory Files 

Shared memory files are stored in the following locations depending on which operating system you are using:

  • Microsoft® Windows® - c:\....webagent....\iis_agent\lib\ folder.
  • Unix® and Linux® - /dev/shm/ directory.
  • Solaris® - /tmp/ directory.

If the web policy agent crashes, it will try to recover (remove) the shared memory files on its own. If it is unable to recover by itself, you will need to manually remove the shared memory files from the relevant location and then restart the web server.

Virtual Hosts support in Apache™

Web policy agents 4.x support installing policy agents into multiple virtual hosts on Apache web servers. Each virtual host has its own web policy agent configuration. However, the installer cannot add more than one configuration into httpd.conf file; this needs to be done manually.

You should follow the instructions given in Web Policy Agent Guide › Installing Apache Web Policy Agents into a Virtual Host to correctly install policy agents into multiple virtual hosts.

Note

Once you have installed your multiple policy agent instances, you can switch an agent instance off by changing AmAgent On for the relevant agent instance to AmAgent Off in the httpd.conf file.

IIS policy agents

IIS policy agents now support multiple worker processes, application pools, restarts and recycles. However, you must not mix 32bit and 64bit agent instances on the same IIS server or within the same Microsoft® Windows® server instance unless you are using IIS policy agent 4.1, which does support this. 

Each IIS site has a bindings table, where you can configure server names and port details for a site; these values must correspond to the policy agent FQDN/cookie domain for that site.

IIS can sometimes lock one or more configuration sections in the IIS Manager (under Site > Management > Configuration), which will cause issues with the installation. This typically happens if an earlier installation was terminated. You can resolve this issue by ensuring all configuration sections are unlocked. 

Refer to Web Policy Agent User's Guide › To disable and enable a web policy agent in an IIS site for further information on enabling or disabling agent instances in IIS.

Reverting IIS configuration

You can revert the IIS configuration to a pre-policy agent state as follows:

  1. Remove agent instances using the following command for each agent instance:
    C:\> agentadmin.exe --r agent_1
  2. Delete all agent instances from IIS using the following command:
    C:\> agentadmin.exe --g
  3. Enter the following command to reset IIS completely:
    C:\> iisreset

Alternatively, you can revert the IIS configuration from the IIS Manager as follows:

  1. Remove the agent instance from the Site > Modules list.
  2. Remove the agent instance from the Global Configuration > Modules > Configure Native Modules list.​

Other information

You should also be aware of the following when you are using the new web policy agents:

  • You can have a maximum of 32 policy agent installs.
  • The shared cache maximum size is limited to 2GB. This is the absolute limit of all of the dynamic cache resizes. You can reduce the limit if required by setting the following environment variable in your operating system:
    AM_MAX_SHARED_POOL_SIZE
  • The cache entry TTL (the overall use of the cache) depends on each particular session and its maxcaching/timeleft values. In the event of the cache entry being valid (within TTL range) and no notification being received, the policy agent will always use the cached entry.
  • Policy requests are limited to a maximum of three retries with a two second wait in between (in case of a communication or any other failure).
  • The Agent POST Data Preservation (PDP) module supports arbitrary data. This can be replayed with one of the following: 
    • with http-form-reposts in the Agent Filter module (as per web policy agents 3.x).
    • with the help of the inline JavaScript® Repost module.
    See Web Policy Agent User's Guide › Configuring Web Policy Agent Advanced Properties for further information.
  • You can now configure JSON-only responses (JSON status / message) as an alternative to the generic HTTP 302 redirect message. This can be configured with the new org.forgerock.agents.config.json.url property as described in Web Policy Agent Guide › JSON-Formatted Response Properties.
  • You should not use the Path Info properties. All policies' not-enforced rules must be written in a form that supports the real request URL, rather than one de-(or re-)composed from a pathinfo value.

See Also

What versions of Policy Agents are compatible with AM/OpenAM?

How do I silently remove a Web Policy Agent 4.x or 5.x?

Best practice for installing IIS Web Policy Agents (All versions)

FAQ: Configuring Policy Agents in AM/OpenAM

Agents and policies in AM/OpenAM

Troubleshooting AM/OpenAM and Policy Agents

Web Policy Agent 4.2 Release Notes

Web Policy Agent 4.2 Guide

Web Policy Agent 4.1 Release Notes

Web Policy Agent 4.1 Guide

OpenAM Web Policy Agent 4 Release Notes

OpenAM Web Policy Agent 4 User's Guide

Related Training

N/A

Related Issue Tracker IDs

AMAGENTS-52 (WPA on Windows should be able to use Schannel for SSL/TLS communication)


Configuration


How do I export configuration details for the Policy Agent (All versions)?

The purpose of this article is to provide information on exporting configuration details for the Policy Agent. Exporting configuration details for the policy agent is a common step in troubleshooting as it allows you (or someone else) to check all your configuration settings.

Exporting policy agent configuration details

You can export the policy agent configuration details using different methods according to which version of AM/OpenAM you are using:

Note

In AM 6 and later, it is not possible to use the exported agent configuration as the basis for creating a local configuration file for an agent. In earlier versions, you could use the exported configuration from the console as it was in the correct format.

REST

Note

Please observe the following when constructing REST calls:

  • Make the REST call to the actual AM server URL (not lb).
  • Change the name of the iPlanetDirectoryPro header to the name of your actual session cookie.
  • Set this session cookie header to the token returned when you authenticated.
  • Ensure the Accept-API-Version header contains valid resource versions (AM 5 and later).

See How do I avoid common issues with REST calls in AM/OpenAM (All versions)? for further information.

You can use REST to obtain the agent's profile as follows:

  1. Authenticate as an admin user. For example:
    • AM 5 and later:
      $ curl -X POST -H "X-OpenAM-Username: amadmin" -H "X-OpenAM-Password: cangetinam" -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.1" http://host1.example.com:8080/openam/json/realms/root/authenticate
      
    • Pre-AM 5:
      $ curl -X POST -H "X-OpenAM-Username: amadmin" -H "X-OpenAM-Password: cangetinam" -H "Content-Type: application/json" http://host1.example.com:8080/openam/json/authenticate
    Example response:
    { "tokenId": "AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*", "successUrl": "/openam/console", "realm": "/" }
    
  2. Return the agent's profile using one of the following curl commands, where myAgent in the URL is replaced with the name of your agent:
    • AM 5 and later:
      $ curl -X GET -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-Type: application/json" http://host1.example.com:8080/openam/json/realms/root/agents/myAgent
      
    • Pre-AM 5:
      $ curl -X GET -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-Type: application/json" http://host1.example.com:8080/openam/json/agents/myAgent

Amster (AM 5 and later)

You can export configuration details for all agents using the export-config command in Amster. For example:

  • Export configuration for all Web agents in the top level realm:
    am> export-config --path /path/to/export --realm / --realmEntities 'WebAgents'
  • Export configuration for all Java agents in the employees realm:
    am> export-config --path /path/to/export --realm employees --realmEntities 'J2eeAgents'
    

Configuration details for each agent will be written to a separate JSON file in the WebAgents or J2eeAgents directory within /path/to/export/realms/[realmName].

ssoadm

You can use ssoadm to return the agent's configuration. Enter the following command:

$ ./ssoadm show-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -o [outputfile]

replacing [realmname], [agentname], [adminID], [passwordfile] and [outputfile] with appropriate values.

Console (pre-AM 6)

You can export the agent configuration using the console as follows in pre-AM 6:

  • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > Agents > [Web or J2EE] > [Agent Name] and click Export Configuration.
  • OpenAM 13.x console: navigate to: Realms > [Realm Name] > Agents > [Web or J2EE] > [Agent Name] and click Export Configuration.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Agents > [Web or J2EE] > [Agent Name] and click Export Configuration.

It is not possible to export the agent configuration using the console in AM 6 and later.  

See Also

How do I collect all the data required for troubleshooting AM/OpenAM and Policy Agents (All versions)?

How do I enable debug logging for troubleshooting Policy Agents (All versions)?

How do I export and import Service configurations for AM/OpenAM (All versions)?

How do I export and import policies in AM/OpenAM (All versions)?

Troubleshooting AM/OpenAM and Policy Agents

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

N/A


How do I configure Agents 5.x to authenticate users against a specific realm, tree or authentication module in AM?

The purpose of this article is to provide information on configuring Web and Java agents to authenticate users against a specific realm, tree or authentication module in AM using conditional redirection rules.

Overview

Communication between the agent and AM uses the OAuth 2.0 Authorization Framework. This means the agent and AM exchange OpenID Connect JSON web tokens (JWTs) containing the information required to authenticate clients and authorize access to protected resources. Agents authenticate to and log out users from the oauth2/authorize endpoint, which is not configurable. To specify the realm, tree or authentication module users should authenticate to, or log out from, you must add a conditional redirection rule. For example, the following value would authenticate users in a realm called 'customers' using an authentication tree called 'myTree':

example.com|http://host1.example.com:8080/openam/oauth2/authorize?realm=customers&service=myTree

See the following links for further information:

Configuring conditional redirection rules (Web Agent)

You can configure conditional redirection rules for the Web agent using the Conditional Login URL property (com.forgerock.agents.conditional.login.url). This is a custom property that you manually set in the agent's profile. You can either add it as an advanced property in the console or via the command line (Amster or ssoadm):

  • Console: navigate to: Realms > [Realm Name] > Applications > Agents > Web > [Agent Name] > Advanced > Custom Properties and add the com.forgerock.agents.conditional.login.url property. For example:
    com.forgerock.agents.conditional.login.url[0] = example.com|http://host1.example.com:8080/openam/oauth2/authorize?realm=customers
  • Amster: follow the steps in How do I update property values in AM (All versions) using Amster? with these values:
    • Entity: WebAgents
    • Property: customProperties
    • Property value: com.forgerock.agents.conditional.login.url[0]
    For example:
            "customProperties": {
                "inherited": false,
                "value": [
                    "com.forgerock.agents.conditional.login.url[0]=example.com|http://host1.example.com/openam/oauth2/authorize?realm=customers"
                ]
            }
    
  • ssoadm: enter the following command:
    $ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a "com.forgerock.agents.conditional.login.url[0]=[conditionalloginURL]"
    replacing [realmname], [agentname], [adminID], [passwordfile] and [conditionalloginURL] with appropriate values, where [conditionalloginURL] consists of the domain|login URL. For example:
    $ ./ssoadm update-agent -e / -b MyWebAgent -u amadmin -f pwd.txt -a "com.forgerock.agents.conditional.login.url[0]=example.com|http://host1.example.com:8080/openam/oauth2/authorize?realm=customers"
Note

If you have a custom Login URL set (which defines the URL of a custom login page) you must also set the Allow Custom Login Mode property (org.forgerock.openam.agents.config.allow.custom.login) to true. This specifies whether the agent should use the default or the custom login mode when redirecting unauthenticated users. See Web Agent User Guide › Login URL Properties for further information.

Configuring conditional redirection rules (Java Agent)

You can configure conditional redirection rules for the Java agent using the Conditional Login URL property (org.forgerock.openam.agents.config.conditional.login.url). You can set this property using either the console, Amster or ssoadm:

  • AM 6 and later console: navigate to: Realms > [Realm Name] > Applications > Agents > Java > [Agent ID] > AM Services > AM Conditional Login URL and enter the conditional redirect rule. For example:
    example.com|http://host1.example.com:8080/openam/oauth2/authorize?realm=customers
  • AM 5.5 console: navigate to: Realms > [Realm Name] > Applications > Agents > J2EE > [Agent Name] > OpenAM Services > OpenAM Conditional Login URL and enter the conditional redirect rule.
  • Amster: follow the steps in How do I update property values in AM (All versions) using Amster? with these values:
    • Entity: J2eeAgents
    • Property: conditionalLoginUrl 
  • ssoadm: enter the following command:
    $ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a "org.forgerock.openam.agents.config.conditional.login.url[0]=[conditionalloginURL]"
    replacing [realmname], [agentname], [adminID], [passwordfile] and [conditionalloginURL] with appropriate values, where [conditionalloginURL] consists of the domain|login URL. For example:
    $ ./ssoadm update-agent -e / -b MyJavaAgent -u amadmin -f pwd.txt -a "org.forgerock.openam.agents.config.conditional.login.url[0]=example.com|http://host1.example.com:8080/openam/oauth2/authorize?realm=customers"
Note

If you have a custom Login URL set (which defines the URL of a custom login page) you must also set the Allow Custom Login Mode property (org.forgerock.openam.agents.config.allow.custom.login) to true. This specifies whether the agent should use the default or the custom login mode when redirecting unauthenticated users. See Java Agent User Guide › Login URL Properties for further information.

See Also

Redirect loop between AM and Agent 5.x after successful authentication

 Web Agent User Guide › Custom Login Redirection Mode

 Java Agent User Guide › Custom Redirection Login Mode

Web Agents User Guide › Redirection and Conditional Redirection

Java Agents User Guide › Redirection and Conditional Redirection

How do I configure policy agents (Web 4.x and JEE 3.5.x) to authenticate users against a specific realm in AM/OpenAM?

Agents and policies in AM/OpenAM

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

N/A


How do I configure policy agents (Web 4.x and JEE 3.5.x) to authenticate users against a specific realm in AM/OpenAM?

The purpose of this article is to provide information on configuring Web and JEE policy agents to authenticate users against a specific realm in AM/OpenAM. This information does not apply to Agents 5 since they use conditional redirection rules to achieve this.

Overview

You can specify a realm in the agent login URL to authenticate users against a realm. For example, you may choose to configure your agent in one realm, yet have your users authenticate through another realm. In this scenario, you would want your agents to redirect users to authenticate to the user's realm, rather than the agent's realm.

Note

Policy agents can only protect one realm; this means a policy agent cannot send some users to realmA for authentication while sending other users to realmB.

Authentication to a specific realm is not enforced when you configure your policy agent for SSO only. SSO only mode verifies that a user has authenticated and that the authentication is valid, but it does not take into account the realm from which the authentication originated. It's one of the few components that doesn't automatically enforce realm authentication; therefore, any user with a valid SSO token is allowed access. If you want the policy agent to enforce that a user must be authenticated to a specific realm, you must also configure a policy with an Environment Condition of type Authentication to a Realm and specify the required realm. See Authorization Guide › Configuring Policies and Setup and Maintenance Guide › Working With Realms and Policy Agents for further details.

See the following sections for further information on setting the login and logout URLs:

Note

Agents 5 uses conditional redirection rules to achieve this. See How do I configure Agents 5.x to authenticate users against a specific realm, tree or authentication module in AM? for further information.

Configuring the login URL

You can configure the login URL for the policy agent using either the console or ssoadm:

  • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > Agents > [Web or J2EE] > [Agent Name] > OpenAM Services > Login URL > OpenAM Login URL and add the login URL (including the realm).
  • OpenAM 13.x console: navigate to: Realms > [Realm Name] > Agents > [Web or J2EE] > [Agent Name] > OpenAM Services > Login URL > OpenAM Login URL and add the login URL (including the realm).
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Agents > [Web or J2EE] > [Agent Name] > OpenAM Services > Login URL > OpenAM Login URL and add the login URL (including the realm).
  • ssoadm: enter the following command:
    $ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a com.sun.identity.agents.config.login.url[0]=[loginURL]
    replacing [realmname], [agentname], [adminID], [passwordfile] and [loginURL] with appropriate values.
Note

If you specify a realm in the login URL, you should also specify the realm in the logout URL.

Accepted URL formats 

The way of specifying a realm parameter in the login URL depends on your AM/OpenAM version as follows, where the realm is employees:

  • AM 5.x / OpenAM 13.5: the query must be defined before the hash (#login), and the realm must be specified using the absolute path (/employees) or the realm DNS alias. Therefore a valid login URL is:
    http://host1.example.com:8080/openam/XUI?realm=/employees#login/
  • Pre-OpenAM 13.5 and Classic UI: in earlier versions of OpenAM, you should use the Classic UI form of the URL even if you use XUI to avoid a known issue:
    http://host1.example.com:8080/openam/UI/Login?realm=employees
    See XUI Login URL with goto parameter causes redirect loop or prevents OpenAM 12.x and 13.x login page loading for further information on this known issue. 

Configuring the logout URL

You can configure the logout URL for the policy agent using either the console or ssoadm:

  • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > Agents > [Web or J2EE] > [Agent Name] > OpenAM Services > Logout URL > OpenAM Logout URL and add the logout URL (including the realm).
  • OpenAM 13.x console: navigate to: Realms > [Realm Name] > Agents > [Web or J2EE] > [Agent Name] > OpenAM Services > Logout URL > OpenAM Logout URL and add the logout URL (including the realm).
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Agents > [Web or J2EE] > [Agent Name] > OpenAM Services > Logout URL > OpenAM Logout URL and add the logout URL (including the realm).
  • ssoadm: enter the following command:
    $ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a com.sun.identity.agents.config.logout.url[0]=[logoutURL]
    replacing [realmname], [agentname], [adminID], [passwordfile] and [logoutURL] with appropriate values.

Accepted URL formats 

The way of specifying a realm parameter in the logout URL depends on your AM/OpenAM version as follows, where the realm is employees:

  • AM 5.x / OpenAM 13.5: the query must be defined before the hash (#logout), and the realm must be specified using the absolute path (/employees) or the realm DNS alias. Therefore a valid logout URL in the XUI is:
    http://host1.example.com:8080/openam/XUI?realm=/employees#logout/
  • Pre-OpenAM 13.5 and Classic UI: in earlier versions of OpenAM, you should use the Classic UI form of the URL even if you use XUI:
    http://host1.example.com:8080/openam/UI/Logout?realm=employees

See Also

FAQ: Configuring Policy Agents in AM/OpenAM

XUI Login URL with goto parameter causes redirect loop or prevents OpenAM 12.x and 13.x login page loading

Agents and policies in AM/OpenAM

Web Policy Agent Guide › Configuring Web Policy Agent OpenAM Services Properties

OpenAM JEE Policy Agents User's Guide › Configuring Java EE Policy Agent OpenAM Services Properties

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

OPENAM-8173 (OpenAM Login URL in the agent profile should support XUI login URL)

OPENAM-8157 (Upgrade from OpenAM 12 to OpenAM 13 XUI login is redirecting to http://undefined/)

OPENAM-6340 (XUI needs to support DNS/Alias behaviour for subrealms as per OPENAM-5508)

OPENAM-5547 (Agent behaviour when appending goto= to LoginURLs is not compatible with XUI login URL)


How do I create a policy agent that inherits group settings using ssoadm in AM/OpenAM (All versions)?

The purpose of this article is to provide information on creating a policy agent that inherits group settings using ssoadm in AM/OpenAM.

Overview

Using Agent groups in AM/OpenAM is recommended when you have multiple policy agents behind a load balancer as it ensures all policy agents have the same updated configuration. Consider the following flow:

  1. AM/OpenAM sends a notification to the load balancer.
  2. The load balancer sends it on to one of the policy agents.
  3. The policy agent receiving the notification updates its configuration; this means the other policy agents now have out-of-date configurations.

Where an agent group is used instead in the above flow, the load balancer sends the notification to the agent group. This means the policy agents within this group will inherit the updated settings.

Creating a policy agent that inherits group settings

You can use ssoadm to create a policy agent that inherits group settings as follows:

  1. Create the agent group using the following ssoadm command:
    $ ./ssoadm create-agent-grp -u [adminID] -f [passwordFile] -t [agentType] -e [realmName] -b [agentGroupName]
    replacing [adminID], [passwordFile], [agentType], [realmName] and [agentGroupName] with appropriate values.
  2. Create the policy agent using the following ssoadm command:
    $ ./ssoadm create-agent -u [adminID] -f [passwordFile] -t [agentType] -e [realmName] -b [agentName] -g [agentURL] -s [serverURL] -a [agentProperties]
    
    replacing [adminID], [passwordFile], [agentType], [realmName], [agentName], [agentURL], [serverURL] and [agentProperties] with appropriate values.
  3. Assign the policy agent you created in step 2 to the group you created in step 1 using the following ssoadm command:
    $ ./ssoadm add-agent-to-grp -u [adminID] -f [passwordFile] -e [realmName] -b [agentGroupName] -s [agentName]
    replacing [adminID], [passwordFile], [realmName], [agentGroupName] and [agentName] with appropriate values.
  4. Remove any properties from the agent's configuration that you want to be inherited from the agent group using the following ssoadm command:
    $ ./ssoadm agent-remove-props -u [adminID] -f [passwordFile] -e [realmName] -b [agentName] -a [agentProperties]
    replacing [adminID], [passwordFile], [realmName], [agentName] and [agentProperties] with appropriate values.
Note

The agent-remove-props command does not support the use of a data file; if you have lots of properties to remove, you may consider using the do-batch command as detailed in How do I make batch changes using ssoadm in AM/OpenAM (All versions)?

Example

The following example demonstrates an agent group being created, a new web policy agent being created, that web policy agent being assigned to the group and finally two properties being removed that should be inherited from the agent group.

$ ./ssoadm create-agent-grp -u amadmin -f pwd.txt -t WebAgent -e / -b agentGroup1

Agent group was created.


$ ./ssoadm create-agent -u amadmin -f pwd.txt -t WebAgent -e / -b agent1 -g http://agent.example.com:80 -s http://host1.example.com:8080/openam -a userpassword=password

Agent configuration was created.


$ ./ssoadm add-agent-to-grp -u amadmin -f pwd.txt -e / -b agentGroup1 -s agent1

Agent was added to group.


$ ./ssoadm agent-remove-props -u amadmin -f pwd.txt -e / -b agent1 -a com.sun.identity.agents.config.sso.only com.sun.identity.agents.config.sso.cache.polling.interval

Properties were removed.

See Also

How do I make batch changes using ssoadm in AM/OpenAM (All versions)?

How do I add multiple attributes with a single ssoadm command in AM/OpenAM (All versions)?

FAQ: Installing and using ssoadm in AM/OpenAM

FAQ: Configuring Policy Agents in AM/OpenAM

Using ssoadm in AM/OpenAM

Reference › Command Line Tools › ssoadm

Web Policy Agent Guide › Implementing Web Policy Agents › Creating Agent Profiles

OpenAM JEE Policy Agent User's Guide › Configuring Java EE Policy Agents › Creating Agent Profiles

Related Training

N/A

Related Issue Tracker IDs

OPENAM-3937 (inheritance does not work with ssoadm update-agent-grp --set)

OPENAM-5466 (Agent does not automatically inherit group settings)


How do I define a list of Not Enforce URLs that Web Policy Agents can ignore for authentication purposes in AM/OpenAM (All versions)?

The purpose of this article is to provide information on defining a list of Not Enforced URLs that Web policy agents can ignore for authentication purposes in AM/OpenAM. You can specify to not enforce complete URLs or URL patterns by using wildcards in the URL, for example, http://example.com/*

Overview

The policy agent is always invoked, even when  a URL is on the Not Enforced URL list, since the policy agent needs to determine whether the resource needs protecting or not; however, policy evaluation does not happen if a URL is on the Not Enforced URL list.

You can see this happening in the agent debug log (when the debug level is set to All); the policy agent is invoked to determine if the resource needs protecting and matches the URL on the Not Enforced URL list. For example:

2016-08-16 20:33:53.504    Debug 65819:7f22ec000950 all: in_not_enforced_list(http://www.example.com/test/): matched 'http://www.example.com/test/' entry in not-enforced list
2016-08-16 20:33:53.504    Debug 65819:7f22ec000950 all: in_not_enforced_list: Allowing access to http://www.example.com/test/

Defining a list of Not Enforced URLs

You can define a list of Not Enforced URLs (if your web policy agent uses centralized configuration) using either the console or ssoadm: 

  • AM 5 and later console: navigate to: Realms > [Realm Name] > Applications > Agents > Web > [Agent Name] > Application > Not Enforced URLs and add the required URLs and/or URL patterns.
  • OpenAM 13.x console: navigate to: Realms > [Realm Name] > Agents > Web > [Agent Name] > Application > Not Enforced URLs and add the required URLs and/or URL patterns.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Agents > Web > [Agent Name] > Application > Not Enforced URLs and add the required URLs and/or URL patterns.
  • ssoadm: enter the following command:
    $ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a com.sun.identity.agents.config.notenforced.url[0]=[URL]
    replacing [realmname], [agentname], [adminID], [passwordfile] and [URL] with appropriate values.

For localized configurations, you must edit the equivalent agent.conf file (located in the /path/to/web_agents/agent_version/instances/Agent_nnn/config directory) instead.

You can add as many URLs and/or URL patterns as required by adding multiple com.sun.identity.agents.config.notenforced.url [n] properties separated by a space and ensuring the [n] increments for each additional URL or URL pattern. For example:

$ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a com.sun.identity.agents.config.notenforced.url[0]=http://www.example.com/example/* com.sun.identity.agents.config.notenforced.url[1]=http://www.example.com/test/*

Wildcards do not match ?. You must explicitly add resource patterns to match URLs with query strings; specifying resource patterns is described in: Authorization Guide › Specifying Resource Patterns with Wildcards. You should also URL encode any spaces in the URL, replacing spaces with %20.

Note

You must restart the web application container in which AM/OpenAM runs to apply these configuration changes. 

See Also

How do I define a list of Not Enforce URIs that Java Policy Agents can ignore for authentication purposes in AM/OpenAM (All versions)?

Authorization Guide › Configuring Resource Types, Policy Sets, and Policies

User Guide › Not-enforced URL Processing Properties

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

N/A


How do I define a list of Not Enforce URIs that Java Policy Agents can ignore for authentication purposes in AM/OpenAM (All versions)?

The purpose of this article is to provide information on defining a list of Not Enforce URIs that Java policy agents can ignore for authentication purposes in AM/OpenAM. You can specify to not enforce complete URIs or URI patterns by using wildcards in the URI, for example, /test/images/*

Defining a list of Not Enforced URIs

You can define a list of Not Enforced URIs (if your Java policy agent uses centralized configuration) using either the console or ssoadm:

  • AM 6 and later console: navigate to: Realms > [Realm Name] > Applications > Agents > Java > [Agent ID] > Application > Not Enforced URIs and add the required URIs and/or URI patterns.
  • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > Agents > J2EE > [Agent Name] > Application > Not Enforced URI Processing > Not Enforced URIs and add the required URIs and/or URI patterns.
  • OpenAM 13.x console: navigate to: Realms > [Realm Name] > Agents > J2EE > [Agent Name] > Application > Not Enforced URI Processing > Not Enforced URIs and add the required URIs and/or URI patterns.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Agents > J2EE > [Agent Name] > Application > Not Enforced URI Processing > Not Enforced URIs and add the required URIs and/or URI patterns.
  • ssoadm: enter the following command:
    $ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a com.sun.identity.agents.config.notenforced.uri[1]=[URI]
    replacing [realmname], [agentname], [adminID], [passwordfile] and [URI] with appropriate values.

For localized configurations, you must edit the equivalent OpenSSOAgentConfiguration.properties file instead. The file location depends on which version of the Java policy agents you are using; the /path/to/java_agents/agent_type/agent_instance/ directory (Java agents 5.x and later) or the /config directory where the JEE policy agent is installed (JEE policy agents 3.5.x).

You can add as many URIs and/or URI patterns as required by adding multiple com.sun.identity.agents.config.notenforced.uri [n] properties separated by a space and ensuring the [n] increments for each additional URI or URI pattern. For example:

$ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a com.sun.identity.agents.config.notenforced.uri[1]=http://www.example.com/example/* com.sun.identity.agents.config.notenforced.uri[2]=http://www.example.com/test/*

Wildcards do not match ?. You must explicitly add resource patterns to match URLs with query strings; specifying resource patterns is described in: Authorization Guide › Specifying Resource Patterns with Wildcards.

Note

You must restart the web application container in which AM/OpenAM runs to apply these configuration changes. 

See Also

How do I define a list of Not Enforce URLs that Web Policy Agents can ignore for authentication purposes in AM/OpenAM (All versions)?

Authorization Guide › Configuring Resource Types, Policy Sets, and Policies

User Guide › Not-Enforced URI Processing Properties

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

N/A


How do I change the session cookie name for AM/OpenAM and Policy Agents (All versions)?

The purpose of this article is to provide information on changing the name of the AM/OpenAM session cookie and also updating the agent session cookies to match. The session cookie is called iPlanetDirectoryPro by default but you should change it for security reasons.

Overview

Once you have changed the AM/OpenAM session cookie name, you must also update the session cookie name in your policy agent profiles to match the new session cookie name. You can change the agent cookies, default agent cookies or the agent group cookies to achieve this.

This article contains information on changing the following session cookie names:

REST calls

Once you have changed the AM/OpenAM session cookie name, you must also update any REST calls to use the new cookie name in the header. For example, if your new cookie is called exampleCookie, you would change the following header in your REST calls from:

-H "iPlanetDirectoryPro: AQIC5..."

To:

-H "exampleCookie: AQIC5..."

Renaming the AM/OpenAM session cookie

You can change the name of this cookie using either the console, ssoadm or Amster (AM 5 and later):

  • AM / OpenAM 13.5 console: navigate to: Configure > Server Defaults > Security > Cookie > Cookie Name and enter the new session cookie name.
  • Pre-OpenAM 13.5 console: navigate to: Configuration > Servers and Sites > Default Server Settings > Security > Cookie Name and enter the new session cookie name.
  • ssoadm: enter the following command:
    $ ./ssoadm update-server-cfg -s default -u [adminID] -f [passwordfile] -a com.iplanet.am.cookie.name=[cookiename]
    replacing [adminID], [passwordfile] and [cookiename] with appropriate values.
  • Amster: follow the steps in How do I update property values in AM (All versions) using Amster?with these values:
    • Entity: DefaultSecurityProperties
    • Property: com.iplanet.am.cookie.name
Note

You must restart the web application container in which AM/OpenAM runs to apply these configuration changes.

Renaming the agent session cookie in AM/OpenAM

You can change the name of this cookie using either the console, ssoadm or Amster (AM 5 and later):

Web Policy Agent

  • AM 5 and later console: navigate to: Realms > [Realm Name] > Applications > Agents > Web > [Agent Name] > SSO > Cookie Name and enter the new session cookie name.
  • OpenAM 13.x console: navigate to: Realms > [Realm Name] > Agents > Web > [Agent Name] > SSO > Cookie Name and enter the new session cookie name.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Agents > Web > [Agent Name] > SSO > Cookie Name and enter the new session cookie name.
  • ssoadm: enter the following command:
    $ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a com.sun.identity.agents.config.cookie.name=[cookiename]
    replacing [realmname], [agentname], [adminID], [passwordfile] and [cookiename] with appropriate values.
  • Amster: follow the steps in How do I update property values in AM (All versions) using Amster?with these values:
    • Entity: WebAgents
    • Property: cookieName

Java Policy Agent

  • AM 6 and later console: navigate to: Realms > [Realm Name] > Applications > Agents > Java > [Agent ID] > SSO > Cookie Name and enter the new session cookie name.
  • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > Agents > J2EE > [Agent Name] > SSO > Cookie Name and enter the new session cookie name.
  • OpenAM 13.x console: navigate to: Realms > [Realm Name] > Agents > J2EE > [Agent Name] > SSO > Cookie Name and enter the new session cookie name.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Agents > J2EE > [Agent Name] > SSO > Cookie Name and enter the new session cookie name.
  • ssoadm: enter the following command:
    $ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a com.iplanet.am.cookie.name=[cookiename]
    replacing [realmname], [agentname], [adminID], [passwordfile] and [cookiename] with appropriate values.
  • Amster: follow the steps in How do I update property values in AM (All versions) using Amster?with these values:
    • Entity: J2eeAgents
    • Property: amCookieName
Note

You must restart the web application container in which AM/OpenAM runs to apply these configuration changes.

Renaming the default agent session cookie in AM/OpenAM

You can change the name of this cookie using ssoadm:

Web Policy Agent

Enter the following command:

$ ./ssoadm set-attr-defs -s AgentService -t Organization -u [adminID] -f [passwordfile] -c WebAgent -a com.sun.identity.agents.config.cookie.name=[cookiename]

replacing [adminID], [passwordfile] and [cookiename] with appropriate values.

Java Policy Agent

Enter the following command:

$ ./ssoadm set-attr-defs -s AgentService -t Organization -u [adminID] -f [passwordfile] -c J2EEAgent -a com.iplanet.am.cookie.name=[cookiename]

replacing [adminID], [passwordfile] and [cookiename] with appropriate values.

Note

You must restart the web application container in which AM/OpenAM runs to apply these configuration changes.

Renaming the agent group session cookie in AM/OpenAM

You can change the name of this cookie using either the console, ssoadm or Amster (AM 5 and later):

Web Policy Agent

  • AM 6 and later console: navigate to: Realms > [Realm Name] > Applications > Agents > Web > Groups > [Group ID] > SSO > Cookie Name and enter the new session cookie name.
  • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > Agents > Web > [Agent Group Name] > SSO > Cookie Name and enter the new session cookie name.
  • OpenAM 13.x console: navigate to: Realms > [Realm Name] > Agents > Web > [Agent Group Name] > SSO > Cookie Name and enter the new session cookie name.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Agents > Web > [Agent Group Name] > SSO > Cookie Name and enter the new session cookie name.
  • ssoadm: enter the following command:
    $ ./ssoadm update-agent-grp -e [realmname] -b [agentgroupname] -u [adminID] -f [passwordfile] -a com.sun.identity.agents.config.cookie.name=[cookiename]
    replacing [realmname], [agentgroupname], [adminID], [passwordfile] and [cookiename] with appropriate values.
  • Amster: follow the steps in How do I update property values in AM (All versions) using Amster?with these values:
    • Entity: WebAgentGroups
    • Property: cookieName

Java Policy Agent

  • AM 6 and later console: navigate to: Realms > [Realm Name] > Applications > Agents > Java > Groups > [Group ID] > SSO > Cookie Name and enter the new session cookie name.
  • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > Agents > J2EE > [Agent Group Name] > SSO > Cookie Name and enter the new session cookie name.
  • OpenAM 13.x console: navigate to: Realms > [Realm Name] > Agents > J2EE > [Agent Group Name] > SSO > Cookie Name and enter the new session cookie name.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Agents > J2EE > [Agent Group Name] > SSO > Cookie Name and enter the new session cookie name.
  • ssoadm: enter the following command:
    $ ./ssoadm update-agent-grp -e [realmname] -b [agentgroupname] -u [adminID] -f [passwordfile] -a com.iplanet.am.cookie.name=[cookiename]
    replacing [realmname], [agentgroupname], [adminID], [passwordfile] and [cookiename] with appropriate values.
  • Amster: follow the steps in How do I update property values in AM (All versions) using Amster?with these values:
    • Entity: J2EEAgentGroups
    • Property: amCookieName
Note

You must restart the web application container in which AM/OpenAM runs to apply these configuration changes.

See Also

Installation Guide › Avoiding Obvious Defaults

Reference › Configuration Reference › Deployment Configuration

Reference › Command Line Tools › ssoadm

Setup and Maintenance Guide › Setting Up Policy Agent Profiles

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

OPENAM-3631 (Renaming of SSO Token Cookie to substring of request URL will cause failed agent evaluation.)


How do I capture HTTP headers set by Web Policy Agents (All versions) in Apache HTTP server using a Perl script?

The purpose of this article is to guide you through creating and executing a Perl® script that will capture user profile attributes set in HTTP headers by Apache™ Web Policy Agents.

Configuring the Web policy agent to publish User profile attributes

You can configure user profile attributes to be set as HTTP headers, such as 'name', 'mail' etc. See User Guide › Reference › Configuring Application Properties for further information.

Creating a Perl script to capture HTTP headers in the Apache HTTP server

  1. Enable the CGI module in the Apache HTTP server. Instructions are available here.
  2. Update the main server configuration file as follows to allow the Apache HTTP server to execute Perl scripts: 
    <Directory /var/www/>
            Options Indexes FollowSymLinks
            Options +ExecCGI
            AddHandler cgi-script .cgi .pl
            AllowOverride None
            Require all granted
    </Directory>
    
  3.  Add the following Perl script (dumpHeaders.pl) to the required site:
    #!/usr/bin/perl
    print "Content-type: text/html\n\n";
    print "HTTP Header: \n";
    print "\n";
    
    for (sort(keys(%ENV))) {
     print "$_ = $ENV{$_}<br>\n";
    }
    
  4. Restart the Apache HTTP server.
  5. Update your AM/OpenAM policies to allow user access to the Perl script you created: http://<HTTPServerIP:HTTPServerPort>/dumpHeaders.pl
  6. Navigate to your Perl script: http://<HTTPServerIP:HTTPServerPort>/dumpHeaders.pl. After successful authentication, the HTTP headers will be displayed, for example:
    HTTP Header: AUTH_TYPE = OpenAM
    CONTEXT_DOCUMENT_ROOT = /var/www/html
    CONTEXT_PREFIX =
    DOCUMENT_ROOT = /var/www/html
    GATEWAY_INTERFACE = CGI/1.1
    HTTP_ACCEPT = text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
    HTTP_ACCEPT_ENCODING = gzip, deflate
    HTTP_ACCEPT_LANGUAGE = en-US,en;q=0.5
    HTTP_CONNECTION = keep-alive
    HTTP_COOKIE = amlbcookie=01; iPlanetDirectoryPro=AQIC5wM2LY4SfcyL0lPgoiFi2wGeyg4Kw_xuyekSlb1_YX0.*AAJTSQACMDIAAlNLABQtNzMxNDgyNjAxNjIyNTI5OTM1MQACUzEAAjAx*
    HTTP_EMAIL = charan@gmail.com
    HTTP_HOST = customers.sample.com:8000
    HTTP_NAME = charan
    HTTP_REFERER = http://customerslogin.sample.com/openam/UI/Login?goto=http%3A%2F%2Fcustomers.sample.com%3A8000%2FdumpHeaders.pl
    HTTP_USER_AGENT = Mozilla/5.0 (Macintosh; Intel Mac OS X 10.11; rv:44.0) Gecko/20100101 Firefox/44.0
    PATH = /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
    QUERY_STRING =
    REMOTE_ADDR = 192.168.56.1
    REMOTE_PORT = 55212
    REMOTE_USER = charan
    REQUEST_METHOD = GET
    REQUEST_SCHEME = http
    REQUEST_URI = /dumpHeaders.pl
    SCRIPT_FILENAME = /var/www/html/dumpHeaders.pl
    SCRIPT_NAME = /dumpHeaders.pl
    SERVER_ADDR = 192.168.56.104
    SERVER_ADMIN = webmaster@localhost
    SERVER_NAME = customers.sample.com
    SERVER_PORT = 8000
    SERVER_PROTOCOL = HTTP/1.1
    SERVER_SIGNATURE =
    Apache/2.4.7 (Ubuntu) Server at customers.sample.com Port 8000
    
    SERVER_SOFTWARE = Apache/2.4.7 (Ubuntu)
    
Note

These HTTP headers can't be captured by tools like LiveHTTP headers, SAML tracer etc as they are not visible in the user's browser. HTTP headers are injected by the policy agent just before redirecting the user to the requested resource. This is explained in more detail in FAQ: Configuring Policy Agents in AM/OpenAM (Q. Why can't I see the http_header attributes in the browser?).

See Also

FAQ: Configuring Policy Agents in AM/OpenAM

Agents and policies in AM/OpenAM

Apache Tutorial: Dynamic Content with CGI

Related Training

N/A

Related Issue Tracker IDs

N/A


SSL Offloading


How do I configure a Web Policy Agent (All versions) for SSL offloading?

The purpose of this article is to provide information on configuring a Web Policy Agent for SSL offloading to ensure the policy agent can redirect to the goto parameter URL successfully, even if this parameter uses protocol http instead of https.

Configuring a policy agent for SSL offloading

You can configure a Web policy agent for SSL offloading using either the console or ssoadm:

  • AM 6 and later console: navigate to: Realms > [Realm Name] > Applications > Agents > Web > [Agent ID] > Advanced and enable Override Request URL Protocol.
  • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > Agents > Web > [Agent Name] > Advanced > Load Balancer > Override Request URL Protocol and select the Enabled option.
  • OpenAM 13.x console: navigate to: Realms > [Realm Name] > Agents > Web > [Agent Name] > Advanced > Load Balancer > Override Request URL Protocol and select the Enabled option.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Agents > Web > [Agent Name] > Advanced > Load Balancer > Override Request URL Protocol and select the Enabled option.
  • ssoadm: enter the following command:
    $ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a com.sun.identity.agents.config.override.protocol=true
    replacing [realmname], [agentname], [adminID] and [passwordfile] with appropriate values.

When this enabled, the protocol part of the incoming request is overridden with the one specified in the com.sun.identity.agents.config.agenturi.prefix property, so you also need to ensure this is set appropriately.

Note

You should enable this property if the policy agent sits behind a SSL/TLS offloader, a load balancer or a proxy, and the protocol used by users is different to the protocol used by the policy agent.

You can set this property using either the console or ssoadm:

  • AM 6 and later console: navigate to: Realms > [Realm Name] > Applications > Agents > Web > [Agent ID] > Global > Agent Deployment URI Prefix and specify the correct URI.
  • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > Agents > Web > [Agent Name] > Global > Profile > Agent Deployment URI Prefix and specify the correct URI.
  • OpenAM 13.x console: navigate to: Realms > [Realm Name] > Agents > Web > [Agent Name] > Global > Profile > Agent Deployment URI Prefix and specify the correct URI.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Agents > Web > [Agent Name] > Global > Profile > Agent Deployment URI Prefix and specify the correct URI.
  • ssoadm: enter the following command:
    $ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a com.sun.identity.agents.config.agenturi.prefix=[URI]
    replacing [realmname], [agentname], [adminID], [passwordfile] and [URI] with appropriate values.

Example

For example, with the following settings:

Load balancer URL=http://host1.example.com:8080
com.sun.identity.agents.config.override.protocol=true
com.sun.identity.agents.config.agenturi.prefix=https://agent.example.com:443/amagent 

When a request is received, the policy agent overrides the protocol part of the incoming URL (http) with the protocol specified in com.sun.identity.agents.config.agenturi.prefix (https) and uses this for the goto parameter.

See Also

How do I configure a Java Policy Agent (All versions) for SSL offloading?

How do I configure SSL offloading at the Policy Agent (All versions) for virtual hosts?

FAQ: SSL/TLS secured connections in AM/OpenAM and Policy Agents

Agents and policies in AM/OpenAM

User Guide › Configuring Advanced Properties

User Guide › Configuring Global Properties

Related Training

N/A

Related Issue Tracker IDs

OPENAM-3375 (IIS6 notification mode does not work if SSL offloading is done at a loadbalancer)


How do I configure a Java Policy Agent (All versions) for SSL offloading?

The purpose of this article is to provide guidance on configuring a Java Policy Agent for SSL offloading to ensure the policy agent can redirect to the URL in the goto parameter successfully, even if this parameter uses protocol http instead of https.

Configuring a policy agent for SSL offloading

You can configure a Java policy agent for SSL offloading using either the console or ssoadm:

  • AM 6 and later console: navigate to: Realms > [Realm Name] > Applications > Agents > Java > [Agent ID] > Advanced > Alternate Agent URL > Alternative Agent Protocol and enter the required protocol (http or https).
  • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > Agents > J2EE > [Agent Name] > Advanced > Alternate Agent URL > Alternative Agent Protocol and enter the required protocol (http or https).
  • OpenAM 13.x console: navigate to: Realms > [Realm Name] > Agents > J2EE > [Agent Name] > Advanced > Alternate Agent URL > Alternative Agent Protocol and enter the required protocol (http or https).
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Agents > J2EE > [Agent Name] > Advanced > Alternate Agent URL > Alternative Agent Protocol and enter the required protocol (http or https).
  • ssoadm: enter the following command:
    $ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a com.sun.identity.agents.config.agent.protocol=[protocol]
    replacing [realmname], [agentname], [adminID], [passwordfile] and [protocol] with appropriate values.

When this is specified, the protocol part of the incoming request is overridden with the one specified here.

Note

You should specify this property if the policy agent sits behind an SSL/TLS offloader, a load balancer or a proxy, and the protocol used by users is different to the protocol used by the policy agent.

Example

For example, with the following settings:

Load balancer URL=http://host1.example.com:8080
com.sun.identity.agents.config.agent.protocol=https

When a request is received, the policy agent overrides the protocol part of the incoming URL (http) with the protocol specified in com.sun.identity.agents.config.agent.protocol (https) and uses this for the goto parameter.

See Also

How do I configure a Web Policy Agent (All versions) for SSL offloading?

How do I configure SSL offloading at the Policy Agent (All versions) for virtual hosts?

FAQ: SSL/TLS secured connections in AM/OpenAM and Policy Agents

Agents and policies in AM/OpenAM

User Guide › Configuring Advanced Properties

User Guide › Configuring Java Agents Behind Load Balancers

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I configure SSL offloading at the Policy Agent (All versions) for virtual hosts?

The purpose of this article is to provide information on configuring SSL offloading at the Policy Agent (Web and Java) for virtual hosts. It is assumed that you have correctly configured your virtual hosts for SSL; you must specify the SSL parameters in all the ssl vhost sections rather than just the default ssl vhost.

Configuring SSL offloading at policy agent

You can configure SSL offloading at the policy agent using either the console or ssoadm:

  • AM 6 and later console: navigate to: Realms > [Realm Name] > Applications > Agents > Web or Java > [Agent ID] > Global > FQDN Virtual Host Map and enter the virtual host domain name you want to map in the 'Map Key' field and the actual FQDN in the 'Corresponding Map Value' field.
  • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > Agents > Web or J2EE > [Agent Name] > Global > Fully Qualified Domain Name Checking > FQDN Virtual Host Map and enter the virtual host domain name you want to map in the 'Map Key' field and the actual FQDN in the 'Corresponding Map Value' field.
  • OpenAM 13.x console: navigate to: Realms > [Realm Name] > Agents > Web or J2EE > [Agent Name] > Global > Fully Qualified Domain Name Checking > FQDN Virtual Host Map and enter the virtual host domain name you want to map in the 'Map Key' field and the actual FQDN in the 'Corresponding Map Value' field.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Agents > Web or J2EE > [Agent Name] > Global > Fully Qualified Domain Name Checking > FQDN Virtual Host Map and enter the virtual host domain name you want to map in the 'Map Key' field and the actual FQDN in the 'Corresponding Map Value' field.
  • ssoadm: enter the following command:
    $ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a com.sun.identity.agents.config.fqdn.mapping=[[domainname]]=[FQDN]
    replacing [realmname], [agentname], [adminID], [passwordfile], [domainname] and [FQDN] with appropriate values. For example, if you have a virtual host domain name of example.net and your FQDN is host1.example.com, you would specify this property as follows in the ssoadm command:
    com.sun.identity.agents.config.fqdn.mapping=[example.net]=host1.example.com
Note

You should set up FQDN mapping for all virtual hosts; if a domain can be reached with and without www, you should specify mapping for both variants. For example, [example.net]=host1.example.com and [www.example.net]=www.host1.example.com

This FQDN mapping will allow you to access the policy agent on different FQDNs but won't affect how policies are evaluated; the policy rule must still match the requested URL for it to be evaluated. 

See Also

How do I configure a Web Policy Agent (All versions) for SSL offloading?

How do I configure a Java Policy Agent (All versions) for SSL offloading?

FAQ: SSL/TLS secured connections in AM/OpenAM and Policy Agents

Agents and policies in AM/OpenAM

Web Agents 5 User Guide › Configuring Global Properties

Java Agents 5 User Guide › Configuring Global Properties

Related Training

N/A

Related Issue Tracker IDs

N/A


Policies


Best practice for creating and testing policies in AM/OpenAM (All versions)

The purpose of this article is to provide best practice advice on creating and testing policies in AM/OpenAM. This article also looks at the types of issues you may encounter when your policy is not evaluated as expected as well as troubleshooting your policy evaluation issues. These types of issue can be difficult to troubleshoot as the authorization process involves a succession of components, where policy evaluation is the last component in the process.

Tips for creating policies

Note

As of OpenAM 13, referral policies are no longer available in OpenAM. If you are upgrading from a previous version of OpenAM and currently use referral policies, please refer to OpenAM 13 Upgrade Guide › Upgrading OpenAM Servers for migration information.

The following recommendations should be followed when creating your policies:

  • Always create the rules in the same order - Typically you will want to create 3 rules (for all policies, including referral policies in OpenAM 12.x) to define policies that access either the top level realm or a specific realm, depending on your setup:
     Top level realm
    • root "/"
    • pages "/*"
    • pages with parameters "/*?*"
    A specific realm, for example, /customers
    • root "/customers"
    • pages "/customers/*"
    • pages with parameters "/customers/*?*"
    We recommend you always create them in the same order to reduce the likelihood of forgetting to create a rule, especially if you have a lot of rules to create.
  • Use deny rules with caution - It is preferable to add explicit allow rules for each protected area individually, rather than create one big global rule and restrict access through deny rules where needed. If you have a global access policy, this allows access to all authenticated users unless you explicitly define a deny policy; forgetting to set the deny policy or setting it incorrectly could be a security risk. When deciding on the use of deny policies for restricted areas, you should take into account the balance between maintainability, performance and security.
  • Never include a forward slash in policy names - You will not be able to edit or delete policies with the forward slash character in their names if you are running Apache Tomcat™ or JBoss® web containers without setting:
    ‑Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true
    in the CATALINA_OPTS environment variable before starting the AM/OpenAM web container. However, it is strongly recommended that you do not set this argument when running AM/OpenAM in production as it introduces a security risk. See OpenAM 12.0.0 Release Notes › Important Changes to Existing Functionality for further information.
  • Never include special characters in your policy names - The special characters to avoid are: double quotes ("), plus sign (+), comma (,), less than (<), equals (=), greater than (>), backslash (\), and null (\u0000).

Known issues

Policies with a forward slash at the end of the policy name

There is a known issue with forward slashes at the end of policy names regardless of web containers: OPENAM-5400 (Policy Editor: Unable to edit/delete policy whose name ends in a '/' character). This issue will affect you even if you are not running the Tomcat or JBoss web containers. This is fixed in OpenAM 12.0.3. 

Policies with a ? in the rule name

There is a known issue which prevents policies with ? in rule names being edited: OPENAM-5364 (11.0 format policies with "?" in the rule name cannot be edited by the Policy Editor). This is fixed in OpenAM 12.0.3.

Policies using root or subtree mode

There are known issues with inconsistent policy evaluation using root or subtree mode: 

It is recommended that you use non-root or self mode (default mode). Details of how to change the mode are given in Unreliable policy evaluation results when using root or subtree mode in OpenAM 12.x or 13.x.

Application changes once a policy has been added

There is a known issue where you cannot rename an application or edit the resources once policies have been added to the application: OPENAM-5114 (User should be able to rename or clone an existing Application containing policies without first deleting the policies). This is fixed in AM 5.

Creating a complex policy

If you want to create a complex policy, that is one that includes multiple subject and environment conditions, we recommend that you split the process into separate steps. You can then test after completing each step to ensure it is correct prior to starting the next step. This will make troubleshooting a lot easier as you will know which step introduced the issue.

The recommended way to create a complex policy is:

  1. Create a policy for the default application type (iPlanetAMWebAgentService) and specify resources and actions to which the policy applies.
  2. Add a subject condition, select All Authenticated Users as the subjects who the policy applies to. You can refine this access later but it is preferable to start with everyone having access when creating a new complex policy.
  3. Test your simple policy (as detailed in the Testing a policy section).
  4. Define an environment condition and test.
  5. Create further subject and environment conditions as needed, testing as you go to make sure each addition works correctly.
  6. Add any response attributes you require and test.

See Authorization Guide › Introducing Authorization for further information on creating policies. 

Testing a policy

You should test your policy during creation (as discussed in the Creating a complex policy section) and after creation. We recommend you test your policy using the REST API as this calls the XACMLRequestProcessor class directly.

You would use a curl command similar to this; the URL changes depending on which version you are using. For example:

  • AM 5 and later:
    $ curl -X POST -H "iPlanetDirectoryPro: AQIC5...DU3*" -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.0" -d '{
        "resources": [
            "http://www.example.com/index.html",
            "http://www.example.com/do?action=run"
        ],
        "application": "iPlanetAMWebAgentService"
     }' https://host1.example.com:8443/openam/json/realms/root/policies?_action=evaluate
    
  • Pre-AM 5:
    $ curl -X POST -H "iPlanetDirectoryPro: AQIC5...DU3*" -H "Content-Type: application/json" -d '{
        "resources": [
            "http://www.example.com/index.html",
            "http://www.example.com/do?action=run"
        ],
        "application": "iPlanetAMWebAgentService"
     }' https://host1.example.com:8443/openam/json/policies?_action=evaluate

Example response that shows both resources being accepted (actions are populated and set to true):

[{"ttl":9223372036854775807,"advices":{},"resource":"http://www.example.com/index.html","actions":{"HEAD":true,"DELETE":true,"POST":true,"GET":true,"OPTIONS":true,"PATCH":true,"PUT":true},"attributes":{}},{"ttl":9223372036854775807,"advices":{},"resource":"http://www.example.com/do?action=run","actions":{"HEAD":true,"DELETE":true,"POST":true,"GET":true,"OPTIONS":true,"PATCH":true,"PUT":true},"attributes":{}}]

Example response that shows the first resource being denied (empty response for actions signifying a deny) and the second one being accepted:

[{"ttl":9223372036854775807,"advices":{},"resource":"http://www.example.com/do?action=run?help","actions":{},"attributes":{}},{"ttl":9223372036854775807,"advices":{},"resource":"http://www.example.com/index.html","actions":{"HEAD":true,"DELETE":true,"POST":true,"GET":true,"OPTIONS":true,"PATCH":true,"PUT":true},"attributes":{}}]

See Authorization Guide › Requesting Policy Decisions for further information and example curl commands. 

Note

You could develop a test suite with the REST API to make testing policies easier; this is especially useful if you are likely to update your policies frequently.

Raising a support ticket for a policy issue

If you are experiencing issues with your policies, where they are not being evaluated as expected, you can raise a support ticket. You should follow this process to ensure you include all the necessary information in your ticket to help us investigate your issues more effectively:

Caution

It is very important that your timestamps match across the entire set of logs and HTTP trace. Failing to do this may mean you need to capture ALL the data again.

  1. Export AM/OpenAM and policy configurations - it is essential to check if there is a configuration issue contributing to your policy issues. You can export these as described in How do I export and import policies in AM/OpenAM (All versions)? and How do I export and import Service configurations for AM/OpenAM (All versions)?
  2. Identify the stage at which the policy evaluation failed - if you have followed the steps in the Creating a complex policy section, you can let us know which step failed testing to help us identify the root cause.
  3. Generate a full set of debug logs and capture the HTTP trace while reproducing the issue. Refer to How do I collect all the data required for troubleshooting AM/OpenAM and Policy Agents (All versions)? for information on how to collect this data.
  4. Capture HTTP container logs (Access and Error) for both AM/OpenAM and policy agents with date and timestamps that correspond to the policy agent and AM/OpenAM debug logs. HTTP container logs show all requests to the server, whether they were successful or not and any corresponding error messages.
  5. Capture LDAP server logs for your data store and configuration store with date and timestamps that correspond to the policy agent and AM/OpenAM debug logs. There are some use cases that require analysis of the LDAP server logs from the AM/OpenAM data store (user profile) and Configuration store. 
  1. Attach the following diagnostic logs and outputs to your support request as detailed in Sending troubleshooting data to ForgeRock Support for analysis 
    • AM/OpenAM and policy configuration exports.
    • Log files from:
      • AM/OpenAM$HOME/[am_instance]/openam/debug and $HOME/[am_instance]/openam/logs
      • Policy Agent /path/to/policy_agent/[agent_instance]/logs/debug directory where the policy agent is installed.
      • HTTP trace - from the HTTP trace browser tool.
      • HTTP container logs - the actual name and location of the server logs are specific to your web container. For example, for AM/OpenAM deployed on Apache Tomcat, the Tomcat logs are called localhost_access_log.YYYY-MM-DD.log and catalina.out, and are located in the /path/to/tomcat/logs/ directory by default.
      • LDAP server logs - for embedded OpenDJ, these log files are located in the $HOME/[am_instance]/opends/logs directory by default and for external OpenDJ, they are located in the /path/to/ds/logs directory.
    • Output from the curl command and response.
  2. Update your ticket to let us know the timestamp(s) of when the issue was reproduced (so we can correlate this with the logs) and AM/OpenAM and Policy Agent versions; some issues are version specific so knowing your version will help us focus on relevant issues only.
Note

Refer to Best practice for raising a ticket with ForgeRock Support for further information on creating a ticket. Follow this guide for submitting technical information needed to help us resolve your issue as soon as possible.

See Also

Best practice for migrating policies when upgrading to OpenAM 12.x or 13.x

Upgrade to OpenAM 12.x or 13.x fails with Failed to modify privilege! message when migrating policies

Policy import fails in OpenAM 13.0 with Invalid resource type null message

Troubleshooting AM/OpenAM and Policy Agents

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

OPENAM-2085 (Unreliable policy evaluation results with com.sun.identity.agents.config.fetch.from.root.resource enabled)

OPENAM-5114 (User should be able to rename or clone an existing Application containing policies without first deleting the policies)

OPENAM-5163 (Policy Self mode and Subtree mode behaves differently)

OPENAM-5187 (Can't delete a migrated policy using Policy Editor)

OPENAM-5364 (11.0 format policies with "?" in the rule name cannot be edited by the Policy Editor)

OPENAM-5400 (Policy Editor: Unable to edit/delete policy whose name ends in a '/' character)

OPENAM-5441 (upgrade from 12.0.0 to 13.0.0 fails)

OPENAM-6013 (Resource types are missing in XACML exported policy and it is not possible to import it)


How do I export and import policies in AM/OpenAM (All versions)?

The purpose of this article is to provide information about exporting and importing your policies in AM/OpenAM. This can provide a quick way to update or add new policies as you can edit the exported policies before importing them. It also provides an easy way of copying policies to different realms or backing up policies.

Exporting and importing policies

You can export and import policies in JSON format (as of OpenAM 13.5) or in XACML (eXtensible Access Control Markup Language) format. Using JSON creates an exact copy of the original policy sets, resource types and policies upon import. See Authorization Guide › Importing and Exporting Policies for a more detailed comparison.

Refer to the following links for further information:

Known issues

Using Amster

You can export and import policies using Amster as follows.

Export

Use the following command to export: 

am> export-config --path /path/to/export --realm / --realmEntities 'Policies'

Details for each policy will be written to a separate JSON file in the Policies directory within /path/to/export/realms/[realmName].

Import

Use the following command to import: 

am> import-config --path /path/to/export

See Also

User Guide › Using the Amster Command-line Interface

Entity Reference › Policies

Reference › ssoadm

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

OPENAM-11584 (Ssoadm policy-import/export throws Guice error)

OPENAM-6013 (Resource types are missing in XACML exported policy and it is not possible to import it)

OPENAM-1601 (ssoadm list-policies fails with NoClassDefFound)


How do I add additional HTTP actions to make them available to policies in AM/OpenAM (All versions)?

The purpose of this article is to provide information on adding non-standard HTTP actions to make them available to policies so they can return an Allow/Deny. For example, this may be useful if you want to enable support for WebDAV HTTP methods.

Adding additional HTTP actions

As of OpenAM 13.0, you can add an action directly via the console as described in Authorization Guide › Implementing Authorization › Configuring Policies. For OpenAM 12.x, you must add the actions as detailed below. You can also use a similar approach if you want to make these changes in AM / OpenAM 13.x without using the console. The only difference is you would update the application type template in step 1 as detailed in Authorization Guide › Implementing Authorization › Managing Application Types and then follow the remaining steps.

OpenAM 12.x

Note

If you want to update an application that already contains policies, you must remove those policies from the application first. You can preserve the policies by doing an export before updating your application and then reimporting the policies after as described in How do I export and import policies in AM/OpenAM (All versions)?

You can add additional HTTP actions as follows:

  1. Create a new application (or update an existing one if preferred) to add the required new actions as described in OpenAM Developer's Guide › RESTful Authorization and Policy Management Services › Defining Applications. For example, for WebDAV, you would need to include the PROPFIND action, so your actions section would look similar to this:
        "actions": {
            "PROPFIND": true,
            "UPDATE": true,
            "PATCH": true,
            "QUERY": true,
            "CREATE": true,
            "DELETE": true,
            "READ": true,
            "ACTION": true
        }
    
  2. Back up the amWebAgent.xml file (located in the $HOME/[am_instance]/config/xml directory).
  3. Edit the amWebAgent.xml file and include the following Attribute schema details to add any new HTTP actions. For example, to add the PROPFIND action:
    <AttributeSchema name="PROPFIND"
      type="single"
      syntax="boolean"
      uitype="radio"
      i18nKey="PUT">
      <IsResourceNameAllowed/>
      <BooleanValues>
        <BooleanTrueValue i18nKey="allow">allow</BooleanTrueValue>
        <BooleanFalseValue i18nKey="deny">deny</BooleanFalseValue>
      </BooleanValues>
    </AttributeSchema>
    
  4. Run the following ssoadm command to import the amended file:
    $ ./ssoadm update-svc -X amWebAgent.xml -u [adminID] -f [passwordfile]
    replacing [adminID] and [passwordfile] with appropriate values.
  5. Restart the web application container in which OpenAM runs to apply these configuration changes.

See Also

Authorization Guide › Implementing Authorization

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I reduce the number of policy matches in AM/OpenAM (All versions)?

The purpose of this article is to provide information on changes you can make to your policy rules to reduce the number of policy matches, which in turn reduces the time it takes for AM/OpenAM to evaluate policies.

Reducing the number of policy matches

There are a number of changes you can make to your policy rules to reduce the the number of policy matches including:

Avoid using wildcards (*)

Always use the full protocol, hostname and port number where ever possible in your policy rules rather than using a wildcard (*).

For example, instead of using: http*://*/test/test.dll/* to cover multiple policy rules, you can separate them out and make them more specific to reduce policy matches, for example:

  • http://example.com:8080/test/test.dll/*
  • https://example.net:8080/test/test.dll/*
  • https://example.com:18080/test/test.dll/*

This technique should also be applied to referral policies from the top level or parent realm in pre-OpenAM 13.0 (referral policies are not available as of OpenAM 13.0). Referral policies are evaluated against the realm to which they refer. If the referral policies use * for the hostname, OpenAM must search all realms for policy matches along with subject rule searches such as groups. This increases the query load on the LDAP server and is inefficient compared to using specific rules in your referral policies.

Use the not enforced URL list

Add URLs for files such as images, JavaScript and css to the Not Enforced URL list to prevent these URLs being evaluated.

You should also ensure the Fetch Attributes for Not Enforced URLs option is not enabled unless specifically required.

Note

You must restart the web application container in which OpenAM runs to apply these policy rule changes if you are using a pre-11.0.2 version of OpenAM.

See Also

Authorization Guide › Introducing Authorization

Web Policy Agent Guide › Reference › Configuring Web Policy Agent Application Properties

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

OPENAM-2460 (Policy evaluation may hang with large number of matching referral privileges)

OPENAM-3626 (Changes to policy rules only take effect after restarting OpenAM)


How do I share values between scripted policies in AM/OpenAM (All versions)?

The purpose of this article is to provide information on sharing values between scripted policies in AM/OpenAM. The only variable you can share between privileges/policies is the environment variable.

Background information

The only variable you can share between privileges/policies is the environment variable as explained here.

The ScriptCondition class sets the following objects, which makes them accessible to scripts:

scriptVariables.put("logger", PolicyConstants.DEBUG);
scriptVariables.put("username", SubjectUtils.getPrincipalId(subject));
scriptVariables.put("resourceURI", resourceName);
scriptVariables.put("environment", environment);
scriptVariables.put("advice", advice);
scriptVariables.put("responseAttributes", responseAttributes);
scriptVariables.put("httpClient", getHttpClient(configuration.getLanguage()));
scriptVariables.put("authorized", Boolean.FALSE);
scriptVariables.put("ttl", Long.MAX_VALUE);
// If a token is present include the corresponding identity and session objects.
scriptVariables.put("identity", new ScriptedIdentity(coreWrapper.getIdentity(ssoToken)));
scriptVariables.put("session", new ScriptedSession(ssoToken));

As you can see, the SSOToken is wrapped in a class called "ScriptedSession" which only exposes the getProperty() method, not setProperty() like the original SSOTokenImpl class did. Therefore, the only variable you can use to share between privileges/policies is environment (for example, environment.get() and environment.put() ).

Example

The following example demonstrates two policies sharing the environment variable:

  1. Set up your policies:
    TestPolicy01 :
        http://agent.example.com:38080/helloworld/index*.html
        All of ... Authentication by Module Chain=ldapService
                      Script=TestPolicyCondition01
    TestPolicy02 :
     http://*.example.com:38080/helloworld/index.html
        All of ... Script=TestPolicyCondition02
    
  2. Create a simple script:
    if (!environment) {
        logger.warning("TestPolicyCondition01:: No environment parameters specified in the evaluation request.");
        authorized = false;
    }
    
    var test = environment.get("test");
    if (test == null) {
        logger.warning("No test specified in the evaluation request environment parameters.");
     environment.put("test", "testvalue1");
    } else {
        logger.message("TestPolicyCondition01:: test=" + test);
    
    }
    
    authorized = true;
    
  3. Use a curl command such as the following to evaluate both policies; the server URL for the endpoint differs depending on which version you are using. For example:
    • AM 5 and later:
      $ curl -X POST -H "iPlanetDirectoryPro: AQIC5...DU3*" -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.0" -d '{
          "resources": [
              "http://agent.example.com:38080/helloworld/index.html"
          ],
          "application": "iPlanetAMWebAgentService",
          "subject": { "ssoToken": "AQIC...*"}
      }' http://host1.example.com:8080/openam/json/realms/root/policies?_action=evaluate
      
    • Pre-AM 5:
      $ curl -X POST -H "iPlanetDirectoryPro: AQIC5...DU3*" -H "Content-Type: application/json" -d '{
          "resources": [
              "http://agent.example.com:38080/helloworld/index.html"
          ],
          "application": "iPlanetAMWebAgentService",
          "subject": { "ssoToken": "AQIC...*"}
      }' http://host1.example.com:8080/openam/json/policies?_action=evaluate
      
  4. Verify that the test value is shared between the policies in the Entitlement debug log. This example indicates which messages have been printed by which policy:
    Entitlement:10/06/2018 03:07:24:873 PM BST: Thread[pool-15-thread-5,5,main]: TransactionId[52169231-8063-4d1e-9156-20d18c8e22f6-1527]
    WARNING: No test specified in the evaluation request environment parameters.  <--- printed from TestPolicy02
    Entitlement:10/06/2018 03:15:11:456 PM BST: Thread[http-bio-18080-exec-6,5,main]: TransactionId[52169231-8063-4d1e-9156-20d18c8e22f6-1527]
    CachingEntitlementCondition.evaluate() caching condition decision "true" for condition: org.forgerock.openam.entitlement.conditions.environment.ScriptCondition{ "scriptId": "5107450e-0167-4369-8f67-23c18d214149" }
    :
    Entitlement:10/06/2018 03:15:14:062 PM BST: Thread[pool-15-thread-6,5,main]: TransactionId[52169231-8063-4d1e-9156-20d18c8e22f6-1527]
    TestPolicyCondition01:: test=testvalue2. <--- printed from TestPolicy01
    
Note

This example is just a simple sample to demonstrate the concept. You should adjust it to fit your requirements.

See Also

How do I create a policy condition script in AM/OpenAM (All versions)?

FAQ: Configuring policies in AM/OpenAM

Agents and policies in AM/OpenAM

Authorization Guide › Scripting a Policy Condition

Authorization Guide › Requesting Policy Decisions

Related Training

N/A

Related Issue Tracker IDs

N/A


Frequently Asked Questions


FAQ: Installing Policy Agents in AM/OpenAM

The purpose of this FAQ is to provide answers to commonly asked questions regarding installing policy agents in AM/OpenAM.

Frequently asked questions

Q. What is the difference between Web and Java policy agents?

A. Web policy agents protect services and web resources hosted on a web or proxy server, whereas Java policy agents protect resources hosted on application or portal servers. Although the primary role of the two types of agents is to enforce authentication and authorization to a protected resource, they differ in the way policy decisions are enforced.

The following chapters provide detailed interactions for both Agent types.

Q. Are any of the policy agents compatible with Oracle Java Development Kit (JDK) 11?

A. Yes, as of Java Agents 5.6, Oracle JDK 11 is supported. You should only use supported versions to prevent compatibility issues.

Q. Is there a Web policy agent that is compatible with IBM AIX?

A. Yes, support for IBM AIX has been provided since Web policy agent 4. Web Agent 5 supports IBM AIX 6 and 7. See Release Notes › Platform Requirements for further information on supported platforms.

Q. Is there a Web policy agent that is compatible with IBM HTTP Server (IHS)?

A. No, IHS is currently an unsupported platform. Although IBM Httpd was forked from Apache™, it is no longer the same as Apache which is why you cannot use an Apache policy agent. 

IHS 9 will be supported on AIX only in a future release.

Q. Is there a Web policy agent for the NGINX Plus web server?

A. Yes, the NGINX Plus web server has been supported since Web Policy Agent 4.1.0. Web Agent 5 supports NGINX Plus R12 and R13 on CentOS™, RedHat Enterprise Linux®, Ubuntu® and Oracle Linux.

See Web Policy Agent 4.1 Release Notes › What's New in Web Policy Agents and User Guide › Installing the NGINX Plus Web Agent for further information.

Why are different platform versions required? 

The vast majority of the kernel options specified in the ngx_auto_config.h files (used during the agent build) need to be identical to the ones on the NGINX server, else the policy agent will fail its checks and will not load. As such, different platform specific versions of the policy agent are available and you should ensure you use the correct version.

If you use the wrong version for your platform, you will likely encounter binary compatibility issues and see errors such as:

"/opt/web_agents/nginx12_agent/lib/openam_ngx_auth_module.so" is not binary compatible in /etc/nginx/nginx.conf:1

Q. Is the Pivotal TC Server supported?

A. The Pivotal TC Server is a Web application server based on open-source Apache Tomcat™, but it is customized in a way that the configuration filename and its location etc are not compliant with the default Tomcat server. For example:

pivotal-tc-server-developer-3.1.7.RELEASE/templates/base-tomcat-7/conf $ls
catalina-fragment.properties    catalina.policy      logging-fragment.properties    server-fragment.xml  web-fragment.xml

pivotal-tc-server-developer-3.1.7.RELEASE/tomcat-7.0.72.B.RELEASE $ls
LICENSE    NOTICE    bin    lib

As such, Java policy agents cannot install on the Pivotal TC Server by default, it has not been tested nor is it supported. If you encounter any issues running on the Pivotal TC Server, you will be asked to reproduce them on a supported container.

Q. What is the difference between centralized and local configuration for policy agents?

A. All policy agents need to have a profile in AM/OpenAM. Besides providing the policy agent name and password, AM/OpenAM URL and policy agent server URL, the profile also defines whether the policy agent is configured locally or centrally. See Setup and Maintenance Guide › Setting Up Policy Agent Profiles for further information.

Centralized

Centralized configuration is the preferred option and is the default. It allows administrators to manage multiple policy agent configurations from a central place, using either the console or ssoadm. Most of the policy agent configuration properties are defined in AM/OpenAM and must be configured within AM/OpenAM. All policy agent configuration and profile information is stored in the AM/OpenAM configuration store. When changes are made to centralized configuration data, a change notification is sent to the affected policy agent, which triggers them to reload the latest configuration. If you are using a load balancer, the notification is sent directly to the policy agent without going via the load balancer.

Local

With local configuration, the only information contained in AM/OpenAM is the details provided when creating the profile (policy agent name and password, AM/OpenAM URL, policy agent server URL and the fact that it is configured locally). The rest of the information is stored in a local configuration file as follows depending on your policy agent. When changes are made to local configuration data, a server restart is required for them to take effect. The name and location of the local configuration file varies depending on the agent and version:

  • Web Policy Agents - the agent.conf file located in the /path/to/web_agents/agent_version/instances/Agent_nnn/config directory.
  • Java Agents 5.x and later - the OpenSSOAgentConfiguration.properties file located in the /path/to/java_agents/agent_type/agent_instance/ directory. 
  • JEE Policy Agents 3.5.x - the OpenSSOAgentConfiguration.properties file located in the /config directory where the policy agent is installed.

See User Guide › Configuring Web Agent Properties and User Guide › Configuring Java Agent Properties for further information on these configuration properties.

Note

In both centralized and local configurations, properties used when the policy agent is started are captured in a local file. This is the same agent.conf file detailed above for Web Policy Agents. For Java Policy Agents, a separate file called OpenSSOAgentBootstrap.properties is used (see next question for information on the bootstrap file).

Q. How is the policy agent bootstrap file used?

A. Policy agent properties are separated into those properties that are read and used at bootstrap time, and those that are not:

  • Web Policy Agents - all properties are stored in the agent.conf file (located in the /path/to/web_agents/agent_version/instances/Agent_nnn/config directory). The properties specific to bootstrap time are only available in the agent.conf file, whereas the other properties are also available in AM/OpenAM if your policy agent is configured centrally.
  • Java Agents 5.x and later - there are two files: the bootstrap file (OpenSSOAgentBootstrap.properties located in the /config directory where the policy agent is installed) and the properties file (OpenSSOAgentConfiguration.properties located in the /path/to/java_agents/agent_type/agent_instance/ directory). See User Guide › Configuring Java Agent Properties for further information about these files.
  • JEE Policy Agents 3.5.x - there are two files in the /config directory where the policy agent is installed: the bootstrap file (OpenSSOAgentBootstrap.properties) and the properties file (OpenSSOAgentConfiguration.properties). See OpenAM JEE Policy Agent User's Guide › Configuring Java EE Policy Agent Properties for further information about these files.
Caution

If your policy agent configuration is not in the top-level realm (/), you must edit agent.conf or OpenSSOAgentBootstrap.properties to identify the sub-realm that has your policy agent configuration. Update the com.sun.identity.agents.config.organization.name property to change the / to the path to your policy agent profile. This allows the policy agent to properly identify itself to the AM/OpenAM server. 

When you start the policy agent, it reads and parses the file(s). It then uses the naming URL property from the bootstrap data to connect to AM/OpenAM and check if the policy agent is configured locally or centrally (remotely); if you are running remotely, a REST API call is used to fetch properties from the AM/OpenAM configuration data store and the properties (in memory) are overwritten with the centralized configuration.

Java Policy Agents

Some properties, such as debug level, exist in both the bootstrap file and AM/OpenAM (centralized configuration) or the configuration file (local configuration). In such cases, the value set for the bootstrap property is used at startup and is then overwritten once the bootstrap process is finished. For example, if you are troubleshooting an issue at startup, you should set up the debug level to all:5 in the bootstrap file; however, if you are troubleshooting an issue such as policy evaluation, you can modify the property centrally in AM/OpenAM (if you have centralized configuration) without needing a restart.

Q. Why do I see "Another instance of agentadmin is already running" error when trying to install the Java agent?

A. The following error is shown when the Java agent agentadmin installer is aborted with the Ctrl+Z key combination instead of Ctrl+C:

ERROR: Another instance of agentadmin is already running. Please stop that instance and try again.

This key combination issues a Linux/Unix® command that suspends the process. You can resume the process by typing fg in the terminal and pressing Enter. At this point, you can choose to continue with the installation or type Ctrl+C to exit. 

Alternatively, you can remove the Agentadmin.lock file located in /path/to/java_agents/agent_type/installer-logs/ to resolve the error and begin a fresh installation. 

See Also

Best practice for installing IIS Web Policy Agents (All versions)

FAQ: Configuring Policy Agents in AM/OpenAM

Agents and policies in AM/OpenAM

Installing and configuring AM/OpenAM

Web Agents User Guide

Java Agents User Guide

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

OPENAM-11104 (Tomcat Admin changes done by J2EEAgent not described (AMLogin.html))


FAQ: Configuring Policy Agents in AM/OpenAM

The purpose of this FAQ is to provide answers to commonly asked questions regarding configuring policy agents in AM/OpenAM.

Frequently asked questions

Q. Can a policy agent protect multiple realms?

A. No, a policy agent can only protect one realm; this means a policy agent cannot send some users to realmA for authentication whilst sending other users to realmB. You can however configure policy agents to authenticate users in a different realm to one in which the agent is configured. See How do I configure Agents 5.x to authenticate users against a specific realm, tree or authentication module in AM? or How do I configure policy agents (Web 4.x and JEE 3.5.x) to authenticate users against a specific realm in AM/OpenAM? for further information.

Authentication to a specific realm is not enforced when you configure your policy agent for SSO only. SSO only mode verifies that a user has authenticated and that the authentication is valid, but it does not take into account the realm from which the authentication originated. It's one of the few components that doesn't automatically enforce realm authentication; therefore, any user with a valid SSO token is allowed in SSO only mode. 

If you want the policy agent to enforce that a user must be authenticated to a specific realm, you must also configure a policy with an Environment Condition of type Authentication to a Realm and specify the required realm. See Authorization Guide › Configuring Policies and Setup and Maintenance Guide › Working With Realms and Policy Agents for further details.

Q. Is it possible to protect virtual hosts with policy agents?

A. Yes, it is possible to protect virtual hosts with the web policy agent. Web policy agents 4.x and later support installing policy agents into multiple virtual hosts on Apache web servers, where each virtual host has its own web policy agent configuration. 

Q. Can I protect REST endpoints with a policy agent?

A. Not currently, although there are plans to provide a REST policy agent for this purpose. An RFE has been raised for this: OPENAM-3635 (Improve agent's MIME type when valid session does not exist).

Q. Why is URL encoding different between web policy agent versions?

A. There have been changes in the way web policy agents 4.x encode URLs to improve RFC3986 compliance and to prevent double encoding. This is discussed in OPENAM-6674 (Address issues with Agent 3/Agent 4 URL encoding differences).

In web policy agents 4.x and later, spaces in the query parameter are set to +, otherwise they are set to %20. For security reasons and also for validating URLs (such as the ones used for non-enforced checking), the URL is parsed first and then the double slashes in the path are removed. This means it is decoded before encoded, which prevents %20 being double encoded as it was in web policy agents 3.x.

There is a known issue in IIS policy agents 4.0, where the space is incorrectly handled: OPENAM-8179 (WPA4 for IIS does not handle space character in request url). This is fixed in web policy agents 4.0.1.

Q. Why is the hostname, port and/or protocol being replaced in the goto URL for my agent protected application?

A. Override request URL properties exist, which can be set when configuring a web policy agent for SSL offloading. When the Agent Deployment URI Prefix (com.sun.identity.agents.config.agenturi.prefix) property is set along with one or more of the following properties, the respective element in the URL is overridden with the value set in the Agent Deployment URI Prefix:

  • Override Request URL Protocol (com.sun.identity.agents.config.override.protocol) - when enabled, the protocol is overridden with the value from the Agent Deployment URI Prefix.
  • Override Request URL Host (com.sun.identity.agents.config.override.host) - when enabled, the host is overridden with the value from the Agent Deployment URI Prefix.
  • ​Override Notification URL (com.sun.identity.agents.config.override.notification.url) - when enabled, the URL is overridden with the value from the Agent Deployment URI Prefix. This property is not supported in Web agents 5.
  • Override Request URL Port (com.sun.identity.agents.config.override.port) - when enabled, the port is overridden with the value from the Agent Deployment URI Prefix.

See How do I configure a Web Policy Agent (All versions) for SSL offloading? and User Guide › Configuring Web Agent Properties for further information.

Q. Why does the fragment identifier disappear from the URL after the web policy agent redirects?

A. Web policy agents don't have access to the fragment identifier (also called hash or anchor) part of the originally requested URL as it never leaves the browser in the HTTP request. This means the part of the URL after # is dropped upon redirect. An RFE has been raised for this: OPENAM-2164 (RFE: Web agents should include the fragment identifier of the original URL on redirect).

Q. What format should I use for adding a single IP address to the Not Enforced IP Processing list?

A. You must use CIDR notation when adding a single IP address, for example:

10.10.0.102/32

See User Guide › Reference › Not Enforced IP Processing Properties 

Q. Can I configure Java policy agents to fetch attributes for not enforced URLs?

A. No, this option is currently only available for web policy agents. An RFE has been raised for this: OPENAM-2339 (Allow J2EE Policy Agent to fetch Attributes for Not Enforced URL).

Q. Can I disable the INCLUDE and FORWARD dispatchers?

A. The following dispatchers are included by default in the web.xml file when the Java policy agent is installed:

<dispatcher>REQUEST</dispatcher> 
<dispatcher>INCLUDE</dispatcher> 
<dispatcher>FORWARD</dispatcher> 
<dispatcher>ERROR</dispatcher>

Either the INCLUDE or FORWARD dispatcher must be present with the REQUEST dispatcher:

  • REQUEST dispatchers are used to intercept requests, for example, a JSP.
  • INCLUDE dispatchers are used when another resource is included from another file such as a header or a footer.
  • FORWARD dispatchers are used in a similar way to client-side redirects, but are wholly server-side with the original request, and possibly additional new parameters, being forwarded on to the new URL. The FORWARD dispatcher can be disabled but it is not always appropriate as there is a risk that other forwarded requests may be missed. If your application uses FORWARD then potentially the policy agent has two chances to evaluate the policy; at the beginning of the request and when the forward is acted upon.

See the Java Agent User Guide Install section for your web application container for further details. For example, for Apache Tomcat™: User Guide › Installing the Tomcat Java Agent 

Q. Why can't I see the http_header attributes in the browser?

A. When the Profile Attribute Fetch Mode property (com.sun.identity.agents.config.profile.attribute.fetch.mode) is set to HTTP_HEADER, the policy agent retrieves the profile attributes through direct communication with AM/OpenAM. The agent will then inject the attribute(s) as a Request header before sending the request to the application, then removes them before displaying the page, meaning you will not see them in your browser but they will be accessible to your application.

You can observe this in your policy agent debug log (amAgent or debug.log), which shows the headers being cleared:

2015-06-03 11:32:54.788  Warning 9819:1d65310 all: clear_headers(): Clearing header name cn.
2015-06-03 11:32:54.788  Warning 9819:1d65310 all: clear_headers(): Clearing header name email.
2015-06-03 11:32:54.788  Warning 9819:1d65310 all: clear_headers(): Clearing header name userId.

You can observe the header is properly set in the policy agent debug log (amAgent or debug.log), where user.0 is the uid of a test user:

2015-07-01 11:26:03.928 Debug 23204:7fd7d830cae0 all: set_user_attributes(): set request header 
key uid, value user.0, returned AM_SUCCESS
Note

How do I capture HTTP headers set by Web Policy Agents (All versions) in Apache HTTP server using a Perl script? provides information on using a Perl® script to capture user profile attributes set in HTTP headers.

Alternatively, you could write a short script at the application level that will print out the headers received. For example, you could write a PHP script as follows:

echo "header : \n";
foreach (getallheaders() as $name => $value) {
    echo "$name: $value\n";
}

You will then be able to check that the values have been received by the application via the HTTP header, for example:

header : 
Host: host1.example.com
Connection: keep-alive
Cache-Control: max-age=0
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/38.0.2125.122 Safari/537.36
Referer: http://host1.example.com:18080/openam/UI/Login?goto=http%3A%2F%2Fhost1.example.com%2Ftest.php
Accept-Encoding: gzip,deflate,sdch
Accept-Language: en-US,en;q=0.8
Cookie: amlbcookie=01; iPlanetDirectoryPro=AQIC5wM2LY4SfcyvzT...
cn: user.0
email address: user.0@forgerock.com
uid: user.0

Q. How does the IIS web agent use the header prefixes HTTP_ and HEADER_?

A. The way the IIS agent uses the header prefixes HTTP_ and HEADER_ varies by IIS version and agent version:

  • IIS 7.5 on Microsoft® Windows® 2008R2 only retrieves a custom header variable if it is preceded by HTTP_. All underscores after the first one will be translated to hyphen '-' characters.
  • IIS 8 on Microsoft Windows 2012R2 can retrieve a custom header variable if it is preceded by HEADER_ or HTTP_. If HEADER_ is used, then the name after this will be treated as raw text (underscores are not translated to hyphens).
  • IIS agent 5 prefixes custom header variables with HEADER_ by default when retrieving custom header variables. This means that IIS agents 5 will not work with IIS 7.5.
  • IIS policy agent 4 does not add a prefix, which means you can choose whether to add HTTP_ or HEADER_ as required.

Q. What do I need to change if I add a load balancer to an existing setup that does not already have a load balancer?

A. If you subsequently add a load balancer in front of a Web or Java agent that was initially configured without a load balancer, you must set the FQDN Default (com.sun.identity.agents.config.fqdn.default) to the policy agent's load balancer URL. In addition, you should check the following settings and update the URLs where necessary:

  • Agent Notification URL (com.sun.identity.client.notification.url). This property is not supported in either Web or Java agents 5; you should remove its value for all agent 5 installations.
  • Agent Deployment URI Prefix (com.sun.identity.agents.config.agenturi.prefix) - Web policy agent only.
Note

It is easier to create a new policy agent profile and set the Agent URL to the load balancer URL. 

See Configuring Web Agents Behind Load Balancers and Configuring Java Agents Behind Load Balancers for further information on configuring policy agents behind load balancers.

Q. How do I configure the policy agent to pass the client IP address when it is behind a load balancer?

A. You can set the advanced com.sun.identity.agents.config.client.ip.header property in the console as follows:

  • AM 6 and later console: navigate to: Realms > [Realm Name] > Applications > Agents > [Web or Java] > [Agent ID] > Advanced > Client IP Address Header.
  • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > Agents > [Web or J2EE] > [Agent Name] > Advanced > Client IP Address Header.
  • OpenAM 13.x console: navigate to: Realms > [Realm Name] > Agents > [Web or J2EE] > [Agent Name] > Advanced > Client IP Address Header.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Agents > [Web or J2EE] > [Agent Name] > Advanced > Client IP Address Header.

For IIS agents this should be set to:

com.sun.identity.agents.config.client.ip.header = HTTP_X_FORWARDED_FOR

For all other agents, it should be set to: 

com.sun.identity.agents.config.client.ip.header = X_FORWARDED_FOR

See Installation Guide › Handling HTTP Request Headers for further information on using the X-Forwarded-For HTTP request header.

Q. What is the com.sun.identity.agents.config.load.balancer.enable property used for?

A. The Load Balancer Setup property (com.sun.identity.agents.config.load.balancer.enable) is an advanced property that is only used in web policy agents 4.x; support for it has been removed in web agents 5.

This property is used in load balanced environments in conjunction with the org.forgerock.agents.config.keepalive.disable property. If you want the policy agent to send the amlbcookie to AM/OpenAM in a load balanced environment, you must set the following properties in the agent.conf file:

com.sun.identity.agents.config.load.balancer.enable=true
org.forgerock.agents.config.keepalive.disable=true
Note

There is a known issue, which prevents you changing the first property in the console: AMAGENTS-1206 (com.sun.identity.agents.config.load.balancer.enable does not work from Central Profile)

Once you have set these properties, you must restart the web policy agent to apply your changes. The amlbcookie is then sent to the AM/OpenAM server in every request related to the current user session. The value of the cookie is derived by the policy agent from the server or site ID in the SSO token. Where there is no SSO token (for example, the initial user login, the initial agent configuration fetch or not enforced fetched attributes) then no amlbcookie is set and the policy agent routes the request to the preset naming or login URLs as appropriate.

You will be able to see the amlbcookie being set in your debug log, for example:

2017-10-27 15:09:28.156 -0100   DEBUG [0x7f684c7f8700:23069][source/net_ops.c:170] create_cookie_header(): request header: Cookie: amlbcookie=03

See Also

How do I create and update an agent in AM/OpenAM (All versions) using the REST API?

FAQ: Configuring policies in AM/OpenAM

How do I rotate Web Policy Agents (All versions) debug and audit logs?

How do I rotate Java Policy Agents (All versions) debug and audit logs?

Agents and policies in AM/OpenAM

Web Agents 5 User Guide

Java Agents 5 User Guide

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

OPENAM-11104 (Tomcat Admin changes done by J2EEAgent not described (AMLogin.html))


FAQ: Configuring policies in AM/OpenAM

The purpose of this FAQ is to provide answers to commonly asked questions regarding configuring policies and policy evaluation in AM/OpenAM.

Frequently asked questions

Q. Can I use both * and -*- wildcards in the same policy rule?

A. No, you cannot use both of these wildcards in a policy rule as although the policies are matched correctly, access is denied regardless of the outcome of the policy evaluation. Using either * or -*- in a policy rule works as expected. See Authorization Guide › Specifying Resource Patterns with Wildcards for further information.

Q. Do I have to URL encode "?" in a policy rule?

A. If you have more than one question mark in your policy rule, the second and subsequent ?s should be URL encoded.

Q. How can I get a count of all my policies?

A. You can use a REST call such as the following, where the resultCount field will return a count of all your active policies: 

$ curl -X GET -H "Content-Type: application/json" -H "iPlanetDirectoryPro:AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" http://host1.example.com:8080/openam/json/policies?_queryFilter=true&_fields=resultCount

Example response:

{
    "result": [
        {
            "_id": "Policy1",
            "_rev": "1509627226562"
        }
    ],
    "resultCount": 1,
    "pagedResultsCookie": null,
    "totalPagedResultsPolicy": "NONE",
    "totalPagedResults": -1,
    "remainingPagedResults": 0
}

There is an RFE to show a policy count in the console: OPENAM-11694 (Create Policy count for tracking number of created Policies).

Q. Which data store is used when evaluating elements of a policy in a sub-realm?

A. Policies are evaluated as follows in sub-realms:

  • The policy is only evaluated in the following scenarios depending on AM/OpenAM version:
  • The elements related to identity (such as Subject Conditions, Identity Membership in Environment Conditions and the Subject Attributes in the Response Attributes) are evaluated against the data store(s) defined in the sub-realm that the policy belongs to (/path/to/subrealm). 
  • The LDAP Filter condition element is unique because it uses the data store defined in the Policy Configuration service of the sub-realm the policy belongs to (/path/to/subrealm).

There is a known issue that only affects OpenAM 12.0.0 when defining subject conditions in a sub-realm: OPENAM-5386 (Policy editor doesn't always use realm-specific REST endpoints).

Q. Does policy evaluation accept OAuth2 or OIDC tokens in the header?

A. No, policy evaluation only accepts session tokens passed via the header. There is an RFE to allow OAuth2 (bearer) and OIDC (JWT) tokens to be accepted as well: OPENAM-11913 (Policy evaluation should accept OAuth2/OIDC tokens ).

Q. How do I specify the realm and chain when using the ”AuthenticateToService” condition if a chain is within a different realm?

A. You can use the AuthenticateToService condition and specify the chain in the following format: /realm:chain. For example:

{
    "type": "AuthenticateToService",
    "authenticateToService": "/employees:LDAP"
}

 Failure against the above policy condition leads to advice showing the LDAP authentication chain in the employees realm is required.

See Authorization Guide › Policy Decision Advice for details on different types of policy decision advice and the conditions that cause AM to return the advice.

Q. Does AM/OpenAM validate the JWT token's signature before checking the subject conditions during policy evaluation?

A. No it does not as explained in Fun with OpenAM13 Authz Policies over REST – the ‘jwt’ parameter of the ‘Subject’. You could enforce this validation using policy condition scripts as demonstrated in Federated Authorization Using 3rd Party JWTs.

Note

Creating policy condition scripts is outside the scope of ForgeRock support; if you want more tailored advice, consider engaging Deployment Support Services

Q. Which URL is enforced by the Apache policy agent when using mod_rewrite?

A. Typically, mod_rewrite actions take place before policy enforcement by the policy agent, meaning the URL after the rewrite is enforced by the policy agent.

However, mod_rewrite is complex as it hooks into two phases, which may affect this processing order. Refer to https://httpd.apache.org/docs/2.4/rewrite/tech.html for further details on how mod_rewrite acts if you experience unexpected results.

Q. How do I add an action to a policy?

A. You can add an action by defining your own application type. See Authorization Guide › Managing Application Types for further information.

Q. Can I share values between scripted policies?

A. Yes, you can share the environment variable between privileges/policies.

See How do I share values between scripted policies in AM/OpenAM (All versions)? for further information and a worked example.

Q. Do policy agents support Perl-compatible regular expressions?

A. Web policy agents do, but the other agents do not. 

The following properties are available for the different areas of the agent that can use Perl-compatible expressions:

  • org.forgerock.agents.config.notenforced.ext.regex.enable (Web agents 4.x and later)
  • com.forgerock.agents.notenforced.url.regex.enable
  • com.forgerock.agents.agent.invalid.url.regex 
  • com.forgerock.agents.agent.logout.url.regex

See User Guide › Configuring Web Agent Properties for further information.

See Also

Best practice for creating and testing policies in AM/OpenAM (All versions)

How do I define a list of Not Enforce URLs that Web policy agents can ignore for authentication purposes in AM/OpenAM (All versions)?

How do I define a list of Not Enforce URIs that Java policy agents can ignore for authentication purposes in AM/OpenAM (All versions)?

How do I create a policy condition script in AM/OpenAM (All versions)?

FAQ: Configuring Policy Agents in AM/OpenAM

Agents and policies in AM/OpenAM

Authorization Guide › Introducing Authorization

Web Agents User Guide

Java Agents User Guide

Related Training

ForgeRock Access Management Core Concepts (AM-400)


FAQ: SSL/TLS secured connections in AM/OpenAM and Policy Agents

The purpose of this FAQ is to provide answers to commonly asked questions regarding SSL/TLS secured connections in AM/OpenAM and Policy Agents.

Frequently asked questions

This article covers questions related to SSL/TLS secured connections; see FAQ: SSL certificate management in AM/OpenAM and Policy Agentsfor questions related to SSL certificate management in AM/OpenAM and Policy Agents.

Q. Should I enable SSL before installing AM/OpenAM?

A. Yes, you should enable SSL before installing AM/OpenAM as this makes configuration a lot simpler. See Installation Guide › Securing Installations › Using Self-Signed Certificates for further information on setting up AM/OpenAM with SSL if you are using Apache Tomcat™ as the deployment container.

If you have already installed AM/OpenAM, refer to the following articles for further information on enabling SSL:

Q. Do I need to do anything differently when installing ssoadm?

A. If you access the configuration store and/or AM/OpenAM instance using a SSL/TLS secured connection, you should include details of the truststore that contains the required certificates in the setup or setup.bat script prior to installing ssoadm and in the ssoadm or ssoadm.bat script once it is installed.

This is described in FAQ: Installing and using ssoadm in AM/OpenAM (Q. How do I install the ssoadm administration tool if I am using SSL?).

Q. How do I make AM/OpenAM communicate with a secured LDAP server, such as DS/OpenDJ?

A. When DS/OpenDJ uses LDAP secured access (LDAPS), you must import the DS/OpenDJ server certificate into your AM/OpenAM truststore. This allows the JVM to trust the DS/OpenDJ server certificate and enables AM/OpenAM to connect to the secured DS/OpenDJ.

See How do I make AM/OpenAM (All versions) communicate with a secured LDAP server? for further information.

Q. How do I configure a policy agent for SSL offloading?

A. You can configure a policy agent for SSL offloading as described in the following articles (depending on policy agent type):

If you use virtual hosts, the following article may also be useful: How do I configure SSL offloading at the Policy Agent (All versions) for virtual hosts? 

Q. How do I test my SSL connection to an external resource?

A. You can use the openssl third-party tool to provide information about the SSL connection as well as attempting a SSL handshake. You can run a command such as the following to provide this information:

$ openssl s_client -connect [hostname:port] -showcerts

Q. How do I debug SSL connection issues?

A. You can enable SSL debug logging to provide detailed SSL debugging information, including details of which truststore is being used and which certificates are included in that truststore. You can enable SSL debugging by adding the following JVM option to the web container or application server on which you have deployed AM/OpenAM:

-Djavax.net.debug=SSL,handshake,trustmanager

The location of the SSL debug logs are specific to your web container or application server. For example, for AM/OpenAM deployed on Apache Tomcat, the SSL debug logs are written to catalina.out, which is located in the /path/to/tomcat/logs directory by default.

See Debugging SSL/TLS Connections for further information on SSL debugging. 

Q. What versions of TLS are supported by AM/OpenAM and the policy agents?

A. Supported versions of TLS are determined by the web application container as well as the underlying version of Java® and OpenSSL. You should ensure you are using appropriate versions of these technologies in accordance with what is supported by your AM/OpenAM and/or policy agent versions.

See Installation Guide › Security Settings for details on setting the protocols used by AM/OpenAM.

Web policy agents: TLS v1.3

Web policy agents 4.2 supports TLSv1.3, which requires OpenSSL 1.1.1 or later. See Web Policy Agent Release Notes › Supported OpenSSL Versions for further information.

Web policy agents: TLS v1.2

Both Java 8 and OpenJDK 8 support TLS v1.2 by default; you can configure Java 7 to use TLS v1.2 if required.

You should ensure you are running Web policy agents 4.x or later, and have installed OpenSSL 1.0.2 or greater. Additionally, you should ensure TLS v1.2 is not specified in the org.forgerock.agents.config.tls advanced encryption property that can be set in the agent.conf file.

The org.forgerock.agents.config.tls property is used to disable SSL/TLS versions. By default, all versions (SSLv3, TLSv1, TLSv1.1 and TLSv1.2) are enabled. If you want to disable any, you can specify them with - in front. For example, the following setting will disable SSLv3 and TLSv1, but leave TLSv1.1 and TLSv1.2 enabled:

org.forgerock.agents.config.tls=-SSLv3 -TLSv1

There is a known issue with the Web Agent 4 product documentation: OPENAM-9640 (WPA property org.forgerock.agents.config.tls usage should be corrected)., which is fixed in 4.1.

See FAQ: SSL certificate management in AM/OpenAM and Policy Agents (Q. How do I configure the Web policy agent for two-way SSL?) for further information on setting this property.

Q. Can I change which SSL/TLS ciphers are used by the policy agents to connect to AM/OpenAM over SSL/TLS?

A. Yes, you can configure the list of ciphers that are supported as described in: User Guide › Configuring Custom Properties.

Q. Does the Java policy agent offer a separate configuration for SSL/TLS client authentication?

A. No, it does not; by default it uses the HttpsURLConnection class provided by the JVM. 

See Also

How do I install an SSL enabled OpenAM 12.x cluster with SSL load balancer?

Policy Agents and AM/OpenAM (All versions) fail to install on IBM WebSphere when SSL is enabled

FAQ: SSL certificate management in AM/OpenAM and Policy Agents

How do I troubleshoot connection via LDAPS issues in DS/OpenDJ (All versions)?

FAQ: SAML certificate management in AM/OpenAM

FAQ: Installing and using ssoadm in AM/OpenAM

SSL in AM/OpenAM and Policy Agents

Installation Guide › Securing Installations

Debugging SSL/TLS Connections


FAQ: SSL certificate management in AM/OpenAM and Policy Agents

The purpose of this FAQ is to provide answers to commonly asked questions about SSL certificate management in AM/OpenAM and Policy Agents.

Frequently asked questions

This article covers questions related to SSL certificate management; see FAQ: SSL/TLS secured connections in AM/OpenAM and Policy Agents for questions related to SSL/TLS secured connections in AM/OpenAM and Policy Agents.

Q. Does AM/OpenAM handle certificate checking for SSL connections?

A. No. The SSL handshake is handled by the HTTP container and the JRE. The container where you install AM/OpenAM requires a certificate in order to set up secure connections. See Installation Guide › Using Self-Signed Certificates for steps that demonstrate how to set up Apache Tomcat™ with an HTTPS connector, using the Java® keytool command to manage the certificate and keystores. 

Q. Why am I getting Exception: unable to find valid certification path?

A. If you encounter certificate errors such as the following:

javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

This means the HTTP container that AM/OpenAM runs on is unable to trust the certificate presented by other servers and/or client applications that are trying to connect to AM/OpenAM over SSL or the certificate is missing. To rectify:

  • Ensure you import the new certificate into each server's default cacerts truststore and restart the containers.
  • Ensure the CN of the certificate matches the hostname of the remote server; to verify this, you can use the following command:
    $ openssl s_client -connect hostname:port 

Q. Where are the Root CA certificates stored?

A. The JDK uses the default cacerts store from the Java home directory. If your certificates have been signed by a public Certificate Authority (CA), those certificates are automatically installed in the Java CA certificates truststore ($JAVA_HOME/jre/lib/security/cacerts) and browsers, and should therefore be recognized by AM/OpenAM without further configuration.  

If you're using a self-signed test certificate, you must also add it to the relevant truststores.  

For example: AM1 needs the certificate of AM2 in its truststore (and vice-versa) as described in the section Installation Guide › Using Self-Signed Certificates. By default this is $JAVA_HOME/jre/lib/security/cacerts.

Q. What is the difference between the keystore and truststore?

A. Truststores are used for public, signed certificates and keystores are used for private keys; the truststore is used to find the certificates of other servers to be trusted, whereas the keystore is what the HTTP container uses to find its own server certificate. Typically, both truststores and keystores have the same default password.

Q. Can I use my own truststore rather than the default truststore?

A. Yes, you can but you must update the server.xml file for your web application container to point to your non-default truststore. In addition, you should ensure you have imported the necessary certificates into the truststore. See How do I import a certificate into the truststore used by AM/OpenAM (All versions) for SSL? for further information.

To connect to DS/OpenDJ over LDAPS in this scenario, you should follow the instructions given in How do I make AM/OpenAM (All versions) communicate with a secured LDAP server?

Q. Does AM/OpenAM require a specific keystore type?

A. AM/OpenAM does not read the server certificate for HTTP(s) connections; the SSL handshake is handled by the container and the JRE. If you are experiencing problems with the keystore format, it is unlikely that it can be fixed from within AM/OpenAM.

In other cases where the certificates are processed by AM/OpenAM itself (for example, SAML2 federation or x509 certificate authentication) the keystore type does matter. The default directory for keystore files (.keypass, .storepass, keystore.jceks / keystore.jks) is %BASE_DIR%/%SERVER_URI%/.

Q. How do I list the keys in my keystore?

A. You can list all the keys in your keystore using one of the following commands depending on your keystore format:

  • JCEKS format:
    $ keytool -list -v -keystore [keystore] -storetype JCEKS -storepass [password]
  • JKS format:
    $ keytool -list -v -keystore [keystore] -storepass [password]

replacing [keystore] with the full path and name of the keystore file, and [password] with the keystore password.

Q. How long do the generated self-signed certificates last?

A. The generated self-signed certificates expire after one year, although you can replace them with ones that have a longer expiration time.

The AM/OpenAM keystore.jceks /keystore.jks has one certificate included by default, which can be used for testing purposes. This has an alias of test and is valid for a 10 year period.

Caution

You must not use this test certificate in production environments; instead, you should use a certificate obtained from a trusted CA or generate your own self-signed certificate. 

Q. Why does the Persistent Cookie module still issue persistent cookies after the certificate has expired?

A. The Persistent Cookie module does not validate the certificate when it issues the persistent cookies (called session-jwt by default).

Q. What happens to persistent cookies that were issued before the certificate was updated?

A. Persistent cookies that were issued by the old certificate are invalidated when you update the certificate in the keystore.

Q. Will the Web policy agent trust the server certificate?

A. Yes, the Web policy agent trusts all server certificates by default. You can disable this behavior by setting the com.sun.identity.agents.config.trust.server.certs property to false. When this is set to false, the policy agent only trusts the AM/OpenAM SSL certificate if the certificate is found to be correct and valid, which is more secure.

You can set this property to false in the agent.conf file (located in the /path/to/web_agents/agent_version/instances/Agent_nnn/config directory). If you set this property to false, you must also set the com.forgerock.agents.config.cert.ca.file property in the agent.conf file.

See the User Guide › Reference for further information on these properties.

Q. How do I configure the Web policy agent for two-way SSL?

A. Two-way SSL (also referred to as mutual SSL or Certificate Authentication) is where the policy agent provides its certificate for AM/OpenAM to check during the SSL handshake (with certificate authentication).

You need to configure the following encryption properties in the agent.conf file (located in the /path/to/web_agents/agent_version/instances/Agent_nnn/config directory):

com.forgerock.agents.config.cert.ca.file = AM_SSL_CA
com.forgerock.agents.config.cert.file = AM_SSL_CERT
com.forgerock.agents.config.cert.key = AM_SSL_KEY
com.forgerock.agents.config.cert.key.password = AM_SSL_PASSWORD
com.forgerock.agents.config.ciphers = AM_SSL_CIPHERS
org.forgerock.agents.config.tls = AM_SSL_OPTIONS

See User Guide › Encryption Properties for further information on these properties. Alternatively, these properties can be set as environment variables prior to installing your web agent as detailed in the Installation > SSL section in Tips and feature insights for Web Policy Agents 4.x (applies to later agents as well).

Q. How do I use an existing CA signed certificate (in PEM format) in AM/OpenAM?

A. You need to add the CA signed certificate to the AM/OpenAM keystore in order to use it. You can do this as follows:

  1. Convert the PEM certificate file to PKCS#12 (.p12) using the openssl third-party tool:
    $ openssl pkcs12 -export -in [certificate.crt] -inkey [privateKey.key] -out [certificate.p12] -name [alias]
    replacing [certificate.crt], [privateKeyml.key], [certificate.p12] and [alias] with appropriate values.
  2. Import the p12 file generated in step 1 into the AM/OpenAM keystore using the keytool command:
    $ keytool -importkeystore -deststorepass [changeit] -destkeypass [changeit] -destkeystore [AMkeystore] -srckeystore [certificate.p12] -srcstoretype PKCS12 -srcstorepass [password] -alias [alias]
    replacing [changeit], [AMkeystore], [certificate.p12], password] and [alias] with appropriate values.

Q. How do I get the certificate out of the keystore in PEM format?

A. You can use the following keytool command to retrieve the certificate from the keystore in PEM format:

$ keytool -exportcert -alias [alias] -keypass [keypassword] -keystore [keystore] -storepass [storepassword] -rfc -file [keyStore.pem]

replacing [alias], [keypassword], [keystore], [storepassword] and [keyStore.pem] with appropriate values, where:

  • [keypassword] is the password used to protect the private key of the generated key pair. 
  • [keystore] is the full path and name of the keystore file.
  • [storepassword] is the keystore password.

Q. How do I convert a PEM certificate file and private key to PKCS#12 (.pfx .p12)?

A. You can use the openssl third-party tool to perform this conversion using the following command:

$ openssl pkcs12 -export -out [certificate.pfx] -inkey [privateKey.key] -in [certificate.crt] -certfile [CACert.crt]

replacing [certificate.pfx], [privateKey.key], [certificate.crt] and [CACert.crt] with appropriate values.

Q. How do I convert a PKCS#12 file (.pfx .p12) that contains a private key and certificates to PEM format?

A. You can use the openssl third-party tool to perform this conversion using the following command:

$ openssl pkcs12 -in [keyStore.pfx] -out [keyStore.pem] -nodes

replacing [keyStore.pfx] and [keyStore.pem] with appropriate values

Note

You can add -nocerts to only output the private key or add -nokeys to only output the certificates.

Q. How can I create an OAuth2 provider HMAC signing key in AM 6.5 and later using keytool ?

A. The OAuth2 provider HMAC signing key (secret id: am.services.oauth2.jwt.authenticity.signing) can be created using the following keytool command:

$ keytool -genseckey -alias hmacsigningtest -keyalg HMacSHA512 -keysize 512 -keystore [keystore] -storetype [storetype] -storepass [storepassword] -keypass [keypassword]

replacing [keystore], [storetype], [storepassword] and [keypassword] with appropriate values.

See Setup and Maintenance Guide › Secret ID Mappings for JWT Authenticity Signing for further information about this signing key.

See Also

FAQ: SAML certificate management in AM/OpenAM

FAQ: SSL/TLS secured connections in AM/OpenAM and Policy Agents

How do I import a certificate into the truststore used by AM/OpenAM (All versions) for SSL?

How do I configure a Web Policy Agent (All versions) for SSL offloading?

How do I configure a Java Policy Agent (All versions) for SSL offloading?

How do I configure SSL offloading at the Policy Agent (All versions) for virtual hosts?

RSA server certificate CommonName (CN) does NOT match server name warning in Proxy log for AM/OpenAM (All versions)

Setup and Maintenance Guide › Setting Up Keys and Keystores

The Most Common OpenSSL Commands

keytool command


FAQ: AM/OpenAM performance and tuning

The purpose of this FAQ is to provide answers to commonly asked questions regarding performance and tuning for AM/OpenAM and Policy Agents.

Frequently asked questions

Q. Do I need to performance test AM/OpenAM?

A. Yes, performance testing is a very important step to ensure that the system you have configured will cope with the expected load once it is in production. By performance testing your system, you can tweak any performance issues you encounter before going live.

Before running any performance tests, you should ensure AM/OpenAM is running and configured in a test environment that closely resembles your planned production environment. You should also be aware of the type of load expected in your production system and the types of identity data involved to make your tests as realistic as possible. For example, you may want to test that your system can handle 20 authentications per second with a concurrency of 2,000 live sessions.

Generating test identity data in DS/OpenDJ is described in How do I generate sample user data for performance testing in DS/OpenDJ (All versions)?

Performing a performance test is described in idmdude - It's OK to Get Stressed Out with OpenAM

Q. How do I tune AM/OpenAM to improve performance?

A. Tuning AM/OpenAM is described in Setup and Maintenance Guide › Tuning an Instance.

Q. How can I improve the performance of ssoadm?

A. There are several approaches you can take to improving the performance of ssoadm as detailed in How do I improve the performance of ssoadm in AM/OpenAM (All versions)?

Q. What is the recommended Java Virtual Machines (JVM) heap size for AM/OpenAM?

A. There are no definitive rules for the size of JVM heap size required as it will vary across individual environments and applications, but you should refer to Best practice for JVM Tuning for best practice advice. There are also a number of things you should be aware of when making a decision for AM/OpenAM:

  • AM/OpenAM response time is independent of heap size.
  • The number of concurrent Single Sign On (SSO) sessions is dependent on heap size. As a rough guide, an AM/OpenAM server in production with a 3 GB heap can handle 100,000 sessions. As heap size increases, so does the number of possible concurrent sessions, however, smaller heap sizes are easier to manage.
  • You must ensure you configure JVM garbage collection appropriately as garbage collection runs can get quite long if you have large heap sizes.

See How do I change the JVM heap size for AM/OpenAM (All versions)? and Setup and Maintenance Guide › Tuning Java Virtual Machine Settings for further information.

Note

For a 32-bit JVM or a 32-bit operating system, the limit for the process size is 4GB, that is, 2^32; this cannot be exceeded regardless of the amount of heap space allocated.

Q. Can I change caching in AM/OpenAM to improve performance?

A. Yes, you can improve performance in AM/OpenAM by configuring caching on the server side; you can configure caching for configuration data and global user data. This is described in Setup and Maintenance Guide › Tuning Caching. You need to balance performance against memory usage when configuring caching; larger caches lead to less requests to AM/OpenAM but increase memory usage.

Q. How do client-based sessions affect performance?

A. Client-based sessions were introduced in OpenAM 13 per: OpenAM 13 Release Notes › What's New in OpenAM › Elasticity and Scaling Features.

Client-based sessions use more CPU than CTS-based sessions; however CTS-based sessions have higher RAM consumption.

See How do I enable Client-based sessions in AM (All versions) and OpenAM 13.x? for further information.

Q. How does the Session Purge Delay setting affect performance?

A. The Session Purge Delay setting (com.iplanet.am.session.purgedelay) is set to 0 by default, which removes the session from memory immediately. If you increase this to a value above 0 (not recommended), the session is then held in memory for that number of minutes before being removed. This setting has been removed in AM 5.

If you have a particular need to increase the session purge delay, you should increase your heap size to compensate for the increase in sessions as described in How do I change the JVM heap size for AM/OpenAM (All versions)?

See Setup and Maintenance Guide › Session Settings​ for further information about these settings. 

Q. What else might affect performance on a Linux system or a Virtual Machine?

A. Low entropy values can cause general system slowness.

Note

Low entropy values is a OS/Java/web container issue, which is independent of AM/OpenAM; as such, the suggested resolutions are outside the scope of ForgeRock support. If you want more tailored advice, consider engaging Deployment Support Services.

On Linux systems you can check if a low entropy value is affecting you by running the following command:

$ cat /proc/sys/kernel/random/entropy_avail

A response of 200 or less is considered low and should be addressed, but you may find that even higher values can cause system slowness.

Resolution

You can increase the amount of entropy available in a variety of ways; two possible approaches are:

  • Use an external tool called RNGD (Random Number Generator Deamon). This can either use the RDRAND instruction set or /dev/urandom if RDRAND is not available, although many Virtual Machines (such as VirtualBox and OpenStack) passthrough the RDRAND instruction set to the VM. You will need to install the rng-tools package.
  • Set the following JVM option in the application web container in which AM/OpenAM runs:
    -Djava.security.egd=file:/dev/./urandom

Q. Which Apache httpd Multi-Processing Module (MPM) should I use with web policy agent?

A. It is recommended that you always use Worker MPM rather than Prefork MPM. You should ensure there are enough processes and threads available to service the expected number of client requests. You can then tune the Worker mode performance in the conf/extra/http-mpm.conf file as detailed in Web Agents User Guide › Tuning Apache Multi-Processing Modules.

You can check which MPM Apache is using with the following command:

$ apachectl -V

The MPM in use is shown against Server MPM.

Note

Turning off the Apache™ KeepAlive feature can potentially improve performance as well since the KeepAlive feature increases memory usage. You should test your performance with KeepAlive enabled and then again with it off to check what impacts it has on your setup.

Q. Are there things I should monitor on an ongoing basis in terms of AM/OpenAM performance?

A. Yes, it is useful to monitor performance on an ongoing basis to allow you to react to changes quickly. Useful things to monitor include:

  • Heap size 
  • Number of open sessions and size of sessions 
  • CPU utilization - utilization of 70-80% is worth investigating.

See How do I monitor session statistics in AM/OpenAM (All versions)? and Setup and Maintenance Guide › Monitoring Services for further information.

See Also

FAQ: Upgrading AM/OpenAM

FAQ: Installing AM/OpenAM

FAQ: Configuring AM/OpenAM

FAQ: General AM/OpenAM

Performance tuning and monitoring ForgeRock products

Related Training

ForgeRock Access Management Core Concepts (AM-400)


How do I troubleshoot WebSocket issues in Agents 5.x?

The purpose of this article is to provide information on troubleshooting WebSocket issues with Agent 5.x in AM.

Overview

Prior to troubleshooting, it is important to understand that one of the major changes introduced with 5.x Web Agents and Java Agents is an improved notification system that uses the WebSocket protocol which is significantly different from previous versions of the Agents. 

Your environment must support WebSockets in order to use AM with Agents 5.x. Among other things, the WebSocket protocol is used when AM notifies agents about configuration and session state changes. WebSockets must still be supported even if you disable notifications, or you will encounter errors. 

Read the Release Notes to understand the impacts of these changes before troubleshooting:

Initial troubleshooting checks and data to gather

You should perform the following initial checks for WebSocket conformance:

  • Ensure any load balancers or reverse proxies configured in your environment support WebSocket protocols. If they do not, you will see errors such as the following and will need to enable support in your environment:
    WARNING: Failed to create new WebSocket connection, backing off
    org.forgerock.openam.agents.notifications.websocket.WebSocketConnectionException: Failed to create connection
  • If you are using Apache™ HTTP Server as a reverse proxy, ensure you have the mod_proxy_wstunnel module as it's required for proxying the WebSocket protocol.
  • Ensure TLD scanning is either properly configured or disabled in your Apache Tomcat™ installation otherwise the appropriate libraries will not be loaded. See How do I make Tomcat startup faster? for further information.
Note

Configuring load balancers and reverse proxies is outside the scope of ForgeRock support; if you want more tailored advice, consider engaging Deployment Support Services

If all initial checks went well, you should gather the following data for troubleshooting and refer to the rest of the article for common issues:

Notifications endpoint responses

The notifications endpoint applies some login processing logic via a servlet filter. If everything is ok, you will see a 101 response, which indicates the request is valid, it has been upgraded successfully and the WebSockets connection is working correctly. If there is an issue, you will see one of the following responses instead: 401, 403 or 404:

Checking the WebSockets jars are being loaded

You can check the jars are being loaded as follows:

  1. Navigate to the Tomcat bin directory and run the noisy command, for example:
    $ cd /path/to/tomcat/bin
    $ lsof | grep websocket
    • If the WebSocket jars are being loaded, you will see something similar to the following.
      java    1014      root  mem       REG                8,1   225632 2097375 /usr/local/tomcat/lib/tomcat-websocket.jar
      java    1014      root  mem       REG                8,1    36905 2097376 /usr/local/tomcat/lib/websocket-api.jar
      java    1014      root   38r      REG                8,1    36905 2097376 /usr/local/tomcat/lib/websocket-api.jar
      ...
      
    • If the WebSocket jars are not being loaded, you won't see them listed.
  2. You can also verify by adding the following option to the Tomcat startup script (setenv.sh) to view further details about the Java® WebSocket API loading:
    JAVA_OPTS=-verbose:class
  3. Restart the web container.
  4. Check the catalina.out log file for WebSocket details. For example, you would expect to see things like the following if the WebSocket API is available:
    $ cat ../logs/catalina.out | grep websocket
    
    [Loaded org.forgerock.openam.notifications.websocket.JsonValueDecoder from file:/path/to/tomcat/webapps/openam/WEB-INF/lib/openam-notifications-websocket-6.5.0.jar]
    
    [Loaded org.forgerock.openam.notifications.websocket.NotificationsWebSocketConfigurator from file:/path/to/tomcat/webapps/openam/WEB-INF/lib/openam-notifications-websocket-6.5.0.jar]
    
    [Loaded javax.websocket.EncodeException from file:/path/to/tomcat/lib/websocket-api.jar]
    
    ...
    

The Java WebSocket API is bundled with Tomcat 7 and 8 so should be available. 

Note

The openam-notifications-websocket-x.x.x.jar is required for WebSockets to work. If it is missing, you will see 404 responses. If this happens, verify your Tomcat configuration or contact your System Administrator for further assistance.

Running the Agent validation tool (Agents 5.5 and later)

The Agent validation tool was introduced in Agents 5.5 and later. This tool performs a number of checks including WebSocket tests and can be run as follows:

$ agentadmin --V agent_instance

The results of the tests are output to the command line and shows tests as ok or not ok depending on whether they passed, for example:

... 
validate_system_resources: ok 
validate_session_profile: skipped 
Agent websocket open error: error (6) 
validate_websocket_connection: not ok 
...

Further information about the tests and detailed results can be found in the Validator log (validate_xx.log located in the agent /log directory).

See Web Agents User Guide › agentadmin or Java Agents User Guide › agentadmin for further information.

Testing the WebSocket connection via curl

You can test the WebSocket connection by sending the agent's token to the notifications endpoint using curl. This will generate a response similar to what is output in the Validator log. Ensure you use the correct agent name, password, AM FQDN URL and cookie name: 

  1. Authenticate as the agent to return the agent's token:
    $ curl -X POST -H "X-OpenAM-Username: webagentname" -H "X-OpenAM-Password: webagentpassword" -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.1" http://host1.example.com:8080/openam/json/realms/root/authenticate?authIndexType=module&authIndexValue=Application
    
    Example response:
    { "tokenId": "AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*", "successUrl": "/openam/console", "realm": "/" }
    
  2. Send the agent's token to the notifications endpoint:
    $ curl -v --include --no-buffer -H "Connection: Upgrade" -H "Upgrade: websocket" -H "Host: agent.example.com:8080" -H "Origin: http://notagent.example.com:8080" -H "Sec-WebSocket-Key: SGVsbG8sIHdvcmxkIQ==" -H "Sec-WebSocket-Version: 13" -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" http://host1.example.com:8080/openam/notifications
    Example 101 response when the WebSocket connection is working correctly:
    *   Trying 198.51.100.0...
    * TCP_NODELAY set
    * Connected to host1.example.com (198.51.100.0) port 8080 (#0)
    > GET /openam/notifications HTTP/1.1
    > Host: agent.example.com:8080
    > User-Agent: curl/7.54.0
    > Accept: */*
    > Connection: Upgrade
    > Upgrade: websocket
    > Origin: http://notagent.example.com:8080
    > Sec-WebSocket-Key: SGVsbG8sIHdvcmxkIQ==
    > Sec-WebSocket-Version: 13
    > iPlanetDirectoryPro: AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*
    
    >
    
    < HTTP/1.1 101
    HTTP/1.1 101
    < X-Frame-Options: SAMEORIGIN
    X-Frame-Options: SAMEORIGIN
    < Upgrade: websocket
    Upgrade: websocket
    < Connection: upgrade
    Connection: upgrade
    < Sec-WebSocket-Accept: qGEgH3En71di5rrssAZTmtRTyFk=
    Sec-WebSocket-Accept: qGEgH3En71di5rrssAZTmtRTyFk=
    < Date: Fri, 15 Mar 2019 17:38:15 GMT
    Date: Fri, 15 Mar 2019 17:38:15 GMT

401/403 response from the notifications endpoint

A 401 or 403 response means the agent has failed to establish a WebSocket connection with AM.

You will see a 403 Access Forbidden response in the browser and a 401 response in the logs:

  • Agents 5.5 and later: in the Validator log file, for example:
    2019-03-19 09:27:13  Agent websocket open error: forbidden (3)
    am_timer(): getaddrinfo took 0 seconds
    http request to host1.example.com:8080
    GET /openam/notifications HTTP/1.1
    Host: host1.example.com:8080
    Upgrade: websocket
    Connection: upgrade
    Sec-WebSocket-Key: e7a7rzfsDr7cl3E8EWcyaA==
    Sec-WebSocket-Version: 13
    Sec-WebSocket-Protocol: v1.notifications.forgerock.org
    
    IPlanetDirectoryPro: IHvS8OJUmnyX8vJzI34I5tnuzio.*AAJTSQACMDIAAlNLABx6SkZ2TzVlcUQ5WUlLdFdCSzd0aFc0aTdlUTQ9AAR0eXBlAANDVFMAAlMxAAIwMQ..*
    
    X-ForgeRock-TransactionId: f8525ddb-a383-cb43-ac29-4324b21ebaeb/1
    
    
    http response 401 from host1.example.com:8080
    X-Frame-Options: SAMEORIGIN
    Content-Length: 0
    Date: Tue, 19 Mar 2019 09:27:13 GMT
    websocket response 401
    
  • All versions: in the system_0.log (located in the agent/log directory), for example:
    2019-03-19 09:27:13 GMT ERROR  [fead55aa-f7a6-5641-5b4f-d6d71ebf518d]: websocket response 401
    2019-03-19 09:27:13 GMT WARNING [fead55aa-f7a6-5641-5b4f-d6d71ebf518d]: websocket: open status: forbidden
    2019-03-19 09:27:13 GMT WARNING [3844:3080]: session for agent / webagent was not removed

A common reason for a 401 response is a mismatch between the agent cookie name and the cookie name on the AM server. This is because the agent cookie name (com.sun.identity.agents.config.cookie.name) is used to construct the request sent to the notifications endpoint and must match what AM is expecting. The AM server default cookie name and agent cookie name are both set to iPlanetDirectoryPro by default. If you rename this cookie on the AM server, then you need to update the same on the Agent side.

For example, an agent with a cookie name of IPlanetDirectoryPro will not be able to authenticate to upgrade the request if the AM server has a cookie name of exampleCookie. 

You can check the AM cookie as follows:

  • Agents 5.5 and later: use the Validator log to check the call made to serverinfo:
    http response 200 from host1.example.com:8080
    X-Frame-Options: SAMEORIGIN
    Cache-Control: no-cache
    Content-API-Version: resource=1.1
    ETag: "812974925"
    X-Content-Type-Options: nosniff
    Content-Type: application/json;charset=UTF-8
    Content-Length: 551
    Date: Tue, 19 Mar 2019 09:41:29 GMT
    Connection: close
    {"_id":"*","_rev":"812974925","domains":["example.com"],"protectedUserAttributes":[],"cookieName":"exampleCookie","
    
  • All versions: use the following REST call:
    $ curl -s 'http://host1.example.com:8080/openam/json/serverinfo/*' | tr ',' '\n' | grep cookieName
    
    "cookieName":"exampleCookie"

If your cookies do not match, you can update them them as described in How do I change the session cookie name for AM/OpenAM and Policy Agents (All versions)?

404 response from the notifications endpoint

A 404 response typically means that the WebSocket request has not been upgraded because the AM notifications servlet filter will never throw a 404. If you get a 404, you at least know that the request being sent to the notification servlet filter is valid. A 404 can be caused by a number of things, including network infrastructure; for example, incorrectly configured load balancers or reverse proxies.

To troubleshoot a 404, you can:

  • Make a direct curl request to the notifications endpoint as described in the Testing the WebSocket connection via curl section. This will provide more details and may give you a clue as to what is going wrong.
  • Rename the agent cookie name to verify that you get a 401 response as expected. If you do get a 401, it confirms the servlet filter logic is being applied correctly and means it is a network issue or a Tomcat issue. One possible Tomcat issue is if the openam-notifications-websocket-x.x.x.jar is missing. If this happens, you must redploy AM.

See Also

Troubleshooting AM/OpenAM and Policy Agents

Web Agents User Guide › Notification System

Web Agents User Guide › Preparing the Environment for Reverse Proxies

Web Agents User Guide › Troubleshooting

Java Agents User Guide › Notification System

Java Agents User Guide › Preparing the Environment for Reverse Proxies

Java Agents User Guide › Troubleshooting

RFC 6455 - The WebSocket Protocol

Related Training

N/A

Related Issue Tracker IDs

AMAGENTS-2195 (Add a Cookie Check to Validator)

AMAGENTS-1216 (Agents should get iPlanetDirectoryPro name from OpenAM server)


Logging


How do I enable debug logging for troubleshooting Policy Agents (All versions)?

The purpose of this article is to provide information on raising the debug logging level for Web and Java Policy Agents. Support frequently use these logging levels for troubleshooting policy agent issues but they are not generally recommended for production due to increase in log size.

Background information

There are different debug levels available to policy agents (varying according to type):

Level Description Available to Web policy agents? Available to Java policy agents?
Off Disables debug logging. -- Yes
Error Logs only error messages. Yes (default) Yes (default)
Warning Logs both warning and error messages. Yes Yes
Info Logs info, warnings and errors messages. Yes --
Message * Logs debug, info, warning and error messages. Yes Yes
All * Max Debug logging. Logs detailed diagnostic messages and debugging information.  Yes --

* In Web policy agents 4.2, level All is the same as Message and provides the same output to better match AM/OpenAM's message levels. 

By default, the policy agent debug log is named and located as follows:

  • Web policy agents - debug.log, which is located in the /path/to/policy_agent/instances/agent_n/logs/debug directory.
  • Java policy agents - amAgent, which is located in the /path/to/policy_agent/agent_n/logs/debug directory.

Web policy agents

Depending on what you are trying to troubleshoot for web policy agents, and whether you have a local or centralized configuration will affect where you need to set the log levels:

The log levels in AM/OpenAM correspond to log levels in the agent.conf file as follows:

AM/OpenAM (console, ssoadm and Amster) log levels agent.conf file log levels
Error error
Warning warning
Info info
Message warning
All debug

Once you have reproduced the problem and captured the debug.log, you should revert the debug level to 'Error' to avoid filling up the disk where the debug log is stored.

Troubleshooting startup issues and local configurations

To troubleshoot startup issues and local configurations once they are up and running, you should set the log level in the agent.conf file. Edit the com.sun.identity.agents.config.debug.level property and set it as follows (you must use lowercase):

com.sun.identity.agents.config.debug.level=debug

This local level setting will be overwritten once the policy agent has fully started up but is useful for troubleshooting startup issues. 

Troubleshooting issues once the policy agent is up and running (centralized configurations)

To troubleshoot centralized configurations once the policy agent is up and running, you should set the log level using either the console, ssoadm or Amster (AM 5 and later). These examples show the log level being raised to 'All':

  • AM 5 and later console: navigate to: Realms > [Realm Name] > Applications > Agents > Web > [Agent Name] > Global > Agent Debug Level and select 'All'.
  • OpenAM 13.x console: navigate to: Realms > [Realm Name] > Agents > Web > [Agent Name] > Global > Agent Debug Level and select 'All'.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Agents > Web > [Agent Name] > Global > Agent Debug Level and select 'All'.
  • ssoadm: enter the following command:
    $ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a com.sun.identity.agents.config.debug.level=all
    replacing [realmname], [agentname], [adminID] and [passwordfile] with appropriate values. 
  • Amster: follow the steps in How do I update property values in AM (All versions) using Amster?with these values:
    • Entity: WebAgents
    • Property: agentDebugLevel
    • Value: All

Java policy agents

Depending on what you are trying to troubleshoot for Java policy agents, and whether you have a local or centralized configuration will affect where you need to set the log levels:

Once you have reproduced the problem and captured the amAgent debug log , you should revert the debug level to 'Error' to avoid filling up the disk where the debug log is stored.

Troubleshooting startup issues and local configurations

To troubleshoot startup issues and local configurations once they are up and running, you should set the log level in the OpenSSOAgentBootstrap.properties file. Edit the com.iplanet.services.debug.level property and set it as follows:

com.iplanet.services.debug.level=message

This local level setting will be overwritten once the policy agent has fully started up but is useful for troubleshooting startup issues. 

Troubleshooting issues once the policy agent is up and running (centralized configurations)

For centralized configurations, you can enable Message level debugging for Java policy agents using either the console, ssoadm or Amster (AM 5 and later):

  • AM 6 and later console: navigate to: Realms > [Realm Name] > Applications > Agents > Java > [Agent ID] > Global > Agent Debug Level and select 'message'.
  • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > Agents > J2EE > [Agent Name] > Global > Agent Debug Level and select 'message'.
  • OpenAM 13.x console: navigate to: Realms > [Realm Name] > Agents > J2EE > [Agent Name] > Global > Agent Debug Level and select 'message'.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Agents > J2EE > [Agent Name] > Global > Agent Debug Level and select 'message'.
  • ssoadm: enter the following command:
    $ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a com.iplanet.services.debug.level=message
    replacing [realmname], [agentname], [adminID] and [passwordfile] with appropriate values.
  • Amster: follow the steps in How do I update property values in AM (All versions) using Amster?with these values:
    • Entity: J2eeAgents
    • Property: debugLevel
    • Value: message

See Also

How do I rotate Web Policy Agents (All versions) debug and audit logs?

How do I rotate Java Policy Agents (All versions) debug and audit logs?

How do I collect all the data required for troubleshooting AM/OpenAM and Policy Agents (All versions)?

FAQ: Configuring Policy Agents in AM/OpenAM

Troubleshooting AM/OpenAM and Policy Agents

Agents and policies in AM/OpenAM

Web Agents 5 User Guide › Configuring Global Properties

Java Agents 5 User Guide › Configuring Global Properties

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

N/A


How do I enable message level debugging for the Java SDK in OpenAM 12.x and 13.x?

The purpose of this article is to provide information on enabling message level debugging for the Java® SDK in OpenAM. The Java SDK is also referred to as the Client SDK. The Java SDK was deprecated in AM 5 and removed in AM 5.5.

Enabling message level debugging

You can enable message level debugging for the Java SDK by setting the following property in the AMConfig.properties file (located in the /path/to/tomcat/webapps/openam/WEB-INF/classes directory):

com.iplanet.services.debug.level=message

You should also check the setting for the com.iplanet.services.debug.directory property in this file as this is where the Java SDK logs, including the amRemotePolicy log, are kept.

Once you have reproduced the problem and captured the debug logs, you should revert the debug level to error to avoid filling up the disks where the debug logs are stored.

See Also

Developer's Guide › Using the OpenAM Java SDK

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I rotate Web Policy Agents (All versions) debug and audit logs?

The purpose of this article is to provide information on rotating Web policy agents debug and audit logs.

Overview

By default, the policy agent logs are named and located as follows:

  • Debug - debug.log, which is located in the /path/to/policy_agent/instances/agent_n/logs/debug directory where the policy agent is installed.
  • Audit - audit.log - which is located in the /path/to/policy_agent/instances/agent_n/logs/audit directory where the policy agent is installed.

Rotating Web Policy Agent debug log

AM/OpenAM does not rotate Web Policy Agent debug logs by default, but you can configure it to do so based on size, for example, once the file reaches 10MB. The size should be specified in bytes, for example, 10000000.

If your web policy agent uses centralized configuration, you can configure the debug log to rotate using either the console, ssoadm or the local configuration file:

  • AM 6 and later console: navigate to: Realms > [Realm Name] > Applications > Agents > Web > [Agent ID] > Global and enable Agent Debug File Rotation. You should then set the corresponding file size at which the file rotates in the 'Agent Debug File Size' field. This defaults to 10000000 (10MB) when rotation is enabled.
  • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > Agents > Web > [Agent Name] > Global > Agent Debug File Rotation and select the Enabled option. You should then set the corresponding file size at which the file rotates in the 'Agent Debug File Size' field. This defaults to 10000000 (10MB) when rotation is enabled.
  • OpenAM 13.x console: navigate to: Realms > [Realm Name] > Agents > Web > [Agent Name] > Global > Agent Debug File Rotation and select the Enabled option. You should then set the corresponding file size at which the file rotates in the 'Agent Debug File Size' field. This defaults to 10000000 (10MB) when rotation is enabled.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Agents > Web > [Agent Name] > Global > Agent Debug File Rotation and select the Enabled option. You should then set the corresponding file size at which the file rotates in the 'Agent Debug File Size' field. This defaults to 10000000 (10MB) when rotation is enabled.
  • ssoadm: enter the following command:
    $ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a com.sun.identity.agents.config.debug.file.rotate=true com.sun.identity.agents.config.debug.file.size=[filesize]
    
    replacing [realmname], [agentname], [adminID], [passwordfile] and [filesize] with appropriate values. 
  • Local configuration file: edit the com.sun.identity.agents.config.debug.file.rotate and com.sun.identity.agents.config.debug.file.size properties in the agent.conf file (located in the /path/to/web_agents/agent_version/instances/Agent_nnn/config directory). You should set these properties as follows:
    com.sun.identity.agents.config.debug.file.rotate=true
    com.sun.identity.agents.config.debug.file.size=[filesize]
    
    replacing [filesize] with an appropriate value.

If using local configuration, you should edit the agent.conf file as described above.

It is recommended that you copy the debug log prior to clearing the contents, rather than deleting the log as this can cause issues if a process is still holding a file handle. Additionally, you should keep debug logging to a minimum (level: error) and only increase it when troubleshooting an issue.

Rotating Web Policy Agent audit log

Note

Audit logs are logged remotely by default. In which case they are located in the $HOME/[am_instance]/openam/log directory by default and cannot be rotated using this method. Instead you can rotate them as per AM/OpenAM audit logs: Reference › Configuration Reference › Logging.

AM/OpenAM does not rotate Web Policy Agent local audit logs by default, but you can configure it to do so based on size, for example, once the file reaches 50MB. The size should be specified in bytes, for example, 52428800.

If your web policy agent uses centralized configuration, you can configure the local audit log to rotate using either the console, ssoadm or the local configuration file:

  • AM 6 and later console: navigate to: Realms > [Realm Name] > Applications > Agents > Web > [Agent ID] > Global and enable Rotate Local Audit Log. You should then set the corresponding file size at which the file rotates in the 'Local Audit Log Rotation Size' field. This defaults to 52428800 (50MB) when rotation is enabled.
  • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > Agents > Web > [Agent Name] > Global > Rotate Local Audit Log and select the Enabled option. You should then set the corresponding file size at which the file rotates in the 'Local Audit Log Rotation Size' field. This defaults to 52428800 (50MB) when rotation is enabled.
  • OpenAM 13.x console: navigate to: Realms > [Realm Name] > Agents > Web > [Agent Name] > Global > Rotate Local Audit Log and select the Enabled option. You should then set the corresponding file size at which the file rotates in the 'Local Audit Log Rotation Size' field. This defaults to 52428800 (50MB) when rotation is enabled.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Agents > Web > [Agent Name] > Global > Rotate Local Audit Log and select the Enabled option. You should then set the corresponding file size at which the file rotates in the 'Local Audit Log Rotation Size' field. This defaults to 52428800 (50MB) when rotation is enabled.
  • ssoadm: enter the following command:
    $ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a com.sun.identity.agents.config.local.log.rotate=true com.sun.identity.agents.config.local.log.size=[filesize]
    
    replacing [realmname], [agentname], [adminID], [passwordfile] and [filesize] with appropriate values. 
  • Local configuration file: edit the com.sun.identity.agents.config.local.log.rotate and com.sun.identity.agents.config.local.log.size properties in the agent.conf file (located in the /path/to/web_agents/agent_version/instances/Agent_nnn/config directory). You should set these properties as follows:
    com.sun.identity.agents.config.local.log.rotate=true
    com.sun.identity.agents.config.local.log.size=[filesize]
    
    replacing [filesize] with an appropriate value.

If using local configuration, you should edit the agent.conf file as described above.

It is recommended that you copy the audit log prior to clearing the contents, rather than deleting the log as this can cause issues if a process is still holding a file handle.

See Also

How do I enable debug logging for troubleshooting Policy Agents (All versions)?

How do I rotate Java Policy Agents (All versions) debug and audit logs?

User Guide › Configuring Global Properties

Related Training

N/A

Related Issue Tracker IDs

OPENAM-4285 (WPA local audit log file is not rotating)

OPENAM-6477 (request for Agent log retention configuration)


How do I rotate Java Policy Agents (All versions) debug and audit logs?

The purpose of this article is to provide information on rotating Java Policy Agents debug and audit logs. By default, the policy agent amAgent debug log is located in the /path/to/policy_agent/[agent_instance]/logs/debug directory where the policy agent is installed and the local audit log is located in the /path/to/policy_agent/[agent_instance]/logs/audit directory where the policy agent is installed.

Rotating Java Policy Agent debug log

AM/OpenAM does not rotate Java Policy Agent debug logs by default, but you can configure it to do so based on:

  • Time interval (in minutes) - for example, every 1440 minutes for once a day. The time interval specified starts when the first log message is logged to the log file.
  • Size (in MB) - for example, when the debug log reaches 2MB. The size option is available as of OpenAM 13. In OpenAM 12, you should consider tools such as logadm (Solaris®) or logrotate (Linux®) if you want to rotate by size. These are third-party tools that we suggest can be used for log rotation but are not supported by ForgeRock.
Note

It is recommended that you copy the debug logs prior to clearing the contents, rather than deleting the logs as this can cause issues if a process is still holding a filehandle. Additionally, you should keep debug logging to a minimum (level: error) and only increase it when troubleshooting an issue.

To configure Java Policy Agent debug file rotation:

  1. Copy the debugconfig.properties file (located in the /path/to/tomcat/webapps/openam/WEB-INF/classes directory) to a temporary location.
  2. Edit the properties in the debugconfig.properties file as detailed in Rotating Debug Logs to configure debug log file rotation. For example, if you want your Java Policy Agent debug logs to rotate every 1440 minutes with a suffix of the date and time, you would set the rotation and suffix properties in this file as follows:
    org.forgerock.openam.debug.rotation=1440
    org.forgerock.openam.debug.suffix=-MM.dd.yyyy-HH.mm
    
    Alternatively, if you want your debug logs to rotate each time they reach 2MB with a suffix of the date and time, you would set the maxsize and suffix properties in this file as follows:
    org.forgerock.openam.debug.rotation.maxsize=2
    org.forgerock.openam.debug.suffix=-MM.dd.yyyy-HH.mm_ss.SSS
  3. Copy the debugconfig.properties file to the classpath of your web application container. For example, if you are using Apache Tomcat™, the /path/to/tomcat/lib directory would be a good location.
  4. Restart the web application container in which the policy agent runs to apply these configuration changes.

Rotating Java Policy Agent audit log

Note

Audit logs are logged remotely by default. In which case they are located in the $HOME/[am_instance]/openam/log directory by default and cannot be rotated using this method. Instead you can rotate them as per AM/OpenAM audit logs: Reference › Configuration Reference › Logging.

AM/OpenAM does not rotate Java Policy Agent local audit logs by default, but you can configure it to do so based on size, for example, once the file reaches 50MB. The size should be specified in bytes, for example, 52428800.

If your Java policy agent uses centralized configuration, you can configure the local audit log to rotate using either the console, ssoadm or the bootstrap file:

  • AM 6 and later console: navigate to: Realms > [Realm Name] > Applications > Agents > Java > [Agent ID] > Global and enable Rotate Local Audit Log.
  • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > Agents > J2EE > [Agent Name] > Global > Rotate Local Audit Log and select the Enabled option. You should then set the corresponding file size at which the file rotates in the 'Local Audit Log Rotation Size' field. This defaults to 52428800 (50MB) when rotation is enabled.
  • OpenAM 13.x console: navigate to: Realms > [Realm Name] > Agents > J2EE > [Agent Name] > Global > Rotate Local Audit Log and select the Enabled option. You should then set the corresponding file size at which the file rotates in the 'Local Audit Log Rotation Size' field. This defaults to 52428800 (50MB) when rotation is enabled.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Agents > J2EE > [Agent Name] > Global > Rotate Local Audit Log and select the Enabled option. You should then set the corresponding file size at which the file rotates in the 'Local Audit Log Rotation Size' field. This defaults to 52428800 (50MB) when rotation is enabled.
  • ssoadm: enter the following command:
    $ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a com.sun.identity.agents.config.local.log.rotate=true com.sun.identity.agents.config.local.log.size=[filesize]
    
    replacing [realmname], [agentname], [adminID], [passwordfile] and [filesize] with appropriate values. 
  • Bootstrap file: edit the com.sun.identity.agents.config.local.log.rotate and com.sun.identity.agents.config.local.log.size properties in the OpenSSOAgentBootstrap.properties file (located in the /config directory where the Java policy agent is installed). You should set these properties as follows:
    com.sun.identity.agents.config.local.log.rotate=true
    com.sun.identity.agents.config.local.log.size=[filesize]
    
    replacing [filesize] with an appropriate value.

If using local configuration, you should edit the OpenSSOAgentBootstrap.properties file as described above.

It is recommended that you copy the audit log prior to clearing the contents, rather than deleting the log as this can cause issues if a process is still holding a file handle.

See Also

How do I enable debug logging for troubleshooting Policy Agents (All versions)?

How do I rotate Web Policy Agents (All versions) debug and audit logs?

Setup and Maintenance Guide › Troubleshooting › Rotating Debug Logs

User Guide › Configuring Global Properties

Related Training

N/A

Related Issue Tracker IDs

OPENAM-4113 (Request for OpenAM debug logs rotation based on size(in MB))

OPENAM-6450 (Log Number of History files count is ignored)

OPENAM-6477 (request for Agent log retention configuration)


How do I clear debug logs in AM/OpenAM (All versions)?

The purpose of this article is to provide information on clearing your debug logs in AM/OpenAM when they get too large (for example, you previously set the debug level to message) and you no longer need them. You can also use this information to clear other logs, such as amAgent. Clearing debug logs as opposed to deleting them negates the need to stop and start your AM/OpenAM server. The information in this article applies if you are using a UNIX® or Linux® system.

Clearing an individual debug log

You can clear an individual debug log as follows from your terminal window:

  1. Change directory to your debug directory (which is typically located in the $HOME/[am_instance]/openam/ directory).
  2. Copy any logs you may want to keep. Once you run the next command, the logs will be permanently gone.
  3. Enter the following command:
    $ cat /dev/null >[filename]
    replacing [filename] with the name of the debug log file you want to clear.

Clearing all debug logs in the debug directory

You can clear all debug logs in the debug directory as follows:

  1. Copy any logs you may want to keep. Once you run the next command, the logs will be permanently gone.
  2. Enter the following command in your terminal window:
    $ for file in /path/to/debug/*; do > $file; done
    For example:
    $ for file in $HOME/openam1/openam/debug/*; do > $file; done
    to empty all the debug log files in the debug directory.

Alias

You could also create an alias to run this command to make it easy to re-use. For example, enter the following command:

$ alias flushamdebug='for file in $HOME/openam1/openam/debug/*; do > $file; done'

and then just enter the following command to run it at any time:

$ flushamdebug

See Also

How do I enable Message level debugging in AM/OpenAM (All versions) debug files?

How do I enable debug logging for troubleshooting Policy Agents (All versions)?

How do I rotate AM/OpenAM (All versions) debug logs?

How do I rotate Web Policy Agents (All versions) debug and audit logs?

How do I rotate Java Policy Agents (All versions) debug and audit logs?

How do I clear stats logs in AM/OpenAM (All versions)?

Related Training

N/A

Related Issue Tracker IDs

N/A


Known Issues


Out of Memory exception causes AM/OpenAM (All versions) to hang due to increasing number of open policy agent sessions

The purpose of this article is to provide assistance if AM/OpenAM frequently hangs due to an Out of Memory exception when you have Apache™ Web Policy Agents making repeated authentication requests.

Symptoms

You see an increasing number of open policy agent sessions building up, where old sessions are not expiring. You can monitor the number of open sessions as detailed in How do I monitor session statistics in AM/OpenAM (All versions)?

The following behavior is seen when this occurs:

  • AM/OpenAM servers frequently hang with Out of Memory exceptions requiring a restart in order to restore service.
  • An Out of Memory exception is frequently seen with an intermittent hang.
  • Out of Memory heap dump analysis indicates that there are a large number of application tokens for the policy agents. See How do I collect JVM data for troubleshooting AM/OpenAM (All versions)? for further information.
  • Refreshing a protected page one minute after login causes the agent to authenticate again, creating a new token while the old one persists in the CTS.

Example application token 

The coreTokenUserID seen in the application session token will be equal to the web agents profile name, as shown in the example below:

  • Web agent profile name: apache24
  • coreTokenUserId: id=apache24,ou=agent,dc=openam,dc=forgerock,dc=com

Recent Changes

N/A

Causes

The agent application token created by the repeated authentication requests are not expiring when unused for a period of time. Eventually, the number of open policy agent sessions will build up in AM/OpenAM until session limits and resources become exhausted causing the server to hang with an Out of Memory exception.

Solution

This issue can be resolved by setting the com.iplanet.am.session.agentSessionIdleTime property appropriately to force idle policy agent sessions to expire.

The default is 0 (policy agent sessions never expire) but you can also set it to a value of 30 or above (no maximum) to indicate the number of minutes a session can be idle. When set to 30 or above, the agent application token is stored in the CTS token store rather than locally. 

You can set this property using either the console, Amster (AM 5 and later) or ssoadm:

  • AM / OpenAM 13.5 console: navigate to: Configure > Server Defaults > Advanced > com.iplanet.am.session.agentSessionIdleTime and amend the required number of minutes.
  • Pre-OpenAM 13.5 console: navigate to: Configuration > Servers and Sites > Default Server Settings > Advanced > com.iplanet.am.session.agentSessionIdleTime and enter the required number of minutes.
  • Amster: follow the steps in How do I update property values in AM (All versions) using Amster? with these values:
    • Entity: DefaultAdvancedProperties
    • Property: com.iplanet.am.session.agentSessionIdleTime
  • ssoadm: enter the following command:
    $ ./ssoadm update-server-cfg -s default -u [adminID] -f [passwordfile] -a com.iplanet.am.session.agentSessionIdleTime=[minutes]
    replacing [adminID], [passwordfile] and [minutes] with appropriate values.
Note

You must restart both the web application container in which AM/OpenAM runs and the Apache server where the agent is installed to apply these configuration changes. 

See Also

How do I monitor session statistics in AM/OpenAM (All versions)?

How do I collect JVM data for troubleshooting AM/OpenAM (All versions)?

How do I use the msnapshots script to capture information for troubleshooting AM/OpenAM (All versions)?

Reference › Configuration Reference › Advanced Properties

Related Training

N/A

Related Issue Tracker IDs

OPENAM-10377 (Agent creates unexpired tokens which are not deleted from CTS)


Apache Web Agent (All versions) repeatedly reports failed to load OPENSSL_init_ssl errors

The purpose of this article is to provide assistance if the Apache™ Web Agent repeatedly reports SSL errors such as "failed to load OPENSSL_init_ssl".

Symptoms

The Web Agent appears to be functioning normally, however, one of the following error snippets is shown repeatedly in your logs depending on which version of the Web Agent you are using:

  • Web Agents 5.5.1.0 and later:
    [Mon Aug 12 14:03:29.156134 2019] [amagent:notice] [pid 1234:tid 140277498116015] OpenSSL library status: trying libssl... libssl.so.1.1 dlopen error: libssl.so.1.1: cannot open shared object file: No such file or directory, found libssl.so.10, failed to load OPENSSL_init_ssl, failed to load TLS_client_method, failed to load SSL_get_state, trying libcrypto... libcrypto.so.1.1 dlopen error: libcrypto.so.1.1: cannot open shared object file: No such file or directory, found libcrypto.so.10, OpenSSL v1.0.x/0.9.8 library support is available
    
  • Pre-Web Agents 5.5.1.0:
    Aug 12 14:03:29.950273 2019] [amagent:error] [pid 1234:tid 140277498116015] init_ssl(): trying libssl...
    [Mon Aug 12 14:03:29.950664  2019] [amagent:error] [pid 1234:tid 140277498116015] init_ssl():  libssl.so.1.1 dlopen error: libssl.so.1.1: cannot open shared object  file: No such file or directory
    [Mon Aug 12 14:03:29.950902 2019] [amagent:error] [pid 1234:tid 140277498116015] init_ssl(): found libssl.so.10
    [Mon Aug 12 14:03:29.951107 2019] [amagent:error] [pid 1234:tid 140277498116015] init_ssl(): failed to load OPENSSL_init_ssl
    [Mon Aug 12 14:03:29.951124 2019] [amagent:error] [pid 1234:tid 140277498116015] init_ssl(): failed to load TLS_client_method
    [Mon Aug 12 14:03:29.951128 2019] [amagent:error] [pid 1234:tid 140277498116015] init_ssl(): failed to load SSL_get_state
    [Mon Aug 12 14:03:29.951309 2019] [amagent:error] [pid 1234:tid 140277498116015] init_ssl(): trying libcrypto...
    [Mon Aug 12 14:03:29.951534  2019] [amagent:error] [pid 1234:tid 140277498116015] init_ssl():  libcrypto.so.1.1 dlopen error: libcrypto.so.1.1: cannot open shared  object file: No such file or directory
    [Mon Aug 12 14:03:29.951707 2019] [amagent:error] [pid 1234:tid 140277498116015] init_ssl(): found libcrypto.so.10
    [Mon Aug 12 14:03:29.951999  2019] [amagent:error] [pid 1234:tid 140277498116015] init_ssl():  OpenSSL v1.0.x/0.9.8 library support is available
    

You may see these error snippets in either, or both the Agent logs and Apache logs (located in /path/to/agent/log and /path/to/apache/logs/error_log respectively). The change in log output is due to AMAGENTS-1933 (init_ssl errors fill error_log), which made the messages less verbose.

Recent Changes

N/A

Causes

The Web Agent tries to load various OpenSSL libraries before finding the appropriate one, as evidenced by the following message:

OpenSSL v1.0.x/0.9.8 library support is available

The reason you see all the messages leading up to this point is because of how the Apache logger works when using MPM preforking. While the Agent is trying to load libraries, there are only two logging options available: Error and Notice. These messages are Notice level and are therefore shown.

Solution

Firstly, these messages can be safely ignored because the OpenSSL library is found in the end. Additionally, you can make them less verbose by upgrading to Agents 5.5.1.0 or later; you can download this from BackStage.

The only way to completely prevent these messages is to change your Apache MPM configuration to use a threaded MPM like worker or event. This is documented on the Apache pages: Multi-Processing Modules (MPMs) but in essence:

  • A threaded MPM like worker or event is suitable for sites that need a lot of scalability.
  • The prefork MPM is suitable for sites that require stability or compatibility with older software.
Note

Managing your Apache configuration is outside the scope of ForgeRock support; if you want more tailored advice, consider engaging Deployment Support Services.

See Also

Installing Web policy agent 4.x or 5.x fails with a no ssl/library support error

SSL in AM/OpenAM and Policy Agents

Related Training

N/A

Related Issue Tracker IDs

AMAGENTS-2716 (Remove init_ssl(): failed to load OPENSSL_init_ssl message in apache error_log)

AMAGENTS-1933 (init_ssl errors fill error_log)


An illegal reflective access operation has occurred when using Java 11 with ForgeRock products

The purpose of this article is to provide assistance if you encounter "An illegal reflective access operation has occurred" warning when using ForgeRock products with Java® 11. This issue affects AM 6.5.x, DS 6.5.x, IDM 6.5.x, IG 6.5.x and Java Agent 5.6.x.

Symptoms

You will see An illegal reflective access operation has occurred warning when installing and using AM (including Amster and ssoadm tools), Java Agents, DS, IDM and IG. The subsequent two lines following this warning vary depending on which product you are using and what you were doing at the time it occurred.

Here are some examples of the types of error you will see by product:

  • AM:
    WARNING: An illegal reflective access operation has occurred
    WARNING: Illegal reflective access by org.codehaus.groovy.vmplugin.v7.Java7$1 (file:/path/to/tomcat/webapps/openam/WEB-INF/lib/groovy-2.4.6.jar (about:blank)) to constructor java.lang.invoke.MethodHandles$Lookup(java.lang.Class,int)
    WARNING: Please consider reporting this to the maintainers of org.codehaus.groovy.vmplugin.v7.Java7$1
    WARNING: Use --illegal-access=warn to enable warnings of further illegal reflective access operations
    WARNING: All illegal access operations will be denied in a future release
    
  • Java Agent:
    WARNING: An illegal reflective access operation has occurred
    WARNING: Illegal reflective access by org.forgerock.openam.sdk.com.google.inject.internal.cglib.core.$ReflectUtils$1 (file:/tmp/5.6.0/java/java_agents/tomcat_agent/lib/jee-agents-installtools-5.6.0.jar) to method java.lang.ClassLoader.defineClass(java.lang.String,byte[],int,int,java.security.ProtectionDomain)
    WARNING: Please consider reporting this to the maintainers of org.forgerock.openam.sdk.com.google.inject.internal.cglib.core.$ReflectUtils$1
    WARNING: Use --illegal-access=warn to enable warnings of further illegal reflective access operations
    WARNING: All illegal access operations will be denied in a future release
    
  • DS:
    WARNING: An illegal reflective access operation has occurred
    WARNING: Illegal reflective access by org.opends.server.util.Platform$PlatformIMPL (file:/path/to/ds/lib/opendj.jar) to constructor sun.security.tools.keytool.CertAndKeyGen(java.lang.String,java.lang.String)
    WARNING: Please consider reporting this to the maintainers of org.opends.server.util.Platform$PlatformIMPL
    WARNING: Use --illegal-access=warn to enable warnings of further illegal reflective access operations
    WARNING: All illegal access operations will be denied in a future release
    
  • IDM:
    WARNING: An illegal reflective access operation has occurred
    WARNING: Illegal reflective access by org.apache.felix.framework.ext.ClassPathExtenderFactory$DefaultClassLoaderExtender (file:/path/to/idm/bin/felix.jar) to method java.net.URLClassLoader.addURL(java.net.URL)
    WARNING: Please consider reporting this to the maintainers of org.apache.felix.framework.ext.ClassPathExtenderFactory$DefaultClassLoaderExtender
    WARNING: Use --illegal-access=warn to enable warnings of further illegal reflective access operations
    WARNING: All illegal access operations will be denied in a future release
    

Recent Changes

Upgraded to Java 11.

Installed AM 6.5.x, DS 6.5.x, IDM 6.5.x or IG 6.5.x with Java 11.

Installed Java Agent 5.6.x with Java 11.

Causes

These warnings occur when using Groovy with Java 11. For reference, these known issues are:

Whenever you use functionality that accesses Groovy scripting, you will see these warnings.  

Additionally, there is a similar compatibility issue with Felix: FELIX-5765 (An illegal reflective access operation has occurred).

Solution

These messages can be safely ignored because they do not impact the use or functionality of ForgeRock products. However, if you do not want to see them, you can downgrade Java to JDK 1.8 or whitelist these warnings.

See Also

SSLHandshakeException or ClassCastException when using an HSM and Java 11 with ForgeRock products

Federation related pages do not display in the console with a java.lang.NoClassDefFoundError: sun/misc/CharacterEncoder error in AM 6.5.x

How do I disable TLS 1.3 when running DS 6.5 with Java 11?

Cannot install or use ssoadm in AM 5.x, 6.0.0.x, 6.5.0, 6.5.0.1 and OpenAM 13.x after restricting configuration store (DS/OpenDJ) cipher suites or Java upgrade

AM 5.x and 6.0.0.x, IDM 6.x and Rest2LDAP cannot connect to DS 5.x or 6 after restricting DS cipher suites or Java upgrade

Related Training

N/A

Related Issue Tracker IDs

OPENAM-14478 (AM on JDK11 shows warning when Groovy access with "Illegal reflective access by org.codehaus.groovy.vmplugin.v7.Java7$1")

OPENIDM-11765 (Warnings on startup when using embedded DS repo with Java 11)

OPENDJ-5664 (JDK 11: illegal reflective access warning during import-ldif)

OPENDJ-5663 (JDK 11: illegal reflective access warning on setup (without profile))

OPENDJ-5660 (JDK 11: illegal reflective access warning on setup (with profile))

AMAGENTS-2616 (Java agent installer makes warning messages when JDK 11 is used)


Schannel communications fail in Web Agents 4.1, 4.2 and 5.x running on Microsoft Windows 2008 R2 or 2012 with TLS 1.2 enabled

The purpose of this article is to provide assistance when Schannel (the built-in Secure Channel API for SSL/TLS communications) fails in Web Agents running on Microsoft® Windows® 2008 R2 or 2012 when TLS 1.2 is enabled. You will see a "creating security context failed (0x80090308)" error when this happens.

Symptoms

The web agent running on Microsoft Windows 2008 R2 or 2012 fails to create a connection to an AM server that only has TLS 1.2 enabled. This issue does not occur on Microsoft Windows 2016 or 2019 servers.

The following error is shown in the agent debug log when this happens:

net_client_handshake_loop(): creating security context failed (0x80090308)
wnet_connect(): failed to connect to 192.0.2.0:8443, error: -29
SSL/TLS connection to 192.0.2.0:8443 failed (operation not completed)
unable to connect to 192.0.2.0:8443

The 0x80090308 code signifies a SEC_E_INVALID_TOKEN error.

Recent Changes

N/A

Causes

The web agent cannot negotiate the acceptable cipher, which causes the connection to fail.

Solution

This issue can be resolved by applying the KB3140245 update: you can download this from: Microsoft Update Catalog: KB3140245.

See Update to enable TLS 1.1 and TLS 1.2 as default secure protocols in WinHTTP in Windows for further information on this update.

See Also

FAQ: SSL/TLS secured connections in AM/OpenAM and Policy Agents

SSL in AM/OpenAM and Policy Agents

User Guide › Configuring Bootstrap Properties

Related Training

N/A

Related Issue Tracker IDs

N/A


ERROR: Failed to obtain auth service url from server: null://null:null stops JEE Policy Agent 3.5.x from starting up correctly

The purpose of this article is to provide assistance if you encounter "ERROR: Failed to obtain auth service url from server: null://null:null" which prevents the JEE policy agent from starting up. You will also see a "com.iplanet.services.naming.ServerEntryNotFoundException: Cannot find server ID" error.

Symptoms

An error similar to the following is shown in the agent logs when the policy agent fails to start:

amAuthContext:10/11/2017 11:28:14:574 AM EST: Thread[default task-2,5,main]
**********************************************
amAuthContext:10/11/2017 11:28:14:574 AM EST: Thread[default task-2,5,main]
ERROR: Failed to obtain auth service url from server: null://null:null
amNaming:10/11/2017 11:28:14:605 AM EST: Thread[default task-2,5,main]
**********************************************
amNaming:10/11/2017 11:28:14:605 AM EST: Thread[default task-2,5,main]
ERROR: WebtopNaming.getServerId():serverId null for server: http://host1.example.com:8080/openam
amNaming:10/11/2017 11:28:14:605 AM EST: Thread[default task-2,5,main]
ERROR: WebtopNaming.getServerId()
com.iplanet.services.naming.ServerEntryNotFoundException: Cannot find server ID.
   at com.iplanet.services.naming.WebtopNaming.getServerID(WebtopNaming.java:724)
   at com.iplanet.services.naming.WebtopNaming.getServerID(WebtopNaming.java:621)

You will also see similar errors in the AM/OpenAM CoreSystem debug log where the Sites URL (2nd line) shows a trailing slash:

amNaming:01/28/2016 11:17:49:763 AM CST: Thread[localhost-startStop-1,5,main]
Sites : [http://siteA.example.com:8080/openam/|02]
amNaming:01/28/2016 11:17:49:777 AM CST: Thread[localhost-startStop-1,5,main]
servers : [http://host1.example.com:8080/openam|01|02]
amNaming:01/28/2016 11:17:49:778 AM CST: Thread[localhost-startStop-1,5,main]
Site Names: [test]
amNaming:01/28/2016 11:17:49:781 AM CST: Thread[localhost-startStop-1,5,main]
NamingService.insertLBCookieValues()LBCookie Mappings : {01=01}
amNaming:01/28/2016 11:17:49:781 AM CST: Thread[localhost-startStop-1,5,main]
SiteID table -> {02=02, 01=02}
amNaming:01/28/2016 11:17:49:781 AM CST: Thread[localhost-startStop-1,5,main]
SiteNameToIDs table -> {test=02}
amNaming:01/28/2016 11:17:49:782 AM CST: Thread[localhost-startStop-1,5,main]
ERROR: WebtopNaming.getServerId():serverId null for server: http://siteA.example.com:8080/openam
amNaming:01/28/2016 11:17:49:785 AM CST: Thread[localhost-startStop-1,5,main]
ERROR: WebtopNaming.getServerId()
com.iplanet.services.naming.ServerEntryNotFoundException: Cannot find server ID.
    at com.iplanet.services.naming.WebtopNaming.getServerID(WebtopNaming.java:757)
    at com.iplanet.services.naming.WebtopNaming.updatePlatformServerIDs(WebtopNaming.java:1336)
    at com.iplanet.services.naming.WebtopNaming.updateNamingTable(WebtopNaming.java:1259)
    at com.iplanet.services.naming.WebtopNaming.getNamingProfile(WebtopNaming.java:1142)
    at com.iplanet.services.naming.WebtopNaming.getServerID(WebtopNaming.java:729)
    at com.iplanet.services.naming.WebtopNaming.getServerID(WebtopNaming.java:654)

Recent Changes

Configured a site.

Updated the Primary or Secondary URL for an existing site.

Configured the JEE Policy Agent 3.5.x.

Causes

When AM/OpenAM sites are configured, the JEE policy agent communicates with the site that includes the AM/OpenAM instance that issued the session token. By default, it uses the site's Primary URL for communications. The trailing slash at the end of the Primary URL causes a bad server lookup, which prevents the JEE policy agent from obtaining the server ID and starting up.

If you have configured your policy agent to use the Secondary URL instead, then a trailing slash at the end of the Secondary URL will cause the same issue.

See OPENAM-8227 (Having a trailing / in your site URL will cause J2EE agent to not properly obtain server id ) for further details. 

Solution

This issue can be resolved by upgrading to Java Agents 5 or later; you can download this from BackStage.

Workaround

You can workaround this issue by removing the trailing slash at the end of the Primary URL and/or Secondary URL using either the console, ssoadm or Amster (AM 5 and later):

  • AM / OpenAM 13.5 console: navigate to: Deployment > Sites > [Site Name] and remove the trailing slash from the Primary URL and/or Secondary URL.
  • Pre-OpenAM 13.5 console: navigate to: Configuration > Servers and Sites > Sites > [Site Name] and remove the trailing slash from the Primary URL and/or Secondary URL.
  • ssoadm: 
    • Primary URL: enter the following command:
      $ ./ssoadm set-site-pri-url -s [sitename] -u [adminID] -f [passwordfile] -i [primaryURL]
      
      replacing [sitename], [adminID], [passwordfile] and [primaryURL] with appropriate values, where [primaryURL] should be the primary URL without the trailing slash.
    • Secondary URL: enter the following command:
      $ ./ssoadm set-site-sec-urls -s [sitename] -u [adminID] -f [passwordfile] -a [secondaryserverURL]
      replacing [sitename], [adminID], [passwordfile] and [secondaryserverURL] with appropriate values, where [secondaryserverURL] should be the secondary URL without the trailing slash.
  • Amster: follow the steps in How do I update property values in AM (All versions) using Amster?with these values:
    • Entity: Sites
    • Primary URL Property: url
    • Secondary URL Property: secondaryURLs
Note

You must restart both the web application containers in which AM/OpenAM and the policy agent runs to apply these configuration changes.

See Also

FAQ: Configuring Policy Agents in AM/OpenAM

Agents and policies in AM/OpenAM

Troubleshooting AM/OpenAM and Policy Agents

Related Training

N/A

Related Issue Tracker IDs

OPENAM-8227 (Having a trailing / in your site URL will cause J2EE agent to not properly obtain server id )

OPENAM-4143 (Validate site URLs to avoid StackOverFlowError)


Installation


redirect_uri_mismatch error occurs after upgrading to, or installing Web Agents 5.x

The purpose of this article is to provide assistance if you encounter a "redirect_uri_mismatch The redirection URI provided does not match a pre-registered value" after upgrading to, or installing Web Agents 5.x, or upgrading to AM 6.x.

Symptoms

The following error is shown in the browser when accessing the resource protected by the agent:

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

You are then redirected to the login URL, which is in a similar format to this example URL:

https://host1.example.com:8443/openam/oauth2/authorize?response_type=id_token&scope=openid&client_id=myWebAgent&redirect_uri=http%3A%2F%2Fhost2.example.net%3A80%2Fagent%2Fcdsso-oauth2&state=475c3531-e74d-ff40-9792-83ebc25d2c77&nonce=95B1765FC776BBEFF70EBCB73782A15E&response_mode=form_post&agent_provider=true&agent_realm=%2F

Recent Changes

Upgraded to, or installed Web Agents 5.x.

Upgraded to AM 6 or later.

Causes

CDSSO improvements in Agents 5 means CDSSO is the only SSO mode used by agents; it is achieved using the OAuth 2.0 protocol and the oauth2/authorize endpoint. See Release Notes › Major Improvements for further information.

Where there is a mismatch between the protocols used to access the resource and the one the agent is configured against (for example, you are accessing a resource with a URL that uses the https protocol but you configured your agent with a URL that uses the http protocol), the hidden OAuth2 agent does not understand the redirection URL and prevents access as a security precaution.

Additionally, this issue can occur after upgrading to AM 6 and later, where an extra forward slash (/) is inadvertently included in the CDSSO Redirect URI, which prevents access.

Solution

This issue can be resolved by ensuring both the Agent Root URL for CDSSO and CDSSO Redirect URI are set correctly.

Agent Root URL for CDSSO

Ensure the root URL for CDSSO is set to the redirection URL in the following format: protocol://host:port/. For the example URL shown in the Symptoms section, you would specify the following root URL:

http://host2.example.net:80

You can set the root URL for CDSSO using either the console, Amster or ssoadm:

  • Console: navigate to: Realms > [Realm Name] > Applications > Agents > Web > [Agent Name] > Global > Agent Root URL for CDSSO and specify the redirection URL.
  • Amster: follow the steps in How do I update property values in AM (All versions) using Amster? with these values:
    • Entity: WebAgents
    • Property: cdssoRootUrl
  • ssoadm: enter the following command:
    $ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a sunIdentityServerDeviceKeyValue[0]=agentRootURL=[redirectionURL]
    replacing [realmname], [agentname], [adminID], [passwordfile] and [redirectionURL] with appropriate values.

CDSSO Redirect URI

The URI should not start with a forward slash, for example, the default value is:

agent/cdsso-oauth2

If it starts with a forward slash (for example, /agent/cdsso-oauth2), you will need to remove the forward slash using either the console, Amster or ssoadm: 

  • Console: navigate to: Realms > [Realm Name] > Applications > Agents > Web > [Agent Name] > SSO > CDSSO Redirect URI and remove the / at the start of the URI. 
  • Amster: follow the steps in How do I update property values in AM (All versions) using Amster? with these values:
    • Entity: WebAgents
    • Property: com.sun.identity.agents.config.cdsso.redirect.uri
  • ssoadm: enter the following command:
    $ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a com.sun.identity.agents.config.cdsso.redirect.uri​​​​​​​=[redirectURI]
    replacing [realmname], [agentname], [adminID], [passwordfile] and [redirectURI​​​​​​​] with appropriate values.

See Also

redirect_uri_mismatch error occurs when using AM/OpenAM (All versions) as an OAuth 2.0 / OpenID client or provider

Unable to retrieve certificate with alias 'test' from keystore after making changes to the keystore in AM (All versions)

Agents and policies in AM/OpenAM

User Guide › Configuring Global Properties

User Guide › Request Process Flow

Related Training

N/A

Related Issue Tracker IDs

AMAGENTS-1538 (document redirect_uri_mismatch )

OPENAM-12531 (Running webagent 5.0.0 against OpenAM 5.5.1 which is upgraded from previous version will result in segmentation fault or crash)


Installing Web policy agent 4.x or 5.x fails with a no ssl/library support error

The purpose of this article is to provide assistance if you receive a "no ssl/library support" error when trying to install a Web policy agent.

Symptoms

An error similar to one of the following is shown when installing the Web policy agent depending on your operating system:

  • On Unix®, Linux® and Solaris® systems:
    init_ssl(): libssl.so is not available 
    init_ssl(): libcrypto.so is not available
    
  • On Microsoft® Windows® systems:
    init_ssl(): ssleay64.dll is not available (error: 126) 
    init_ssl(): libeay64.dll is not available (error: 126)
    
    init_ssl(): ssleay32.dll is not available (error: 126) 
    init_ssl(): libeay32.dll is not available (error: 126)
    

The corresponding install log shows the following error:

2017-08-31 11:27:09 am_agent_login(): error -26 (no ssl/library support) connecting to https://host1.example.com:8443/openam (https://host1.example.com:8443/openam)

Recent Changes

N/A

Causes

The Web policy agent cannot load the SSL libraries. There can be various reasons for this, including:

  • You are trying to install a 32bit version of the policy agent on a 64bit system; the 32bit version of the agentadmin tool cannot open the 64bit SSL libraries.
  • The SSL libraries are not installed.
Note

As of Web policy agents 4, independent NSS/NSPR libraries are no longer included for handling SSL; as of Web policy agent 4.1, the native Schannel for SSL communication is used for Microsoft Windows by default. If your operating system does not include native openssl packages, you must install OpenSSL. See OpenAM Web Policy Agent Release Notes › Before You Install › Important Changes to Existing Functionality (Table 2.2. Supported OpenSSL Versions) for further information on supported versions and Tips and feature insights for Web Policy Agents 4.x for further information on installation.

Solution

The solution depends on the cause as follows:

  • Ensure you are installing the appropriate version of the policy agent; if you have a 64bit operating system, you must install the 64bit policy agent.
  • Ensure either the operating system provides native openssl packages or OpenSSL is installed. If you are using OpenSSL, you can check that the OpenSSL libraries are in the correct location as follows and add them if they are missing:
    • On Linux systems:
      1. Check that the LD_LIBRARY_PATH environment variable is set. For example:
        $ echo $LD_LIBRARY_PATH
        
      2. Check that the OpenSSL libraries (libcrypto.so and libssl.so) are available in the path specified in this environment variable (LD_LIBRARY_PATH). 
    • On Unix and Solaris systems: 
      1. Check that either the LD_LIBRARY_PATH or LD_LIBRARY_PATH_64 environment variable (depending on whether you have a 32bit or 64bit system) is set. For example:
        $ echo $LD_LIBRARY_PATH
        $ echo $LD_LIBRARY_PATH_64
      2. Check that the OpenSSL libraries (libcrypto.so and libssl.so) are available in the path specified in the relevant environment variable (LD_LIBRARY_PATH or LD_LIBRARY_PATH_64). 
    • On Microsoft Windows systems, check that the OpenSSL libraries are in the correct location as follows (depending on whether you have a 32bit or 64bit system):
      • 32bit systems - libeay32.dll and ssleay32.dll files are in the \windows\syswow64  directory.
      • 64bit systems - libeay64.dll and ssleay64.dll files are in the \windows\system32 directory.

See Also

How do I upgrade to Web Policy Agent 4.x from a previous version?

Best practice for installing IIS Web Policy Agents (All versions)

How do I install AM/OpenAM (All versions) with Apache Web Policy Agent on Red Hat Enterprise Linux or CentOS configured with SELinux?

How do I silently remove a Web Policy Agent 4.x or 5.x?

FAQ: SSL/TLS secured connections in AM/OpenAM and Policy Agents

SSL in AM/OpenAM and Policy Agents

Web Agent User Guide

Related Training

N/A

Related Issue Tracker IDs

N/A


Apache Web Policy Agent 4.1.0 fails to start with no space left on device Configuration Failed error

The purpose of this article is to provide assistance if your Apache Web Policy Agent 4.1.0 (patch 4.1.0-28 and earlier) fails to start or install with "status: no space left on device Configuration Failed" error. You may also see the error "am_shm_create(): free disk space on the system is only x bytes, required y bytes".

Symptoms

The following error is shown when starting the Apache agent:

[Mon Nov 06 16:20:45 2017] [error] amagent_init() status: no space left on device 
Configuration Failed

An error similar to the following is shown in the agent debug log:

2017-11-06 16:27:09.422 +0000   ERROR [0x7fc7bf8457e0:18067] am_shm_create(): free disk space on the system is only 969605120 bytes, required 1073741824 bytes
2017-11-06 16:27:09.422 +0000   ERROR [0x7fc7bf8457e0:18067] get_memory_segment(): shared memory error: blocks

You may also encounter this issue when trying to install the Apache agent: 

[Fri Nov 10 11:35:43.082435 2017] [amagent:error] [pid 17392:tid 140597884139392] amagent_init() status: no space left on device 
[Fri Nov 10 11:35:43.082453 2017] [:emerg] [pid 17392:tid 140597884139392] AH00020: Configuration Failed, exiting

Recent Changes

Upgraded to, or installed Web policy agents 4.1.0 (patch 4.1.0-28 and earlier).

Added additional Apache instances.

Causes

Web policy agent 4.1.0 shares memory between instances to improve performance and this shared memory (as reported by statfs on the /dev/shm mount) is insufficient. This can happen if you have low memory or you have many Apache instances.

Solution

This issue can be resolved by upgrading to Web Agents 4.2 or later; you can download this from BackStage

Workaround

You can workaround this issue using one of the following approaches:

  • Reduce the amount of shared memory used.
  • Increase the shared memory available.
  • Reduce the number of Apache instances.

Reduce the amount of shared memory used

Try running the Apache instances with the following environment variables to reduce the amount of memory used:

AM_MAX_SHARED_POOL_SIZE=0x200000
AM_MAX_SESSION_CACHE_SIZE=0x4000000
export AM_MAX_SHARED_POOL_SIZE
export AM_MAX_SESSION_CACHE_SIZE

These variables set a maximum of 2MB of memory to be used for configuration and audit, and a maximum of 128MB for the session cache.

You can set these variables by editing /etc/sysconfig/httpd (or equivalent place such as envvars). 

See Web Policy Agent Guide › Configuring Web Policy Agent Environment Variables for further information.

Increase the shared memory available

Firstly you need to determine how much shared memory is required; the required value shown in the error is misleading. You can determine the absolute minimum value by running the agentadmin command with the --v option and then adding up the values shown below in bold:

$ ./agentadmin --v

OpenAM Web Agent for Apache Server 2.2.x
 Version: 4.1.0
 Revision: 31e821e
 Build machine: delacroix
 Build date: Nov 16 2016 11:40:32

System Resources:
 total memory size: 3.2GB
 pre-allocated session/policy cache size: 829.0MB
 log buffer size: 128.7MB
 min audit log buffer size: 2MB, max 2.0GB
 total disk (tmpfs/swap) size: 1.6GB
 free disk (tmpfs/swap) space size: 1.6GB

System contains sufficient resources (with remote audit log feature disabled).

We typically use 1.5GB for testing, so this may be a good starting point.

See How To Resize /dev/shm Filesystem In Linux? for further information on changing /dev/shm. For Docker, you need to set the --shm-size option when running it.

Reduce the number of Apache instances 

You should keep the number of Apache instances to the minimum and consider using vhosts instead; each agent can support a maximum of 32 vhosts.

We recommend the following when using vhosts:

  • Each vhost should have a separate AmAgentConf setting.
  • Set the AmAgentId property in each Apache instance's httpd.conf file to a different value, for example: 
    • In the first Apache instance:
      AmAgentId 0
      
    • For the next Apache instance:
      AmAgentId 1
      
      etc.
  • Ensure all Apache instances on the operating system pick up the following environment variable:
    AM_MAX_SESSION_CACHE_SIZE=0xf424000

If you choose to use a large number of Apache instances instead of using vhosts, you must monitor memory usage on each additional install and increase shared memory as needed. Additionally, further limiting of AM_MAX_SESSION_CACHE_SIZE may help, but you will need to test performance carefully after changing this. An increase in agent instances will also have an impact on AM/OpenAM servers, so you will need to monitor their CPU and RAM as well.

See Also

Web Policy Agent Release Notes › Web Policy Agents Platform Requirements

Web Policy Agent Guide › Configuring Web Policy Agent Environment Variables 

Web Policy Agent Guide › Installing Apache Web Policy Agents into a Virtual Host

Agents and policies in AM/OpenAM

Related Training

N/A

Related Issue Tracker IDs

AMAGENTS-1259 (DOC: Clarify the requirements on shm size)

AMAGENTS-581 (Agent 4.x has hard limit of 32 instances)

AMAGENTS-383 (Document shared memory commandline variables)

AMAGENTS-315 (Agent fails to start with insufficient shared memory)

AMAGENTS-273 (Improve WebAgent to not using shared memory /dev/shm)


Web policy agents 4 install fails with messages such as send_session_request or Server returned HTTP response code

The purpose of this article is to provide assistance if your Web policy agent 4 install fails with messages such as "send_session_request(): response status code: 200" or "Server returned HTTP response code: 500 for URL:".

Symptoms

These are two separate issues but they both cause the installer to fail and have the same resolution:

Silent Install

When performing a silent install for IIS or Apache™ web policy agents, the installation fails with a message similar to the following:

Error validating OpenAM - Agent configuration. 
See installation log C:\web_agents\iis_agent\bin\..\log\install_20160215316004.log file for more details. Exiting.

Cleaning up validation data...

Installation failed. 
See installation log C:\web_agents\iis_agent\bin\..\log\install_20160215316004.log file for more details. Exiting.

Corresponding error shown in the install log:

<Response><![CDATA[<SessionResponse vers="1.0" reqid="2">
<AddSessionListener> 
<Exception>AQIC5wM2LY4Sfcxwo1cOJAMRkbIsn0bS8Pm1IB623MLBCnM=@AAJTSQACNDAAAlMxAAIzMA==# Server returned HTTP response code: 500 for URL: http://openam.example.com:8080/amserver/sessionservice</Exception> 
</AddSessionListener>
</SessionResponse>]]></Response>

Interactive install

When performing an interactive install for IIS or Apache web policy agents, the following error is shown in the install log when the install fails:

2016-02-15 12:37:13 send_session_request(): response status code: 200
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ResponseSet vers="1.0" svcid="session" reqid="0">
<Response><![CDATA[<SessionResponse vers="1.0" reqid="1">
<GetSession>
...
</Session></GetSession>
</SessionResponse>]]></Response>
<Response><![CDATA[<SessionResponse vers="1.0" reqid="2">
<AddSessionListener>
<Exception>AQIC5wM2LY4Sfcxwo1cOJAMRkbIsn0bS8Pm1IB623MLBCnM http://host/openam/sessionservice</Exception>
</AddSessionListener>
</SessionResponse>]]></Response>
</ResponseSet>
2016-02-15 12:37:13 send_session_request(): status: error
2016-02-15 12:37:13 am_agent_login(): closing connection after failure

Recent Changes

N/A

Causes

Silent Install

The policy agent installer performs some unnecessary profile checks using the agent profile; the installation stops if these checks fail.

Interactive install

The policy agent installer performs an unnecessary session notification subscription, which causes the installer to fail in interactive mode.

Solution

This issue can be resolved by upgrading to Web Policy Agent 4.0.1 or later; you can download this from BackStage.

Alternatively, you can include the --forceInstall switch and perform a silent install, using the following command depending on your operating system:

  • UNIX® example:
    $ agentadmin --s --forceInstall
    
  • Microsoft® Windows® example:
    $ agentadmin.exe --s --forceInstall

See Also

How do I upgrade to Web Policy Agent 4.x from a previous version?

Tips and feature insights for Web Policy Agents 4.x 

Best practice for installing IIS Web Policy Agents (All versions)

OpenAM Web Policy Agent 4 Release Notes 

OpenAM Web Policy Agent 4 User's Guide

Related Training

N/A

Related Issue Tracker IDs

OPENAM-7452 (WPA4 agent might crash in configuration validation phase (silent install) )

OPENAM-8065 (WPA4 agentadmin installer fails in send_session_request when notifications are disabled in OpenAM)


Unable to find the "User" entry in the httpd.conf file error when installing the Apache Web policy agent 4.x or 5.x

The purpose of this article is to provide assistance if you receive errors about users and groups when installing the Apache™ Web policy agent. You will see "Unable to find the "User" entry in the httpd.conf file, will try APACHE_RUN_USER environment variable" and/or "Unable to find the "Group" entry in the httpd.conf file, will try APACHE_RUN_GROUP environment variable" errors.

Symptoms

The following error is shown when installing the Web policy agent:

OpenAM Web Agent for Apache Server installation.

Validating...
Error validating OpenAM - Agent configuration.
Installation failed.

The corresponding Install log shows the following errors:

2017-09-17 10:11:23 OpenAM Web Agent for Apache server silent installation
2017-09-17 10:11:23 license accepted with --acceptLicence option
2017-09-17 10:11:23 license was accepted earlier
2017-09-17 10:11:23 Unable to find the "User" entry in the httpd.conf file, will try APACHE_RUN_USER environment variable
2017-09-17 10:11:23 Unable to find the "Group" entry in the httpd.conf file, will try APACHE_RUN_GROUP environment variable
2017-09-17 10:11:23 am_agent_login(): closing connection after failure
2017-09-17 10:11:23 error validating OpenAM agent configuration
2017-09-17 10:11:23 installation error
2017-09-17 10:11:23 installation exit

Alternatively, you may not see an error when you install but instead see the following error in the error_log (located in the /path/to/apache/logs directory) when you start the server:

[unixd:alert] [pid 6616:tid 140758435143128] AH02155: getpwuid: couldn't determine user name from uid 4294967295, you probably need to modify the User directive

Recent Changes

N/A

Causes

These errors occur when the user and group are not set in the Apache httpd.conf file (located in the path/to/apache/conf directory) or in the APACHE_RUN_USER and APACHE_RUN_GROUP environment variables (envvars file).The Apache worker process requires read/write access to the agent configuration and log files. These entries ensure that Apache is running with the correct user context and that the Agent files are created in a way that is owned and accessible to them.

Solution

This issue can be resolved as follows:

  1. Check whether the user and group are set; you can do this via the httpd.conf file or equivalent file (such as envvars). For example: 
    • Review the httpd.conf file and check whether the user and group are set. By default they are set to apache, for example:
      $ cat httpd.conf | grep 'User\|Group'
      ...
      User apache
      Group apache
      ..
      
      
      If they are not set, you should set them; you can set them to apache or nobody.
    • Review the envvars file to ensure the user and group are set in the APACHE_RUN_USER and APACHE_RUN_GROUP environment variables. For example:
      $ cat envvars | grep 'APACHE_RUN_USER\|APACHE_RUN_GROUP'
      export APACHE_RUN_USER=apache
      export APACHE_RUN_GROUP=apache
      
      If they are not set, you should set them; you can set them to apache or nobody.
  2. Review the passwd and group files to check whether the user and group match what is set in your httpd.conf file or equivalent. For example:
    $ cat /etc/passwd | grep apache
    apache:x:48:48:apache:/usr/share/httpd:/sbin/nologin
    $ cat /etc/group | grep apache
    apache:x:48:
    

            If they are not set, you should set them to match what is in the httpd.conf file or equivalent.

Note

The Agent installer can change the ownership to the same User and Group specified in the Apache configuration. For further details on using the installer to set the appropriate permissions. See User Guide › To Install the Apache Web Agent.

See Also

Installing Web policy agent 4.x or 5.x fails with a no ssl/library support error

Tips and feature insights for Web Policy Agents 4.x

User Guide › Installing the Apache Web Agent › Before You Install

Related Training

N/A

Related Issue Tracker IDs

AMAGENTS-258 (If the Web agent Installation take more than 4 sec , it will throw "error validating OpenAM agent configuration")

OPENAM-8486 (WPA interactive installator can't correctly read provided Apache configuration path)

OPENAM-8406 (Agent 4.0.0 can not process the default apache2 config on Unbuntu 14.04)

AMAGENTS-59 (Apache_v24_Linux_64bit_4.0.0 fails to install on Suse 12 SP1)


Policy Agents and AM/OpenAM (All versions) fail to install on IBM WebSphere when SSL is enabled

The purpose of this article is to provide assistance if Policy Agents and AM/OpenAM fail with "java.lang.ClassNotFoundException: Cannot find the specified class com.ibm.websphere.ssl.protocol.SSLSocketFactory", when installing on IBM® WebSphere® with SSL is enabled. Additionally, this issue only occurs when using an IBM JVM.

Symptoms

The following error is shown in the policy agent or AM/OpenAM install log after the failed install attempt:

09/23/2016 19:10:05:930 EDT] ValidateURL.isServerUrlValid threw exception :
java.net.SocketException: java.lang.ClassNotFoundException: Cannot find the specified class com.ibm.websphere.ssl.protocol.SSLSocketFactory
   at javax.net.ssl.DefaultSSLSocketFactory.a(SSLSocketFactory.java:7)
   at javax.net.ssl.DefaultSSLSocketFactory.createSocket(SSLSocketFactory.java:1)
   at com.ibm.net.ssl.www2.protocol.https.c.afterConnect(c.java:62)
   at com.ibm.net.ssl.www2.protocol.https.d.connect(d.java:19)
   at com.ibm.net.ssl.www2.protocol.https.b.connect(b.java:57)
   at com.sun.identity.install.tools.configurator.ValidateURL.isServerURLValidInternal(ValidateURL.java:103)
   at com.sun.identity.install.tools.configurator.ValidateURL.access$000(ValidateURL.java:44)
   at com.sun.identity.install.tools.configurator.ValidateURL$URLValidatorProxy.run(ValidateURL.java:350)
   at java.lang.Thread.run(Thread.java:736)
Caused by: java.lang.ClassNotFoundException: Cannot find the specified class com.ibm.websphere.ssl.protocol.SSLSocketFactory

Recent Changes

N/A

Causes

The IBM JVM does not contain any SSL implementation classes, which means com.ibm.websphere.ssl.protocol.SSLSocketFactory is not found during the install process. 

This is a known issue with WebSphere when SSL is enabled: Cannot find the specified class com.ibm.websphere.ssl.protocol.SSLSocketFactory

Solution

This issue can be resolved by either using the Oracle® JVM instead of the IBM JVM or by making changes to the java.security file (located in the /path/to/websphere/java*/jre/lib/security directory).

To change the java.security file, you need to uncomment the two default JSSE socket factories and comment out the two WebSphere specific ones, so that it looks like this:

# Default JSSE socket factories 
ssl.SocketFactory.provider=com.ibm.jsse2.SSLSocketFactoryImpl 
ssl.ServerSocketFactory.provider=com.ibm.jsse2.SSLServerSocketFactoryImpl 
# WebSphere socket factories (in cryptosf.jar) 
#ssl.SocketFactory.provider=com.ibm.websphere.ssl.protocol.SSLSocketFactory 
#ssl.ServerSocketFactory.provider=com.ibm.websphere.ssl.protocol.SSLServerSocketFactory

See Also

Installation Guide › Preparing for Installation › Preparing IBM WebSphere

User Guide › Installing the WebSphere Java Agent

Related Training

N/A

Related Issue Tracker IDs

OPENAM-2341 (Improve WebSphere Portal agent integration)


Permission denied when starting Apache Web Policy Agent on Red Hat Enterprise Linux or CentOS system configured with SELinux

The purpose of this article is to provide assistance if you get a Syntax error ending with Permission denied when starting an Apache™ Web Policy Agent on a Red Hat® Enterprise Linux® (RHEL) or CentOS system configured with SELinux.

Symptoms

When starting the Apache web policy agent, you get an error similar to the following:

Starting httpd: httpd: Syntax error on line 1035 of /etc/httpd/conf/httpd.conf: Syntax 
error on line 1 of /opt/openam/web_agents/apache22_agent/Agent_001/config/dsame.conf: 
Cannot load /opt/openam/web_agents/apache22_agent/lib/libamapc22.so 
into server: /opt/openam/web_agents/apache22_agent/lib/libamapc22.so: 
failed to map segment from shared object: Permission denied

Recent Changes

Installed web policy agent for Apache HTTP Server.

Made SELinux configuration changes on the RHEL or CentOS system where the policy agent is already running.

Causes

When SELinux is in Enforcing mode (which enforces all configured parameters and logs any violations to the /var/log/audit/audit.log file), it can prevent external .so files being loaded.

You can check what mode SELinux is in using the following command:

getenforce

Solution

This issue can be resolved by giving access to the shared lib using the following command:

chcon -R -h -t httpd_sys_script_exec_t /opt/openam/web_agents/apache22_agent/lib/libamapc22.so

Alternatively, you can temporarily change the mode for SELinux to Permissive (which does not enforce the configured parameters but does log any violations to /var/log/audit/audit.log for troubleshooting purposes) using the following command:

setenforce Permissive
Note

The mode reverts to Enforcing when the system is rebooted; you can make this change permanent, if required, by editing the /etc/sysconfig/selinux file and changing SELINUX=enforcing to SELINUX=permissive.

See Also

How do I install AM/OpenAM (All versions) with Apache Web Policy Agent on Red Hat Enterprise Linux or CentOS configured with SELinux?

OpenAM Web Policy Agent Release Notes › Limitations

Security-Enhanced Linux User Guide

SELinux

Related Training

N/A

Related Issue Tracker IDs

N/A


Redirect


Policy Agent (All versions) does not redirect user correctly if the redirect URL is too long

The purpose of this article is to provide assistance if users are not redirected by the policy agent as expected when the redirect URL is too long.

Symptoms

The user is redirected incorrectly when the redirect URL is too long; shortening the URL results in a successful redirection.

An error similar to the following is shown in the patternMatching debug log when this happens:

RedirectUrlValidator.isRedirectUrlValid: The url was length nnnn which is longer than the allowed maximum of 2000

Where nnnn signifies the length of the redirect URL. 

Recent Changes

N/A

Causes

The maximum redirect URL that can be validated by AM/OpenAM is 2000 characters by default. If the length of the URL exceeds this, validation of the requested goto URL will not succeed and therefore does not redirect to the expected page.

Solution

This issue can be resolved by increasing the maximum length of the redirect URL to at least the number stated in the patternMatching debug log. This is an advanced property (org.forgerock.openam.redirecturlvalidator.maxUrlLength), which is available in AM, OpenAM 13.5.x and OpenAM 12.0.4. Prior to these versions, you cannot increase the maximum length.

You can update this property using either the console, Amster (AM 5 and later) or ssoadm:

  • AM / OpenAM 13.5 console: navigate to: Configure > Server Defaults > Advanced > org.forgerock.openam.redirecturlvalidator.maxUrlLength and enter the maximum redirect URL length that can be validated.
  • Pre-OpenAM 13.5 console: navigate to: Configuration > Servers and Sites > Default Server Settings > Advanced > org.forgerock.openam.redirecturlvalidator.maxUrlLength and enter the maximum redirect URL length that can be validated.
  • Amster: follow the steps in How do I update property values in AM (All versions) using Amster?with these values:
    • Entity: DefaultAdvancedProperties
    • Property: org.forgerock.openam.redirecturlvalidator.maxUrlLength
  • ssoadm: enter the following command:
    $ ./ssoadm update-server-cfg -s default -u [adminID] -f [passwordfile] -a org.forgerock.openam.redirecturlvalidator.maxUrlLength=[length]
    replacing [adminID], [passwordfile] and [length] with appropriate values.
Note

You must restart the web application container in which AM/OpenAM runs to apply these configuration changes.

See Also

redirect_uri_mismatch error occurs after upgrading to, or installing Web Agents 5.x

JEE Policy Agent 3.5.x fails to redirect to AM/OpenAM login or logout URL and shows 500: Internal server error

Agents and policies in AM/OpenAM

Reference › Advanced Properties

Related Training

N/A

Related Issue Tracker IDs

OPENAM-13109 (Default org.forgerock.openam.redirecturlvalidator.maxUrlLength is too short)


Redirect loop between AM and Agent 5.x after successful authentication

The purpose of this article is to provide assistance if you encounter a redirect loop between AM and Agent 5.x after successful authentication.

Symptoms

After a successful login, the user is redirected back to the protected resource and then back to the AM login page for authentication, thereby creating a redirect loop. The redirect loop may happen automatically without you re-entering your credentials.

You will also notice a redirect URL similar to the following (with URL encoding removed for readability). Note the agent/cdsso-oauth2 parameter:

https://host1.example.com/openam/XUI/?realm=/employees#login&goto=host1.example.com:8080/openam/oauth2/authorize?response_mode=form_post&state=247f267e-941b-bd7e-284e-8a8f13fbef81&redirect_uri=http://host2.example.net:8080/agent/cdsso-oauth2&response_type=id_token&scope=openid&client_id=webagent&agent_provider=true&agent_realm=%2F&nonce=E7ADEC50C034652415FB830236D4BCBB

Additionally, this redirect loop only happens when the agent initially redirects you to the protected resource. If you navigate directly to the login page, you can authenticate successfully.

Recent Changes

Upgraded to, or installed Agents 5.x.

Configured the AM Login URL (com.sun.identity.agents.config.login.url property):

  • With a URL that directs the user to a realm, for example:
    com.sun.identity.agents.config.login.url property=https://host1.example.com/openam/XUI/?realm=/employees#login
  • Because you have a custom login.

Causes

As of Agents 5, communication between the agent and AM uses the OAuth 2.0 Authorization Framework. This means the agent and AM exchange OpenID Connect JSON web tokens (JWTs) containing the information required to authenticate clients and authorize access to protected resources. Agents authenticate to and log out users from the oauth2/authorize endpoint, which is not configurable. See the following links for further information:

This redirect issue can arise in the following scenarios:

  • You want users to authenticate against a specific realm: By default, the AM Login URL is not observed and the OAuth2 flow defaults to the root realm rather than a specific realm (you may see realm=%2F in URLs). To configure the agent for this use case, you must specify the OpenAM Conditional Login URL instead.
  • You have a custom login: When the AM Login URL is set (which defines the URL of a custom login page), the Allow Custom Login Mode property must also be set to true.

Solution

This issue can be resolved as follows depending on the cause:

Authenticate against a specific realm

If you want users to authenticate against a specific realm, you must specify the OpenAM Conditional Login URL property (com.forgerock.agents.conditional.login.url) with the realm name included as a URL parameter. See How do I configure Agents 5.x to authenticate users against a specific realm, tree or authentication module in AM? for further information.

Custom login

If you have a custom login, you must also set the Allow Custom Login Mode property (org.forgerock.openam.agents.config.allow.custom.login) to true. This is a custom property that you manually set in the agent's profile. You can either add it as an advanced property in the console or via the command line (Amster or ssoadm):

  • Console: navigate to: Realms > [Realm Name] > Applications > Agents > [Agent Type] > [Agent Name] > Advanced > Custom Properties and add the property, for example:
    org.forgerock.openam.agents.config.allow.custom.login=true
  • Amster: follow the steps in How do I update property values in AM (All versions) using Amster? with these values:
    • Entity: WebAgents or J2eeAgents
    • Property: customProperties 
    • Property value: org.forgerock.openam.agents.config.allow.custom.login
    For example:
            "customProperties": {
                "inherited": false,
                "value": [
                    "org.forgerock.openam.agents.config.allow.custom.login=true"
                ]
            }
    
  • ssoadm: enter the following command:
    $ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a org.forgerock.openam.agents.config.allow.custom.login=true
    replacing [realmname], [agentname], [adminID] and [passwordfile] with appropriate values.

See Also

Web Agent User Guide › Custom Login Redirection Mode

Java Agent User Guide › Custom Redirection Login Mode

Agents and policies in AM/OpenAM

Related Training

N/A

Related Issue Tracker IDs

N/A


XUI Login URL with goto parameter causes redirect loop or prevents OpenAM 12.x and 13.x login page loading

The purpose of this article is to provide assistance if you encounter a redirect loop between OpenAM 12.x and 13.x and Web Policy Agents when using the XUI Login URL with a goto parameter. Alternatively, you may notice that the OpenAM login page gets stuck on the Loading message instead of redirecting.

Symptoms

Upon authenticating, the user is redirected back to the protected resource and then back to the OpenAM login page for authentication, thereby creating a redirect loop. This does not happen if you use the Chrome™ browser; you just get redirected back to the protected resource without an error.

The browser shows a Loading... message and the URL is similar to the following where there is a ? between the login URL and the goto parameter:

http://openam.example.com:8080/openam/XUI/#login/&realm=employees?goto=http%3A%2F%2Fagent.test.com%2F

Recent Changes

Enabled XUI.

Upgraded to OpenAM 12.0.0 or later, which uses the XUI by default.

Changed the default OpenAM Login URL from /openam/UI/Login to the XUI equivalent: /openam/XUI/#login

Configured the OpenAM Conditional Login URL.

Causes

The policy agent appends the OpenAM Login URL or the OpenAM Conditional Login URL with ?goto= instead of &goto= which is not compatible with the XUI login URL. Instead of redirecting as expected to the protected resource after authentication, the goto parameter is treated as the realm parameter for login. Since this parameter cannot be resolved as a realm, the login page fails to load resulting in the redirect loop.

Solution

This issue can be resolved by updating the OpenAM Login URL or OpenAM Conditional Login URL as follows:

  • All versions of OpenAM: Revert to the classic UI format (which redirects users to /openam/XUI/#login/&goto= when XUI is enabled). For example:
    http://openam.example.com:8080/openam/UI/Login
  • Pre-OpenAM 13 versions only: Append it with & which causes the agent to normalize with &goto= instead. For example:
    http://openam.example.com:8080/openam/XUI/#login/&
    http://openam.example.com:8080/openam/XUI/#login/&realm=employees&

You can change the the OpenAM Login URL using either the OpenAM console or ssoadm as detailed in How do I configure policy agents (Web 4.x and JEE 3.5.x) to authenticate users against a specific realm in AM/OpenAM?

The OpenAM Conditional Login URL is not yet maintainable in the OpenAM console. You can either add it as an advanced property in the OpenAM console or via ssoadm:

  • OpenAM 13.x console: navigate to: Realms > [Realm Name] > Agents > Web > [Agent Name] > Advanced > Custom Properties and add the com.forgerock.agents.conditional.login.url property. For example:
    com.forgerock.agents.conditional.login.url[0] = example.com|http://openam.example.com:8080/openam/XUI/#login/&
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Agents > Web > [Agent Name] > Advanced > Custom Properties and add the com.forgerock.agents.conditional.login.url property.
  • ssoadm: enter the following command:
    $ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a "com.forgerock.agents.conditional.login.url[0]=[conditionalloginURL]"
    replacing [realmname], [agentname], [adminID], [passwordfile] and [conditionalloginURL] with appropriate values, where [conditionalloginURL] consists of the domain|login URL. For example:
    $ ./ssoadm update-agent -e / -b Web -u amadmin -f pwd.txt -a "com.forgerock.agents.conditional.login.url[0]=example.com|http://openam.example.com:8080/openam/XUI/#login/&"

See Web Policy Agent Guide › Reference › Configuring Access Management Services Properties for further information on the required format for this property.

See Also

How do I configure policy agents (Web 4.x and JEE 3.5.x) to authenticate users against a specific realm in AM/OpenAM?

Web Policy Agent Guide › Reference › Configuring Access Management Services Properties 

Related Training

N/A

Related Issue Tracker IDs

OPENAM-5547 (Agent behaviour when appending goto= to LoginURLs is not compatible with XUI login URL)

OPENAM-8173 (OpenAM Login URL in the agent profile should support XUI login URL)


Redirect loop between OpenAM and JEE Policy Agent 3.5.0 causes high session numbers and poor performance

The purpose of this article is to provide assistance if you get a redirect loop between OpenAM and JEE Policy Agent 3.5.0 that causes high session numbers, poor performance and potentially Out of Memory exceptions. The associated error is "Application token passed in, is invalid.token error".

Symptoms

The following error is shown multiple times in the amAgent debug log, where the same token is being passed in each time:

Session.processSessionResponseException: exception received from server:Application token passed in, is invalid.token:AQIC5...QACMDM.*
amSession:05/10/2016 05:19:52:021 PM CST: Thread[catalina-exec-6,5,main]
Session.processSessionResponseException: AppTokenInvalid = TRUE
amSession:05/10/2016 05:19:52:021 PM CST: Thread[catalina-exec-6,5,main]
Session.processSessionResponseException: Destorying AppToken
amSecurity:05/10/2016 05:19:52:021 PM CST: Thread[catalina-exec-6,5,main]
AdminTokenAction:invalid called
amSession:05/10/2016 05:19:52:021 PM CST: Thread[catalina-exec-6,5,main]
WARNING: Session.processSessionResponseException processSessionResponseException: server responded with app token invalid error,refetching the app sso token
amSecurity:05/10/2016 05:19:52:021 PM CST: Thread[catalina-exec-6,5,main]
AdminTokenAction::run Unable to get SSOToken  from serverconfig.xml

Session numbers keep increasing as sessions do not expire, which can cause poor performance and potentially Out of Memory exceptions. Eventually, this may result in an outage of the OpenAM server.

Recent Changes

Upgraded to, or installed the JEE policy agent 3.5.0.

Causes

The policy agent receives an invalid application token from OpenAM and authenticates again to refresh it. However, the policy agent keeps using the invalid token rather than replacing it with a new application token and keeps trying to refresh it, which causes the redirect loop between the policy agent and OpenAM. Meanwhile, the number of sessions keep increasing as this process continues to create new and unused sessions on the server.

Solution

This issue can be resolved by upgrading to JEE policy agent 3.5.1 or later; you can download this version from BackStage.

Note

This issue only applies to the JEE policy agent and can only be resolved by upgrading the JEE policy agent. No changes are required to OpenAM.

See Also

How do I monitor session statistics in AM/OpenAM (All versions)?

Related Training

N/A

Related Issue Tracker IDs

OPENAM-5835 (Redirect loop between OpenAM and J2EE Agent in case of invalid admin token)


JEE Policy Agent 3.5.x fails to redirect to AM/OpenAM login or logout URL and shows 500: Internal server error

The purpose of this article is to provide assistance if the JEE Policy Agent fails to redirect to the AM/OpenAM login or logout page and shows a 500: Internal server error. You will also see the "ERROR: URLFailoverHelper: No URL is available at this time" error in the agent debug log.

Symptoms

The following error is shown in the agent debug log when the redirect failure occurs:

amFilter:11/17/2015 10:06:22:725 AM CEST: Thread[http-bio-10343-exec-2,5,main] 
ERROR: URLFailoverHelper: No URL is available at this time 
amFilter:11/17/2015 10:06:22:725 AM CEST: Thread[http-bio-10343-exec-2,5,main] 
ERROR: AmFilter: a server error occurred. 
[AgentException Stack] 
com.sun.identity.agents.arch.AgentServerErrorException: No URL is available at this time 
   at com.sun.identity.agents.common.URLFailoverHelper.getAvailableURL(URLFailoverHelper.java:155) 
   at com.sun.identity.agents.common.URLFailoverHelper.getAvailableURL(URLFailoverHelper.java:82) 
   at com.sun.identity.agents.filter.AmFilterRequestContext.getLoginURL(AmFilterRequestContext.java:835) 

Recent Changes

N/A

Causes

The policy agent performs a connectivity check by default prior to redirecting the user to AM/OpenAM for login or logout; however, the AM/OpenAM login or logout URL is typically only accessible to end-users not the policy agent, which causes this connectivity check to fail. In turn, this prevents the policy agent redirecting the user to AM/OpenAM. This connectivity check is unnecessary.

Solution

This issue can be resolved by upgrading to Java Agents 5 or later; you can download this from BackStage.

Workaround

You can workaround this issue by disabling this unnecessary connectivity check using either the console or ssoadm:

  • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > Agents > J2EE > [Agent Name] > OpenAM Services and deselect the Enabled option against Login URL Probe and Logout URL Probe.
  • OpenAM 13.x console: navigate to: Realms > [Realm Name] > Agents > J2EE > [Agent Name] > OpenAM Services and deselect the Enabled option against Login URL Probe and Logout URL Probe.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Agents > J2EE > [Agent Name] > OpenAM Services and deselect the Enabled option against Login URL Probe and Logout URL Probe.
  • ssoadm: enter the following command:
    $ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a com.sun.identity.agents.config.login.url.probe.enabled=false
    com.sun.identity.agents.config.logout.url.probe.enabled=false
    replacing [realmname], [agentname], [adminID] and [passwordfile] with appropriate values.

See Also

OpenAM JEE Policy Agent User's Guide › Configuring Java EE Policy Agent OpenAM Services Properties

Related Training

N/A

Related Issue Tracker IDs

OPENAM-3294 (Agents should not probe the loginURL / logoutURL before redirecting by default)


Policies


Guice configuration errors when importing or exporting policies using ssoadm in AM 5, 5.1.x and OpenAM 13.5.1

The purpose of this article is to provide assistance if you receive an "Exception in thread "main" com.google.inject.ConfigurationException: Guice configuration errors" response when using the export-policy or import-policy ssoadm commands in AM/OpenAM.

Symptoms

Using the export-policy or import-policy ssoadm command fails with the following exception:

Exception in thread "main" com.google.inject.ConfigurationException: Guice configuration errors:

1) Could not find a suitable constructor in org.forgerock.http.Client. Classes must have either one (and only one) constructor annotated with @Inject or a zero-argument constructor that is not private.
   at org.forgerock.http.Client.class(Unknown Source)
   while locating org.forgerock.http.Client
     for parameter 0 at org.forgerock.openam.cli.entitlement.PolicyExport.<init>(Unknown Source)
   while locating org.forgerock.openam.cli.entitlement.PolicyExport

1 error
   at com.google.inject.internal.InjectorImpl.getProvider(InjectorImpl.java:1004)
   at com.google.inject.internal.InjectorImpl.getProvider(InjectorImpl.java:961)
   at com.google.inject.internal.InjectorImpl.getInstance(InjectorImpl.java:  
   at org.forgerock.guice.core.InjectorHolder.getInstance(InjectorHolder.java:72)
   at com.sun.identity.cli.SubCommand.execute(SubCommand.java:295)
   at com.sun.identity.cli.CLIRequest.process(CLIRequest.java:217)
   at com.sun.identity.cli.CLIRequest.process(CLIRequest.java:139)
   at com.sun.identity.cli.CommandManager.serviceRequestQueue(CommandManager.java:581)
   at com.sun.identity.cli.CommandManager.<init>(CommandManager.java:178)
   at com.sun.identity.cli.CommandManager.main(CommandManager.java:155)

This occurs when you use a command such as the following:

$ ./ssoadm policy-export -e / -u amadmin -f pwd.txt -s "http://host1.example.com:8080/openam" -J policy.json

Recent Changes

Upgraded to, or installed AM 5 or 5.1.x.

Upgraded to, or installed OpenAM 13.5.1.

Causes

Recent changes to resolve OPENAM-9749 (Resource leak in ssoadm's audit logging) have caused this issue with exporting and importing policies via ssoadm.

Solution

This issue can be resolved by upgrading to OpenAM 13.5.2, or AM 5.5 and later; you can download this from BackStage.

Workaround

You can workaround this issue as follows depending on your version:

AM 5 and 5.1.x

You can use Amster or REST to export and import policies. For example, you would use the following command to export with Amster:

am> export-config --path /path/to/export --realm / --realmEntities 'Policies'

See Authorization Guide › Importing and Exporting XACML 3.0 for further information on using REST.

OpenAM 13.5.1

You can install and use the ssoadm tool from OpenAM 13.5 or you can use REST to export and import policies.

See Developer's Guide › Importing and Exporting XACML 3.0 for further information on using REST.

See Also

How do I export and import policies in AM/OpenAM (All versions)?

create-realm ssoadm command fails in AM 5 with Guice configuration errors

Amster User Guide > Exporting Configuration Data

Amster User Guide > Importing Configuration Data

Related Training

N/A

Related Issue Tracker IDs

OPENAM-11584 (Ssoadm policy-import throws Guice error)

OPENAM-9749 (Resource leak in ssoadm's audit logging)


Upgrade to OpenAM 12.x or 13.x fails with Failed to modify privilege! message when migrating policies

The purpose of this article is to provide assistance if your upgrade to OpenAM 12.x or 13.x fails with ERROR: "Failed to modify privilege!" when migrating policies. This issue will only occur if you are upgrading from a pre-OpenAM 12.0.0 release and the policies are being migrated to the OpenAM 12.x or 13.x format for the first time.

Symptoms

The upgrade fails and you see the following message in the Upgrade wizard:

Failed to modify privilege!

An error similar to the following is shown in the amUpgrade log when the Upgrade fails:

amUpgrade:10/12/2015 04:07:22:665 PM PDT: Thread[catalina-exec-1,5,main]
ERROR: Failed to modify privilege!
com.sun.identity.entitlement.EntitlementException: Invalid Resource https://openam.example.com:8443/web/personal-details?*
	at com.sun.identity.entitlement.Entitlement.validateResourceNames(Entitlement.java:826)
	at com.sun.identity.entitlement.Privilege.validateResourceNames(Privilege.java:164)
	at com.sun.identity.entitlement.opensso.PolicyPrivilegeManager.modify(PolicyPrivilegeManager.java:265)
	at org.forgerock.openam.upgrade.steps.policy.conditions.OldPolicyConditionMigrationUpgradeStep.perform(OldPolicyConditionMigrationUpgradeStep.java:193)
	at org.forgerock.openam.upgrade.UpgradeServices.upgrade(UpgradeServices.java:186)
	at com.sun.identity.config.upgrade.Upgrade.doUpgrade(Upgrade.java:79)
...	
amUpgrade:10/12/2015 04:07:22:666 PM PDT: Thread[catalina-exec-1,5,main]
ERROR: Error occured while upgrading OpenAM
org.forgerock.openam.upgrade.UpgradeException: Failed to modify privilege!
	at org.forgerock.openam.upgrade.steps.policy.conditions.OldPolicyConditionMigrationUpgradeStep.perform(OldPolicyConditionMigrationUpgradeStep.java:196)
	at org.forgerock.openam.upgrade.UpgradeServices.upgrade(UpgradeServices.java:186)
	at com.sun.identity.config.upgrade.Upgrade.doUpgrade(Upgrade.java:79)

Recent Changes

Upgrading from a pre-OpenAM 12.0.0 release.

Causes

You only have one referral rule from the top-level realm. As per changes that were introduced in OpenAM 11.0.0, you should have three referral rules, for example: 

  • root "/"
  • pages "/*"
  • pages with parameters "/*?*"

Solution

This issue can be resolved by adding the other two referral rules and re-running the upgrade. 

For example, if your current referral rule is: 

https://openam.example.com:8443/*

You would need to add the following referral rules:

https://openam.example.com:8443/
https://openam.example.com:8443/*?*
Note

Although referrals are not used in OpenAM 13, they still need to be correct prior to upgrading as they are processed during the upgrade process as detailed in OpenAM 13 Upgrade Guide › Upgrading OpenAM Servers.

See Also

Best practice for migrating policies when upgrading to OpenAM 12.x or 13.x

Best practice for creating and testing policies in AM/OpenAM (All versions)

OpenAM 11.0.0 Release Notes › OpenAM Changes & Deprecated Functionality › Important Changes to Existing Functionality 

OpenAM 12.0.0 Release Notes › OpenAM Changes and Deprecated Functionality › Important Changes to Existing Functionality

Related Training

N/A

Related Issue Tracker IDs

OPENAM-5441 (upgrade from 12.0.0 to 13.0.0 fails)

OPENAM-5333 (Upgrade failure when policy has more than one rule)

OPENAM-3509 (PolicyEvaluation strips off trailing '/' from resource resulting in wrong enforcement on agent side)


Policy import fails in OpenAM 13.0 with Invalid resource type null message

The purpose of this article is to provide assistance if you receive an "Invalid resource type null, must be one from the set defined against the containing application" message when trying to import a policy in OpenAM 13.0 via REST or ssoadm. The policy import fails in the OpenAM console without a message.

Symptoms

The following error is shown when attempting to import a policy in XACML format using ssoadm:

com.sun.identity.entitlement.EntitlementException: Invalid resource type null, must be one from the set defined against the containing application.

The following response is received when attempting to import a policy in XACML format using the REST API:

{"code":400,"reason":"Bad Request","message":"Invalid resource type null, must be one from the set defined against the containing application."}

If you try to import a policy via the OpenAM console, the policy is not imported but you do not get a message saying it failed. 

Recent Changes

Installed, or upgraded to OpenAM 13.0.

Causes

OpenAM 13 introduced a new concept - Resource Types which form part of describing policies in OpenAM 13. The resource types are missing from the xml file for the exported policy. The existing resource type is not associated with the imported policy and as such the policy fails validation

Solution

This issue can be resolved by upgrading to OpenAM 13.5 or later; you can download this version from BackStage.

Workaround

Alternatively, this issue can be resolved by manually re-creating the policy using either the OpenAM console or the REST API.

If you want to use the REST API, see How do I create a policy in AM/OpenAM (All versions) using the REST API? for details on successfully creating a policy, including retrieving the missing resource types. This article also provides a Postman collection  to make it easier to create policies.

See Also

How do I export and import policies in AM/OpenAM (All versions)?

Related Training

N/A

Related Issue Tracker IDs

OPENAM-6013 (Resource types are missing in XACML exported policy and it is not possible to import it)

OPENAM-8495 (XACML Import - Existing resource type not being associated with the imported policy)


OpenAM 13.0 hangs when creating or updating policies and policy sets with BLOCKED and WAITING threads

The purpose of this article is to provide assistance if OpenAM 13.0 hangs when creating or updating policies and policy sets, and you see BLOCKED or WAITING threads. You may also encounter these symptoms in other policy related scenarios, including exporting policies using the ssoadm list-xacml command, accessing UMA resources and upgrading with a large number of policies.

Symptoms

OpenAM intermittently hangs when creating or updating policies and policy sets, exporting policies using the ssoadm list-xacml command or accessing UMA resources. Once it hangs, restarting the web application container in which OpenAM runs will temporarily restore functionality.

You will see either BLOCKED or WAITING threads in a JStack when OpenAM hangs, for example:

http-/0.0.0.0:8080-14" #109 daemon prio=5 os_prio=0 tid=0x0000000022a0d800 nid=0xfc0 in Object.wait() [0x000000002617a000]
java.lang.Thread.State: WAITING (on object monitor)
        at java.lang.Object.wait(Native Method)
        at java.lang.Object.wait(Object.java:502)
        at org.forgerock.util.promise.PromiseImpl.await(PromiseImpl.java:572)
        - locked <0x00000000c7a5ec00> (a org.forgerock.util.promise.PromiseImpl)
        at org.forgerock.util.promise.PromiseImpl.getOrThrow(PromiseImpl.java:143)
        at org.forgerock.opendj.ldap.CachedConnectionPool.getConnection(CachedConnectionPool.java:789)
        at com.sun.identity.sm.ldap.SMDataLayer.getConnection(SMDataLayer.java:107)
        at com.sun.identity.sm.ldap.SMSLdapObject.getConnection(SMSLdapObject.java:574)
        at com.sun.identity.sm.ldap.SMSLdapObject.search(SMSLdapObject.java:591)
        at com.sun.identity.sm.SMSEntry.search(SMSEntry.java:1069)
        at com.sun.identity.entitlement.opensso.DataStore.searchPrivileges(DataStore.java:902)
        at com.sun.identity.entitlement.opensso.DataStore.search(DataStore.java:822)
        at com.sun.identity.entitlement.opensso.OpenSSOIndexStore$SearchTask.run(OpenSSOIndexStore.java:96)
...
        at com.sun.identity.entitlement.ApplicationPrivilegeManager.getInstance(ApplicationPrivilegeManager.java:188)

Thread 2931: (state = BLOCKED)
 - sun.misc.Unsafe.park(boolean, long) @bci=0 (Interpreted frame)
 - java.util.concurrent.locks.LockSupport.parkNanos(java.lang.Object, long) @bci=20, line=226 (Interpreted frame)
 - java.util.concurrent.locks.AbstractQueuedSynchronizer$ConditionObject.awaitNanos(long) @bci=68, line=2082 (Interpreted frame)
 - java.util.concurrent.LinkedBlockingQueue.poll(long, java.util.concurrent.TimeUnit) @bci=62, line=467 (Interpreted frame)
 - org.forgerock.opendj.ldif.ConnectionEntryReader.getNextResponse() @bci=21, line=398 (Interpreted frame)
 - org.forgerock.opendj.ldif.ConnectionEntryReader.hasNext() @bci=1, line=231 (Interpreted frame)
 - com.sun.identity.sm.ldap.SMSLdapObject.searchObjects(com.iplanet.sso.SSOToken, java.lang.String, java.lang.String, int, int, boolean, boolean, org.forgerock.opendj.ldap.Connection) @bci=81, line=702 (Interpreted frame)

Upgrade process

This issue can also cause the upgrade process to hang with one of the following errors in the amUpgrade debug log, in addition to BLOCKED threads:

ERROR: Error occured while upgrading OpenAM
org.forgerock.openam.upgrade.UpgradeException: Failed to gather policies for application iPlanetAMWebAgentService
   at org.forgerock.openam.upgrade.steps.policy.UpgradeResourceTypeStep.upgradePrivileges(UpgradeResourceTypeStep.java:416)
   at org.forgerock.openam.upgrade.steps.policy.UpgradeResourceTypeStep.perform(UpgradeResourceTypeStep.java:249)
   at org.forgerock.openam.upgrade.UpgradeServices.upgrade(UpgradeServices.java:151)
   at com.sun.identity.config.upgrade.Upgrade.doUpgrade(Upgrade.java:83)
   at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
   at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:57)
   at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
ERROR: Error occured while upgrading OpenAM
org.forgerock.openam.upgrade.UpgradeException: Application cloning failed
   at org.forgerock.openam.upgrade.steps.RemoveReferralsStep.instateReferredApplications(RemoveReferralsStep.java:204)
   at org.forgerock.openam.upgrade.steps.RemoveReferralsStep.perform(RemoveReferralsStep.java:195)
   at org.forgerock.openam.upgrade.UpgradeServices.upgrade(UpgradeServices.java:151)
   at com.sun.identity.config.upgrade.Upgrade.doUpgrade(Upgrade.java:83)

Recent Changes

Upgraded to, or installed OpenAM 13.0.

Causes

Connections are being opened but not closed and returned to the connection pool, which eventually causes OpenAM to hang. During the upgrade process, this can happen when the upgrade reaches the policy section and is migrating policies or removing policy referrals.

Solution

This issue can be resolved by upgrading to OpenAM 13.5 or later; you can download this version from BackStage.

See Also

Best practice for migrating policies when upgrading to OpenAM 12.x or 13.x

Upgrade to OpenAM 12.x or 13.x fails with Failed to modify privilege! message when migrating policies

How do I export and import policies in AM/OpenAM (All versions)?

Related Training

N/A

Related Issue Tracker IDs

OPENAM-8531 (Connection leak in policy codebase)

OPENAM-8459 (LDAPAuthUtils should set operations timeout in seconds)

OPENAM-10116 (Search timeout for LDAP filter condition should be in seconds)


Unreliable policy evaluation results when using root or subtree mode in OpenAM 12.x or 13.x

The purpose of this article is to provide assistance if your policies are not always correctly evaluated when using root or subtree mode in OpenAM. For example, policy rules that should allow access to policy agent protected resources are denied.

Symptoms

Policy rules that should allow access to policy agent protected resources are denied.

Recent Changes

N/A

Causes

When using root or subtree mode, the policy agent requests all policy decisions from OpenAM and then performs some local policy processing. URLs are broken down into their component parts and each part is evaluated looking for possible matches. This approach can cause unexpected results when evaluating policy rules, particularly if they contain wildcards.

The non-root or self mode is simpler and the policy agent requests a single match for the complete URL from OpenAM and does not perform any additional local policy processing. This mode is the default and results in fewer evaluations being performed.

Note

The difference between root and subtree modes is terminology for policy agents; web policy agents use root or non-root mode and Java EE policy agents use subtree or self mode.

Solution

This issue can be resolved by changing your policy agents to use non-root or self mode.

Web Policy Agent

You can change your web policy agents using either the OpenAM console or ssoadm:

  • OpenAM 13.x console: navigate to: Realms > [Realm Name] > Agents > Web > [Agent Name] > OpenAM Services > Policy Client Service > Fetch Policies from Root Resource and deselect the Enabled option.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Agents > Web > [Agent Name] > OpenAM Services > Policy Client Service > Fetch Policies from Root Resource and deselect the Enabled option.
  • ssoadm: enter the following command:
    $ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a com.sun.identity.agents.config.fetch.from.root.resource=false
    replacing [realmname], [agentname], [adminID] and [passwordfile] with appropriate values.

Java EE Policy Agent

You can change your Java EE policy agents using either the OpenAM console or ssoadm:

  • OpenAM 13.x console: navigate to: Realms > [Realm Name] > Agents > J2EE > [Agent Name] > OpenAM Services > Policy Client Service > Policy Client Cache Mode and select the self option.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Agents > J2EE > [Agent Name] > OpenAM Services > Policy Client Service > Policy Client Cache Mode and select the self option.
  • ssoadm: enter the following command:
    $ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a com.sun.identity.policy.client.cacheMode=self
    replacing [realmname], [agentname], [adminID] and [passwordfile] with appropriate values.
Note

You must restart the web application container in which OpenAM runs to apply these configuration changes. 

See Also

OpenAM 12.0.0 Release Notes › OpenAM Fixes, Limitations, & Known Issues › Known Issues

Best practice for creating and testing policies in AM/OpenAM (All versions)

Related Training

N/A

Related Issue Tracker IDs

OPENAM-2085 (Unreliable policy evaluation results with com.sun.identity.agents.config.fetch.from.root.resource enabled)


Source


Aether ClassNotFound when building Policy Agents and OpenAM 12.x, 13 from source

The purpose of this article is to provide assistance if you receive a java.lang.NoClassDefFoundError: org/sonatype/aether/* when building Policy Agents and OpenAM from source using Apache Maven™ 3.1.0.

Warning

ForgeRock support covers the use of the official binary builds made available and downloaded from our customer portal: BackStage. We will support builds made from source providing no changes have been made to the core code of the product, the product was built from a tag that matches an official release, for example, 13 and said product was built using the ForgeRock build scripts provided as part of the source. In the event that a customer experiences an issue with a ForgeRock product built from source where ForgeRock believe the issue is as a result of the build process, ForgeRock reserves the right to ask the customer to attempt to reproduce the issue on an official ForgeRock binary build. Customers who are running custom builds or who need further clarification should contact their ForgeRock sales representative.

Symptoms

You will see errors that refer to:

java.lang.NoClassDefFoundError: org/sonatype/aether/*
Caused by: java.lang.ClassNotFoundException: org.sonatype.aether.*

An example error could be as follows when attempting to build from source:

[INFO] Dependency-reduced POM written at: /home/ArchiSecu/temp/openam-agents/jee-agents/jee-agents-jboss/jee-agents-jboss-v40/dependency-reduced-pom.xml 
[WARNING] Error injecting: org.apache.maven.shared.dependency.graph.internal.Maven3DependencyGraphBuilder 
java.lang.NoClassDefFoundError: org/sonatype/aether/version/VersionConstraint 
   at java.lang.Class.getDeclaredMethods0(Native Method) 
   at java.lang.Class.privateGetDeclaredMethods(Class.java:2427) 
   at java.lang.Class.getDeclaredMethods(Class.java:1791) 
   at com.google.inject.spi.InjectionPoint.getInjectionPoints(InjectionPoint.java:674) 
   at com.google.inject.spi.InjectionPoint.forInstanceMethodsAndFields(InjectionPoint.java:366) 
   at com.google.inject.internal.ConstructorBindingImpl.getInternalDependencies(ConstructorBindingImpl.java:165)
...
Caused by: java.lang.ClassNotFoundException: org.sonatype.aether.version.VersionConstraint 
   at org.codehaus.plexus.classworlds.strategy.SelfFirstStrategy.loadClass(SelfFirstStrategy.java:50) 
   at org.codehaus.plexus.classworlds.realm.ClassRealm.unsynchronizedLoadClass(ClassRealm.java:259) 
   at org.codehaus.plexus.classworlds.realm.ClassRealm.loadClass(ClassRealm.java:242) 
   at org.codehaus.plexus.classworlds.realm.ClassRealm.loadClass(ClassRealm.java:227) 
...

Recent Changes

N/A

Causes

This is a known issue that exists in Maven 3.1.0. This error is caused by the Maven 3.1-alpha-1 migration from Sonatype Aether to Eclipse Aether, which is an incompatible change for some plugins. You can use this link AetherClassNotFound to check the current status of this issue from Apache.

Solution

This issue can be resolved by upgrading the affected plugins if you use Maven 3.0.x or 3.1.x. AetherClassNotFound lists the affected plugins and the corresponding minimum needed version.

Alternatively, you can downgrade to Maven 3.0.5. You can download Maven from: Download Apache Maven.

See Also

FAQ: Source code in AM/OpenAM

Source code in ForgeRock products

AetherClassNotFound

Related Training

N/A

Related Issue Tracker IDs

OPENAM-2834 (Build issues with Maven 3.1.0)

OPENAM-4451 (Java EE agents can't be compiled using Maven 3.1.0+)


Copyright and TrademarksCopyright © 2018 - 2019 ForgeRock, all rights reserved.

This content has been optimized for printing.

Loading...