diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-monitoring.adoc b/openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-monitoring.adoc index 9b072f5a12..a02a4bce6f 100644 --- a/openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-monitoring.adoc +++ b/openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-monitoring.adoc @@ -106,7 +106,7 @@ You can also browse the MBeans by connecting to your web application container, [#figure-jconsole-to-openam] image::images/jconsole-to-openam.png[] -Also see link:http://docs.oracle.com/javase/1.5.0/docs/guide/management/agent.html[Monitoring and Management Using JMX, window=\_blank] for instructions on how to connect remotely, how to use SSL, and so forth. +Also see link:https://docs.oracle.com/en/java/javase/11/management/monitoring-and-management-using-jmx-technology.html[Monitoring and Management Using JMX Technology, window=\_blank] for instructions on how to connect remotely, how to use SSL, and so forth. [IMPORTANT] ==== diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-sts.adoc b/openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-sts.adoc index 9f28ae40ef..8011492dd5 100644 --- a/openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-sts.adoc +++ b/openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-sts.adoc @@ -1501,7 +1501,7 @@ Deploy the `.war` file as follows: . OpenAM supports the following web containers for SOAP STS deployments: + -* Apache Tomcat 6, 7, or 8 +* Apache Tomcat 10.1.x or 11 * Jetty 7, 8, or 9 @@ -1609,13 +1609,13 @@ Then, you can make the following changes: [#sts-soap-logger] ==== Configuring the SOAP STS Logger -OpenAM SOAP STS logs to the Simple Logging Facade for Java (SLF4J) API. Because the Apache CXF framework, by default, logs to the `java.util.logging` object, the OpenAM SOAP STS is built with a maven dependency upon `slf4j-jdk14`, which allows OpenAM SOAP STS log entries to be configured via `java.util.logging`. As a result, you can implement both OpenAM SOAP STS and Apache CXF logging to be configured via the `logging.properties` file in the Tomcat `conf` directory. +OpenAM SOAP STS logs to the Simple Logging Facade for Java (SLF4J) API. Because the Apache CXF framework, by default, logs to the `java.util.logging` object, the OpenAM SOAP STS is built with a maven dependency upon `slf4j`, which allows OpenAM SOAP STS log entries to be configured via `java.util.logging`. As a result, you can implement both OpenAM SOAP STS and Apache CXF logging to be configured via the `logging.properties` file in the Tomcat `conf` directory. You can configure and customize Apache CXF-related logging according to directions given at the following web site: link:http://cxf.apache.org/docs/debugging-and-logging.html[http://cxf.apache.org/docs/debugging-and-logging.html, window=\_blank] [NOTE] ==== -Because the OpenAM SOAP STS code logs to the SLF4J API, the manner in which these logs are realized is a function of the jar file state bundled in the OpenAM SOAP STS server `.war` file. If you implement the OpenAM SOAP STS logs using a different framework, you can replace the `slf4j-jdk14` Maven dependency in the OpenAM SOAP STS server `pom.xml` file by the desired dependency and rebuild the `.war` file. Or you can change the generated OpenAM SOAP STS server `.war` file to include the desired `.jar` file, which will realize the SLF4J API with the desired logging framework. +Because the OpenAM SOAP STS code logs to the SLF4J API, the manner in which these logs are realized is a function of the jar file state bundled in the OpenAM SOAP STS server `.war` file. If you implement the OpenAM SOAP STS logs using a different framework, you can replace the `slf4j` Maven dependency in the OpenAM SOAP STS server `pom.xml` file by the desired dependency and rebuild the `.war` file. Or you can change the generated OpenAM SOAP STS server `.war` file to include the desired `.jar` file, which will realize the SLF4J API with the desired logging framework. Also, note that the `debugfiles.properties` included in the OpenAM SOAP STS server `.war` file does not configure logging. It is present only because some OpenAM code leveraged by the SOAP STS continues to have dependencies upon the legacy, OpenAM debug logger. The presence of this file minimizes the number of harmless error logs generated by the initialization of this legacy debug logger. OpenAM SOAP STS does not utilize this logger. ==== diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/deployment-planning/chap-high-level-start.adoc b/openam-documentation/openam-doc-source/src/main/asciidoc/deployment-planning/chap-high-level-start.adoc index 643081e2d2..19e21bd077 100644 --- a/openam-documentation/openam-doc-source/src/main/asciidoc/deployment-planning/chap-high-level-start.adoc +++ b/openam-documentation/openam-doc-source/src/main/asciidoc/deployment-planning/chap-high-level-start.adoc @@ -329,9 +329,9 @@ The installation process requires that you implement your deployment plan. * *Prepare the Operating System*. Prepare your operating system, depending on the OS: Linux, Solaris, Windows, Cloud (Amazon EC2, OpenStack, and so forth), Virtual Machines (VMWare, Xen, Hyper-V, and so forth) -* *Prepare the Java Environment*. Prepare your Java environment, depending on your vendor type: Oracle, IBM, OpenJDK. +* *Prepare the Java Environment*. Prepare your Java environment, depending on your vendor type: Oracle, OpenJDK, Eclipse Temurin etc. -* *Prepare the App Server*. Prepare your application server, depending on type: Apache Tomcat, JBoss 4/5, WildFly, Jetty, Oracle WebLogic, IBM WebSphere. Also, prepare each app server for HTTPS. +* *Prepare the App Server*. Prepare your application server, depending on type: Apache Tomcat, Jetty, Oracle WebLogic, IBM WebSphere. Also, prepare each app server for HTTPS. * *Prepare the Directory Servers*. Prepare the configuration directory server, OpenDJ for the core token service (CTS), and the LDAP identity repository. For information on installing data repositories, see xref:../install-guide/chap-prepare-install.adoc#chap-prepare-install["Preparing For Installation"] in the __Installation Guide__. diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/deployment-planning/chap-hw-sw-requirements.adoc b/openam-documentation/openam-doc-source/src/main/asciidoc/deployment-planning/chap-hw-sw-requirements.adoc index 120fe59fad..1ee9c7c1a1 100644 --- a/openam-documentation/openam-doc-source/src/main/asciidoc/deployment-planning/chap-hw-sw-requirements.adoc +++ b/openam-documentation/openam-doc-source/src/main/asciidoc/deployment-planning/chap-hw-sw-requirements.adoc @@ -182,11 +182,8 @@ a|2008, 2008 R2, 2012, 2012 R2 |=== |Vendor |Version -a|Oracle JDK -a|7, 8 - -a|IBM SDK, Java Technology Edition (Websphere only) -a|7 +a|Any JDK vendor, i.e. Oracle JDK, Eclipse Temurin, Amazon Coretto +a|11 LTS or later |=== @@ -201,7 +198,7 @@ a|7 |Web Container |Version a|Apache Tomcat -a|7, 8 +a|10.1.X, 11 a|Oracle WebLogic Server a|12c @@ -341,7 +338,7 @@ a|[none] a|[none] * 5, 6, 7 a|[none] -* Apache Tomcat 6, 7, 8 +* Apache Tomcat 10.1.X, 11 * IBM Web Sphere Application Server 8, 8.5 * JBoss Enterprise Application Platform 6 * JBoss Application Server 7 @@ -353,7 +350,7 @@ a|[none] a|[none] * 2008, 2008 R2, 2012, 2012 R2 a|[none] -* Apache Tomcat 6, 7, 8 +* Apache Tomcat 10.1.X, 11 a|[none] * Oracle Solaris x64 @@ -361,7 +358,7 @@ a|[none] a|[none] * 10, 11 a|[none] -* Apache Tomcat 6, 7, 8 +* Apache Tomcat 10.1.X, 11 * Oracle WebLogic Server 11g, 12c a|[none] @@ -369,7 +366,7 @@ a|[none] a|[none] * 12.04 LTS, 14.04 LTS a|[none] -* Apache Tomcat 6, 7, 8 +* Apache Tomcat 10.1.X, 11 * IBM Web Sphere Application Server 8, 8.5 * JBoss Enterprise Application Platform 6 * JBoss Application Server 7 diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/deployment-planning/chap-intro.adoc b/openam-documentation/openam-doc-source/src/main/asciidoc/deployment-planning/chap-intro.adoc index 7ca2a0364e..c1802e973e 100644 --- a/openam-documentation/openam-doc-source/src/main/asciidoc/deployment-planning/chap-intro.adoc +++ b/openam-documentation/openam-doc-source/src/main/asciidoc/deployment-planning/chap-intro.adoc @@ -172,7 +172,4 @@ In February 2010, a small group of former Sun employees founded ForgeRock to con * 2016: OpenAM 14 -* 2025: OpenAM 15 - - - +* 2025: OpenAM 15 and 16 diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/install-guide/chap-prepare-install.adoc b/openam-documentation/openam-doc-source/src/main/asciidoc/install-guide/chap-prepare-install.adoc index a6fd6c0273..838a10ad22 100644 --- a/openam-documentation/openam-doc-source/src/main/asciidoc/install-guide/chap-prepare-install.adoc +++ b/openam-documentation/openam-doc-source/src/main/asciidoc/install-guide/chap-prepare-install.adoc @@ -51,7 +51,7 @@ Check the effective top-level domain list at link:https://publicsuffix.org/list/ [#prepare-java] === Preparing a Java Environment -OpenAM software depends on a Java runtime environment. Check the output of `java -version` to make sure your the version is supported. The current OpenAM release supports Java Development Kit 8, 11, 17 or 21 LTS version. +OpenAM software depends on a Java runtime environment. Check the output of `java -version` to make sure your the version is supported. The current OpenAM release supports Java Development Kit 11, 17, 21 or 25 LTS version. [#prepare-java-sun] ==== Settings For Sun/Oracle Java Environments @@ -1355,7 +1355,7 @@ You should also ensure `sslProtocol` is set to `TLS`, which disables the potenti maxThreads="150" scheme="https" secure="true" clientAuth="false" sslProtocol="TLS" URIEncoding="UTF-8" /> ---- -The following example script, `/etc/init.d/tomcat`, manages the service at system startup and shutdown. This script assumes you run OpenAM as the user `openam` and that you use Oracle JDK 8. +The following example script, `/etc/init.d/tomcat`, manages the service at system startup and shutdown. This script assumes you run OpenAM as the user `openam` and that you use JDK 11 LTS or later. [source, shell] ---- diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/jee-users-guide/chap-apache-tomcat.adoc b/openam-documentation/openam-doc-source/src/main/asciidoc/jee-users-guide/chap-apache-tomcat.adoc index cc27729bb1..818bdb5bc6 100644 --- a/openam-documentation/openam-doc-source/src/main/asciidoc/jee-users-guide/chap-apache-tomcat.adoc +++ b/openam-documentation/openam-doc-source/src/main/asciidoc/jee-users-guide/chap-apache-tomcat.adoc @@ -12,7 +12,7 @@ information: "Portions copyright [year] [name of copyright owner]". Copyright 2017 ForgeRock AS. - Portions Copyright 2024 3A Systems LLC. + Portions Copyright 2024-2025 3A Systems LLC. //// :figure-caption!: @@ -28,57 +28,38 @@ This chapter covers installation of the policy agent for Apache Tomcat. [#before-tomcat-agent-install] === Before You Install -Make sure OpenAM is installed and running, and that you can contact OpenAM from the system running the policy agent. Next, create a profile for your policy agent as described in xref:../jee-users-guide/chap-jee-agent-config.adoc#create-agent-profiles[Creating Agent Profiles]. To protect resources with the agent, create at least one policy as described in link:../../../openam/13/admin-guide/#chap-authz-policy[Configuring Policies, window=\_blank] in the __OpenAM Administration Guide__. Consider creating a simple policy, such as a policy that allows only authenticated users to access your resources in order to test your policy agent after installation. +Make sure OpenAM is installed and running, and that you can contact OpenAM from the system running the policy agent. Next, create a profile for your policy agent as described in xref:../jee-users-guide/chap-jee-agent-config.adoc#create-agent-profiles[Creating Agent Profiles]. To protect resources with the agent, create at least one policy as described in link:../../../openam/admin-guide/chap-cdsso[Configuring Policies, window=\_blank] in the __OpenAM Administration Guide__. Consider creating a simple policy, such as a policy that allows only authenticated users to access your resources in order to test your policy agent after installation. You must install Apache Tomcat before you install the policy agent, and you must stop the server during installation. All of the Tomcat scripts must be present in `$CATALINA_HOME/bin`. The Tomcat Windows executable installer does not include the scripts, for example. If the scripts are not present in your installation, copy the contents of the `bin` directory from a .zip download of Tomcat of the same version as the one you installed. -You must install a supported version of the Java runtime environment. Set the `JAVA_HOME` environment variable accordingly. The policy agent installer requires Java. +You must install a supported version of the Java runtime environment. Set the `JAVA_HOME` environment variable accordingly. The policy agent requires Java. [source, console] ---- $ echo $JAVA_HOME /path/to/java ---- -See the OpenAM __Installation Guide__ section, link:../../../openam/13/install-guide/#download-openam-software[Obtaining OpenAM Software, window=\_blank] to determine which version of the agent to download, and download the agent. Also verify the checksum of the file you download against the checksum posted on the download page. +Download the agent distribution of the J2EE Agent from link:https://github.com/OpenIdentityPlatform/OpenAM-JEE-Agents/releases/[GitHub, window=\_blank]. +Also verify the checksum of the file you download against the checksum posted on the download page. Unzip the file in the directory where you plan to install the J2EE policy agent. The agent you install stores its configuration and logs under this directory. -When you unzip the policy agent, you find the following directories under the `j2ee_agents/tomcat_v6_agent` directory. +When you unzip the policy agent, you find the following files and directories under the `jee-agent-uberjar` or `jee-agent-jar-with-lib` directory. Despite the directory name, the policy agent supports multiple container versions. -- -`bin`:: -The installation and configuration program `agentadmin`. For more details about the available command-line tools, see xref:tools-reference.adoc#tools-reference[Command-Line Tool Reference]. +`agent.jar`:: +The policy agent JAR file itself. -`config`:: -Configuration templates used by the `agentadmin` command during installation - -`data`:: -Not used - -`etc`:: -Configuration templates used during installation - -`installer-logs`:: -Location for log files written during installation - -`legal-notices`:: -Contains licensing information including third-party licenses - -`lib`:: -Shared libraries used by the Java EE policy agent - -`locale`:: -Property files used by the installation program - -`README`:: -README file containing platform and install information for the agent +`agent-lib`:: +For the `jar-with-lib` distribution. Contains external libraries that the agent needs to run. +`agent-locale`:: +Locale files and templates -- -The web application deployment descriptor file, `web.xml`, is the basic configuration file for web applications. As such, the specific content of the `web.xml` file depends on the application. Apache Tomcat also provides a global `/path/to/tomcat/conf/web.xml` deployment descriptor, which sets defaults for all deployed applications. When you install the Apache Tomcat policy agent, you should be concerned with `/path/to/tomcat/conf/web.xml`, and also with the `WEB-INF/web.xml` files in each protected application. [#install-tomcat-agent] @@ -120,48 +101,9 @@ In centralized configuration mode, the Agent URL is used to populate the Agent P ==== -[#d0e4644] -.To Create a Password File -==== - -. Create a text file containing only the password specified when creating the agent profile. -+ -UNIX example: -+ - -[source, console] ----- -$ echo password > /tmp/pwd.txt ----- -+ -Windows example: -+ - -[source, console] ----- -C:\> echo password > pwd.txt ----- - -. Protect the password file you create as appropriate for your operating system: -+ -UNIX example: -+ - -[source, console] ----- -$ chmod 400 /tmp/pwd.txt ----- -+ -Windows example: -+ -In Windows Explorer, right-click the created password file, for example `pwd.txt`, select Read-Only, and then click OK. - -==== - -[#install-agent-into-tomcat6] -.To Install the Policy Agent into Tomcat 6 +[#install-agent-into-tomcat] +.To Install the Policy Agent into Tomcat ==== -The steps required for policy agent installation into Tomcat 6 are subtly different from those required for Tomcat 7. For Tomcat 6, you have the option to include a global `web.xml` file during the installation process if you plan to project every application within the container. . Shut down the Tomcat server where you plan to install the agent: + @@ -171,244 +113,60 @@ The steps required for policy agent installation into Tomcat 6 are subtly differ $ /path/to/tomcat/bin/shutdown.sh ---- -. Make sure OpenAM is running. - -. Run `agentadmin --install` to install the agent: -+ - -[source, console] ----- -$ /path/to/j2ee_agents/tomcat_v6_agent/bin/agentadmin --install --acceptLicense ----- -+ - -.. When you run the command, you will be prompted to read and accept the software license agreement for the agent installation. You can suppress the license agreement prompt by including the `--acceptLicence` parameter. The inclusion of the option indicates that you have read and accepted the terms stated in the license. To view the license agreement, open `/legal-notices/license.txt`. - -.. Enter the path to the Tomcat configuration folder. For example, `/path/to/apache-tomcat/conf`. - -.. Enter the OpenAM URL. For example, `\http://openam.example.com:8080/openam`. The installer attempts to connect with the OpenAM server. If OpenAM is not running, you can continue with the installation. - -.. Enter the `$CATALINA_HOME` environment variable specifying the path to the root of the Tomcat server. For example, `/path/to/apache-tomcat/`. - -.. For Tomcat 6 Installs Only: you will be prompted if you want the installer to deploy the agent filter in the global `web.xml`. Press Enter to accept the default value of `true` if you want to protect all applications in the container. If you want to protect only a few applications, enter `false`. For this example, accept the default: -+ - -[source, console] ----- -Choose yes to deploy the policy agent in the global web.xml file. -[ ? : Help, < : Back, ! : Exit ] -Install agent filter in global web.xml ? [true]: ----- - -.. Enter the agent URL. For example, `\http://openam.example.com:8080/agentapp`. - -.. Enter the agent profile name that you created in OpenAM. For example, `Tomcat Agent`. - -.. Enter the path to the password file. For example, `/tmp/pwd.txt`. - - -. Next, review a summary of your responses and select an action to continue, go back a step, start over, or exit from the install: -+ - -[source, console] ----- ------------------------------------------------ -SUMMARY OF YOUR RESPONSES ------------------------------------------------ -Tomcat Server Config Directory : /path/to/tomcat/conf -OpenAM server URL : http://openam.example.com:8080/openam -$CATALINA_HOME environment variable : /path/to/tomcat - -Tomcat global web.xml filter install : true -Agent URL : http://www.example.com:8080/agentapp -Agent Profile name : Tomcat Agent -Agent Profile Password file name : /tmp/pwd.txt - -Verify your settings above and decide from the choices below. -1. Continue with Installation -2. Back to the last interaction -3. Start Over -4. Exit -Please make your selection [1]: -... - -SUMMARY OF AGENT INSTALLATION ------------------------------ -Agent instance name: Agent_001 -Agent Bootstrap file location: -/path/to/j2ee_agents/tomcat_v6_agent/Agent_001/config/ -OpenSSOAgentBootstrap.properties -Agent Configuration file location -/path/to/j2ee_agents/tomcat_v6_agent/Agent_001/config/ -OpenSSOAgentConfiguration.properties -Agent Audit directory location: -/path/to/j2ee_agents/tomcat_v6_agent/Agent_001/logs/audit -Agent Debug directory location: -/path/to/j2ee_agents/tomcat_v6_agent/Agent_001/logs/debug - -Install log file location: -/path/to/j2ee_agents/tomcat_v6_agent/installer-logs/audit/install.log - -Thank you for using OpenAM Policy Agent ----- -+ -Upon successful completion, the installer adds the agent configuration to the Tomcat configuration, and set up the configuration and log directories for the agent. +. Create the Agent configuration files + - -[NOTE] -====== -If the agent is in a different domain than the server, refer to the __Administration Guide__ procedure, link:../../../openam/13/admin-guide/#chap-cdsso[Configuring Cross-Domain Single Sign On, window=\_blank]. -====== - -. Take note of the configuration files and log locations. -+ -Each agent instance that you install on the system has its own numbered configuration and logs directory. The first agent's configuration and logs are thus located under the directory `j2ee_agents/tomcat_v6_agent/Agent_001/`: -+ --- - -`config/OpenSSOAgentBootstrap.properties`:: -Used to bootstrap the Java EE policy agent, allowing the agent to connect to OpenAM and download its configuration. - -`config/OpenSSOAgentConfiguration.properties`:: -Only used if you configured the Java EE policy agent to use local configuration. - -`logs/audit/`:: -Operational audit log directory, only used if remote logging to OpenAM is disabled. - -`logs/debug/`:: -Debug directory where the `debug.out` debug file resides. Useful in troubleshooting policy agent issues. - -- +`debugconfig.properties`: -. If your policy agent configuration is not in the top-level realm (/), then you must edit config/OpenSSOAgentBootstrap.properties to identify the sub-realm that has your policy agent configuration. Find com.sun.identity.agents.config.organization.name and change the "/" to the path to your policy agent profile. This allows the policy agent to properly identify itself to the OpenAM server. - -. Start the Tomcat server where you installed the agent: -+ - -[source, console] +[source, properties] ---- -$ /path/to/tomcat/bin/startup.sh +org.forgerock.openam.debug.prefix= +org.forgerock.openam.debug.suffix= +org.forgerock.openam.debug.rotation= ---- +and -==== - -[#install-agent-into-tomcat7] -.To Install the Policy Agent into Tomcat 7 -==== -The steps required for policy agent installation into Tomcat 7 are subtly different from those required for Tomcat 6. For Tomcat 7, you do not install the global `web.xml` file, but configure the application-specific `WEB-INF/web.xml` file after basic installation is complete. The `agentapp.war` is automatically copied to the Tomcat `webapps` folder. The Tomcat 8 install is identical to the Tomcat 7 installation process: - -. Shut down the Tomcat server where you plan to install the agent: -+ - -[source, console] ----- -$ /path/to/tomcat/bin/shutdown.sh +`OpenSSOAgentBootstrap.properties`: +[source, properties] ---- +com.iplanet.am.naming.url=http://openam.example.org:8080/openam/namingservice +com.sun.identity.agents.config.service.resolver=org.openidentityplatform.identity.agents.GenericAgentServiceResolver +com.sun.identity.agents.app.username=amadmin +com.iplanet.am.service.secret = AQIC5wM2LY4SfcwrWIPia7mlGbsTreZGLWhi +am.encryption.pwd = KmhUnWR1MYWDYW4xuqdF5nbm+CXIyOVt +com.sun.identity.agents.config.profilename=myAgent -. Make sure OpenAM is running. - -. Run `agentadmin --install` to install the agent: -+ +com.iplanet.services.debug.level=message +com.iplanet.services.debug.directory=/path/to/j2ee_agents/Agent_001/logs/debug +com.sun.services.debug.mergeall=on +com.sun.identity.agents.config.local.logfile=/path/to/j2ee_agents/Agent_001/logs/debug/debug.out +com.sun.identity.agents.config.organization.name=/ +com.sun.identity.agents.config.lock.enable=false -[source, console] ----- -$ /path/to/j2ee_agents/tomcat_v6_agent/bin/agentadmin --install --acceptLicense +com.iplanet.am.server.protocol=http +com.iplanet.am.server.host=openam.example.org +com.iplanet.am.server.port=8080 +com.iplanet.am.services.deploymentDescriptor=/openam ---- -+ - -.. When you run the command, you will be prompted to read and accept the software license agreement for the agent installation. You can suppress the license agreement prompt by including the `--acceptLicence` parameter. The inclusion of the option indicates that you have read and accepted the terms stated in the license. To view the license agreement, open `/legal-notices/license.txt`. -.. Enter the path to the Tomcat configuration folder. For example, `/path/to/apache-tomcat/conf`. - -.. Enter the OpenAM URL. For example, `\http://openam.example.com:8080/openam`. - -.. Enter the `$CATALINA_HOME` environment variable specifying the path to the root of the Tomcat server. For example, `/path/to/apache-tomcat/`. - -.. Enter the agent URL. For example, `\http://openam.example.com:8080/agentapp`. - -.. Enter the agent profile name that you created in OpenAM. For example, `Tomcat Agent`. - -.. Enter the path to the password file. For example, `/tmp/pwd.txt`. - - -. Next, review a summary of your responses and select an action to continue, go back a step, start over, or exit from the install: -+ - -[source, console] ----- ------------------------------------------------ -SUMMARY OF YOUR RESPONSES ------------------------------------------------ -Tomcat Server Config Directory : /path/to/tomcat/conf -OpenAM server URL : http://openam.example.com:8080/openam -$CATALINA_HOME environment variable : /path/to/tomcat - -Tomcat global web.xml filter install : false -Agent URL : http://www.example.com:8080/agentapp -Agent Profile name : Tomcat Agent -Agent Profile Password file name : /tmp/pwd.txt - -Verify your settings above and decide from the choices below. -1. Continue with Installation -2. Back to the last interaction -3. Start Over -4. Exit -Please make your selection [1]: -... - -SUMMARY OF AGENT INSTALLATION ------------------------------ -Agent instance name: Agent_001 -Agent Bootstrap file location: -/path/to/j2ee_agents/tomcat_v6_agent/Agent_001/config/ -OpenSSOAgentBootstrap.properties -Agent Configuration file location -/path/to/j2ee_agents/tomcat_v6_agent/Agent_001/config/ -OpenSSOAgentConfiguration.properties -Agent Audit directory location: -/path/to/j2ee_agents/tomcat_v6_agent/Agent_001/logs/audit -Agent Debug directory location: -/path/to/j2ee_agents/tomcat_v6_agent/Agent_001/logs/debug - -Install log file location: -/path/to/j2ee_agents/tomcat_v6_agent/installer-logs/audit/install.log - -Thank you for using OpenAM Policy Agent ----- -+ -Upon successful completion, the installer adds the agent configuration to the Tomcat configuration, and also set up the configuration and log directories for the agent. -+ +Adjust configuration parameters to your needs according to xref:./chap-jee-agent-config.adoc#configure-j2ee-policy-agent[Configuring Java EE Policy Agent Properties] [NOTE] ====== -If the agent is in a different domain than the server, refer to the __Administration Guide__ procedure, link:../../../openam/13/admin-guide/#chap-cdsso[Configuring Cross-Domain Single Sign On, window=\_blank]. +If the agent is in a different domain than the server, refer to the __Administration Guide__ procedure, link:../../../openam/admin-guide/chap-cdsso[Configuring Cross-Domain Single Sign On, window=\_blank]. ====== -. Take note of the configuration files and log locations. -+ -Each agent instance that you install on the system has its own numbered configuration and logs directory. The first agent's configuration and logs are thus located under the directory `j2ee_agents/tomcat_v6_agent/Agent_001/`: -+ --- - -`config/OpenSSOAgentBootstrap.properties`:: -Used to bootstrap the Java EE policy agent, allowing the agent to connect to OpenAM and download its configuration. - -`config/OpenSSOAgentConfiguration.properties`:: -Only used if you configured the Java EE policy agent to use local configuration. - -`logs/audit/`:: -Operational audit log directory, only used if remote logging to OpenAM is disabled. - -`logs/debug/`:: -Debug directory where the `debug.out` debug file resides. Useful in troubleshooting policy agent issues. - -- - ++ . If your policy agent configuration is not in the top-level realm (/), then you must edit config/OpenSSOAgentBootstrap.properties to identify the sub-realm that has your policy agent configuration. Find com.sun.identity.agents.config.organization.name and change the "/" to the path to your policy agent profile. This allows the policy agent to properly identify itself to the OpenAM server. . If you want to protect all applications in the container, you must add a filter manually for each protected application's `WEB-INF/web.xml` deployment descriptor file, following the opening tag. Make sure that the agent filter is first in the filter chain: + +Add the `agent.jar` file, contents of the `agent-lib` directory, for `jee-agent-jar-with-lib` distribution, and contents of the `agent-locale` to the Apache Tomcat's `lib` directory. + +Add filter to the Tomcat's `conf/web.xml` configuration file: + [source, xml] ---- @@ -455,12 +213,12 @@ INFO: Server startup in 810 ms [source, console] ---- -$ tail -n 7 /path/to/j2ee_agents/tomcat_v6_agent/Agent_001/logs/debug/debug.out +$ tail -n 7 /path/to/j2ee_agents/Agent_001/logs/debug/debug.out ======================================= Version: ... Revision: 3111 -Build Date: 20120915 -Build Machine: builds.forgerock.org +Build Date: Build Date: 2025-08-21T09:44:23Z +Build Machine: runner ======================================= ---- @@ -469,23 +227,16 @@ Build Machine: builds.forgerock.org ==== -[#silent-tomcat-agent-installation] -=== Silent Tomcat Policy Agent Installation - -When performing a scripted, silent installation, use `agentadmin --install --saveResponse response-file` to create a response file for scripted installation. Then install silently using `agentadmin --install --acceptLicense --useResponse response-file`. - - [#uninstall-tomcat-agent] === Remove Tomcat Policy Agent Software -Shut down the Tomcat server before you uninstall the policy agent: - +. Shut down the Tomcat server before you uninstall the policy agent: ++ [source, console] ---- $ /path/to/tomcat/bin/shutdown.sh ---- -To remove the Java EE policy agent, use `agentadmin --uninstall`. You must provide the Tomcat server configuration directory location. - -Uninstall does not remove the agent instance directory, but you can do so manually after removing the agent configuration from Tomcat. +. Remove agent files from the Apache Tomcat's `lib` directory. +. Remove the Agent filter from the Tomcat's `conf/web.xml` configuration file diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/jee-users-guide/chap-jboss-7.adoc b/openam-documentation/openam-doc-source/src/main/asciidoc/jee-users-guide/chap-jboss-7.adoc deleted file mode 100644 index b3056bc38d..0000000000 --- a/openam-documentation/openam-doc-source/src/main/asciidoc/jee-users-guide/chap-jboss-7.adoc +++ /dev/null @@ -1,328 +0,0 @@ -//// - The contents of this file are subject to the terms of the Common Development and - Distribution License (the License). You may not use this file except in compliance with the - License. - - You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the - specific language governing permission and limitations under the License. - - When distributing Covered Software, include this CDDL Header Notice in each file and include - the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL - Header, with the fields enclosed by brackets [] replaced by your own identifying - information: "Portions copyright [year] [name of copyright owner]". - - Copyright 2017 ForgeRock AS. - Portions Copyright 2024 3A Systems LLC. -//// - -:figure-caption!: -:example-caption!: -:table-caption!: - - -[#chap-jboss-7] -== Installing Java EE Agents in JBoss 7 - -This chapter covers installation of the policy agent for JBoss Application Server. - -[#before-jboss7-agent-install] -=== Before You Install - -Make sure OpenAM is installed and running, and that you can contact OpenAM from the system running the policy agent. Next, create a profile for your policy agent as described in xref:../jee-users-guide/chap-jee-agent-config.adoc#create-agent-profiles[Creating Agent Profiles]. To protect resources with the agent, create at least one policy as described in link:../../../openam/13/admin-guide/#chap-authz-policy[Configuring Policies, window=\_blank] in the __OpenAM Administration Guide__. Consider creating a simple policy, such as a policy that allows only authenticated users to access your resources in order to test your policy agent after installation. - -You must install JBoss before installing the policy agent. - -You must install a supported version of the Java runtime environment. Set the `JAVA_HOME` environment variable accordingly. The policy agent installer requires Java. - -[source, console] ----- -$ echo $JAVA_HOME -/path/to/java ----- -See the OpenAM __Installation Guide__ section, link:../../../openam/13/install-guide/#download-openam-software[Obtaining OpenAM Software, window=\_blank] to determine which version of the agent to download, and download the agent. Also verify the checksum of the file you download against the checksum posted on the download page. - -Unzip the file in the directory where you plan to install the J2EE policy agent. The agent you install stores its configuration and logs under this directory. - -When you unzip the policy agent, you find the following directories under the `j2ee_agents/jboss_v7_agent` directory. - -Despite the directory name, the policy agent supports multiple container versions. --- - -`bin`:: -The installation and configuration program `agentadmin`. For more details about the available command-line tools, see xref:tools-reference.adoc#tools-reference[Command-Line Tool Reference]. - -`config`:: -Configuration templates used by the `agentadmin` command during installation - -`data`:: -Not used - -`etc`:: -Configuration templates used during installation - -`installer-logs`:: -Location for log files written during installation - -`legal-notices`:: -Contains licensing information including third-party licenses - -`lib`:: -Shared libraries used by the Java EE policy agent - -`locale`:: -Property files used by the installation program - -`README`:: -README file containing platform and install information for the agent - --- - - -[#install-jboss7-agent] -=== Installing the JBoss Policy Agent - -Complete the following procedures to install the policy agent. - -[#d0e5276] -.To Create the Agent Profile -==== -Regardless of whether you store configurations centrally in OpenAM or locally with your agents, the agent requires a profile so that it can connect to and communicate with OpenAM. - -. In the OpenAM console, browse to Realms > __Realm Name__ > Agents > J2EE, and then click the New... button in the Agent table. - -. Complete the web form using the following hints: -+ --- - -Name:: -The name for the agent profile used when you install the agent - -Password:: -Password the agent uses to authenticate to OpenAM - -Configuration:: -Centralized configurations are stored in the OpenAM configuration store. You can manage the centralized configuration through the OpenAM console. Local configurations are stored in a file alongside the agent. - -Server URL:: -The full URL to an OpenAM instance, or if OpenAM is deployed in a site configuration (behind a load balancer) then the site URL -+ -In centralized configuration mode, the Server URL is used to populate the agent profile for services, such as Login, Logout, Naming, and Cross Domain SSO. - -Agent URL:: -The URL to the J2EE agent application, such as `\http://www.example.com:8080/agentapp` -+ -In centralized configuration mode, the Agent URL is used to populate the Agent Profile for services, such as notifications. - --- - -==== - -[#d0e5328] -.To Create a Password File -==== - -. Create a text file containing only the password specified when creating the agent profile. -+ -UNIX example: -+ - -[source, console] ----- -$ echo password > /tmp/pwd.txt ----- -+ -Windows example: -+ - -[source, console] ----- -C:\> echo password > pwd.txt ----- - -. Protect the password file you create as appropriate for your operating system: -+ -UNIX example: -+ - -[source, console] ----- -$ chmod 400 /tmp/pwd.txt ----- -+ -Windows example: -+ -In Windows Explorer, right-click the created password file, for example `pwd.txt`, select Read-Only, and then click OK. - -==== - -[#install-agent-into-jboss7] -.To Install the Policy Agent into JBoss -==== -If you want to include an application-specific module, make sure to type in `false` when prompted with the following question: - -[source] ----- -Install agent as global module? [true]: ----- - -. Shut down the JBoss server where you plan to install the agent. - -. Make sure OpenAM is running. - -. Run `agentadmin --install` to install the agent. -+ -When you run the command, you will be prompted to read and accept the software license agreement for the agent installation. You can suppress the license agreement prompt by including the `--acceptLicence` parameter. The inclusion of the option indicates that you have read and accepted the terms stated in the license. To view the license agreement, open `/legal-notices/license.txt`. -+ - -[source, console] ----- -$ /path/to/j2ee_agents/jboss_v7_agent/bin/agentadmin --install --acceptLicense -... ------------------------------------------------ -SUMMARY OF YOUR RESPONSES ------------------------------------------------ -JBoss home directory : /path/to/jboss/ -JBoss deployment mode: standalone -Install agent as global module: true -OpenAM server URL : http://openam.example.com:8080/openam -Agent URL : http://www.example.com:8080/agentapp -Agent Profile name : JBossAgent -Agent Profile Password file name : /tmp/pwd.txt - -... -SUMMARY OF AGENT INSTALLATION ------------------------------ -Agent instance name: Agent_001 -Agent Bootstrap file location: -/path/to/j2ee_agents/jboss_v7_agent/Agent_001/config/ - OpenSSOAgentBootstrap.properties -Agent Configuration file location -/path/to/j2ee_agents/jboss_v7_agent/Agent_001/config/ - OpenSSOAgentConfiguration.properties -Agent Audit directory location: -/path/to/j2ee_agents/jboss_v7_agent/Agent_001/logs/audit -Agent Debug directory location: -/path/to/j2ee_agents/jboss_v7_agent/Agent_001/logs/debug - - -Install log file location: -/path/to/j2ee_agents/jboss_v7_agent/installer-logs/audit/install.log -... ----- -+ -Upon successful completion, the installer updates the JBoss configuration, adds the agent web application under `JBOSS_HOME/server/standalone/deployments`, and also sets up configuration and log directories for the agent. -+ - -[NOTE] -====== -If the agent is in a different domain than the server, refer to __Administration Guide__ procedure, link:../../../openam/13/admin-guide/#chap-cdsso[Configuring Cross-Domain Single Sign On, window=\_blank]. -====== - -. Take note of the configuration files and log locations. -+ -Each agent instance that you install on the system has its own numbered configuration and logs directory. The first agent's configuration and logs are thus located under the directory `j2ee_agents/jboss_v7_agent/Agent_001/`: -+ --- - -`config/OpenSSOAgentBootstrap.properties`:: -Used to bootstrap the Java EE policy agent, allowing the agent to connect to OpenAM and download its configuration. - -`config/OpenSSOAgentConfiguration.properties`:: -Only used if you configured the Java EE policy agent to use local configuration. - -`logs/audit/`:: -Operational audit log directory, only used if remote logging to OpenAM is disabled. - -`logs/debug/`:: -Debug directory where the debug file resides. Useful in troubleshooting policy agent issues. - --- - -. If your policy agent configuration is not in the top-level realm (/), then you must edit config/OpenSSOAgentBootstrap.properties to identify the sub-realm that has your policy agent configuration. Find com.sun.identity.agents.config.organization.name and change the / to the realm to your policy agent profile. This allows the policy agent to properly identify itself to the OpenAM server. - -. To protect a web application, you must add the following filter to the application's `WEB-INF/web.xml` deployment descriptor, following the opening tag: -+ - -[source, xml] ----- - - Agent - Agent - OpenAM Policy Agent Filter - com.sun.identity.agents.filter.AmAgentFilter - - - Agent - /* - REQUEST - INCLUDE - FORWARD - ERROR - ----- -+ -You also need to add the following security constraint specification to the application's `WEB-INF/web.xml` file: -+ - -[source, xml] ----- - - - All resources - Protects all resources - *.do - - ----- -+ -You must also add the following security domain specification to the `jboss-web.xml` configuration file of the application: -+ - -[source, xml] ----- -java:/jaas/AMRealm ----- -+ -You can find that file packed in the `agentsample.ear` archive in the `/path/to/j2ee_agents/jboss_v7_agent/sampleapp/dist` directory. Once unpacked, you can find the file in the `WEB-INF` subdirectory. - -. If you typed in `false` to the `Install agent as global module` question during the installation process, you will need to add the following line to the `META-INF/MANIFEST.MF` file of the application: -+ - -[source, xml] ----- -Dependencies: org.forgerock.openam.agent ----- - -. If you responded `domain` to the `Enter the name of the deployment mode` question during the installation process, you must manually deploy the `j2ee_agents/jboss_v7_agent/etc/agentapp.war` file to JBoss. -+ -The reason manual deployment is required when running JBoss in domain mode is that the agent installer uses auto-deployment capabilities provided by the JBoss deployment scanner. The deployment scanner is used only in standalone mode. When running JBoss in standalone mode, it is not necessary to manually deploy the `agentapp.war` file. - -==== - -[#run-jboss7-after-agent-installation] -.To Run JBoss After Agent Installation -==== - -. Run JBoss. - -. (Optional) If you have a policy configured, you can test your policy agent. For example, try to browse to a resource that your policy agent protects. You should be redirected to OpenAM to authenticate, for example, as user `demo`, password `changeit`. After you authenticate, OpenAM then redirects you back to the resource you tried to access. - -==== - - -[#silent-jboss7-agent-installation] -=== Silent JBoss Policy Agent Installation - -When performing a scripted, silent installation, use `agentadmin --install --saveResponse response-file` to create a response file for scripted installation. Then install silently using `agentadmin --install --acceptLicense --useResponse response-file`. - - -[#uninstall-jboss7-agent] -=== Removing JBoss Policy Agent Software - -Shut down the JBoss server before you uninstall the policy agent. - -To remove the Java EE policy agent, use `agentadmin --uninstall`. You must provide the JBoss configuration directory location. - -Uninstall does not remove the agent instance directory, but you can do so manually after removing the agent configuration from JBoss. - - diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/jee-users-guide/chap-jetty.adoc b/openam-documentation/openam-doc-source/src/main/asciidoc/jee-users-guide/chap-jetty.adoc index 17842b173f..d02280d58c 100644 --- a/openam-documentation/openam-doc-source/src/main/asciidoc/jee-users-guide/chap-jetty.adoc +++ b/openam-documentation/openam-doc-source/src/main/asciidoc/jee-users-guide/chap-jetty.adoc @@ -12,7 +12,7 @@ information: "Portions copyright [year] [name of copyright owner]". Copyright 2017 ForgeRock AS. - Portions Copyright 2024 3A Systems LLC. + Portions Copyright 2024-2025 3A Systems LLC. //// :figure-caption!: @@ -32,65 +32,31 @@ Make sure OpenAM is installed and running, and that you can contact OpenAM from You must install Jetty before you install the policy agent, and you must stop the server during installation. -You must install a supported version of the Java runtime environment. Set the `JAVA_HOME` environment variable accordingly. The policy agent installer requires Java. +You must install a supported version of the Java runtime environment. Set the `JAVA_HOME` environment variable accordingly. The policy agent requires Java. [source, console] ---- $ echo $JAVA_HOME /path/to/java ---- -See the OpenAM __Installation Guide__ section, link:../../../openam/13/install-guide/#download-openam-software[Obtaining OpenAM Software, window=\_blank] to determine which version of the agent to download, and download the agent. Also verify the checksum of the file you download against the checksum posted on the download page. +Download the agent distribution of the J2EE Agent from link:https://github.com/OpenIdentityPlatform/OpenAM-JEE-Agents/releases/[GitHub, window=\_blank]. +Also verify the checksum of the file you download against the checksum posted on the download page. -[NOTE] -==== -Command line examples in this chapter show Jetty accessed remotely. If you are following the examples and have issues accessing Jetty remotely, you might have to change filter settings in the deployment descriptor file, such as `/path/to/jetty/webapps/test/WEB-INF/web.xml`, as shown in the following example: - -[source, xml] ----- - - TestFilter - com.acme.TestFilter - - remote - true - - ----- -==== Unzip the file in the directory where you plan to install the J2EE policy agent. The agent you install stores its configuration and logs under this directory. -When you unzip the policy agent, you find the following directories under the `j2ee_agents/jetty_v61_agent` directory. +When you unzip the policy agent, you find the following files and directories under the `jee-agent-uberjar` or `jee-agent-jar-with-lib` directory. Despite the directory name, the policy agent supports multiple container versions. -- -`bin`:: -The installation and configuration program `agentadmin`. For more details about the available command-line tools, see xref:tools-reference.adoc#tools-reference[Command-Line Tool Reference]. - -`config`:: -Configuration templates used by the `agentadmin` command during installation +`agent.jar`:: +The policy agent JAR file itself. -`data`:: -Not used - -`etc`:: -Configuration templates used during installation - -`installer-logs`:: -Location for log files written during installation - -`legal-notices`:: -Contains licensing information including third-party licenses - -`lib`:: -Shared libraries used by the Java EE policy agent - -`locale`:: -Property files used by the installation program - -`README`:: -README file containing platform and install information for the agent +`agent-lib`:: +For the `jar-with-lib` distribution. Contains external libraries that the agent needs to run. +`agent-locale`:: +Locale files and templates -- @@ -133,43 +99,7 @@ In centralized configuration mode, the Agent URL is used to populate the Agent P ==== -[#d0e5817] -.To Create a Password File -==== - -. Create a text file containing only the password specified when creating the agent profile. -+ -UNIX example: -+ - -[source, console] ----- -$ echo password > /tmp/pwd.txt ----- -+ -Windows example: -+ - -[source, console] ----- -C:\> echo password > pwd.txt ----- - -. Protect the password file you create as appropriate for your operating system: -+ -UNIX example: -+ - -[source, console] ----- -$ chmod 400 /tmp/pwd.txt ----- -+ -Windows example: -+ -In Windows Explorer, right-click the created password file, for example `pwd.txt`, select Read-Only, and then click OK. -==== [#install-agent-into-jetty] .To Install the Policy Agent into Jetty @@ -177,79 +107,57 @@ In Windows Explorer, right-click the created password file, for example `pwd.txt . Shut down the Jetty server where you plan to install the agent. -. Make sure OpenAM is running. - -. Run `agentadmin --install` to install the agent. -+ -When you run the command, you will be prompted to read and accept the software license agreement for the agent installation. You can suppress the license agreement prompt by including the `--acceptLicence` parameter. The inclusion of the option indicates that you have read and accepted the terms stated in the license. To view the license agreement, open `/legal-notices/license.txt`. +. Create the Agent configuration files + +-- +`debugconfig.properties`: -[source, console] +[source, properties] ---- -$ /path/to/j2ee_agents/jetty_v61_agent/bin/agentadmin --install --acceptLicense -... ------------------------------------------------ -SUMMARY OF YOUR RESPONSES ------------------------------------------------ -Jetty Server Config Directory : /path/to/jetty/etc -OpenAM server URL : http://openam.example.com:8080/openam -Jetty installation directory. : /path/to/jetty -Agent URL : http://www.example.com:8080/agentapp -Agent Profile name : Jetty Agent -Agent Profile Password file name : /tmp/pwd.txt +org.forgerock.openam.debug.prefix= +org.forgerock.openam.debug.suffix= +org.forgerock.openam.debug.rotation= +---- +and -... -SUMMARY OF AGENT INSTALLATION ------------------------------ -Agent instance name: Agent_001 -Agent Bootstrap file location: -/path/to/j2ee_agents/jetty_v61_agent/Agent_001/config/ - OpenSSOAgentBootstrap.properties -Agent Configuration file location -/path/to/j2ee_agents/jetty_v61_agent/Agent_001/config/ - OpenSSOAgentConfiguration.properties -Agent Audit directory location: -/path/to/j2ee_agents/jetty_v61_agent/Agent_001/logs/audit -Agent Debug directory location: -/path/to/j2ee_agents/jetty_v61_agent/Agent_001/logs/debug - - -Install log file location: -/path/to/j2ee_agents/jetty_v61_agent/installer-logs/audit/install.log -... +`OpenSSOAgentBootstrap.properties`: +[source, properties] ---- -+ -Upon successful completion, the installer updates Jetty's `start.jar` to reference the agent, sets up the agent web application, and also sets up configuration and log directories for the agent. -+ +com.iplanet.am.naming.url=http://openam.example.org:8080/openam/namingservice +com.sun.identity.agents.config.service.resolver=org.openidentityplatform.identity.agents.GenericAgentServiceResolver +com.sun.identity.agents.app.username=amadmin +com.iplanet.am.service.secret = AQIC5wM2LY4SfcwrWIPia7mlGbsTreZGLWhi +am.encryption.pwd = KmhUnWR1MYWDYW4xuqdF5nbm+CXIyOVt +com.sun.identity.agents.config.profilename=myAgent + +com.iplanet.services.debug.level=message +com.iplanet.services.debug.directory=/path/to/j2ee_agents/Agent_001/logs/debug +com.sun.services.debug.mergeall=on +com.sun.identity.agents.config.local.logfile=/path/to/j2ee_agents/Agent_001/logs/debug/debug.out +com.sun.identity.agents.config.organization.name=/ +com.sun.identity.agents.config.lock.enable=false + +com.iplanet.am.server.protocol=http +com.iplanet.am.server.host=openam.example.org +com.iplanet.am.server.port=8080 +com.iplanet.am.services.deploymentDescriptor=/openam +---- + +Adjust configuration parameters to your needs according to xref:./chap-jee-agent-config.adoc#configure-j2ee-policy-agent[Configuring Java EE Policy Agent Properties] [NOTE] ====== -If the agent is in a different domain than the server, refer to __Administration Guide__ procedure, link:../../../openam/13/admin-guide/#chap-cdsso[Configuring Cross-Domain Single Sign On, window=\_blank]. +If the agent is in a different domain than the server, refer to the __Administration Guide__ procedure, link:../../../openam/admin-guide/chap-cdsso[Configuring Cross-Domain Single Sign On, window=\_blank]. ====== - -. Take note of the configuration files and log locations. -+ -Each agent instance that you install on the system has its own numbered configuration and logs directory. The first agent's configuration and logs are thus located under the directory `j2ee_agents/jetty_v61_agent/Agent_001/`: -+ -- +. If your policy agent configuration is not in the top-level realm (/), then you must edit config/OpenSSOAgentBootstrap.properties to identify the sub-realm that has your policy agent configuration. Find com.sun.identity.agents.config.organization.name and change the "/" to the path to your policy agent profile. This allows the policy agent to properly identify itself to the OpenAM server. -`config/OpenSSOAgentBootstrap.properties`:: -Used to bootstrap the Java EE policy agent, allowing the agent to connect to OpenAM and download its configuration. - -`config/OpenSSOAgentConfiguration.properties`:: -Only used if you configured the Java EE policy agent to use local configuration. - -`logs/audit/`:: -Operational audit log directory, only used if remote logging to OpenAM is disabled. - -`logs/debug/`:: -Debug directory where the `debug.out` debug file resides. Useful in troubleshooting policy agent issues. - --- +. If you want to protect all applications in the container, you must add a filter manually for each protected application's `WEB-INF/web.xml` deployment descriptor file, following the opening tag. Make sure that the agent filter is first in the filter chain: ++ -. If your policy agent configuration is not in the top-level realm (/), then you must edit config/OpenSSOAgentBootstrap.properties to identify the sub-realm that has your policy agent configuration. Find com.sun.identity.agents.config.organization.name and change the / to the path to your policy agent profile. This allows the policy agent to properly identify itself to the OpenAM server. +Add the `agent.jar` file to the Jetty's `resources` directory and contents of the `agent-lib` directory, for `jee-agent-jar-with-lib` distribution, and contents of the `agent-locale` to the Jetty's `resources` directory. -. To protect a web application, you must add the following filter to the application's `WEB-INF/web.xml` deployment descriptor, following the opening tag. +Add filter to the Jetty's `etc/webdefault.xml` configuration file: + [source, xml] @@ -286,20 +194,10 @@ $ cd /path/to/jetty ; java -jar start.jar ==== - -[#silent-jetty-agent-installation] -=== Silent Jetty Policy Agent Installation - -When performing a scripted, silent installation, use `agentadmin --acceptLicense --saveResponse response-file` to create a response file for scripted installation. Then install silently using `agentadmin --install --acceptLicense --useResponse response-file`. - - [#uninstall-jetty-agent] === Removing Jetty Policy Agent Software -Shut down the Jetty server before you uninstall the policy agent. - -To remove the Java EE policy agent, use `agentadmin --uninstall`. You must provide the Jetty configuration directory location. - -Uninstall does not remove the agent instance directory, but you can do so manually after removing the agent configuration from Jetty. +. Remove agent files from the Jetty's `lib` and `resources` directories. +. Remove the Agent filter from the Jetty's `etc/webdefault.xml` configuration file diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/jee-users-guide/chap-weblogic.adoc b/openam-documentation/openam-doc-source/src/main/asciidoc/jee-users-guide/chap-weblogic.adoc deleted file mode 100644 index 9a5781c787..0000000000 --- a/openam-documentation/openam-doc-source/src/main/asciidoc/jee-users-guide/chap-weblogic.adoc +++ /dev/null @@ -1,427 +0,0 @@ -//// - The contents of this file are subject to the terms of the Common Development and - Distribution License (the License). You may not use this file except in compliance with the - License. - - You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the - specific language governing permission and limitations under the License. - - When distributing Covered Software, include this CDDL Header Notice in each file and include - the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL - Header, with the fields enclosed by brackets [] replaced by your own identifying - information: "Portions copyright [year] [name of copyright owner]". - - Copyright 2017 ForgeRock AS. - Portions Copyright 2024 3A Systems LLC. -//// - -:figure-caption!: -:example-caption!: -:table-caption!: - - -[#chap-weblogic] -== Installing Java EE Agents in Oracle WebLogic - -This chapter covers installation of the policy agent for Oracle WebLogic. - -[#before-weblogic-agent-install] -=== Before You Install - -Make sure OpenAM is installed and running, and that you can contact OpenAM from the system running the policy agent. Next, create a profile for your policy agent as described in xref:../jee-users-guide/chap-jee-agent-config.adoc#create-agent-profiles[Creating Agent Profiles]. To protect resources with the agent, create at least one policy as described in link:../../../openam/13/admin-guide/#chap-authz-policy[Configuring Policies, window=\_blank] in the __OpenAM Administration Guide__. Consider creating a simple policy, such as a policy that allows only authenticated users to access your resources in order to test your policy agent after installation. - -You must install WebLogic before you install the policy agent, and you must stop the server during installation. - -You must install a supported version of the Java runtime environment. Set the `JAVA_HOME` environment variable accordingly. The policy agent installer requires Java. - -[source, console] ----- -$ echo $JAVA_HOME -/path/to/java ----- -See the OpenAM __Installation Guide__ section, link:../../../openam/13/install-guide/#download-openam-software[Obtaining OpenAM Software, window=\_blank] to determine which version of the agent to download, and download the agent. Also verify the checksum of the file you download against the checksum posted on the download page. - -Unzip the file in the directory where you plan to install the J2EE policy agent. The agent you install stores its configuration and logs under this directory. - -When you unzip the policy agent, you find the following directories under the `j2ee_agents/weblogic_v10_agent` directory. - -Despite the directory name, the policy agent supports multiple container versions. --- - -`bin`:: -The installation and configuration program `agentadmin`. For more details about the available command-line tools, see xref:tools-reference.adoc#tools-reference[Command-Line Tool Reference]. - -`config`:: -Configuration templates used by the `agentadmin` command during installation - -`data`:: -Not used - -`etc`:: -Configuration templates used during installation - -`installer-logs`:: -Location for log files written during installation - -`legal-notices`:: -Contains licensing information including third-party licenses - -`lib`:: -Shared libraries used by the Java EE policy agent - -`locale`:: -Property files used by the installation program - -`README`:: -README file containing platform and install information for the agent - --- - - -[#install-weblogic-agent] -=== Installing the WebLogic Policy Agent - -Complete the following procedures to install the policy agent. - -[#d0e6173] -.To Create the Agent Profile -==== -Regardless of whether you store configurations centrally in OpenAM or locally with your agents, the agent requires a profile so that it can connect to and communicate with OpenAM. - -. In the OpenAM console, browse to Realms > __Realm Name__ > Agents > J2EE, and then click the New... button in the Agent table. - -. Complete the web form using the following hints: -+ --- - -Name:: -The name for the agent profile used when you install the agent - -Password:: -Password the agent uses to authenticate to OpenAM - -Configuration:: -Centralized configurations are stored in the OpenAM configuration store. You can manage the centralized configuration through the OpenAM console. Local configurations are stored in a file alongside the agent. - -Server URL:: -The full URL to an OpenAM instance, or if OpenAM is deployed in a site configuration (behind a load balancer) then the site URL -+ -In centralized configuration mode, the Server URL is used to populate the agent profile for services, such as Login, Logout, Naming, and Cross Domain SSO. - -Agent URL:: -The URL to the J2EE agent application, such as `\http://www.example.com:8080/agentapp` -+ -In centralized configuration mode, the Agent URL is used to populate the Agent Profile for services, such as notifications. - --- - -==== - -[#d0e6225] -.To Create a Password File -==== - -. Create a text file containing only the password specified when creating the agent profile. -+ -UNIX example: -+ - -[source, console] ----- -$ echo password > /tmp/pwd.txt ----- -+ -Windows example: -+ - -[source, console] ----- -C:\> echo password > pwd.txt ----- - -. Protect the password file you create as appropriate for your operating system: -+ -UNIX example: -+ - -[source, console] ----- -$ chmod 400 /tmp/pwd.txt ----- -+ -Windows example: -+ -In Windows Explorer, right-click the created password file, for example `pwd.txt`, select Read-Only, and then click OK. - -==== - -[#install-agent-into-weblogic] -.To Install the Policy Agent into WebLogic -==== - -. Shut down the WebLogic server where you plan to install the agent. - -. Make sure OpenAM is running. - -. Run `agentadmin --install` to install the agent. -+ -When you run the command, you will be prompted to read and accept the software license agreement for the agent installation. You can suppress the license agreement prompt by including the `--acceptLicence` parameter. The inclusion of the option indicates that you have read and accepted the terms stated in the license. To view the license agreement, open `/legal-notices/license.txt`. -+ - -[source, console] ----- -$ /path/to/j2ee_agents/weblogic_v10_agent/bin/agentadmin --install --acceptLicense -... ------------------------------------------------ -SUMMARY OF YOUR RESPONSES ------------------------------------------------ -Startup script location : -/path/to/domain/mydomain/bin/startWebLogic.sh -WebLogic Server instance name : AdminServer -WebLogic home directory : /path/to/wlserver -OpenAM server URL : http://openam.example.com:8080/openam -Agent URL : http://www.example.com:7001/agentapp -Agent Profile name : WebLogic Agent -Agent Profile Password file name : /tmp/pwd.txt - -... -SUMMARY OF AGENT INSTALLATION ------------------------------ -Agent instance name: Agent_001 -Agent Bootstrap file location: -/path/to/j2ee_agents/weblogic_v10_agent/Agent_001/config/ - OpenSSOAgentBootstrap.properties -Agent Configuration file location -/path/to/j2ee_agents/weblogic_v10_agent/Agent_001/config/ - OpenSSOAgentConfiguration.properties -Agent Audit directory location: -/path/to/j2ee_agents/weblogic_v10_agent/Agent_001/logs/audit -Agent Debug directory location: -/path/to/j2ee_agents/weblogic_v10_agent/Agent_001/logs/debug - - -Install log file location: -/path/to/j2ee_agents/weblogic_v10_agent/installer-logs/audit/install.log -... ----- -+ -Upon successful completion, the installer updates the WebLogic configuration, copies the agent libraries to WebLogic's library directory, and also sets up configuration and log directories for the agent. -+ - -[NOTE] -====== -If the agent is in a different domain than the server, refer to the __Administration Guide__ procedure, link:../../../openam/13/admin-guide/#chap-cdsso[Configuring Cross-Domain Single Sign On, window=\_blank]. -====== - -. Take note of the configuration files and log locations. -+ -Each agent instance that you install on the system has its own numbered configuration and logs directory. The first agent's configuration and logs are thus located under the directory `j2ee_agents/weblogic_v10_agent/Agent_001/`: -+ --- - -`config/OpenSSOAgentBootstrap.properties`:: -Used to bootstrap the Java EE policy agent, allowing the agent to connect to OpenAM and download its configuration. - -`config/OpenSSOAgentConfiguration.properties`:: -Only used if you configured the Java EE policy agent to use local configuration. - -`logs/audit/`:: -Operational audit log directory, only used if remote logging to OpenAM is disabled. - -`logs/debug/`:: -Debug directory where the debug file resides. Useful in troubleshooting policy agent issues. - --- - -. If your policy agent configuration is not in the top-level realm (/), then you must edit config/OpenSSOAgentBootstrap.properties to identify the sub-realm that has your policy agent configuration. Find com.sun.identity.agents.config.organization.name and change the / to the path to your policy agent profile. This allows the policy agent to properly identify itself to the OpenAM server. - -. The agent requires sourcing before it will work properly. There are two ways to source: -+ - -* Manually source the file containing the policy agent environment settings for WebLogic before starting the application server. -+ - -[source, console] ----- -$ . /path/to/setAgentEnv_AdminServer.sh ----- - -* Or edit the `startWebLogic.sh` script to set the sourcing needed for the agent, by adding these lines after the code block shown. Add the setAgentEnv_AdminServer.sh line to the following location in the file. The drawback to this approach is that it could be overwritten, as noted in the file: -+ - -[source, console] ----- -$ cat /path/to/startWebLogic.sh -... -# Any changes to this script may be lost when adding extensions to this -# configuration. -DOMAIN_HOME="/opt/Oracle/Middleware/user_projects/domains/base_domain" - . /path/to/setAgentEnv_AdminServer.sh -${DOMAIN_HOME}/bin/startWebLogic.sh $* ----- - -+ - -[NOTE] -====== -If the sourcing is not set properly, the following message appears: - -[source, console] ----- - - <[STANDBY] ExecuteThread: '5' for queue: 'weblogic.kernel. -Default (self-tuning)'> <> <><> <> <1360800613441> - tag: -+ - -[source, xml] ----- - - Agent - Agent - OpenAM Policy Agent Filter - com.sun.identity.agents.filter.AmAgentFilter - - - Agent - /* - REQUEST - INCLUDE - FORWARD - ERROR - ----- -+ -You might also have to update additional configuration files. See the sample application located under `/path/to/j2ee_agents/weblogic_v10_agent/sampleapp` for examples. - -. (Optional) If you have a policy configured, you can test your policy agent. For example, try to browse to a resource that your policy agent protects. You should be redirected to OpenAM to authenticate, for example, as user `demo`, password `changeit`. After you authenticate, OpenAM then redirects you back to the resource you tried to access. - -==== - - -[#silent-weblogic-agent-installation] -=== Silent WebLogic Policy Agent Installation - -When performing a scripted, silent installation, use `agentadmin --install --saveResponse response-file` to create a response file for scripted installation. Then install silently using `agentadmin --install --acceptLicense --useResponse response-file`. - - -[#post-weblogic-agent-installation] -=== Post Installation of WebLogic Policy Agent - -After installing WebLogic, some configuration is required before the policy agent will work. - -[#configure-weblogic-agent] -.To Configure the WebLogic Policy Agent -==== -WebLogic is unique in that it requires additional configuration after the installation is complete: - -. Go to the WebLogic Server Administration Console and login. - -. Click `Security realms`. - -. Click the name of the realm to use for OpenAM. - -. Click `Providers` > `Authentication`. - -. Click `Lock & Edit` > `New`. - -. Enter the desired type in `Type as AgentAuthenticator`, provide a name, and click `OK`. - -. Click on the name of the agent authenticator you just created. - -. Use `OPTIONAL` for the control flag and save. - -. Click on `Providers` to display the Authentication Providers Table. - -. Click on `Default Authenticator`, use `OPTIONAL` for the control flag, and save. - -. Activate the changes once the default authenticator is done saving. -+ -You will need to restart the WebLogic Server to implement the changes. - -==== - - -[#weblogic-agents-multi-server] -=== Installing WebLogic Policy Agents in Multi-Server Domains - -In many WebLogic domains, the administration server provides a central point for controlling and managing the configuration of the managed servers that host protected applications. - -If WebLogic-managed-servers run on different hosts, you must create separate agent profiles and perform separate installations for each so that OpenAM can send notifications to the appropriate addresses. - -[#web-logic-agents-for-admin-and-managed-servers] -.To Install the Policy Agent on Administration & Managed Servers -==== -For multi-server WebLogic domains, install policy agent as follows: - -. If servers are on different hosts, create agent profiles for each server where you plan to install the policy agent. -+ -The steps are described under xref:#install-weblogic-agent[Installing the WebLogic Policy Agent]. - -. Prepare your protected web applications by adding the policy agent filter configuration as described in xref:#protect-weblogic-apps-after-agent-installation[To Protect Applications After Agent Installation]. - -. Use the `agentadmin` command to install the policy agent either interactively, or silently on each server in the domain. -+ - -* For interactive installation, prepare password files for the servers as described under xref:#install-weblogic-agent[Installing the WebLogic Policy Agent]. -+ -Then install the policy agent on the servers as described in xref:#install-agent-into-weblogic[To Install the Policy Agent into WebLogic]. - -* For silent installation, follow the instructions in xref:#silent-weblogic-agent-installation[Silent WebLogic Policy Agent Installation]. - - -. Start WebLogic, and then set up an authentication provider as described in xref:#configure-weblogic-agent[To Configure the WebLogic Policy Agent]. - -. On each server in the domain, deploy the policy agent `agentapp.war`. - -. On each managed server in the domain, update the classpath to include policy agent .jar files. -+ -In WebLogic Node Manager console, browse to Environment > Servers > __server__ > Server Start > Class Path, and then edit the classpath as in the following example, but all on a single line: -+ - -[source, shell] ----- -/path/to/j2ee_agents/weblogic_v10_agent/lib/agent.jar: -/path/to/j2ee_agents/weblogic_v10_agent/lib/openssoclientsdk.jar: -/path/to/j2ee_agents/weblogic_v10_agent/locale: -/path/to/j2ee_agents/weblogic_v10_agent/Agent_001/config: -$CLASSPATH ----- -+ -Replace the paths in the example with the actual paths for your domain. - -. Restart the managed servers. - -==== - - -[#uninstall-weblogic-agent] -=== Removing WebLogic Policy Agent Software - -Shut down the WebLogic server before you uninstall the policy agent. - -To remove the Java EE policy agent, use `agentadmin --uninstall`. You must provide the WebLogic configuration directory location. - -Uninstall does not remove the agent instance directory, but you can do so manually after removing the agent configuration from WebLogic. - - diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/jee-users-guide/chap-websphere.adoc b/openam-documentation/openam-doc-source/src/main/asciidoc/jee-users-guide/chap-websphere.adoc deleted file mode 100644 index da6c31bc11..0000000000 --- a/openam-documentation/openam-doc-source/src/main/asciidoc/jee-users-guide/chap-websphere.adoc +++ /dev/null @@ -1,367 +0,0 @@ -//// - The contents of this file are subject to the terms of the Common Development and - Distribution License (the License). You may not use this file except in compliance with the - License. - - You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the - specific language governing permission and limitations under the License. - - When distributing Covered Software, include this CDDL Header Notice in each file and include - the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL - Header, with the fields enclosed by brackets [] replaced by your own identifying - information: "Portions copyright [year] [name of copyright owner]". - - Copyright 2017 ForgeRock AS. - Portions Copyright 2024 3A Systems LLC. -//// - -:figure-caption!: -:example-caption!: -:table-caption!: - - -[#chap-websphere] -== Installing Java EE Agents in IBM WebSphere - -This chapter covers installation of the policy agent for IBM WebSphere. - -[#before-websphere-agent-install] -=== Before You Install - -Make sure OpenAM is installed and running, and that you can contact OpenAM from the system running the policy agent. Next, create a profile for your policy agent as described in xref:../jee-users-guide/chap-jee-agent-config.adoc#create-agent-profiles[Creating Agent Profiles]. To protect resources with the agent, create at least one policy as described in link:../../../openam/13/admin-guide/#chap-authz-policy[Configuring Policies, window=\_blank] in the __OpenAM Administration Guide__. Consider creating a simple policy, such as a policy that allows only authenticated users to access your resources in order to test your policy agent after installation. - -You must install WebSphere before you install the policy agent, and you must stop the server during installation. - -You must install a supported version of the Java runtime environment. Set the `JAVA_HOME` environment variable accordingly. The policy agent installer requires Java. - -[source, console] ----- -$ echo $JAVA_HOME -/path/to/java ----- -If you are using IBM Java, see xref:#install-with-ibm-jvm[To Install With IBM Java]. - -See the OpenAM __Installation Guide__ section, link:../../../openam/13/install-guide/#download-openam-software[Obtaining OpenAM Software, window=\_blank] to determine which version of the agent to download, and download the agent. Also verify the checksum of the file you download against the checksum posted on the download page. - -Unzip the file in the directory where you plan to install the J2EE policy agent. The agent you install stores its configuration and logs under this directory. - -When you unzip the policy agent, you find the following directories under the `j2ee_agents/websphere_v61_agent` directory. - -Despite the directory name, the policy agent supports multiple container versions. --- - -`bin`:: -The installation and configuration program `agentadmin`. For more details about the available command-line tools, see xref:tools-reference.adoc#tools-reference[Command-Line Tool Reference]. - -`config`:: -Configuration templates used by the `agentadmin` command during installation - -`data`:: -Not used - -`etc`:: -Configuration templates used during installation - -`installer-logs`:: -Location for log files written during installation - -`legal-notices`:: -Contains licensing information including third-party licenses - -`lib`:: -Shared libraries used by the Java EE policy agent - -`locale`:: -Property files used by the installation program - -`README`:: -README file containing platform and install information for the agent - --- - -[#install-with-ibm-jvm] -.To Install With IBM Java -==== -The WebSphere policy agent runs with IBM Java. To install the policy agent using IBM Java on platforms other than AIX, you must change the `agentadmin` script to use the IBM Java Cryptography Extensions (JCE). - -Note that line breaks and continuation marker (*\*) characters have been manually added to the following examples to aid display in the documentation. These are not required when editing the script file. - -. Open the file, `bin/agentadmin` for editing. - -. Remove the `if` statement surrounding the line defining the `AGENT_OPTS` environment variable for AIX platforms: -+ -Before: -+ - -[source, sh] ----- -if [ "$OS_TYPE" = "AIX" ]; then - AGENT_OPTS="-DamKeyGenDescriptor.provider=IBMJCE \ - -DamCryptoDescriptor.provider=IBMJCE \ - -DamRandomGenProvider=IBMJCE" -else - AGENT_OPTS= -fi ----- -+ -After: -+ - -[source, sh] ----- -AGENT_OPTS="-DamKeyGenDescriptor.provider=IBMJCE \ - -DamCryptoDescriptor.provider=IBMJCE \ - -DamRandomGenProvider=IBMJCE" ----- - -. Edit the line that calls the `AdminToolLauncher` to move the `$AGENT_OPTS` environment variable before the classpath is set: -+ -Before: -+ - -[source, sh] ----- -$JAVA_VM -classpath "$AGENT_CLASSPATH" $AGENT_OPTS \ - com.sun.identity.install.tools.launch.AdminToolLauncher $* ----- -+ -After: -+ - -[source, sh] ----- -$JAVA_VM $AGENT_OPTS -classpath "$AGENT_CLASSPATH" \ - com.sun.identity.install.tools.launch.AdminToolLauncher $* ----- - -. Save your work. -+ -You can now install the WebSphere policy agent with IBM Java as described in xref:#install-websphere-agent[Installing the WebSphere Policy Agent]. - -==== - - -[#install-websphere-agent] -=== Installing the WebSphere Policy Agent - -Complete the following procedures to install the policy agent. - -[#d0e6866] -.To Create the Agent Profile -==== -Regardless of whether you store configurations centrally in OpenAM or locally with your agents, the agent requires a profile so that it can connect to and communicate with OpenAM. - -. In the OpenAM console, browse to Realms > __Realm Name__ > Agents > J2EE, and then click the New... button in the Agent table. - -. Complete the web form using the following hints: -+ --- - -Name:: -The name for the agent profile used when you install the agent - -Password:: -Password the agent uses to authenticate to OpenAM - -Configuration:: -Centralized configurations are stored in the OpenAM configuration store. You can manage the centralized configuration through the OpenAM console. Local configurations are stored in a file alongside the agent. - -Server URL:: -The full URL to an OpenAM instance, or if OpenAM is deployed in a site configuration (behind a load balancer) then the site URL -+ -In centralized configuration mode, the Server URL is used to populate the agent profile for services, such as Login, Logout, Naming, and Cross Domain SSO. - -Agent URL:: -The URL to the J2EE agent application, such as `\http://www.example.com:8080/agentapp` -+ -In centralized configuration mode, the Agent URL is used to populate the Agent Profile for services, such as notifications. - --- - -==== - -[#d0e6918] -.To Create a Password File -==== - -. Create a text file containing only the password specified when creating the agent profile. -+ -UNIX example: -+ - -[source, console] ----- -$ echo password > /tmp/pwd.txt ----- -+ -Windows example: -+ - -[source, console] ----- -C:\> echo password > pwd.txt ----- - -. Protect the password file you create as appropriate for your operating system: -+ -UNIX example: -+ - -[source, console] ----- -$ chmod 400 /tmp/pwd.txt ----- -+ -Windows example: -+ -In Windows Explorer, right-click the created password file, for example `pwd.txt`, select Read-Only, and then click OK. - -==== - -[#install-agent-into-websphere] -.To Install the Policy Agent into WebSphere -==== - -. Shut down the WebSphere server where you plan to install the agent. - -. Make sure OpenAM is running. - -. Run `agentadmin --install` to install the agent. -+ -When you run the command, you will be prompted to read and accept the software license agreement for the agent installation. You can suppress the license agreement prompt by including the `--acceptLicence` parameter. The inclusion of the option indicates that you have read and accepted the terms stated in the license. To view the license agreement, open `/legal-notices/license.txt`. -+ - -[source, console] ----- -$ /path/to/j2ee_agents/websphere_v61_agent/bin/agentadmin --install \ - --acceptLicense -... ------------------------------------------------ -SUMMARY OF YOUR RESPONSES ------------------------------------------------ -Instance Config Directory : -/path/to/WebSphere/AppServer/profiles/AppSrv01/config/cells/wwwNode01Cell/ - nodes/wwwNode01/servers/server1 - -Instance Server name : server1 -WebSphere Install Root Directory : /path/to/WebSphere/AppServer -OpenAM server URL : http://openam.example.com:8080/openam -Agent URL : http://www.example.com:9080/agentapp -Agent Profile name : WebSphere Agent -Agent Profile Password file name : /tmp/pwd.txt - -... -SUMMARY OF AGENT INSTALLATION ------------------------------ -Agent instance name: Agent_001 -Agent Bootstrap file location: -/path/to/j2ee_agents/websphere_v61_agent/Agent_001/config/ - OpenSSOAgentBootstrap.properties -Agent Configuration file location -/path/to/j2ee_agents/websphere_v61_agent/Agent_001/config/ - OpenSSOAgentConfiguration.properties -Agent Audit directory location: -/path/to/j2ee_agents/websphere_v61_agent/Agent_001/logs/audit -Agent Debug directory location: -/path/to/j2ee_agents/websphere_v61_agent/Agent_001/logs/debug - - -Install log file location: -/path/to/j2ee_agents/websphere_v61_agent/installer-logs/audit/install.log -... ----- -+ -Upon successful completion, the installer updates the WebSphere configuration, copies the agent libraries to WebSphere's external library directory, and also sets up configuration and log directories for the agent. -+ - -[NOTE] -====== -If the agent is in a different domain than the server, refer to the __Administration Guide__ procedure, link:../../../openam/13/admin-guide/#chap-cdsso[Configuring Cross-Domain Single Sign On, window=\_blank]. -====== - -. Take note of the configuration files and log locations. -+ -Each agent instance that you install on the system has its own numbered configuration and logs directory. The first agent's configuration and logs are thus located under the directory `j2ee_agents/websphere_v61_agent/Agent_001/`: -+ --- - -`config/OpenSSOAgentBootstrap.properties`:: -Used to bootstrap the Java EE policy agent, allowing the agent to connect to OpenAM and download its configuration. - -`config/OpenSSOAgentConfiguration.properties`:: -Only used if you configured the Java EE policy agent to use local configuration. - -`logs/audit/`:: -Operational audit log directory, only used if remote logging to OpenAM is disabled. - -`logs/debug/`:: -Debug directory where the debug file resides. Useful in troubleshooting policy agent issues. - --- - -. If your policy agent configuration is not in the top-level realm (/), then you must edit config/OpenSSOAgentBootstrap.properties to identify the sub-realm that has your policy agent configuration. Find com.sun.identity.agents.config.organization.name and change the / to the path to your policy agent profile. This allows the policy agent to properly identify itself to the OpenAM server. - -. Restart the WebSphere server. - -==== - -[#protect-websphere-apps-after-agent-installation] -.To Protect Applications After Agent Installation -==== - -. (Optional) Deploy the `/path/to/j2ee_agents/websphere_v61_agent/etc/agentapp.war` agent application in WebSphere. -+ -The `agentapp.war` application is required to enable notifications. If you decide not to deploy the application, you may want to enable the `com.sun.identity.agents.config.load.interval` property to allow the agent to fetch configuration changes from OpenAM. - -. For each web application to protect, add the following filter to the application's `WEB-INF/web.xml` deployment descriptor, following the opening tag: -+ - -[source, xml] ----- - - Agent - Agent - OpenAM Policy Agent Filter - com.sun.identity.agents.filter.AmAgentFilter - - - Agent - /* - REQUEST - INCLUDE - FORWARD - ERROR - ----- -+ -You might also have to update additional configuration files. See the sample application located under `/path/to/j2ee_agents/websphere_v61_agent/sampleapp` for examples. - -. (Optional) If you have a policy configured, you can test your policy agent. For example, try to browse to a resource that your policy agent protects. You should be redirected to OpenAM to authenticate, for example, as user `demo`, password `changeit`. After you authenticate, OpenAM then redirects you back to the resource you tried to access. - -==== - - -[#silent-websphere-agent-installation] -=== Silent WebSphere Policy Agent Installation - -When performing a scripted, silent installation, use `agentadmin --install --saveResponse response-file` to create a response file for scripted installation. Then install silently using `agentadmin --install --acceptLicense --useResponse response-file`. - - -[#uninstall-websphere-agent] -=== Removing WebSphere Policy Agent Software - -Shut down the WebSphere server before you uninstall the policy agent. - -To remove the Java EE policy agent, use `agentadmin --uninstall`. You must provide the WebSphere configuration directory location. - -Uninstall does not remove the agent instance directory, but you can do so manually after removing the agent configuration from WebSphere. - - -[#websphere-network-deployment] -=== Notes About WebSphere Network Deployment - -When using WebSphere Application Server Network Deployment, you must install policy agents on the Deployment Manager, on each Node Agent, and on each Application Server. Installation requires that you stop and then restart the Deployment Manager, each Node Agent, and each Application Server in the Network Deployment. - -Before installation, synchronize each server configuration with the profile saved by the Deployment Manager using the `syncNode` command. After agent installation, copy the server configuration for each node stored in `server.xml` to the corresponding Deployment Manager profile. After you have synchronized the configurations, you must restart the Deployment Manager for the Network Deployment. - - diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/jee-users-guide/index.adoc b/openam-documentation/openam-doc-source/src/main/asciidoc/jee-users-guide/index.adoc index 55b6513775..a321c17a56 100644 --- a/openam-documentation/openam-doc-source/src/main/asciidoc/jee-users-guide/index.adoc +++ b/openam-documentation/openam-doc-source/src/main/asciidoc/jee-users-guide/index.adoc @@ -15,12 +15,12 @@ Portions Copyright 2024 3A Systems LLC. //// -= User's Guide += OpenAM J2EE Agents User's Guide :doctype: book :toc: :authors: Mark Craig, Gene Hirayama, Chris Lee :copyright: Copyright 2011-2017 ForgeRock AS. -:copyright: Portions Copyright 2024 3A Systems LLC. +:copyright: Portions Copyright 2024-2025 3A Systems LLC. :imagesdir: ../ :figure-caption!: @@ -34,9 +34,5 @@ include::./chap-about-jee-agents.adoc[] include::./chap-jee-agents-features.adoc[] include::./chap-jee-agent-config.adoc[] include::./chap-apache-tomcat.adoc[] -include::./chap-jboss-7.adoc[] include::./chap-jetty.adoc[] -include::./chap-weblogic.adoc[] -include::./chap-websphere.adoc[] include::./chap-troubleshooting.adoc[] -include::./tools-reference.adoc[] diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/jee-users-guide/tools-reference.adoc b/openam-documentation/openam-doc-source/src/main/asciidoc/jee-users-guide/tools-reference.adoc deleted file mode 100644 index 54cbb1ed1f..0000000000 --- a/openam-documentation/openam-doc-source/src/main/asciidoc/jee-users-guide/tools-reference.adoc +++ /dev/null @@ -1,173 +0,0 @@ -//// - The contents of this file are subject to the terms of the Common Development and - Distribution License (the License). You may not use this file except in compliance with the - License. - - You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the - specific language governing permission and limitations under the License. - - When distributing Covered Software, include this CDDL Header Notice in each file and include - the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL - Header, with the fields enclosed by brackets [] replaced by your own identifying - information: "Portions copyright [year] [name of copyright owner]". - - Copyright 2017 ForgeRock AS. - Portions Copyright 2024 3A Systems LLC. -//// - -:figure-caption!: -:example-caption!: -:table-caption!: - - -[#tools-reference] -== Command-Line Tool Reference - -[#agentadmin] -=== agentadmin — manage OpenAM Java EE policy agent installation - -==== Synopsis -`agentadmin` {options} - -[#d0e7311] -==== Description -This command manages OpenAM policy agent installations. The `agentadmin` command requires a Java runtime environment. - -[#d0e7319] -==== Options -The following options are supported. --- - -`--install`:: -Installs a new agent instance. - -+ -Usage: `agentadmin --install [--useResponse | --saveResponse file-name]` -+ -[open] -==== - -`--useResponse`:: -Use this option to install in silent mode by specifying all the responses in the __file-name__ file. When this option is used, `agentadmin` runs in non-interactive mode. - -`--saveResponse`:: -Use this option to save all the supplied responses in a response file specified by __file-name__. - -==== - -`--custom-install`:: -Installs a new agent instance, specifying additional configuration options such as the key used to encrypt passwords. - -+ -Usage: `agentadmin --custom-install [--useResponse | --saveResponse file-name]` -+ -[open] -==== - -`--useResponse`:: -Use this option to install in silent mode by specifying all the responses in the __file-name__ file. When this option is used, `agentadmin` runs in non-interactive mode. - -`--saveResponse`:: -Use this option to save all the supplied responses to the __file-name__ file. - -==== - -`--acceptLicense`:: -Auto-accepts the software license agreement. If this option is present on the command line with the `--install` or `--custom-install` option, the license agreement prompt is suppressed and the agent installation continues. To view the license agreement, open `/legal-notices/license.txt`. - -`--uninstall`:: -Uninstalls an existing agent instance. - -+ -Usage: `agentadmin --uninstall [--useResponse | --saveResponse file-name]` -+ -[open] -==== - -`--useResponse`:: -Use this option to uninstall in silent mode by specifying all the responses in the __file-name__ file. When this option is used, `agentadmin` runs in non-interactive mode. - -`--saveResponse`:: -Use this option to save all the supplied responses to the __file-name__ file. - -==== - -`--version`:: -Displays the version information. - -`--uninstallAll`:: -Uninstalls all the agent instances. - -`--migrate`:: -Migrate agent to newer version - -`--listAgents`:: -Displays details of all the configured agents. - -`--agentInfo`:: -Displays details of the agent corresponding to the specified __agent-id__. - -+ -Example: `agentadmin --agentInfo agent_001` - -`--encrypt`:: -Encrypts a given string. - -+ -Usage: `agentadmin --encrypt agent-instance password-file` -+ -[open] -==== - -__agent-instance__:: -Agent instance identifier. The encryption functionality requires the use of agent instance specific encryption key present in its configuration file. - -__password-file__:: -File containing the password to encrypt. - -==== - -`--getEncryptKey`:: -Generates an agent encryption key. - --- - -[#d0e7535] -==== Examples -The following example installs an Apache HTTP Server 2.2 interactively, where Apache HTTP Server has been installed under `/path/to/apache22`. - -[source, console] ----- -$ ./agentadmin --install --acceptLicense -... ------------------------------------------------ -SUMMARY OF YOUR RESPONSES ------------------------------------------------ -Apache Server Config Directory : /path/to/apache22/conf -OpenSSO server URL : http://openam.example.com:8080/openam -Agent URL : http://www.example.com:80 -Agent Profile name : Apache Web Agent -Agent Profile Password file name : /tmp/pwd.txt - -... -SUMMARY OF AGENT INSTALLATION ------------------------------ -Agent instance name: Agent_001 -Agent Bootstrap file location: -/path/to/web_agents/apache22_agent/Agent_001/config/ - OpenSSOAgentBootstrap.properties -Agent Configuration Tag file location -/path/to/web_agents/apache22_agent/Agent_001/config/ - OpenSSOAgentConfiguration.properties -Agent Audit directory location: -/path/to/web_agents/apache22_agent/Agent_001/logs/audit -Agent Debug directory location: -/path/to/web_agents/apache22_agent/Agent_001/logs/debug - - -Install log file location: -/path/to/web_agents/apache22_agent/installer-logs/audit/install.log -... ----- - - diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/reference/chap-config-ref.adoc b/openam-documentation/openam-doc-source/src/main/asciidoc/reference/chap-config-ref.adoc index 783965938d..2818a0f51b 100644 --- a/openam-documentation/openam-doc-source/src/main/asciidoc/reference/chap-config-ref.adoc +++ b/openam-documentation/openam-doc-source/src/main/asciidoc/reference/chap-config-ref.adoc @@ -1979,7 +1979,7 @@ Type of encryption keystore. Options include JCEKS, JKS, PKCS#11, and PKCS#12. D [NOTE] ====== -Before using a PKCS#11 keystore, make sure your Java runtime environment supports it. For more information, see the link:https://docs.oracle.com/javase/8/docs/technotes/guides/security/p11guide.html[JDK 8 PKCS#11 Reference Guide., window=\_blank] +Before using a PKCS#11 keystore, make sure your Java runtime environment supports it. For more information, see the link:https://docs.oracle.com/en/java/javase/11/security/pkcs11-reference-guide1.html[JDK 11 PKCS#11 Reference Guide., window=\_blank] ====== + `ssoadm` attribute: `openam-authenticator-oath-device-settings-encryption-keystore-type` @@ -2052,7 +2052,7 @@ Type of encryption keystore. Options include JCEKS, JKS, PKCS#11, and PKCS#12. [NOTE] ====== -Before using a PKCS#11 keystore, make sure your Java runtime environment supports it. For more information, see the link:https://docs.oracle.com/javase/8/docs/technotes/guides/security/p11guide.html[JDK 8 PKCS#11 Reference Guide., window=\_blank] +Before using a PKCS#11 keystore, make sure your Java runtime environment supports it. For more information, see the link:https://docs.oracle.com/en/java/javase/11/security/pkcs11-reference-guide1.html[JDK 11 PKCS#11 Reference Guide., window=\_blank] ====== + Default: `JKS`