diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-admin-tools.adoc b/openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-admin-tools.adoc index 8c2bbc6f78..4f284712b3 100644 --- a/openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-admin-tools.adoc +++ b/openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-admin-tools.adoc @@ -12,12 +12,13 @@ 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!: :example-caption!: :table-caption!: +:openam-version: 15.1.3 [#chap-admin-tools] @@ -82,19 +83,19 @@ Unpack this tool as part of policy agent installation. This tool lets you change OpenAM Administrator passwords, and display encrypted password values. + -Install this from the `SSOAdminTools-13.5.2.zip`. +Install this from the `SSOAdminTools-{openam-version}.zip`. `amverifyarchive`:: This tool checks log archives for tampering. + -Install this from `SSOAdminTools-13.5.2.zip`. +Install this from `SSOAdminTools-{openam-version}.zip`. -`openam-distribution-configurator-13.5.2.jar`:: +`openam-distribution-configurator-{openam-version}.jar`:: This executable `.jar` file lets you perform a silent installation of an OpenAM server with a configuration file. For example, the `java -jar configurator.jar -f config.file` command couples the `configurator.jar` archive with the __config.file__. The `sampleconfiguration` file provided with the tool is set up with the format for the `config.file`, and it must be adapted for your environment. + -Install this from `SSOConfiguratorTools-13.5.2.zip`. +Install this from `SSOConfiguratorTools-{openam-version}.zip`. `ssoadm`:: This tool provides a rich command-line interface for the configuration of OpenAM core services. @@ -103,7 +104,7 @@ This tool provides a rich command-line interface for the configuration of OpenAM In a test environment, you can activate `ssoadm.jsp` to access the same functionality in your browser. Once active, you can use many features of the `ssoadm` command by navigating to the `ssoadm.jsp` URI, in a URL, such as `\http://openam.example.com:8080/openam/ssoadm.jsp`. + -Install this from `SSOAdminTools-13.5.2.zip`. +Install this from `SSOAdminTools-{openam-version}.zip`. + To translate settings applied in OpenAM console to service attributes for use with `ssoadm`, log in to the OpenAM console as `amadmin` and access the services page, in a URL, such as `\http://openam.example.com:8080/openam/services.jsp`. diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-audit-logging.adoc b/openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-audit-logging.adoc index 261f4c9de8..12af24b9d9 100644 --- a/openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-audit-logging.adoc +++ b/openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-audit-logging.adoc @@ -18,6 +18,7 @@ :figure-caption!: :example-caption!: :table-caption!: +:openam-version: 15.1.3 [#chap-audit-logging] @@ -27,7 +28,7 @@ OpenAM supports a comprehensive Audit Logging Service that captures key auditing Audit logs gather operational information about events occurring within an OpenAM deployment to track processes and security data, such as authentication mechanisms, system access, user and administrator activity, error messages, and configuration changes. -This chapter describes the new, common REST-based Audit Logging Service available in OpenAM 13.5.2-15. OpenAM 13.5.2-15 also supports a legacy Logging Service, based on a Java SDK and available in OpenAM versions prior to OpenAM 13.5.2-15. The legacy Logging Service will be deprecated in a future release of OpenAM. +This chapter describes the new, common REST-based Audit Logging Service available in OpenAM {openam-version}. OpenAM {openam-version} also supports a legacy Logging Service, based on a Java SDK and available in OpenAM versions prior to OpenAM {openam-version}. The legacy Logging Service will be deprecated in a future release of OpenAM. The Audit Logging Service uses a structured message format that adheres to a consistent and documented log structure common across the Open Identity Platform stack, including OpenAM, OpenIDM, OpenDJ, and OpenIG. @@ -45,7 +46,7 @@ OpenAM's Audit Logging Service provides a versatile and rich feature set as foll * *Global and Realm-Based Log Configuration*. You can configure audit logging globally, which ensures that all realms inherit your global log settings. You can also configure audit logging by realm, which allows you to set different log settings for each realm. -* *Audit Event Handlers*. The Audit Logging Service supports a variety of audit event handlers that allow you to write logs to different types of data stores. See xref:#configuring-audit-event-handlers["Configuring Audit Event Handlers"] for a list of event handlers available in OpenAM 13.5.2-15. +* *Audit Event Handlers*. The Audit Logging Service supports a variety of audit event handlers that allow you to write logs to different types of data stores. See xref:#configuring-audit-event-handlers["Configuring Audit Event Handlers"] for a list of event handlers available in OpenAM {openam-version}. * *Audit Event Buffering*. By default, OpenAM writes each log message separately as they are generated. OpenAM supports message buffering, a type of batch processing, that stores log messages in memory and flushes the buffer after a preconfigured time interval or after a certain number of log messages reaches the configured threshold value. diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-cdsso.adoc b/openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-cdsso.adoc index 7356812950..6693e5cfa6 100644 --- a/openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-cdsso.adoc +++ b/openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-cdsso.adoc @@ -12,12 +12,13 @@ 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!: :example-caption!: :table-caption!: +:openam-version: 15.1.3 [#chap-cdsso] @@ -126,7 +127,7 @@ You can find this file where you deployed OpenAM, such as `/path/to/tomcat/webap + When you add an image or other presentation element, make sure that you retain the form and JavaScript as is. -. Unpack OpenAM-13.5.2.war, and replace the file with your modified version. +. Unpack OpenAM-{openam-version}.war, and replace the file with your modified version. + Also include any images you reference in the page. diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-federation.adoc b/openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-federation.adoc index 19f2f789c5..9d565f9799 100644 --- a/openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-federation.adoc +++ b/openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-federation.adoc @@ -18,6 +18,7 @@ :figure-caption!: :example-caption!: :table-caption!: +:openam-version: 15.1.3 [#chap-federation] @@ -407,12 +408,12 @@ Deploying the identity provider discovery service involves the following stages: ==== How you deploy the discovery service `.war` file depends on your web application container. The procedure in this section shows how to deploy on Apache Tomcat. -. Copy the `IDPDiscovery-13.5.2.war` file to the `webapps/` directory. +. Copy the `IDPDiscovery-{openam-version}.war` file to the `webapps/` directory. + -[source, console] +[source, console, subs="attributes"] ---- -$ cp ~/Downloads/openam/IDPDiscovery-13.5.2.war \ +$ cp ~/Downloads/openam/IDPDiscovery-{openam-version}.war \ /path/to/tomcat/webapps/disco.war ---- @@ -1560,7 +1561,7 @@ The following table provides information to help you decide whether to implement |=== |Deployment Task or Requirement |Implementation Mode -a|You are migrating an existing OpenAM SAML v2.0 deployment from OpenAM 12 (or earlier) to OpenAM 13.5.2-15. Note that all OpenAM SAML v2.0 deployments prior to OpenAM 13 are standalone mode deployments. +a|You are migrating an existing OpenAM SAML v2.0 deployment from OpenAM 12 (or earlier) to OpenAM {openam-version}. Note that all OpenAM SAML v2.0 deployments prior to OpenAM 13 are standalone mode deployments. a|Do not modify your deployment to integrated mode unless you want to change your authentication scenario to have SAML v2.0 authentication integrated into an OpenAM authentication chain. a|You want to deploy SAML v2.0 SSO and SLO using the easiest technique. @@ -2110,7 +2111,7 @@ Edit the source of the OpenAM Java Server Page, `saml2/jsp/autosubmitaccessright + When you add an image or other presentation element, make sure that you retain the form and Java code as is. -. Unpack OpenAM-13.5.2.war, and add your modified template files under `WEB-INF/classes/` where you unpacked the .war. +. Unpack OpenAM-{openam-version}.war, and add your modified template files under `WEB-INF/classes/` where you unpacked the .war. + Also include any images you reference in the page. 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 760af96b5e..9b072f5a12 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 @@ -12,12 +12,13 @@ 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!: :example-caption!: :table-caption!: +:openam-version: 15.1.3 [#chap-monitoring] @@ -149,7 +150,7 @@ To enable SNMP, see xref:#monitoring-snmp["SNMP Monitoring"] Once activated, SNMP monitoring works over UDP by default. You may want to install one of many available network monitoring tools. For the purpose of this section, basic SNMP service and monitoring tools have been installed on a GNU/Linux system. The same commands should work on a Mac OS X system. -SNMP depends on labels known as Object Identifiers (OIDs). These are uniquely defined labels, organized in tree format. For OpenAM, they are configured in a `.mib` file named `FORGEROCK-OPENAM-CTS.mib`, found inside the `/path/to/tomcat/webapps/openam/WEB-INF/lib/openam-mib-schema-13.5.2-15.jar` file of the OpenAM deployment. +SNMP depends on labels known as Object Identifiers (OIDs). These are uniquely defined labels, organized in tree format. For OpenAM, they are configured in a `.mib` file named `FORGEROCK-OPENAM-CTS.mib`, found inside the `/path/to/tomcat/webapps/openam/WEB-INF/lib/openam-mib-schema-{openam-version}.jar` file of the OpenAM deployment. For detailed information on configured OIDs, see xref:../reference/chap-cts-oids.adoc#chap-cts-oids["Core Token Service (CTS) Object Identifiers"] in the __Reference__. @@ -185,7 +186,7 @@ You can monitor policy evaluation performance over SNMP. OpenAM records statisti Interface Stability: link:#interface-stability[Evolving] -As described in xref:#cts-monitor-commands["CTS SNMP Monitoring"], SNMP uses OIDs defined in the `.mib` file, `FORGEROCK-OPENAM-POLICY.mib`, found inside the `/path/to/tomcat/webapps/openam/WEB-INF/lib/openam-mib-schema-13.5.2-15.jar` file of the OpenAM deployment. This file specifies the statistics OpenAM keeps for policy evaluation operations. Adapt the examples in xref:#cts-monitor-commands["CTS SNMP Monitoring"] to read monitoring statistics about policy evaluation on the command line. +As described in xref:#cts-monitor-commands["CTS SNMP Monitoring"], SNMP uses OIDs defined in the `.mib` file, `FORGEROCK-OPENAM-POLICY.mib`, found inside the `/path/to/tomcat/webapps/openam/WEB-INF/lib/openam-mib-schema-{openam-version}.jar` file of the OpenAM deployment. This file specifies the statistics OpenAM keeps for policy evaluation operations. Adapt the examples in xref:#cts-monitor-commands["CTS SNMP Monitoring"] to read monitoring statistics about policy evaluation on the command line. When monitoring is active, OpenAM records statistics about both the numbers and rates of policy evaluations performed, and also the times taken to process policy evaluations. @@ -260,7 +261,7 @@ SNMP monitoring is not available for stateless sessions. Interface Stability: link:#interface-stability[Evolving] -As described in xref:#cts-monitor-commands["CTS SNMP Monitoring"], SNMP uses OIDs defined in a `.mib` file that specifies the statistics OpenAM keeps for policy evaluation operations, the `FORGEROCK-OPENAM-SESSION.mib` file. This file is found inside the `/path/to/tomcat/webapps/openam/WEB-INF/lib/openam-mib-schema-13.5.2-15.jar` file of the OpenAM deployment. Adapt the examples in xref:#cts-monitor-commands["CTS SNMP Monitoring"] to read monitoring statistics about sessions on the command line. +As described in xref:#cts-monitor-commands["CTS SNMP Monitoring"], SNMP uses OIDs defined in a `.mib` file that specifies the statistics OpenAM keeps for policy evaluation operations, the `FORGEROCK-OPENAM-SESSION.mib` file. This file is found inside the `/path/to/tomcat/webapps/openam/WEB-INF/lib/openam-mib-schema-{openam-version}.jar` file of the OpenAM deployment. Adapt the examples in xref:#cts-monitor-commands["CTS SNMP Monitoring"] to read monitoring statistics about sessions on the command line. When monitoring is active, OpenAM records statistics about both the numbers of internal, remote, and CTS sessions, and also the times taken to process sessions. diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-radius.adoc b/openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-radius.adoc index 3aac1713e7..65504a068c 100644 --- a/openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-radius.adoc +++ b/openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-radius.adoc @@ -18,6 +18,7 @@ :figure-caption!: :example-caption!: :table-caption!: +:openam-version: 15.1.3 [#chap-radius] @@ -155,7 +156,7 @@ You can also configure the RADIUS Server service to log the packets sent between [#radius-troubleshooting-client] ==== Running the Sample RADIUS Client -The `openam-radius-server-13.5.2-15.jar` includes a sample client that you can use to test simple connectivity to the RADIUS Server service. +The `openam-radius-server-{openam-version}.jar` includes a sample client that you can use to test simple connectivity to the RADIUS Server service. The following procedure describes how to set up and run the sample client: @@ -193,9 +194,9 @@ show-traffic=true . Make sure that your current working directory is the directory in which you created the `radius.properties` file, then execute the sample client. Messages from the sample client indicate success or failure authenticating. If you specify `show-traffic=true` in the `radius.properties` file, the packets to and from the OpenAM RADIUS server appear in standard output: + -[source, console] +[source, console, subs="attributes"] ---- -$ java -jar //path/to/tomcat/webapps/openam/WEB-INF/lib/openam-radius-server-13.5.2-15.jar +$ java -jar //path/to/tomcat/webapps/openam/WEB-INF/lib/openam-radius-server-{openam-version}.jar ? Username: demo ? Password: changeit Packet To openam.example.com:1812 diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-realms.adoc b/openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-realms.adoc index c819f66d89..4ba304dd17 100644 --- a/openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-realms.adoc +++ b/openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-realms.adoc @@ -12,12 +12,13 @@ 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!: :example-caption!: :table-caption!: +:openam-version: 15.1.3 [#chap-realms] @@ -93,7 +94,7 @@ Delegating administration privileges in the top-level realm allows members of th * (Optional) To grant users in the group access to the administration console for the realm, select Read and write access to all realm and policy properties. + -In OpenAM 13.5.2-15, administrators can use the OpenAM administration console as follows: +In OpenAM {openam-version}, administrators can use the OpenAM administration console as follows: + ** Delegated administrators with the `RealmAdmin` privilege can access full administration console functionality within the realms they can administer. diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-saml-1.adoc b/openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-saml-1.adoc index 3009364f31..37f491aa19 100644 --- a/openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-saml-1.adoc +++ b/openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-saml-1.adoc @@ -12,12 +12,13 @@ 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!: :example-caption!: :table-caption!: +:openam-version: 15.1.3 [#chap-saml-1] @@ -163,12 +164,12 @@ If you have multiple servers in an OpenAM site set up behind a load balancer, yo This example is for an asserting party where the site load balancer host is `ap.example.net`. The command is bundled with OpenAM server, shown with lines folded to fit on the printed page: + -[source, console] +[source, console, subs="attributes"] ---- $ cd /path/to/tomcat/webapps/openam/WEB-INF/lib/ $ java \ - -cp forgerock-util-20.0.0.jar:openam-shared-13.5.2.jar:\ - openam-federation-library-13.5.2.jar com.sun.identity.saml.common.SAMLSiteID \ + -cp forgerock-util-20.0.0.jar:openam-shared-{openam-version}.jar:\ + openam-federation-library-{openam-version}.jar com.sun.identity.saml.common.SAMLSiteID \ https://ap.example.net/openam 9BAg4UmVS6IbjccsSj9gAFYGO9Y= ---- 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 b2c39d2625..4b1940bceb 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 @@ -18,7 +18,7 @@ :figure-caption!: :example-caption!: :table-caption!: - +:openam-version: 15.1.3 [#chap-sts] == Configuring the Security Token Service @@ -1403,10 +1403,10 @@ $ mvn install .. Copy the SOAP STS server `.war` file to the deployment directory: + -[source, console] +[source, console, subs="attributes"] ---- $ cd target -$ cp openam-soap-sts-server-13.5.2.war /path/to/openam/soapstsdeployment +$ cp openam-soap-sts-server-{openam-version}.war /path/to/openam/soapstsdeployment ---- diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-troubleshooting.adoc b/openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-troubleshooting.adoc index 6e680a6e3c..0b0925eaa7 100644 --- a/openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-troubleshooting.adoc +++ b/openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-troubleshooting.adoc @@ -12,12 +12,13 @@ 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!: :example-caption!: :table-caption!: +:openam-version: 15.1.3 [#chap-troubleshooting] @@ -43,13 +44,13 @@ mark 1739 1 0 14:47... ---- For a container installed from native packages with a dedicated user, $HOME may not be where you think it is. Look at the user's entry in `/etc/passwd` to locate the home directory. The user running the web container where you install OpenAM must be able to read from and write in this directory. -If you cannot change the permissions to the user's home directory, you can, as a workaround, unpack `OpenAM-13.5.2.war`, set the `configuration.dir` property in the `WEB-INF/classes/bootstrap.properties` to a directory with appropriate permissions, and repack `openam.war` with the adjusted file before deploying that: +If you cannot change the permissions to the user's home directory, you can, as a workaround, unpack `OpenAM-{openam-version}.war`, set the `configuration.dir` property in the `WEB-INF/classes/bootstrap.properties` to a directory with appropriate permissions, and repack `openam.war` with the adjusted file before deploying that: -[source, console] +[source, console, subs="attributes"] ---- -$ cd ~/Downloads/openam/OpenAM-13.5.2.war +$ cd ~/Downloads/openam/OpenAM-{openam-version}.war $ mkdir unpacked ; cd unpacked -$ jar xf ../OpenAM-13.5.2.war +$ jar xf ../OpenAM-{openam-version}.war $ vi WEB-INF/classes/bootstrap.properties $ grep ^config WEB-INF/classes/bootstrap.properties configuration.dir=/my/readwrite/config/dir diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-usr-selfservices.adoc b/openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-usr-selfservices.adoc index abdd06d9e6..a0fcbf70b7 100644 --- a/openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-usr-selfservices.adoc +++ b/openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-usr-selfservices.adoc @@ -12,12 +12,13 @@ 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!: :example-caption!: :table-caption!: +:openam-version: 15.1.3 [#chap-usr-selfservices] @@ -27,7 +28,7 @@ OpenAM provides user self-service features that enable your customers to self-re [NOTE] ==== -The Password Reset service, located on the OpenAM console at Configure > Global Services, is deprecated for OpenAM 13.5.2-15 and will no longer be supported in a future OpenAM release. +The Password Reset service, located on the OpenAM console at Configure > Global Services, is deprecated for OpenAM {openam-version} and will no longer be supported in a future OpenAM release. ==== [#about-user-self-service] 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 5a3372a56b..7ca2a0364e 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 @@ -18,6 +18,7 @@ :figure-caption!: :example-caption!: :table-caption!: +:openam-version: 15.1.3 [#chap-intro] @@ -82,31 +83,31 @@ OpenAM core server can be deployed and integrated within existing network infras |=== |Distribution |Description -a|ClientSDK-13.5.2-15.jar +a|ClientSDK-{openam-version}.jar a|OpenAM's default distribution `.war` file includes the core server code with an embedded OpenDJ directory server, which stores configuration data and simplifies deployments. The distribution includes an administrative graphical user interface (GUI) Web console. During installation, the `.war` file accesses a bootstrap file to obtain the fully qualified domain name, port, context path, and the location of the configuration folder. OpenAM provides a client SDK for developers to code extensions for their web applications to access OpenAM's services. The client SDK contains the Java packages, classes, property files, and sample code to help you develop your code. -a|ExampleClientSDK-CLI-13.5.2-15.zip +a|ExampleClientSDK-CLI-{openam-version}.zip a|OpenAM provides client SDK examples to help you run them on OpenAM. The `zip` distribution file contains setup scripts and samples that you can run to learn how to use the client SDK. -a|ExampleClientSDK-WAR-13.5.2-15.war +a|ExampleClientSDK-WAR-{openam-version}.war a|The example client SDK also comes in a `.war` file, which installs on your container. -a|Fedlet-13.5.2-15.zip +a|Fedlet-{openam-version}.zip a|OpenAM provides a core server-only `.war` file without the OpenAM Console. This setup is often used in multi-server deployments wherein the deployments is managed using a full server instance using the `ssoadm` command-line tool. The OpenAM server installs with an embedded OpenDJ directory server. OpenAM provides an OpenAM Fedlet, a light-weight SAML v2.0 service provider. The Fedlet lets you set up a federated deployment without the need of a fully-featured service provider. -a|IDPDiscovery-13.5.2-15.war +a|IDPDiscovery-{openam-version}.war a|OpenAM provides an IdP Discovery Profile (SAMLv2 binding profile) for its IdP Discovery service. The profile keeps track of the identity providers for each user. -a|OpenAM-13.5.2-15.war +a|OpenAM-{openam-version}.war a|OpenAM provides a smaller subset of the OpenAM SDK, providing client-side API to OpenAM services. The Client SDK allows you to write remote standalone or Web applications to access OpenAM and run its core services. OpenAM's distribution `.war` file includes the core server code with an embedded OpenDJ directory server, which stores configuration data and simplifies deployments. The distribution includes an administrative graphical user interface (GUI) Web console. During installation, the `.war` file accesses properties to obtain the fully qualified domain name, port, context path, and the location of the configuration folder. These properties can be obtained from the `boot.properties` file in the OpenAM installation directory, from environment variables, or from a combination of the two. -a|openam-soap-sts-server-13.5.2-15.war +a|openam-soap-sts-server-{openam-version}.war a|OpenAM provides a SOAP-based security token service (STS) server that issues tokens based on the WS-Security protocol. -a|SSOAdminTools-13.5.2-15.zip +a|SSOAdminTools-{openam-version}.zip a|OpenAM provides an `ssoadm` command-line tool that allows administrators to configure and maintain OpenAM as well as create their own configuration scripts. The `zip` distribution file contains binaries, properties file, script templates, and setup scripts for UNIX and windows servers. -a|SSOConfiguratorTools-13.5.2-15.zip +a|SSOConfiguratorTools-{openam-version}.zip a|OpenAM provides configuration and upgrade tools for installing and maintaining your server. The `zip` distribution file contains libraries, legal notices, and supported binaries for these configuration tools. Also, you can view example configuration and upgrade properties files that can be used as a template for your deployments. |=== @@ -165,8 +166,13 @@ In February 2010, a small group of former Sun employees founded ForgeRock to con * 2014: OpenAM 11.1 and 12.0 -ForgeRock continues to develop, enhance, and support the industry-leading OpenAM product to meet the changing and growing demands of the market. +* In November 2016 ForgeRock closed OpenAM source code, renamed OpenAM to ForgeRock Access Management, and began distributing source code under a paid, commercial license. + +* Since November 2016, the Open Identity Platform Community continued to support the OpenAM Product. + +* 2016: OpenAM 14 + +* 2025: OpenAM 15 -ForgeRock also took over responsibility for support and development of the OpenDS directory server, which was renamed as OpenDJ. ForgeRock plans to continue to maintain, enhance, and support OpenDJ. diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/dev-guide/appendix-deprecated-apis.adoc b/openam-documentation/openam-doc-source/src/main/asciidoc/dev-guide/appendix-deprecated-apis.adoc index 5f41f393c3..9d4a8be76d 100644 --- a/openam-documentation/openam-doc-source/src/main/asciidoc/dev-guide/appendix-deprecated-apis.adoc +++ b/openam-documentation/openam-doc-source/src/main/asciidoc/dev-guide/appendix-deprecated-apis.adoc @@ -12,19 +12,20 @@ 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!: :example-caption!: :table-caption!: +:openam-version: 15.1.3 [appendix] [#appendix-deprecated-apis] == Deprecated REST APIs -This appendix provides information about REST APIs deprecated in OpenAM 13.5.2-15. +This appendix provides information about REST APIs deprecated in OpenAM {openam-version}. [#deprecated-session-apis-auth] === Deprecated Session Information APIs diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/dev-guide/chap-client-dev.adoc b/openam-documentation/openam-doc-source/src/main/asciidoc/dev-guide/chap-client-dev.adoc index e29231fce3..c23a85503c 100644 --- a/openam-documentation/openam-doc-source/src/main/asciidoc/dev-guide/chap-client-dev.adoc +++ b/openam-documentation/openam-doc-source/src/main/asciidoc/dev-guide/chap-client-dev.adoc @@ -12,12 +12,13 @@ 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!: :example-caption!: :table-caption!: +:openam-version: 15.1.3 [#chap-client-dev] @@ -43,7 +44,7 @@ As an architectural style, REST has very broad applications. The designs of both Open Identity Platform Common REST (CREST) applies RESTful principles to define common verbs for HTTP-based APIs that access web resources and collections of web resources. -Native OpenAM REST APIs in version 11.0.0 and later use the CREST verbs. (In contrast, OAuth 2.0, OpenID Connect 1.0 and UMA 1.0 APIs follow their respective standards.) APIs covered in link:../dev-guide/index.html#appendix-deprecated-apis[Deprecated REST APIs] predate CREST, do not use the CREST verbs, and are deprecated in OpenAM 13.5.2-15. +Native OpenAM REST APIs in version 11.0.0 and later use the CREST verbs. (In contrast, OAuth 2.0, OpenID Connect 1.0 and UMA 1.0 APIs follow their respective standards.) APIs covered in link:../dev-guide/index.html#appendix-deprecated-apis[Deprecated REST APIs] predate CREST, do not use the CREST verbs, and are deprecated in OpenAM {openam-version}. When using a CREST API, you use the common verbs as query string parameters in resource and resource collection URIs. -- @@ -168,17 +169,17 @@ Any changes to the methods used to make REST API calls will incur a __protocol__ [#rest-api-versioning-supported-versions] ===== Supported REST API Versions -The REST API version numbers supported in OpenAM 13.5.2-15 are as follows: +The REST API version numbers supported in OpenAM {openam-version} are as follows: -- __Supported protocol versions__:: -The __protocol__ versions supported in OpenAM 13.5.2-15 are: +The __protocol__ versions supported in OpenAM {openam-version} are: + [none] * `1.0` __Supported resource versions__:: -The __resource__ versions supported in OpenAM 13.5.2-15 are shown in the following table. +The __resource__ versions supported in OpenAM {openam-version} are shown in the following table. + [#rest-api-supported-resource-versions] @@ -1307,7 +1308,7 @@ http://openam.example.com:8080/openam/json/users?_action=validateGoto [#rest-api-logging] ==== Logging -OpenAM 13.5.2-15 supports two Audit Logging Services: a new common REST-based Audit Logging Service, and the legacy Logging Service, which is based on a Java SDK and is available in OpenAM versions prior to OpenAM 13. The legacy Logging Service is deprecated in OpenAM 13.5.2-15. +OpenAM {openam-version} supports two Audit Logging Services: a new common REST-based Audit Logging Service, and the legacy Logging Service, which is based on a Java SDK and is available in OpenAM versions prior to OpenAM 13. The legacy Logging Service is deprecated in OpenAM {openam-version}. Both audit facilities log OpenAM REST API calls. @@ -9065,12 +9066,12 @@ If there is an active recording event, output similar to the following appears: [#sec-sdk] === Using the OpenAM Java SDK -This section introduces OpenAM Java SDK. OpenAM Java SDK is delivered with the full version of OpenAM, `OpenAM-13.5.2.zip`. +This section introduces OpenAM Java SDK. OpenAM Java SDK is delivered with the full version of OpenAM, `OpenAM-{openam-version}.zip`. [#install-sdk-samples] ==== Installing OpenAM Client SDK Samples -The full OpenAM download, `OpenAM-13.5.2.zip`, contains the Java Client SDK library, `ClientSDK-13.5.2.jar`, as well as samples for use on the command line in `ExampleClientSDK-CLI-13.5.2.zip`, and samples in a web application, `ExampleClientSDK-WAR-13.5.2.war`. The link:../apidocs[OpenAM Java SDK API Specification, window=\_blank] provides a reference to the public APIs. +The full OpenAM download, `OpenAM-{openam-version}.zip`, contains the Java Client SDK library, `ClientSDK-{openam-version}.jar`, as well as samples for use on the command line in `ExampleClientSDK-CLI-{openam-version}.zip`, and samples in a web application, `ExampleClientSDK-WAR-{openam-version}.war`. The link:../apidocs[OpenAM Java SDK API Specification, window=\_blank] provides a reference to the public APIs. [#deploy-client-sdk-war] .To Deploy the Sample Web Application @@ -9082,7 +9083,7 @@ The sample web application deploys in your container to show you the client SDK [source, console] ---- -$ cp ExampleClientSDK-WAR-13.5.2.war /path/to/tomcat/webapps/client.war +$ cp ExampleClientSDK-WAR-{openam-version}.war /path/to/tomcat/webapps/client.war ---- . If you have run this procedure before, make sure to deploy a fresh copy of the .war file to a different location, such as `/path/to/tomcat/webapps/client1.war` @@ -9156,10 +9157,10 @@ Follow these steps to set up the command-line examples. . Unpack the sample applications and related libraries. + -[source, console] +[source, console, subs="attributes"] ---- $ mkdir sdk && cd sdk -$ unzip ~/Downloads/ExampleClientSDK-CLI-13.5.2.zip +$ unzip ~/Downloads/ExampleClientSDK-CLI-{openam-version}.zip ---- . Configure the samples to access OpenAM. diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/dev-guide/chap-customizing.adoc b/openam-documentation/openam-doc-source/src/main/asciidoc/dev-guide/chap-customizing.adoc index b2befabd0e..4bdcd0b318 100644 --- a/openam-documentation/openam-doc-source/src/main/asciidoc/dev-guide/chap-customizing.adoc +++ b/openam-documentation/openam-doc-source/src/main/asciidoc/dev-guide/chap-customizing.adoc @@ -18,6 +18,7 @@ :figure-caption!: :example-caption!: :table-caption!: +:openam-version: 15.1.3 [#chap-customizing] @@ -36,7 +37,7 @@ Adding a custom attribute involves both updating the `iPlanetAMUserService`, and [IMPORTANT] ==== -In OpenAM 13.5.2-15, the ability to edit custom profile attributes is limited to the classic UI. Custom profile attributes do not appear in the user profile when users log in to OpenAM using the XUI. +In OpenAM {openam-version}, the ability to edit custom profile attributes is limited to the classic UI. Custom profile attributes do not appear in the user profile when users log in to OpenAM using the XUI. ==== This section includes the following procedures. @@ -1282,12 +1283,12 @@ org.forgerock.openam.examples.quotaexhaustionaction.SampleQuotaExhaustionAction Choice Values were set. ---- -Extract `amSession.properties` and if necessary the localized versions of this file from `openam-core-13.5.2.jar` to `WEB-INF/classes/` where OpenAM is deployed. For example, if OpenAM is deployed under `/path/to/tomcat/webapps/openam`, then you could run the following commands. +Extract `amSession.properties` and if necessary the localized versions of this file from `openam-core-{openam-version}.jar` to `WEB-INF/classes/` where OpenAM is deployed. For example, if OpenAM is deployed under `/path/to/tomcat/webapps/openam`, then you could run the following commands. -[source, console] +[source, console, subs="attributes"] ---- $ cd /path/to/tomcat/webapps/openam/WEB-INF/classes/ -$ jar -xvf ../lib/openam-core-13.5.2.jar amSession.properties +$ jar -xvf ../lib/openam-core-{openam-version}.jar amSession.properties inflated: amSession.properties ---- Add the following line to `amSession.properties`. @@ -1418,7 +1419,7 @@ For information on downloading and building OpenAM sample source code, see link: . Build the module using Apache Maven: + -[source, console] +[source, console, subs="attributes"] ---- $ cd /path/to/openam-source/openam-samples $ cd policy-evaluation-plugin @@ -1426,7 +1427,7 @@ $ mvn install [INFO] Scanning for projects... [INFO] [INFO] ------------------------------------------------------------------------ -[INFO] Building policy-evaluation-plugin 13.5.2-15 +[INFO] Building policy-evaluation-plugin {openam-version} [INFO] ------------------------------------------------------------------------ [INFO] [INFO] --- maven-resources-plugin:2.6:resources (default-resources) @ @@ -1434,7 +1435,7 @@ $ mvn install ... -[INFO] Building jar: .../target/policy-evaluation-plugin-13.5.2-15.jar +[INFO] Building jar: .../target/policy-evaluation-plugin-{openam-version}.jar [INFO] ... @@ -2010,7 +2011,7 @@ The `IdOperation.SERVICE` operation is rarely used in recent OpenAM deployments. [#idrepo-plugin-deployment] ==== Identity Repository Plugin Deployment -When you build your IdRepo plugin, include `openam-core-13.5.2.jar` in the classpath. This file is found under `WEB-INF/lib/` where OpenAM is deployed. +When you build your IdRepo plugin, include `openam-core-{openam-version}.jar` in the classpath. This file is found under `WEB-INF/lib/` where OpenAM is deployed. You can either package your plugin as a .jar, and then add it to `WEB-INF/lib/`, or add the classes under `WEB-INF/classes/`. @@ -2047,12 +2048,12 @@ Also include the `AttributeSchema` required to configure your IdRepo plugin. Notice the `i18nKey` attributes on `SubSchema` elements. The `i18nKey` attribute values correspond to properties in the `amIdRepoService.properties` file under `WEB-INF/classes/` where OpenAM is deployed. OpenAM console displays the label for the configuration user interface that it retrieves from the value of the `i18nKey` property in the `amIdRepoService.properties` file. -To make changes to the properties, first extract `amIdRepoService.properties` and if necessary the localized versions of this file from `openam-core-13.5.2.jar` to `WEB-INF/classes/` where OpenAM is deployed. For example, if OpenAM is deployed under `/path/to/tomcat/webapps/openam`, then you could run the following commands. +To make changes to the properties, first extract `amIdRepoService.properties` and if necessary the localized versions of this file from `openam-core-{openam-version}.jar` to `WEB-INF/classes/` where OpenAM is deployed. For example, if OpenAM is deployed under `/path/to/tomcat/webapps/openam`, then you could run the following commands. -[source, console] +[source, console, subs="attributes"] ---- $ cd /path/to/tomcat/webapps/openam/WEB-INF/classes/ -$ jar -xvf ../lib/openam-core-13.5.2.jar amIdRepoService.properties +$ jar -xvf ../lib/openam-core-{openam-version}.jar amIdRepoService.properties inflated: amIdRepoService.properties ---- Register your plugin using the `ssoadm` command after copy the files into place. diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/dev-guide/chap-fedlets.adoc b/openam-documentation/openam-doc-source/src/main/asciidoc/dev-guide/chap-fedlets.adoc index 0615dd60d5..598233c3d2 100644 --- a/openam-documentation/openam-doc-source/src/main/asciidoc/dev-guide/chap-fedlets.adoc +++ b/openam-documentation/openam-doc-source/src/main/asciidoc/dev-guide/chap-fedlets.adoc @@ -12,12 +12,13 @@ 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!: :example-caption!: :table-caption!: +:openam-version: 15.1.3 [#chap-fedlets] @@ -108,15 +109,15 @@ $ mkdir fedlet . Move all the files under `$HOME/fedlet/conf` to `$HOME/fedlet`. -. Obtain the `Fedlet-13.5.2.zip` file from the full OpenAM distribution file, `OpenAM-13.5.2.zip`. +. Obtain the `Fedlet-{openam-version}.zip` file from the full OpenAM distribution file, `OpenAM-{openam-version}.zip`. -. Unzip the `Fedlet-13.5.2.zip` file: +. Unzip the `Fedlet-{openam-version}.zip` file: + -[source, console] +[source, console, subs="attributes"] ---- $ cd /path/to/openam-distribution/openam -$ unzip Fedlet-13.5.2.zip +$ unzip Fedlet-{openam-version}.zip ---- + @@ -1073,7 +1074,7 @@ Another JSP file, `fedletXACMLResp.jsp`, sends the query to the XACML PDP using An OpenAM Fedlet is a small web application that makes it easy to add SAML v2.0 Service Provider (SP) capabilities to your Java web application. The OpenAM console offers a wizard for configuring a Java Fedlet as a SAML v2.0 Service Provider with OpenAM as the Identity Provider (IDP). If that fits your purposes, then read the chapter xref:#sec-fedlet-java["Using Fedlets in Java Web Applications"] instead. -The full distribution file, `OpenAM-13.5.2.zip`, also includes a Java Fedlet, `Fedlet-13.5.2.zip`, that you can configure by hand. This chapter covers how to configure a Java Fedlet using that distribution, by manually editing the Circle of Trust, Java properties, and IDP and SP XML configuration templates. +The full distribution file, `OpenAM-{openam-version}.zip`, also includes a Java Fedlet, `Fedlet-{openam-version}.zip`, that you can configure by hand. This chapter covers how to configure a Java Fedlet using that distribution, by manually editing the Circle of Trust, Java properties, and IDP and SP XML configuration templates. Seen from a high level, what you must do is this: * Determine the roles that the IDP(s) and Fedlet play in SAML v2.0 Circles of Trust. @@ -1100,15 +1101,15 @@ An IDP relies on the standard SAML v2.0 metadata to communicate with the Fedlet. Unpack the Java Fedlet distribution into a working directory. -[source, console] +[source, console, subs="attributes"] ---- $ mkdir fedlet && cd fedlet -$ unzip ../Fedlet-13.5.2.zip +$ unzip ../Fedlet-{openam-version}.zip ---- -- -When you unpack the `Fedlet-13.5.2.zip` file, you find the following files. +When you unpack the `Fedlet-{openam-version}.zip` file, you find the following files. -`Fedlet-13.5.2.war`:: +`Fedlet-{openam-version}.war`:: This file contains a Java Fedlet web application that serves as an example, and that you can embed in your applications. `README`:: @@ -2057,7 +2058,7 @@ Default: `fedletcot` [#unconfigured-fedlet-embedding] ==== Embedding the Java Fedlet in a Web Application -The Fedlet war file, `Fedlet-13.5.2.war`, serves both as an example and also to provide the code needed to embed the Fedlet in your web application. +The Fedlet war file, `Fedlet-{openam-version}.war`, serves both as an example and also to provide the code needed to embed the Fedlet in your web application. The basic steps for using the Fedlet in your application are as follows. * Unpack the Fedlet war file to a working directory, remove any files you do not want to keep such as `index.jsp` or `fedletEncode.jsp`, and overlay the Fedlet files with those of your web application. diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/dev-guide/chap-sts.adoc b/openam-documentation/openam-doc-source/src/main/asciidoc/dev-guide/chap-sts.adoc index e2b7244084..94116a5218 100644 --- a/openam-documentation/openam-doc-source/src/main/asciidoc/dev-guide/chap-sts.adoc +++ b/openam-documentation/openam-doc-source/src/main/asciidoc/dev-guide/chap-sts.adoc @@ -12,12 +12,13 @@ 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!: :example-caption!: :table-caption!: +:openam-version: 15.1.3 [#chap-sts] @@ -554,7 +555,7 @@ The SOAP STS client SDK is not part of the OpenAM client SDK. footnote:d15472e21 . Run the `mvn install` command. -. Locate the `openam-soap-sts-client-13.5.2-15.jar` file in the `openam-sts/openam-soap-sts/openam-soap-sts-client/target` directory. +. Locate the `openam-soap-sts-client-{openam-version}.jar` file in the `openam-sts/openam-soap-sts/openam-soap-sts-client/target` directory. ==== diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/getting-started/chap-first-steps.adoc b/openam-documentation/openam-doc-source/src/main/asciidoc/getting-started/chap-first-steps.adoc index 2566b7408d..877ea52755 100644 --- a/openam-documentation/openam-doc-source/src/main/asciidoc/getting-started/chap-first-steps.adoc +++ b/openam-documentation/openam-doc-source/src/main/asciidoc/getting-started/chap-first-steps.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!: @@ -25,17 +25,10 @@ This guide shows you how to quickly set up OpenAM and get started with access management. In reading and following the instructions in this guide, you will learn how to protect a Web page using OpenAM and a Web policy agent. -[IMPORTANT] -==== -You need a Linux, Solaris, or Windows system that can run the OpenAM Web policy agent with a minimum of 1 GB of available RAM memory, a few hundred MB of free disk space, a web browser, and an Internet connection to download software. - -If you are using Mac OS X, set up a virtual machine running Linux to try these procedures because the web policy agent is not built for Apache HTTP Server on Mac OS X. -==== - [#how-openam-helps-manage-access] === About OpenAM -OpenAM provides a service called __access management__, which manages access to resources, such as a web page, an application, or web service, available over the network. Once it is set up, OpenAM provides an infrastructure for managing users, roles, and access to resources. In this chapter, you manage access to a single web page. +OpenAM provides a service called __access management__, which manages access to resources, such as a web page, an application, or a web service, available over the network. Once it is set up, OpenAM provides an infrastructure for managing users, roles, and access to resources. In this chapter, you manage access to a single web page. OpenAM centralizes access control by handling both __authentication__ and __authorization__. Authentication is the process of identifying an individual, for example, by confirming a successful login. Authorization is the process of granting access to resources to authenticated individuals. @@ -51,31 +44,11 @@ The rest of this chapter has you demonstrate OpenAM access management by install [#software-you-need] === Software Requirements To Try Out OpenAM -This chapter shows you how to install the software OpenAM needs to protect a web page. You will learn how to install Apache HTTP Server, Apache Tomcat, OpenAM core server with OpenAM Console, and OpenAM Apache Policy Agent. Installation instructions for Java Development Kit (JDK) are not included in this chapter, as OpenAM is a Java web application, and the JDK is pre-installed. - -* Java Development Kit -+ -OpenAM is a Java web application, and requires a Java Development Kit installed on the system where it runs. -+ -The OpenAM web policy agent installer is also a Java program. - -* Apache HTTP Server -+ -Apache HTTP Server serves the web page OpenAM protects. - -* Apache Tomcat -+ -Because OpenAM is a Java web application, it runs in a web container, in this case, Apache Tomcat. - -* OpenAM core server with OpenAM Console -+ -This is the main web application for OpenAM. OpenAM sets up an OpenDJ directory server at configuration time to use, in this case, to hold OpenAM's configuration and to serve as an identity store and authentication service. +The only software you need to install is Docker. If you don't have Docker on your computer follow the instructions from the following link: link:https://docs.docker.com/get-started/get-docker/#supported-platforms[https://docs.docker.com/get-started/get-docker/#supported-platforms, target=_blank]. -* OpenAM Apache Policy Agent -+ -Install a policy agent in Apache HTTP Server to intercept requests from users and enforce access policy decisions OpenAM makes. The policy agent intercepts requests from users, and enforces access policy decisions made by OpenAM. The policy agent enforces policy by redirecting users to OpenAM for authentication and by contacting OpenAM to get authorization decisions for resources, such as the web page to protect. +You will learn how to run OpenAM docker container, and how to install OpenAM Apache Policy Agent for the Apache HTTP Server. -Follow the steps in the following sections of this chapter to learn how OpenAM protects a web site without changing the web site itself. +''' [#software-setup] @@ -85,11 +58,9 @@ This section includes the following procedures that detail how to set up OpenAM * xref:#prepare-etc-hosts["To Prepare Your Hosts File"] -* xref:#install-apache-http["To Install Apache HTTP Server"] +* xref:#install-openam["To Run OpenAM Docker Image"] -* xref:#install-apache-tomcat["To Install Apache Tomcat"] - -* xref:#install-openam["To Install OpenAM"] +* xref:#configure-cookie-domain[To Configure Cookie Domain in OpenAM] * xref:#configure-policy["To Configure a Policy in OpenAM"] @@ -101,6 +72,7 @@ The procedures in this section are written for use on a Linux system. If you are [#prepare-etc-hosts] .To Prepare Your Hosts File + ==== OpenAM requires that you use fully qualified domain names when protecting web resources. This is because OpenAM uses link:http://en.wikipedia.org/wiki/HTTP_cookie[HTTP cookies, window=\_blank] to keep track of sessions for single sign-on (SSO), and setting and reading cookies depends on the server name and domain. @@ -124,220 +96,26 @@ $ cat /etc/hosts | grep openam ==== -[#install-apache-http] -.To Install Apache HTTP Server -==== -Apache HTTP Server is a popular web server that is supported by OpenAM's web policy agents. Apache HTTP Server might already be installed on your system, but since you are installing software for the sole purpose of getting started with OpenAM, install the web server separately instead of modifying any existing installations. - -Full installation instructions are available link:http://httpd.apache.org/docs/2.2/install.html[online, window=\_blank]. - -. Verify the correct tools are installed to build Apache HTTP Server 2.2 from source. -+ -For Linux distributions, you need development tools including the C compiler. How you install these depends on your distribution. -+ -For Red Hat and CentOS distributions: -+ - -[source, console] ----- -# yum groupinstall 'Development Tools' ----- -+ -For Ubuntu distributions: -+ - -[source, console] ----- -$ sudo apt-get install build-essential checkinstall ----- - -. Download Apache HTTP Server 2.2 sources from link:http://httpd.apache.org/download.cgi[the Apache download page, window=\_blank]. -+ -The OpenAM web policy agent requires Apache Portable Runtime 1.3 or later, so make sure you download Apache HTTP Server 2.2.9 or later. - -. Extract the download. -. Configure the sources for compilation. -+ -The `--prefix` option can be used to install the Web server in a location where you can write files. -+ -[source, console] ----- -$ cd ~/Downloads/httpd-2.2.25 -$ ./configure --prefix=/path/to/apache ----- - -. Compile Apache HTTP Server. -+ - -[source, console] ----- -$ make ----- - -. Install Apache HTTP Server. -+ - -[source, console] ----- -$ make install ----- - -. Edit the configuration to set the server name to `www.example.com` and the port to one, such as 8000 that the web server process can use when starting with your user ID. -+ - -[source, console] ----- -$ vi /path/to/apache/conf/httpd.conf -$ grep 8000 /path/to/apache/conf/httpd.conf -Listen 8000 -ServerName www.example.com:8000 ----- - -. Test the installation to ensure Apache HTTP Server is working. -+ - -.. Make sure that your system's firewall does not block the port that Apache HTTP Server uses. -+ -See the documentation for your version of your system regarding how to allow traffic through the firewall on a specific port. A variety of firewalls are in use on Linux systems. The one in use depends on your specific distribution. - -.. Start the web server. -+ - -[source, console] ----- -$ /path/to/apache/bin/apachectl -k start ----- - -.. Point your browser to following URL: link:http://www.example.com:8000[http://www.example.com:8000, window=\_blank]. -+ - -[#figure-web-server-home-page] -image::images/web-server-home-page.png[] -+ -This is the page to protect with OpenAM. Do not proceed with the next steps unless this page appears. - - -==== - -[#install-apache-tomcat] -.To Install Apache Tomcat +[#install-openam] +.To Install OpenAM ==== -OpenAM runs as a Java web application inside an application container. Apache Tomcat is an application container that runs on a variety of platforms. The following instructions are loosely based on the `RUNNING.txt` file delivered with Tomcat. - -. Make sure you have a recent JDK LTS release installed. -+ -One way of checking the version of the JDK is to list the version of the `javac` compiler. -+ +Create a Docker network for OpenAM. [source, console] ---- -$ javac -version +$ docker network create openam-quickstart ---- -+ -If the `javac` compiler is not found, then either you do not have a Java Development Kit installed, or it is installed, but not on your `PATH`. - -. Download Apache Tomcat 9 from its link:http://tomcat.apache.org/download-90.cgi[download page, window=\_blank]. - -. Extract the download. -+ +Run the OpenAM Docker image. [source, console] ---- -$ cd /path/to -$ unzip ~/Downloads/apache-tomcat-9.0.93.zip -$ mv apache-tomcat-9.0.93 tomcat +$ docker run -h openam.example.com -p 8080:8080 --network openam-quickstart --name openam openidentityplatform/openam ---- +You can access the web application in a browser at `\http://openam.example.com:8080/openam/`. -. On UNIX-like systems, make the scripts in Tomcat's `bin/` directory executable. -+ - -[source, console] ----- -$ chmod +x /path/to/tomcat/bin/*.sh ----- - -. Set the `JAVA_HOME` environment variable to the file system location of the Java Development Kit. -+ -On Linux, set `JAVA_HOME` as follows. -+ - -[source] ----- -export JAVA_HOME=/path/to/jdk ----- - -. Create a Tomcat `setenv.sh` (Unix/Linux) or `setenv.bat` (Windows) script to set the `JAVA_HOME` environment variable to the file system location of the Java Development Kit, and to set the heap and permanent generation size or metaspace size appropriately. -+ -If you are using JDK 7: -+ - -[source, console] ----- -export JAVA_HOME="/path/to/usr/jdk" -export CATALINA_OPTS="$CATALINA_OPTS -Xmx2g -XX:MaxPermSize=256m" ----- -+ -If you are using JDK 8: -+ - -[source, console] ----- -export JAVA_HOME="/path/to/usr/jdk" -export CATALINA_OPTS="$CATALINA_OPTS -Xmx2g -XX:MaxMetaspaceSize=256m" ----- - -. If you have a custom installation that differs from the documented Tomcat installation, make sure to set Tomcat's `CATALINA_TMPDIR` to a writable directory to ensure the installation succeeds. This temporary directory is used by the JVM (`java.io.tmpdir`) to write disk-based storage policies and other temporary files. - -. Make sure that your system's firewall does not block the port that Apache Tomcat uses. -+ -See the Apache documentation for instructions for allowing traffic through the firewall on a specific port for the version of Tomcat on your system. A variety of firewalls are in use on Linux systems. The version your system uses depends on your specific distribution. - -. Start Tomcat. -+ - -[source, console] ----- -$ /path/to/tomcat/bin/startup.sh ----- -+ -It might take Tomcat several seconds to start. When Tomcat has successfully started, you should see information indicating how long startup took in the `/path/to/tomcat/logs/catalina.out` log file. -+ - -[source] ----- -INFO: Server startup in 4655 ms ----- - -. Browse to Tomcat's home page, such as `\http://openam.example.com:8080`. -+ - -[#figure-tomcat-home-page] -image::images/tomcat-home-page.png[] -+ -Tomcat will serve the OpenAM web application. Make sure you have successfully gotten to this point before you proceed. - -==== - -[#install-openam] -.To Install OpenAM -==== -Deploy OpenAm into Tomcat and then configure it for use. - -. Download the OpenAM `.war` file from the OpenAM link:https://github.com/OpenIdentityPlatform/OpenAM/releases[releases page, window=\_blank] on the GitHub. - -. Deploy the `.war` file in Tomcat as `openam.war`. -+ - -[source, console] ----- -$ mv ~/Downloads/OpenAM-13.5.2.war /path/to/tomcat/webapps/openam.war ----- -+ -Tomcat deploys OpenAM under the `/path/to/tomcat/webapps/openam/` directory. You can access the web application in a browser at `\http://openam.example.com:8080/openam/`. - -. Browse to OpenAM where it is deployed in Tomcat, in this example, `\http://openam.example.com:8080/openam/`, to configure the application. +. Browse to OpenAM in this example, `\http://openam.example.com:8080/openam/`, to configure the application. . On the OpenAM home page, click Create Default Configuration. + @@ -362,8 +140,6 @@ image::images/openam-default-configuration.png[] ====== If you were configuring OpenAM for real-world use, you would not use either of those passwords, but this is only to get started with OpenAM. The `amadmin` user is the OpenAM administrator, who is like a superuser in that `amadmin` has full control over the OpenAM configuration. ====== -+ -The `UrlAccessAgent` is not used in this guide. . Click the Proceed to Login link, then log in as `amadmin` with the password specified in the previous step, `changeit`. + @@ -375,10 +151,18 @@ image::images/openam-realms.png[] + OpenAM stores its configuration, including the embedded OpenDJ directory server in the folder named `~/openam/` in your home directory. The folder shares the same name as your server instance. It also has a hidden folder, `~/.openamcfg/`, with a file used by OpenAM when it starts up. If you ruin your configuration of OpenAM somehow, the quickest way to start over is to stop Tomcat, delete these two folders, and configure OpenAM again. + -OpenAM core server and OpenAM Console are now configured. Make sure you have successfully logged in to OpenAM Console before you proceed. +The OpenAM core server and OpenAM Console are now configured. Make sure you have successfully logged in to OpenAM Console before you proceed. ==== +[#configure-cookie-domain] +.To Configure Cookie Domain in OpenAM +==== +Navigate to Configure -> Global Services -> Platform -> Cookie Domain. + +Set the cookie domain to .example.com, and save your settings. +==== + [#configure-policy] .To Configure a Policy in OpenAM ==== @@ -454,7 +238,7 @@ Next, you must create a web policy agent profile before installing the agent in ==== OpenAM stores profile information about policy agents centrally by default. You can manage the policy agent profile through OpenAM Console. The policy agent retrieves its configuration from its OpenAM profile at installation and start up, and OpenAM notifies the policy agent of changes to its configuration. Follow these steps before installing the policy agent itself. -. In OpenAM Console, browse to Realms > / Top Level Realm > Agents > Web, and then click New in the Agents table. +. In OpenAM Console, browse to Realms > / Top Level Realm > Applications > Web Agents, and then click New in the Agents table. . In the page to configure your new web policy agent, set the following values. + @@ -491,89 +275,59 @@ Next, install a policy agent in Apache HTTP Server to enforce your new policy. [#install-web-policy-agent] .To Install OpenAM Web Policy Agent + ==== -OpenAM policy agents enforce policies defined in OpenAM. While the policy agent's job is to verify that users have the appropriate privileges to the resources they request, the policy agents do not make policy decisions. They call on OpenAM to make policy decisions using information presented by the user (or the user's client application), such as the SSO token in the HTTP cookie, which OpenAM uses to manage user sessions. A policy agent is, in essence, a gatekeeper for OpenAM. +Create a Dockerfile on your machine folder with the following contents: -The agent runs inside of Apache HTTP Server as a library, which the server loads at startup time. When a request comes in, the agent redirects users to OpenAM for authentication and calls on OpenAM for policy decisions as necessary. +[source, dockerfile] +---- +FROM httpd:2.4.34 -. Download the OpenAM policy agent for your version of Apache HTTP Server from the Web Agent link:https://github.com/OpenIdentityPlatform/OpenAM-Web-Agents/releases[releases, window=\_blank] page on the GitHub. +ENV PA_PASSWORD secret12 -. Create a password file, for example `$HOME/.pwd.txt`, that the agent installer reads when first connecting to OpenAM to read its profile. The file should only contain the password string, on a single line. -+ -The password file should be read-only by the user who installs the policy agent. -+ +#Install pre-requisite packages +RUN echo "deb [trusted=yes] http://archive.kernel.org/debian-archive/debian/ jessie main" >> /etc/apt/sources.list -[source, console] ----- -$ chmod 400 $HOME/.pwd.txt ----- -+ -The password is stored encrypted after installation. +RUN apt-get update || true -. Make sure OpenAM is running. -+ -You can verify this by logging into OpenAM Console. +RUN apt-get install -y curl unzip -. Stop Apache HTTP Server while you install the policy agent. -+ +#Install OpenAM Apache Agent +RUN curl -L -o /tmp/Apache_v24_Linux_64bit_4.1.1.zip https://github.com/OpenIdentityPlatform/OpenAM-Web-Agents/releases/download/4.1.1/Apache_v24_Linux_64bit_4.1.1.zip -[source, console] ----- -$ /path/to/apache/bin/apachectl stop ----- +RUN unzip /tmp/Apache_v24_Linux_64bit_4.1.1.zip -d /usr/ -. Extract the download. -+ +RUN rm /tmp/Apache_v24_Linux_64bit_4.1.1.zip -[source, console] ----- -$ cd /path/to -$ unzip ~/Downloads/Apache-v22-Linux-64-Agent-4.1.zip +RUN echo $PA_PASSWORD > /tmp/pwd.txt + +RUN cat /tmp/pwd.txt + +RUN cat /etc/issue + +#Configure OpenAM Apache Agent +RUN /usr/web_agents/apache24_agent/bin/agentadmin --s "/usr/local/apache2/conf/httpd.conf" "http://openam.example.com:8080/openam" "http://example.com:80" "/" "WebAgent" "/tmp/pwd.txt" --acceptLicence --changeOwner ---- -. Install the web policy agent in Apache HTTP Server, making sure that you provide the correct information to the installer as shown in the following example. -+ -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`. -+ +Build Apache Docker image with the preconfigured OpenAM Apache Policy Agent. [source, console] ---- -$ cd /path/to/web_agents/apache22_agent/bin -$ ./agentadmin --install --acceptLicense -... - ------------------------------------------------ -SUMMARY OF YOUR RESPONSES ------------------------------------------------ -Apache Server Config Directory : /path/to/apache/conf -OpenAM server URL : http://openam.example.com:8080/openam -Agent URL : http://www.example.com:8000 -Agent Profile name : WebAgent -Agent Profile Password file name : $HOME/.pwd.txt - -... +docker build --network=host -t apache_agent -f Dockerfile . ---- -. Start Apache HTTP Server, and verify that the web policy agent is configured correctly. -+ +Run the image: [source, console] ---- -$ /path/to/apache/bin/apachectl -k start -$ tail /path/to/apache/logs/error_log -...[notice] Apache/2.2.25 (Unix) OpenAM WPA/4.1 configured -- resuming - normal operations +docker run -it --name apache_agent -p 8000:80 -h www.example.com --shm-size 2G --network openam-quickstart apache_agent ---- -+ -You can now try your installation to see OpenAM in action. - -==== [#try-it-out] === Trying It Out -Now that you have completed xref:#software-setup["Setting Up the Software"], you can access the protected web page to see OpenAM at work. +Now that you have completed the steps above, you can access the protected web page to see OpenAM at work. . Log out of OpenAM Console. @@ -587,7 +341,7 @@ At this point, the policy agent intercepts your request for the page. Your brows [#figure-openam-login] image::images/openam-login.png[] + -On successful login, OpenAM sets a session cookie named `iPlanetDirectoryPro` in your browser for the domain `.example.com`. The cookie is then returned to servers in the `example.com` domain, such as, `openam.example.com` and `www.example.com`. +On successful login, OpenAM sets a session cookie named `iPlanetDirectoryPro` in your browser for the domain `.example.com`. The cookie is then returned to servers in the `example.com` domain, such as `openam.example.com` and `www.example.com`. + If you examine this cookie in your browser, you see that it has a value, such as `AQIC5wM2LY4SfcwciyfvJcQDUIB7kIWEH187Df_txqLdAVc.*AAJTSQACMDEAAlNLABMxMDYwNzY1MjQ0NTE0ODI2NTkx*`. This is the SSO Token value. The value is in fact an encrypted reference to the session that is stored only by OpenAM. So, only OpenAM can determine whether you are actually logged in, or instead, that the session is no longer valid and you need to authenticate again. + diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/images/gsg-policies-actions.png b/openam-documentation/openam-doc-source/src/main/asciidoc/images/gsg-policies-actions.png index 15c72d1cf2..bfef633925 100644 Binary files a/openam-documentation/openam-doc-source/src/main/asciidoc/images/gsg-policies-actions.png and b/openam-documentation/openam-doc-source/src/main/asciidoc/images/gsg-policies-actions.png differ diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/images/gsg-policies-add-a-new-policy.png b/openam-documentation/openam-doc-source/src/main/asciidoc/images/gsg-policies-add-a-new-policy.png index 5b2fd1a7b0..978b8942a4 100644 Binary files a/openam-documentation/openam-doc-source/src/main/asciidoc/images/gsg-policies-add-a-new-policy.png and b/openam-documentation/openam-doc-source/src/main/asciidoc/images/gsg-policies-add-a-new-policy.png differ diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/images/gsg-policies-new-policies-settings.png b/openam-documentation/openam-doc-source/src/main/asciidoc/images/gsg-policies-new-policies-settings.png index 5dbd1cfa7a..1867fffe93 100644 Binary files a/openam-documentation/openam-doc-source/src/main/asciidoc/images/gsg-policies-new-policies-settings.png and b/openam-documentation/openam-doc-source/src/main/asciidoc/images/gsg-policies-new-policies-settings.png differ diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/images/gsg-policies-new-settings.png b/openam-documentation/openam-doc-source/src/main/asciidoc/images/gsg-policies-new-settings.png index 6c3f17aa1a..453aa366b9 100644 Binary files a/openam-documentation/openam-doc-source/src/main/asciidoc/images/gsg-policies-new-settings.png and b/openam-documentation/openam-doc-source/src/main/asciidoc/images/gsg-policies-new-settings.png differ diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/images/gsg-policies-subjects.png b/openam-documentation/openam-doc-source/src/main/asciidoc/images/gsg-policies-subjects.png index edc1814731..5f0086892e 100644 Binary files a/openam-documentation/openam-doc-source/src/main/asciidoc/images/gsg-policies-subjects.png and b/openam-documentation/openam-doc-source/src/main/asciidoc/images/gsg-policies-subjects.png differ diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-conf-amadmin.png b/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-conf-amadmin.png index 068bbb00ca..ac9303656f 100644 Binary files a/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-conf-amadmin.png and b/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-conf-amadmin.png differ diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-conf-pa.png b/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-conf-pa.png index d1042a2ef9..5502444abf 100644 Binary files a/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-conf-pa.png and b/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-conf-pa.png differ diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-conf-server-settings.png b/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-conf-server-settings.png index 16d539d0a4..eb212f2c9c 100644 Binary files a/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-conf-server-settings.png and b/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-conf-server-settings.png differ diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-conf-site.png b/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-conf-site.png index a4716c43c3..ec8f600bc8 100644 Binary files a/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-conf-site.png and b/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-conf-site.png differ diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-conf-store.png b/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-conf-store.png index c8c3725ed3..c1ab963c72 100644 Binary files a/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-conf-store.png and b/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-conf-store.png differ diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-conf-summary.png b/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-conf-summary.png index f998c096c6..76c778b47d 100644 Binary files a/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-conf-summary.png and b/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-conf-summary.png differ diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-conf-user-store.png b/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-conf-user-store.png index 42aed25494..0f2e3f641b 100644 Binary files a/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-conf-user-store.png and b/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-conf-user-store.png differ diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-default-conf.png b/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-default-conf.png index 56dfa4f680..c94fa94f99 100644 Binary files a/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-default-conf.png and b/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-default-conf.png differ diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-default-configuration.png b/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-default-configuration.png index 56dfa4f680..6a75a64393 100644 Binary files a/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-default-configuration.png and b/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-default-configuration.png differ diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-first-login.png b/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-first-login.png index 17850ff3aa..de249bbec3 100644 Binary files a/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-first-login.png and b/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-first-login.png differ diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-home-page.png b/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-home-page.png index 8e8ffa7050..b924ac38f0 100644 Binary files a/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-home-page.png and b/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-home-page.png differ diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-license-default.png b/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-license-default.png index a4e9372c3a..8db8f8e410 100644 Binary files a/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-license-default.png and b/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-license-default.png differ diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-license-dialog.png b/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-license-dialog.png index a4e9372c3a..cc328a25bd 100644 Binary files a/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-license-dialog.png and b/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-license-dialog.png differ diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-realms.png b/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-realms.png index e8c784a027..231b217746 100644 Binary files a/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-realms.png and b/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-realms.png differ diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-start.png b/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-start.png index 8e8ffa7050..d21c680acc 100644 Binary files a/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-start.png and b/openam-documentation/openam-doc-source/src/main/asciidoc/images/openam-start.png differ diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/images/web-agent-profile.png b/openam-documentation/openam-doc-source/src/main/asciidoc/images/web-agent-profile.png index 1469dd42e7..58f22b6d71 100644 Binary files a/openam-documentation/openam-doc-source/src/main/asciidoc/images/web-agent-profile.png and b/openam-documentation/openam-doc-source/src/main/asciidoc/images/web-agent-profile.png differ diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/install-guide/chap-custom-ui.adoc b/openam-documentation/openam-doc-source/src/main/asciidoc/install-guide/chap-custom-ui.adoc index afa7481a23..5ae6459ffa 100644 --- a/openam-documentation/openam-doc-source/src/main/asciidoc/install-guide/chap-custom-ui.adoc +++ b/openam-documentation/openam-doc-source/src/main/asciidoc/install-guide/chap-custom-ui.adoc @@ -18,6 +18,7 @@ :figure-caption!: :example-caption!: :table-caption!: +:openam-version: 15.1.3 [#chap-custom-ui] @@ -405,15 +406,15 @@ image::images/modified-fr-login.png[] ==== To customize classic UI elements, such as button text on the login screen, follow these steps. -. Unpack the core OpenAM library, `openam-core-13.5.2.jar`, that contains the text in Java properties files. +. Unpack the core OpenAM library, `openam-core-{openam-version}.jar`, that contains the text in Java properties files. + This library is available under `WEB-INF/lib/` where OpenAM is unpacked for deployment. In the following example OpenAM is deployed on Apache Tomcat. + -[source, console] +[source, console, subs="attributes"] ---- $ mkdir openam-core && cd openam-core -$ jar xf /path/to/tomcat/webapps/openam/WEB-INF/lib/openam-core-13.5.2.jar +$ jar xf /path/to/tomcat/webapps/openam/WEB-INF/lib/openam-core-{openam-version}.jar ---- . Edit only property values in the appropriate properties files. @@ -421,9 +422,9 @@ $ jar xf /path/to/tomcat/webapps/openam/WEB-INF/lib/openam-core-13.5.2.jar . Prepare a new core OpenAM library with your modifications. + -[source, console] +[source, console, subs="attributes"] ---- -$ jar cf ../openam-core-13.5.2.jar * +$ jar cf ../openam-core-{openam-version}.jar * ---- . Replace the existing core OpenAM library with your modified version. @@ -431,12 +432,12 @@ $ jar cf ../openam-core-13.5.2.jar * The following example replaces the library only in a deployed OpenAM server. + -[source, console] +[source, console, subs="attributes"] ---- -$ cp openam-core-13.5.2.jar /path/to/tomcat/webapps/openam/WEB-INF/lib/ +$ cp openam-core-{openam-version}.jar /path/to/tomcat/webapps/openam/WEB-INF/lib/ ---- + -When preparing for production deployment make the modification in the OpenAM war file, `OpenAM-13.5.2.war`, instead. +When preparing for production deployment make the modification in the OpenAM war file, `OpenAM-{openam-version}.war`, instead. . Restart OpenAM or the container in which it runs to load the changes. diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/install-guide/chap-install-core.adoc b/openam-documentation/openam-doc-source/src/main/asciidoc/install-guide/chap-install-core.adoc index aeb0a80ee7..0fbc88ec80 100644 --- a/openam-documentation/openam-doc-source/src/main/asciidoc/install-guide/chap-install-core.adoc +++ b/openam-documentation/openam-doc-source/src/main/asciidoc/install-guide/chap-install-core.adoc @@ -12,20 +12,20 @@ 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!: :example-caption!: :table-caption!: - +:openam-version: 15.1.3 [#chap-install-core] == Installing OpenAM Core Services This chapter covers tasks required for a full install of OpenAM server with or without OpenAM Console. -This chapter does not cover installation for enforcing policies on resource servers. To manage access to resources on other servers, you can use OpenIG or OpenAM policy agents. +This chapter does not cover installation for enforcing policies on resource servers. To manage access to resources on other servers, you can use OpenIG (recommended) or OpenAM policy agents. link:https://github.com/OpenIdentityPlatform/OpenIG[OpenIG, window=\_blank] is a high-performance reverse proxy server with specialized session management and credential replay functionality. It can function as a standards-based policy enforcement point. @@ -40,7 +40,7 @@ OpenAM policy agents provide policy enforcement on supported web servers and Jav a|Install quickly for evaluation using default settings a|xref:#deploy-openam["To Deploy OpenAM"] and xref:#configure-openam-defaults["To Configure OpenAM With Defaults"] - Alternatively, follow the full example in xref:../getting-started/index.adoc[Getting Started With OpenAM]. +Alternatively, follow the full example in xref:../getting-started/index.adoc[Getting Started With OpenAM]. a|Install OpenAM server, choosing settings a|xref:#deploy-openam["To Deploy OpenAM"] and xref:#configure-openam-custom["To Custom Configure OpenAM"] @@ -71,16 +71,16 @@ Select the `.war` file based on the type of deployment you need, as defined in t [#deploy-openam] .To Deploy OpenAM ==== -The `OpenAM-13.5.2.war` file contains OpenAM server with OpenAM Console. How you deploy the `.war` file depends on your web application container. +The `OpenAM-{openam-version}.war` file contains OpenAM server with OpenAM Console. How you deploy the `.war` file depends on your web application container. . Deploy the `.war` file on your container. + For example, copy the file to deploy on Apache Tomcat. + -[source, console] +[source, console, subs="attributes"] ---- -$ cp OpenAM-13.5.2.war /path/to/tomcat/webapps/openam.war +$ cp OpenAM-{openam-version}.war /path/to/tomcat/webapps/openam.war ---- + You change the file name to `openam.war` when deploying in Tomcat so that the deployment URI is `/openam`. @@ -288,7 +288,7 @@ Password for the directory administrator user. . In the Site Configuration screen, you can set up OpenAM as part of a site where the load is balanced across multiple OpenAM servers. + -If you have a site configuration with a load balancer, you can enable session high availability persistence and failover.footnote:d14351e2811[You can configure OpenAM to store sessions__statefully__or__statelessly__. Stateful sessions are stored in memory on the OpenAM server. They are also written to disk by thexref:chap-cts.adoc#chap-cts["Configuring the Core Token Service"]if you select the Enable Session HA and Persistence and Failover option in the Site Configuration screen. Stateless sessions are stored in HTTP cookies. The Enable Session HA and Persistence and Failover setting does not apply to stateless sessions. For more information about stateful and stateless sessions, seexref:../admin-guide/chap-session-state.adoc#chap-session-state["Configuring Session State"]in the__Administration Guide__.] OpenAM then stores sessions across server restarts, so that users do not have to login again. +If you have a site configuration with a load balancer, you can enable session high availability persistence and failover.footnote:d14351e2811[You can configure OpenAM to store sessions __statefully__ or __statelessly__. Stateful sessions are stored in memory on the OpenAM server. They are also written to disk by thexref:chap-cts.adoc#chap-cts["Configuring the Core Token Service"]if you select the Enable Session HA and Persistence and Failover option in the Site Configuration screen. Stateless sessions are stored in HTTP cookies. The Enable Session HA and Persistence and Failover setting does not apply to stateless sessions. For more information about stateful and stateless sessions, seexref:../admin-guide/chap-session-state.adoc#chap-session-state["Configuring Session State"]in the__Administration Guide__.] OpenAM then stores sessions across server restarts, so that users do not have to login again. + If you then add additional servers to this OpenAM site, OpenAM performs __session failover__, storing session data in a directory service that is shared by different OpenAM servers. The shared storage means that if an OpenAM server fails, other OpenAM servers in the site have access to the user's session data and can serve requests about that user. As a result, the user does not have to log in again. If session failover is important for your deployment, also follow the instructions in xref:chap-session-failover.adoc#chap-session-failover["Setting Up OpenAM Session Failover"]. + diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/install-guide/chap-install-tools.adoc b/openam-documentation/openam-doc-source/src/main/asciidoc/install-guide/chap-install-tools.adoc index 8ec0bf038e..1b428d058e 100644 --- a/openam-documentation/openam-doc-source/src/main/asciidoc/install-guide/chap-install-tools.adoc +++ b/openam-documentation/openam-doc-source/src/main/asciidoc/install-guide/chap-install-tools.adoc @@ -12,12 +12,13 @@ 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!: :example-caption!: :table-caption!: +:openam-version: 15.1.3 [#chap-install-tools] @@ -26,13 +27,13 @@ OpenAM tools are found in `.zip` files where you unpacked the archive of the entire package, such as `~/Downloads/openam`. A list and description of these files follows. -- -`SSOAdminTools-13.5.2.zip`:: +`SSOAdminTools-{openam-version}.zip`:: Administration tools: `ampassword`, `ssoadm`, and `amverifyarchive` + See xref:#install-openam-admin-tools["To Set Up Administration Tools"]. -`SSOConfiguratorTools-13.5.2.zip`:: +`SSOConfiguratorTools-{openam-version}.zip`:: Configuration and upgrade tools, alternatives to using the GUI configuration wizard + @@ -69,7 +70,7 @@ $ mkdir -p /path/to/openam-tools/admin [source, console] ---- $ cd /path/to/openam-tools/admin -$ unzip ~/Downloads/openam/SSOAdminTools-13.5.2.zip +$ unzip ~/Downloads/openam/SSOAdminTools-{openam-version}.zip ---- . Add `--acceptLicense` to the `java` command at the end of the `setup` or `setup.bat` script if you want to auto-accept the license agreement and suppress the license acceptance screen to the user: @@ -252,26 +253,26 @@ $ mkdir -p /path/to/openam-tools/config . Unpack the tools from where you unzipped OpenAM. + -[source, console] +[source, console, subs="attributes"] ---- $ cd /path/to/openam-tools/config -$ unzip ~/Downloads/openam/SSOConfiguratorTools-13.5.2.zip -Archive: ~/Downloads/openam/SSOConfiguratorTools-13.5.2.zip +$ unzip ~/Downloads/openam/SSOConfiguratorTools-{openam-version}.zip +Archive: ~/Downloads/openam/SSOConfiguratorTools-{openam-version}.zip creating: legal-notices/ inflating: legal-notices/LICENSE.DOM-software.html inflating: legal-notices/NOTICE.resolver.txt inflating: legal-notices/LICENSE.DOM-documentation.html ... (more output) ... extracting: lib/xml-apis-2.11.0.jar - extracting: openam-configurator-tool-13.5.2.jar + extracting: openam-configurator-tool-{openam-version}.jar extracting: lib/servlet-api-2.5.jar ---- -. Configure OpenAM server in a silent mode by using the openam-configurator-tool-13.5.2.jar tool after you deploy the `.war` file. +. Configure OpenAM server in a silent mode by using the openam-configurator-tool-{openam-version}.jar tool after you deploy the `.war` file. + OpenAM server must be deployed and running, but not configured yet, when you use the tool. + -The openam-configurator-tool-13.5.2.jar relies on a properties file to specify the configuration for the OpenAM server. The following example shows the equivalent of a default configuration, which installs OpenAM to run as HTTP. +The openam-configurator-tool-{openam-version}.jar relies on a properties file to specify the configuration for the OpenAM server. The following example shows the equivalent of a default configuration, which installs OpenAM to run as HTTP. + If you want implement HTTPS, see the next step. + @@ -307,7 +308,7 @@ When the OpenAM server `.war` file is deployed and running, you can configure it [source, console] ---- -$ java -jar openam-configurator-tool-13.5.2.jar --file config.properties +$ java -jar openam-configurator-tool-{openam-version}.jar --file config.properties Checking license acceptance...License terms accepted. Checking configuration directory /home/openam/openam....Success. Installing OpenAM configuration store...Success RSA/ECB/OAEPWithSHA1AndMGF1... @@ -367,13 +368,13 @@ DS_DIRMGRDN=cn=Directory Manager DS_DIRMGRPASSWD=password ---- -. Then, when the OpenAM `.war` file is deployed and the server is running, configure the server to use HTTPS using the openam-configurator-tool-13.5.2.jar tool with the properties file as follows. +. Then, when the OpenAM `.war` file is deployed and the server is running, configure the server to use HTTPS using the openam-configurator-tool-{openam-version}.jar tool with the properties file as follows. + -[source, console] +[source, console, subs="attributes"] ---- java '-Djavax.net.ssl.trustStore=PATH_TO_JKS_TRUSTSTORE' \ - -jar openam-configurator-tool-13.5.2.jar \ + -jar openam-configurator-tool-{openam-version}.jar \ --file config.properties ---- 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 b155d70ac3..9607ab067c 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 @@ -18,6 +18,7 @@ :figure-caption!: :example-caption!: :table-caption!: +:openam-version: 15.1.3 [#chap-prepare-install] @@ -1135,43 +1136,43 @@ For each release of the OpenAM core services, you can download the entire packag After you download the `.zip` file, create a new openam folder, and unzip the `.zip` file to access the content. -[source, console] +[source, console, subs="attributes"] ---- $ cd ~/Downloads $ mkdir openam ; cd openam -$ unzip ~/Downloads/OpenAM-13.5.2.zip +$ unzip ~/Downloads/OpenAM-{openam-version}.zip ---- -- When you unzip the archive of the entire package, you get ldif, license, and legal directories in addition to the following files. -`ClientSDK-13.5.2.jar`:: +`ClientSDK-{openam-version}.jar`:: The OpenAM Java client SDK library -`ExampleClientSDK-CLI-13.5.2.zip`:: +`ExampleClientSDK-CLI-{openam-version}.zip`:: The .zip file containing the Java client SDK command-line examples, and .jar files needed to run the examples -`ExampleClientSDK-WAR-13.5.2.war`:: +`ExampleClientSDK-WAR-{openam-version}.war`:: The `.war` file containing Java client SDK examples in a web application. -`IDPDiscovery-13.5.2.war`:: +`IDPDiscovery-{openam-version}.war`:: The IDP discovery `.war` file, deployed as a service to service providers that must discover which identity provider corresponds to a SAML v2.0 request. + For details, see xref:../admin-guide/chap-federation.adoc#deploy-idp-discovery["Deploying the Identity Provider Discovery Service"] in the __Administration Guide__. -`Fedlet-13.5.2.zip`:: +`Fedlet-{openam-version}.zip`:: The `.zip` file that contains the lightweight service provider implementations that you can embed in your Java EE applications to enable it to use federated access management. -`OpenAM-13.5.2.war`:: +`OpenAM-{openam-version}.war`:: The deployable `.war` file. -`SSOAdminTools-13.5.2.zip`:: +`SSOAdminTools-{openam-version}.zip`:: The .zip file that contains tools to manage OpenAM from the command line -`SSOConfiguratorTools-13.5.2.zip`:: +`SSOConfiguratorTools-{openam-version}.zip`:: The .zip file that contains tools to configure OpenAM from the command line -`openam-soap-sts-server-13.5.2.war`:: +`openam-soap-sts-server-{openam-version}.war`:: A pre-built SOAP STS server `.war` file. + @@ -1189,11 +1190,11 @@ Instead, you must edit the deployment descriptor file before deploying OpenAM. C . Unpack the OpenAM `.war` file. + -[source, console] +[source, console, subs="attributes"] ---- $ mkdir /tmp/openam $ cd /tmp/openam/ -$ jar -xf ~/Downloads/openam/OpenAM-13.5.2.war +$ jar -xf ~/Downloads/openam/OpenAM-{openam-version}.war ---- . Edit the deployment descriptor file, `WEB-INF/web.xml`, to add a CORS filter configuration. @@ -1311,11 +1312,11 @@ To use the SecurID authentication module, you must first build an OpenAM war fil . Unpack the OpenAM .war file. + -[source, console] +[source, console, subs="attributes"] ---- $ mkdir /tmp/openam $ cd /tmp/openam/ -$ jar -xf ~/Downloads/openam/OpenAM-13.5.2.war +$ jar -xf ~/Downloads/openam/OpenAM-{openam-version}.war ---- . Obtain the `authapi.jar` (for example, `authapi-2005-08-12.jar`) and its dependency file, `crypto.jar` from RSA. Then, copy `authapi-2005-08-12.jar` into the `WEB-INF/lib` directory. @@ -1373,10 +1374,7 @@ CATALINA_HOME="/path/to/tomcat" export CATALINA_HOME JAVA_HOME=/path/to/jdk export JAVA_HOME -# For JDK 7, use: -CATALINA_OPTS="-server -Xmx2g -XX:PermSize=256m -XX:MaxPermSize=256m" -# For JDK 8, use: -# CATALINA_OPTS="-server -Xmx2g -XX:MetaspaceSize=256m -XX:MaxMetaspaceSize=256m" +CATALINA_OPTS="-server -Xmx2g -XX:MetaspaceSize=256m -XX:MaxMetaspaceSize=256m" export CATALINA_OPTS case "${1}" in @@ -1473,9 +1471,7 @@ After configuring JBoss or WildFly, you then prepare OpenAM for deployment by ma + Change the JVM heap size to `-Xmx1024m`. The default JVM heap size for some versions of JBoss might already exceed the recommended value. If you are using the embedded version of OpenDJ, the minimum heap size may be higher. For details on the JVM options to use, see xref:#prepare-java["Preparing a Java Environment"]. + -When using JDK 7, change the permanent generation size to `-XX:MaxPermSize=256m` if the default size does not exceed this amount. -+ -When using JDK 8, change the metaspace size to `-XX:MaxMetaspaceSize=256m` if the default size does not exceed this amount. +Change the metaspace size to `-XX:MaxMetaspaceSize=256m` if the default size does not exceed this amount. .. Set the following JVM `JAVA_OPTS` setting in the same file: + @@ -1497,14 +1493,14 @@ Verify that the headers include the `Expires` attribute rather than only `Max-Ag ==== To prepare OpenAM to run with JBoss or WildFly, you should make a change to the OpenAM `war` file. JBoss and WildFly deploy applications from different temporary directories every time you restart the container, which would require reconfiguring OpenAM. To avoid problems, change the OpenAM `war` file as follows: -. If you have not already done so, create a temporary directory and expand the `OpenAM-13.5.2.war` file. +. If you have not already done so, create a temporary directory and expand the `OpenAM-{openam-version}.war` file. + -[source, console] +[source, console, subs="attributes"] ---- $ cd /tmp $ mkdir /tmp/openam ; cd /tmp/openam -$ jar xvf ~/Downloads/OpenAM-13.5.2.war +$ jar xvf ~/Downloads/OpenAM-{openam-version}.war ---- . Locate the `bootstrap.properties` file in the `WEB-INF/classes` directory of the expanded `war` archive. Update the `# configuration.dir=` line in this file to specify a path with read and write permissions, and then save the change. @@ -1544,7 +1540,7 @@ To deploy OpenAM in WebLogic, perform the following steps: . Update the JVM options as described in xref:#prepare-java["Preparing a Java Environment"]. -. Customize the `OpenAM-13.5.2.war` file as described in xref:#prep-openam-for-weblogic["To Prepare OpenAM for Oracle WebLogic"]. +. Customize the `OpenAM-{openam-version}.war` file as described in xref:#prep-openam-for-weblogic["To Prepare OpenAM for Oracle WebLogic"]. [#prep-openam-for-weblogic] @@ -1554,14 +1550,14 @@ To prepare OpenAM to run in WebLogic, change the OpenAM `war` file to ensure tha Change the OpenAM `war` file as follows: -. Create a temporary directory and expand the `OpenAM-13.5.2.war` file: +. Create a temporary directory and expand the `OpenAM-{openam-version}.war` file: + -[source, console] +[source, console, subs="attributes"] ---- $ cd /tmp $ mkdir /tmp/openam ; cd /tmp/openam -$ jar xvf ~/Downloads/OpenAM-13.5.2.war +$ jar xvf ~/Downloads/OpenAM-{openam-version}.war ---- . Locate the `bootstrap.properties` file in the `WEB-INF/classes` directory of the expanded `war` file. diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/install-guide/chap-session-failover.adoc b/openam-documentation/openam-doc-source/src/main/asciidoc/install-guide/chap-session-failover.adoc index aa9a36dc8a..e21c4a18a3 100644 --- a/openam-documentation/openam-doc-source/src/main/asciidoc/install-guide/chap-session-failover.adoc +++ b/openam-documentation/openam-doc-source/src/main/asciidoc/install-guide/chap-session-failover.adoc @@ -77,12 +77,12 @@ Without session logout/destroy broadcasting, it is possible for a user to log ou * Select Disabled if you do not want the OpenAM server to broadcast session logout/destroy messages. Session logout/destroy broadcasting is disabled by default. Disabling broadcasting is suitable when you do not need the highest level of security. Disable broadcasting when you do not expect users to maliciously attempt to access logged out or destroyed sessions. * Specify one of the two broadcast options to achieve a higher level of security, at a cost of incurring additional network I/O. Select "Broadcast only to local site servers" if your session store supports a single OpenAM site. Select "Broadcast to servers in all sites" if your session store supports multiple OpenAM sites. - + +-- The Reduced Crosstalk Purge Delay option specifies the amount of time (in minutes) before sessions are purged from OpenAM servers after the server receives session logout/destroy broadcast notification. The delay ensures that sessions are in memory during the time between session logout/destruction and session store replication. -+ -The default purge delay is 1 minute, which should be adequate unless session store replication is abnormally slow on your network. +The default purge delay is 1 minute, which should be adequate unless session store replication is abnormally slow on your network. +-- . Click Add to save your work. + OpenAM enables session failover immediately after you save the configuration changes. It is not necessary to restart the servers in your site. diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/install-guide/chap-uninstall.adoc b/openam-documentation/openam-doc-source/src/main/asciidoc/install-guide/chap-uninstall.adoc index baf8084e5d..f9f632b165 100644 --- a/openam-documentation/openam-doc-source/src/main/asciidoc/install-guide/chap-uninstall.adoc +++ b/openam-documentation/openam-doc-source/src/main/asciidoc/install-guide/chap-uninstall.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!: @@ -54,29 +54,29 @@ A full uninstall of OpenAM core services and configuration files consists of rem * The configuration directory, by default `$HOME/openam`. If you did not use the default configuration location, check the value of the Base installation directory property under Deployment > Servers > __Server Name__ > General > System. * The hidden directory that holds a file pointing to the configuration directory. For example, if you are using Apache Tomcat as the web container, this file could be `$HOME/.openamcfg/AMConfig_path_to_tomcat_webapps_openam_` OR `$HOME/.openssocfg/AMConfig_path_to_tomcat_webapps_openam_`. - + +-- [source, console] ---- $ rm -rf $HOME/openam $HOME/.openamcfg ---- -+ + Or: -+ [source, console] ---- $ rm -rf $HOME/openam $HOME/.openssocfg ---- -+ + If you used an external configuration store, you must remove the configuration manually from your external directory server. The default base DN for the OpenAM configuration is `dc=openam,dc=forgerock,dc=org`. -+ + [NOTE] ====== At this point, you can restart the web container and configure OpenAM anew if you only want to start over with a clean configuration rather than removing OpenAM completely. ====== +-- . Undeploy the OpenAM web application. + 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 41130d2784..34ca6be876 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 @@ -18,6 +18,7 @@ :figure-caption!: :example-caption!: :table-caption!: +:openam-version: 15.1.3 [#chap-config-ref] @@ -173,7 +174,7 @@ You configure OpenAM's legacy logging settings on this page: [NOTE] ====== -OpenAM 13.5.2-15 supports two Audit Logging Services: the legacy Logging Service, which is based on a Java SDK and is available in OpenAM versions prior to OpenAM 13.5.2-15, and a new common REST-based Audit Logging Service available in OpenAM 13.5.2-15. The legacy Logging Service will be deprecated in a future release. +OpenAM {openam-version} supports two Audit Logging Services: the legacy Logging Service, which is based on a Java SDK and is available in OpenAM versions prior to OpenAM {openam-version}, and a new common REST-based Audit Logging Service available in OpenAM {openam-version}. The legacy Logging Service will be deprecated in a future release. ====== `ssoadm` service name: `iPlanetAMLoggingService` @@ -2095,7 +2096,7 @@ Password to unlock the private key. [NOTE] ==== -OpenAM 13.5.2-15 supports two user self-service components: the Legacy User Self Service, which is based on a Java SDK and is available in OpenAM versions prior to OpenAM 13.5.2-15, and a new common REST-based/XUI-based User Self Service available in OpenAM 13.5.2-15. The Legacy User Self Service will be deprecated in a future release. +OpenAM {openam-version} supports two user self-service components: the Legacy User Self Service, which is based on a Java SDK and is available in OpenAM versions prior to OpenAM {openam-version}, and a new common REST-based/XUI-based User Self Service available in OpenAM {openam-version}. The Legacy User Self Service will be deprecated in a future release. ==== -- `ssoadm` service name: `RestSecurity` @@ -2774,7 +2775,7 @@ Default:`false` [NOTE] ==== -OpenAM 13.5.2-15 supports two user password reset components: the legacy Password Reset Service, which is based on a Java SDK and is available in OpenAM versions prior to OpenAM 13.5.2-15, and a new common REST-based/XUI-based User Self Service available in OpenAM 13.5.2-15. The Legacy Password Reset Service will be deprecated in a future release. +OpenAM {openam-version} supports two user password reset components: the legacy Password Reset Service, which is based on a Java SDK and is available in OpenAM versions prior to OpenAM {openam-version}, and a new common REST-based/XUI-based User Self Service available in OpenAM {openam-version}. The Legacy Password Reset Service will be deprecated in a future release. ==== `ssoadm` service name: `iPlanetAMPasswordResetService` -- @@ -2786,10 +2787,10 @@ OpenAM uses this LDAP attribute and the value entered by the user to look up the `ssoadm` attribute: `iplanet-am-password-reset-userValidate` Secret Question:: -This list corresponds to property values held in the file `amPasswordReset.properties` inside `openam-core-13.5.2.jar`, which you can find under `WEB-INF/lib/` where OpenAM is installed. +This list corresponds to property values held in the file `amPasswordReset.properties` inside `openam-core-{openam-version}.jar`, which you can find under `WEB-INF/lib/` where OpenAM is installed. + -To make changes, extract a version from `openam-core-13.5.2.jar`, copy it to `WEB-INF/classes/` where OpenAM is deployed, and then edit `WEB-INF/classes/amPasswordReset.properties`. +To make changes, extract a version from `openam-core-{openam-version}.jar`, copy it to `WEB-INF/classes/` where OpenAM is deployed, and then edit `WEB-INF/classes/amPasswordReset.properties`. + Localized versions of this file are named `amPasswordReset_locale.properties`. You should localize only the questions at the end, leaving the rest of the localized file as is. For example, if the default properties file contains: diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/reference/chap-log-messages.adoc b/openam-documentation/openam-doc-source/src/main/asciidoc/reference/chap-log-messages.adoc index 98f8289849..743392eb67 100644 --- a/openam-documentation/openam-doc-source/src/main/asciidoc/reference/chap-log-messages.adoc +++ b/openam-documentation/openam-doc-source/src/main/asciidoc/reference/chap-log-messages.adoc @@ -18,6 +18,7 @@ :figure-caption!: :example-caption!: :table-caption!: +:openam-version: 15.1.3 [#chap-log-messages] @@ -27,7 +28,7 @@ This chapter gives information about the different log files and messages for Op [NOTE] ==== -OpenAM 13.0.0 introduces a new Audit Logging Service, which is an audit logging framework common across all Open Identity Platform products. Both logging services are available in OpenAM 13.5.2-15, but the classic Logging Service will be deprecated in a future release. +OpenAM 13.0.0 introduces a new Audit Logging Service, which is an audit logging framework common across all Open Identity Platform products. Both logging services are available in OpenAM {openam-version}, but the classic Logging Service will be deprecated in a future release. ==== [#log-files] diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/reference/openam-cli-tools.adoc b/openam-documentation/openam-doc-source/src/main/asciidoc/reference/openam-cli-tools.adoc index d89bdf4314..81e7780f3c 100644 --- a/openam-documentation/openam-doc-source/src/main/asciidoc/reference/openam-cli-tools.adoc +++ b/openam-documentation/openam-doc-source/src/main/asciidoc/reference/openam-cli-tools.adoc @@ -18,6 +18,7 @@ :figure-caption!: :example-caption!: :table-caption!: +:openam-version: 15.1.3 [#openam-cli-tools] @@ -271,7 +272,7 @@ $ amverifyarchive \ [#d981e773] ==== Description -This executable .jar file, openam-configurator-tool-13.5.2.jar, lets you perform silent installation, configuring a deployed OpenAM server by applying settings from a configuration file. +This executable .jar file, openam-configurator-tool-{openam-version}.jar, lets you perform silent installation, configuring a deployed OpenAM server by applying settings from a configuration file. [#d981e778] ==== Options @@ -324,7 +325,7 @@ COOKIE_DOMAIN:: Name of the trusted DNS domain OpenAM returns to a browser when it grants a session ID to a user. By default, it is set to the full URL that was used to access the configurator, such as `example.com`. ACCEPT_LICENSES:: -Optional boolean property that can be set to always auto-accept the software license agreement and suppress the display of the license acceptance screen to the user. A value of `true` auto-accepts the license; any other value will be assumed to equal `false`, resulting in the presentation of the license. Default value is `false`. This property takes precedence over the `--acceptLicense` option, which can also be passed in to the application with the openam-configurator-tool-13.5.2.jar file. +Optional boolean property that can be set to always auto-accept the software license agreement and suppress the display of the license acceptance screen to the user. A value of `true` auto-accepts the license; any other value will be assumed to equal `false`, resulting in the presentation of the license. Default value is `false`. This property takes precedence over the `--acceptLicense` option, which can also be passed in to the application with the openam-configurator-tool-{openam-version}.jar file. -- .Configuration Store Properties @@ -448,7 +449,7 @@ DEPLOYMENT_URI:: URI where OpenAM is deployed on the web container, such as `/openam` ACCEPT_LICENSES:: -Optional boolean property that can be set to always auto-accept the software license agreement and suppress displaying the license acceptance screen to the user. A value of `true` auto-accepts the license; any other value will be assumed to equal `false`, resulting in the presentation of the license. Default value is `false`. This property takes precedence over the `--acceptLicense` option, which can also be passed in to the application with the openam-configurator-tool-13.5.2.jar file. +Optional boolean property that can be set to always auto-accept the software license agreement and suppress displaying the license acceptance screen to the user. A value of `true` auto-accepts the license; any other value will be assumed to equal `false`, resulting in the presentation of the license. Default value is `false`. This property takes precedence over the `--acceptLicense` option, which can also be passed in to the application with the openam-configurator-tool-{openam-version}.jar file. -- @@ -552,10 +553,10 @@ ACCEPT_LICENSES=true ---- The following example uses a configuration file with the `--acceptLicense` option on the command line. -[source, console] +[source, console, subs="attributes"] ---- $ java \ - -jar openam-configurator-tool-13.5.2.jar \ + -jar openam-configurator-tool-{openam-version}.jar \ -f config.file \ --acceptLicense ---- @@ -569,7 +570,7 @@ $ java \ [#d981e1307] ==== Description -This executable jar file, openam-upgrade-tool-13.5.2.jar, lets you perform a silent upgrade on a deployed OpenAM server by applying settings from a configuration file or using arguments. This capability allows you to include the `upgrade.jar` from a command line or in an upgrade script. +This executable jar file, openam-upgrade-tool-{openam-version}.jar, lets you perform a silent upgrade on a deployed OpenAM server by applying settings from a configuration file or using arguments. This capability allows you to include the `upgrade.jar` from a command line or in an upgrade script. [#d981e1315] ==== Options @@ -600,7 +601,7 @@ DEPLOYMENT_URI:: URI where OpenAM is deployed on the web container, such as `/openam`. ACCEPT_LICENSES:: -Optional boolean property that can be set to always auto-accept the software license agreement and suppress displaying the license acceptance screen to the user. A value of `true` auto-accepts the license; any other value will be assumed to equal `false`, resulting in the presentation of the license. Default value is `false`. This property takes precedence over the `--acceptLicense` option, which can also be passed in to the application with the openam-upgrade-tool-13.5.2.jar file. +Optional boolean property that can be set to always auto-accept the software license agreement and suppress displaying the license acceptance screen to the user. A value of `true` auto-accepts the license; any other value will be assumed to equal `false`, resulting in the presentation of the license. Default value is `false`. This property takes precedence over the `--acceptLicense` option, which can also be passed in to the application with the openam-upgrade-tool-{openam-version}.jar file. -- @@ -615,9 +616,9 @@ DEPLOYMENT_URI=/openam ACCEPT_LICENSES=true ---- -[source] +[source, subs="attributes"] ---- -$JAVA_HOME/bin/java -jar ~/openam/tools/openam-upgrade-tool-13.5.2.jar \ +$JAVA_HOME/bin/java -jar ~/openam/tools/openam-upgrade-tool-{openam-version}.jar \ -f /tmp/upgrade.txt ---- The following example shows how to specify system properties with the `upgrade.jar`. @@ -629,9 +630,9 @@ DEPLOYMENT_URI=/openam ACCEPT_LICENSES=true ---- -[source] +[source, subs="attributes"] ---- -$JAVA_HOME/bin/java -jar ~/openam/tools/openam-upgrade-tool-13.5.2.jar \ +$JAVA_HOME/bin/java -jar ~/openam/tools/openam-upgrade-tool-{openam-version}.jar \ -DSERVER_URL=http://openam.example.com:8080 -DDEPLOYMENT_URI=/openam ---- The following example shows the use of the `--acceptLicense` option with the `upgrade.jar`. @@ -642,9 +643,9 @@ SERVER_URL=http://openam.example.com:8080 DEPLOYMENT_URI=/openam ---- -[source] +[source, subs="attributes"] ---- -$JAVA_HOME/bin/java -jar ~/openam/tools/openam-upgrade-tool-13.5.2.jar \ +$JAVA_HOME/bin/java -jar ~/openam/tools/openam-upgrade-tool-{openam-version}.jar \ -DSERVER_URL=http://openam.example.com:8080 -DDEPLOYMENT_URI=/openam \ --acceptLicense ---- diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/upgrade-guide/chap-about-upgrades.adoc b/openam-documentation/openam-doc-source/src/main/asciidoc/upgrade-guide/chap-about-upgrades.adoc index 4aeb310f18..c58b7bd752 100644 --- a/openam-documentation/openam-doc-source/src/main/asciidoc/upgrade-guide/chap-about-upgrades.adoc +++ b/openam-documentation/openam-doc-source/src/main/asciidoc/upgrade-guide/chap-about-upgrades.adoc @@ -12,12 +12,13 @@ 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!: :example-caption!: :table-caption!: +:openam-version: 15.1.3 [#chap-about-upgrades] @@ -30,7 +31,7 @@ Release levels, and how much change to expect in a maintenance, minor, or major [#sec-supported-upgrades] === Supported Upgrade Paths -The following table contains information about the supported upgrade paths to OpenAM 13.5.2-15: +The following table contains information about the supported upgrade paths to OpenAM {openam-version}: [#am-supported-upgrades] .Upgrade Paths @@ -55,14 +56,14 @@ a|Yes a|OpenAM 13.x.x a|Yes -|=== -[NOTE] -==== -Upgrading between OpenAM Enterprise and OpenAM OEM versions is not supported. -==== -For more information, see link:https://backstage.forgerock.com/#!/knowledge/kb/article/a18529200[Checking your product versions are supported, window=\_blank] in the __ForgeRock Knowledge Base__. +a|OpenAM 14.x.x +a|Yes + +a|OpenAM 15.x.x +a|Yes +|=== [#upgrade-planning] === Planning the Upgrade @@ -75,7 +76,7 @@ How much you must do to upgrade OpenAM software depends on the magnitude of the * These suggestions are true both for OpenAM server components, and also for policy agents. -To upgrade from an OpenAM server, use the Upgrade wizard. The OpenAM server Upgrade wizard appears when you replace a deployed OpenAM server `.war` file with a newer version and browse to the deployment URL. The Upgrade wizard brings the OpenAM configuration, including the version number, up to date with the new version. The CLI counterpart of the Upgrade wizard is openam-upgrade-tool-13.5.2.jar, which you install as described in xref:../install-guide/chap-install-tools.adoc#install-openam-config-tools["To Set Up Configuration Tools"] in the __Installation Guide__. +To upgrade from an OpenAM server, use the Upgrade wizard. The OpenAM server Upgrade wizard appears when you replace a deployed OpenAM server `.war` file with a newer version and browse to the deployment URL. The Upgrade wizard brings the OpenAM configuration, including the version number, up to date with the new version. The CLI counterpart of the Upgrade wizard is openam-upgrade-tool-{openam-version}.jar, which you install as described in xref:../install-guide/chap-install-tools.adoc#install-openam-config-tools["To Set Up Configuration Tools"] in the __Installation Guide__. [#upgrade-policies] @@ -148,8 +149,7 @@ These are described in the xref:../install-guide/chap-custom-ui.adoc#chap-custom * Any changes to OpenAM classes -* Any changes or additional Java class libraries (such as .jar files in `WEB-INF/lib` - +* Any changes or additional Java class libraries (such as .jar files in `WEB-INF/lib`) [#post-upgrade-rollback] diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/upgrade-guide/chap-upgrade-components.adoc b/openam-documentation/openam-doc-source/src/main/asciidoc/upgrade-guide/chap-upgrade-components.adoc index 9f280b9239..4b80264d7e 100644 --- a/openam-documentation/openam-doc-source/src/main/asciidoc/upgrade-guide/chap-upgrade-components.adoc +++ b/openam-documentation/openam-doc-source/src/main/asciidoc/upgrade-guide/chap-upgrade-components.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!: @@ -48,7 +48,7 @@ Also back up the configuration if it is stored centrally in OpenAM. . Stop the web server where the policy agent is installed. -. Remove the old policy agent as described in the link:../../../openam-web-policy-agents/web-users-guide/#web-users-guide[OpenAM Web Policy Agent User's Guide, window=\_blank]. +. Remove the old policy agent as described in the xref:../web-users-guide/index.adoc[OpenAM Web Policy Agent User's Guide, window=\_blank]. + If the uninstallation process has changed, refer to the version of the __Web Policy Agent Installation Guide__ that corresponds to your web policy agent. diff --git a/openam-documentation/openam-doc-source/src/main/asciidoc/upgrade-guide/chap-upgrade-servers.adoc b/openam-documentation/openam-doc-source/src/main/asciidoc/upgrade-guide/chap-upgrade-servers.adoc index 69353e5cd7..94c5a8ac14 100644 --- a/openam-documentation/openam-doc-source/src/main/asciidoc/upgrade-guide/chap-upgrade-servers.adoc +++ b/openam-documentation/openam-doc-source/src/main/asciidoc/upgrade-guide/chap-upgrade-servers.adoc @@ -12,12 +12,13 @@ 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!: :example-caption!: :table-caption!: +:openam-version: 15.1.3 [#chap-upgrade-servers] @@ -72,12 +73,12 @@ When you deploy the new `.war` file, you might have to delete working files left * Navigate to the OpenAM URL, for example `\https://openam.example.com:443/openam`, and follow the instructions in the Upgrade Wizard for an interactive upgrade. -* Use the `openam-upgrade-tool-13.5.2.jar` tool for an unattended upgrade: +* Use the `openam-upgrade-tool-{openam-version}.jar` tool for an unattended upgrade: + -.. Install the `openam-upgrade-tool-13.5.2.jar` tool as described in xref:../install-guide/chap-install-tools.adoc#install-openam-config-tools["To Set Up Configuration Tools"] in the __Installation Guide__. A `sampleupgrade` file will be expanded in the directory where you install the tool. +.. Install the `openam-upgrade-tool-{openam-version}.jar` tool as described in xref:../install-guide/chap-install-tools.adoc#install-openam-config-tools["To Set Up Configuration Tools"] in the __Installation Guide__. A `sampleupgrade` file will be expanded in the directory where you install the tool. -.. Create a configuration file for the `openam-upgrade-tool-13.5.2.jar`. You can use the `sampleupgrade` file as a template to create a configuration file, for example `upgrade.properties`. +.. Create a configuration file for the `openam-upgrade-tool-{openam-version}.jar`. You can use the `sampleupgrade` file as a template to create a configuration file, for example `upgrade.properties`. + An upgrade configuration file may resemble the following: + @@ -93,9 +94,9 @@ $ grep -v "^#" upgrade.properties .. Upgrade OpenAM by using the tool with the properties file following this example: + -[source, console] +[source, console, subs="attributes"] ---- -$ java -jar openam-upgrade-tool-13.5.2.jar --file upgrade.properties +$ java -jar openam-upgrade-tool-{openam-version}.jar --file upgrade.properties Writing Backup; Done. Upgrading Services @@ -156,7 +157,7 @@ See xref:../install-guide/chap-prepare-install.adoc#prepare-configuration-store[ . (Optional) If you want to configure the upgraded system for the Core Token Service (CTS), read xref:../install-guide/chap-cts.adoc#chap-cts["Configuring the Core Token Service"] in the __Installation Guide__. -. Referral policies are not supported in OpenAM 13.5.2-15. If your OpenAM deployment has referral policies, the following warning message will appear when you upgrade your OpenAM server to OpenAM 13.5.2-15: +. Referral policies are not supported in OpenAM {openam-version}. If your OpenAM deployment has referral policies, the following warning message will appear when you upgrade your OpenAM server to OpenAM {openam-version}: + [source] @@ -174,14 +175,14 @@ OpenAM will take the following actions during the upgrade: + For example, suppose you had an OpenAM 12 deployment with a referral policy in realm A, and that referral policy referred to policies in realm B. During an upgrade, OpenAM would delete the referral policy in realm A and copy all the resource types and policy sets associated with the deleted referral policy from realm A to realm B. + -After upgrading to OpenAM 13.5.2-15, you are responsible for reconfiguring OpenAM so that policy evaluation that previously depended upon referrals continues to function correctly. You might need to take one or both of the following actions: +After upgrading to OpenAM {openam-version}, you are responsible for reconfiguring OpenAM so that policy evaluation that previously depended upon referrals continues to function correctly. You might need to take one or both of the following actions: + -* Reconfiguring your policy agent with the realm and policy set footnote:d0e728[The agent configuration UI refers to a policy set as an application.] that contain policies to be evaluated when that agent requests a policy decision from OpenAM. Previously, you might have configured the agent to use a realm that contained a referral policy. Because referral policies are not supported in OpenAM 13.5.2-15, this is no longer possible. +* Reconfiguring your policy agent with the realm and policy set footnote:d0e728[The agent configuration UI refers to a policy set as an application.] that contain policies to be evaluated when that agent requests a policy decision from OpenAM. Previously, you might have configured the agent to use a realm that contained a referral policy. Because referral policies are not supported in OpenAM {openam-version}, this is no longer possible. + For more information about configuring an agent with a realm and policy set, see xref:../admin-guide/chap-realms.adoc#realms-agents["Working With Realms and Policy Agents"] in the __Administration Guide__. -* Copying or moving a policy or a group of policies. OpenAM 13.5.2-15 has new REST API endpoints that let you copy and move policies. This functionality might be helpful when migrating away from policy deployments that use referral policies. For more information about the REST endpoints that let you copy and move policies, see xref:../dev-guide/chap-client-dev.adoc#rest-api-authz-policies-copy-move-policies["Copying and Moving Policies"] in the __Developer's Guide__. +* Copying or moving a policy or a group of policies. OpenAM {openam-version} has new REST API endpoints that let you copy and move policies. This functionality might be helpful when migrating away from policy deployments that use referral policies. For more information about the REST endpoints that let you copy and move policies, see xref:../dev-guide/chap-client-dev.adoc#rest-api-authz-policies-copy-move-policies["Copying and Moving Policies"] in the __Developer's Guide__. . Validate that the service is performing as expected.