<?xml version="1.0" encoding="UTF-8"?>

<chapter xml:id='chap-compatibility'

xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'

xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'

xsi:schemaLocation='http://docbook.org/ns/docbook

xmlns:xlink='http://www.w3.org/1999/xlink'>

<title>OpenAM Changes &amp; Deprecated Functionality</title>

<para>This chapter covers both major changes to existing functionality, and

also deprecated and removed functionality.</para>

<section xml:id="changes">

<title>Important Changes to Existing Functionality</title>

<itemizedlist>

<para>

These changes are new in OpenAM ${serverDocTargetVersion}.

</para>

<listitem>

<para>

Consistency has been improved in how OpenAM policy rules match resources.

Policy rules are now interpreted more consistently

in line with the documentation,

and more consistently across platforms and across self and subtree modes.

Before you upgrade, consider how these changes affect policy rules.

</para>

<itemizedlist>

<para>

Although the changes introduced by the improvements affect mainly edge cases,

they do impact deployments relying on previous, inconsistent behaviors.

The following points describe how OpenAM and policy agents behave

following upgrade to OpenAM 11.0.1 and web policy agents 3.3.1.

</para>

<listitem>

<para>

Policy agents configured to use subtree mode behave

as they did prior to 3.3.0.

</para>

</listitem>

<listitem>

<para>

If you created your policies with OpenAM 11.0.0 and web policy agents 3.3.0,

then note that trailing slashes are no longer stripped from resource names

(<link xlink:show="new"

xlink:href="https://bugster.forgerock.org/jira/browse/OPENAM-3509"

>OPENAM-3509</link>).

</para>

<para>

In order to match a trailing slash, your rule must end in a slash,

or a slash followed by a wildcard.

</para>

</listitem>

<listitem>

<para>

When policy agents are configured to use self mode,

trailing wildcards, except after <literal>?</literal>,

match zero or more characters.

</para>

</listitem>

<listitem>

<para>

When policy agents are configured to use self mode,

previously a trailing wildcard after a slash, <literal>/*</literal>,

matched one or more characters, whereas it now matches zero or more.

This means that a resource ending in <literal>/</literal>

previously would not match a rule ending in <literal>/*</literal>,

whereas it now does.

</para>

<para>

If you already have two rules to allow access,

one ending in <literal>/</literal> and the other in <literal>/*</literal>,

then you have nothing to do.

Only the latter rule is now required.

</para>

<para>

If however you have only rules ending in <literal>/*</literal>

and intend these to deny access to resources ending in <literal>/</literal>,

then add rules ending in <literal>/</literal>

specifically to deny access to resources ending in <literal>/</literal>.

</para>

</listitem>

<listitem>

<para>

When web policy agents are configured to use self mode,

trailing wildcards after <literal>?</literal>

match <emphasis>one</emphasis> or more characters.

This means that a resource with a trailing <literal>?</literal>

no longer matches a rule of the form <literal>/*?*</literal>,

whereas it would have matched with earlier versions.

</para>

<para>

To match the behavior of previous releases,

when using self mode with resources having empty query strings,

add additional rules without trailing wildcards as in <literal>/*?</literal>

before you upgrade OpenAM.

</para>

</listitem>

</itemizedlist>

</listitem>

<listitem>

<para>

OpenAM now handles SAML single logout (SLO) requests differently

when the user presents an invalid session

(<link xlink:show="new"

xlink:href="https://bugster.forgerock.org/jira/browse/OPENAM-3437"

>OPENAM-3437</link>).

</para>

<para>

In this scenario OpenAM no longer follows

the <literal>RelayState</literal> without validation.

To ensure that the <literal>RelayState</literal> validation succeeds,

include the <literal>metaAlias</literal> request parameter

when invoking the SLO JSPs.

</para>

</listitem>

<listitem>

<para>

For LDAP and Active Directory data store configurations

the settings for the Authentication Naming Attribute

(<literal>sun-idrepo-ldapv3-config-auth-naming-attr</literal>)

and the LDAP Users Search Attribute

(<literal>sun-idrepo-ldapv3-config-users-search-attribute</literal>)

now have the same effects as they did in versions prior to 11.0.0

(<link xlink:show="new"

xlink:href="https://bugster.forgerock.org/jira/browse/OPENAM-3428"

>OPENAM-3428</link>).

</para>

<para>

The Authentication Naming Attribute

is now used only to find the user when performing authentication.

The LDAP Users Search Attribute is used in other cases

when searching for users.

When upgrading from OpenAM 11.0.0,

make sure these attributes are correctly set in data store configurations.

</para>

</listitem>

</itemizedlist>

<itemizedlist>

<para>

The following changes were listed for OpenAM 11.0.0.

</para>

<!-- OPENAM-2051: Document the OpenAM suffix configuration changes -->

<listitem>

<para>When you create a new OpenAM custom configuration that uses an

external LDAP directory server for the configuration data store, you must

use a root suffix DN with at least two domain components, such as

<literal>dc=example,dc=com</literal>.</para>

</listitem>

<listitem>

<para>The advanced server property used to set the HTTP header name,

<literal>com.sun.identity.authentication.client.ipAddressHeader</literal>,

has replaced the legacy OpenSSO property

<literal>com.sun.identity.session.httpClientIPHeader</literal> (<link

xlink:href="https://bugster.forgerock.org/jira/browse/OPENAM-1879"

xlink:show="new">OPENAM-1879</link>).</para>

</listitem>

<listitem>

<para>Legacy naming conventions have been changed to conform to the

current product name, OpenAM.</para>

<para><filename>$HOME/.openamcfg/</filename> is the new name for

<filename>$HOME/.openssocfg/</filename>. If you upgrade, OpenAM still

supports use of <filename>$HOME/.openssocfg/</filename>, and does not

rename the folder. For new OpenAM installs, OpenAM creates the directory

with the new name, <filename>$HOME/.openamcfg/</filename>, at configuration

time.</para>

<para>Other files, such as the <filename>openam.war</filename> file, and

paths have been modified to ensure consistency with the naming

conventions.</para>

</listitem>

<listitem>

<para>OpenAM now ships with multiple .war files. You no longer have to

build custom .war files for core server-only or distributed authentication

UI installations for example.</para>

</listitem>

<listitem>

<para>In versions before OpenAM 10.1.0 the default root suffix DN for OpenAM

configuration and profile data was <literal>dc=opensso,dc=java,dc=net</literal>.

The default root suffix is now <literal><?eval ${defaultRootSuffix}?></literal>.</para>

</listitem>

<listitem>

<itemizedlist>

<para>The fix for <link xlink:show="new"

xlink:href="https://bugster.forgerock.org/jira/browse/OPENAM-1630"

>OPENAM-1630</link> changes SAML metadata signing in OpenAM to better

conform with the SAML 2.0 standard.</para>

<listitem>

<para>Metadata for hosted entities is signed using the

<literal>metadataSigningKey</literal> configured for the realm, or

inherited from the global configuration for the server.</para>

</listitem>

<listitem>

<para>OpenAM now signs the <literal>EntityDescriptor</literal> element

that contains child <literal>SPSSODescriptor</literal> or

<literal>IDPSSODescriptor</literal> elements.</para>

</listitem>

<listitem>

<para>When importing remote entity metadata with signatures, OpenAM does

not modify the signatures, but instead returns them as they were when they

were imported.</para>

</listitem>

<listitem>

<para>When OpenAM imports remote entity metadata that has no signature and

signed metadata is requested on export, OpenAM signs the metadata with

the <literal>metadataSigningKey</literal>.</para>

</listitem>

</itemizedlist>

</listitem>

<listitem>

<para>The default policy evaluation mode for new policy agent profiles is

now self rather than subtree, in order to better scale for large numbers of

policy rules.</para>

<para>Upgrade does not change existing policy agent profile configurations,

however. If you want to adopt the new default setting for existing policy

agents, you must change the setting manually.</para>

<para>To do so for Java EE policy agents, set

<literal>com.sun.identity.policy.client.cacheMode=self</literal>.</para>

<para>For web policy agents, set

<literal>com.sun.identity.agents.config.fetch.from.root.resource=false</literal>.</para>

</listitem>

<listitem>

<para>

You now specify rules for referrals in the same way as rules for policies.

</para>

<para>

For example, with previous releases a referral rule for

<literal>http://example.com/</literal> matched everything underneath.

Now you would need three rules, <literal>http://example.com/</literal>,

<literal>http://example.com/*</literal>,

and <literal>http://example.com/*?*</literal>.

When used at the end of a rule

<literal>*</literal> matches one or more characters,

rather than zero or more characters.

</para>

<para>

When you upgrade OpenAM, the upgrade tool converts existing referral rules.

</para>

</listitem>

</itemizedlist>

</section>

<section xml:id="deprecated">

<title>Deprecated Functionality</title>

<para>

The following functionality is deprecated in OpenAM 11.0.0,

and is likely to be removed in a future release.

</para>

<itemizedlist>

<listitem>

<para>With the implementation of OAuth 2.0 in this release, OAuth 1.0 has been

deprecated. OAuth 1.0 support was originally provided in OpenAM 9.</para>

</listitem>

<listitem>

<para>The Netscape LDAP API is to be removed from OpenAM, with OpenAM

using the OpenDJ LDAP SDK instead. This affects all classes in

<literal>com.sun.identity.shared.ldap.*</literal> packages.</para>

</listitem>

<listitem>

<para>OpenAM currently uses Sun Java System Application Framework (JATO).

JATO is deprecated and is likely to be replaced in a future release.</para>

</listitem>

<listitem>

<para>With the implementation of the Persistent Cookie authentication module, the

Core Authentication module persistent cookie options are deprecated and are

likely to be removed in a future release.</para>

</listitem>

<listitem>

<para>Older REST services relying on the following end points are

deprecated.</para>

<simplelist type="vert" columns="2">

<member>/identity/attributes</member>

<member>/identity/authenticate</member>

<!-- Pending replacement <member>/identity/authorize</member> -->

<member>/identity/create</member>

<member>/identity/delete</member>

<!-- Pending replacement <member>/identity/isTokenValid</member>

<member>/identity/logout</member>

<member>/identity/read</member>

<member>/identity/search</member>

<member>/identity/update</member>

<!-- Pending replacement <member>/ws/1/entitlement/decision</member>

</simplelist>

<para>The following table shows how legacy and newer end points

correspond.</para>

<table>

<title>REST End Points</title>

<tgroup cols="2">

<colspec colnum="1" colwidth="1*"/>

<colspec colnum="2" colwidth="1*"/>

<thead>

<row>

<entry>Deprecated URIs</entry>

<entry>Newer Evolving URIs</entry>

</row>

</thead>

<tbody>

<row>

<entry>/identity/attributes</entry>

<entry>/json/users</entry>

</row>

<row>

<entry>/identity/authenticate</entry>

<entry>/json/authenticate</entry>

</row>

<!--

<row>

<entry>/identity/create, /identity/delete, /identity/read,

/identity/search, /identity/update</entry>

<entry>/json/agents, /json/groups, /json/realms, /json/users</entry>

</row>

<!--

<!--

<row>

<entry>/identity/logout</entry>

<entry>/json/sessions/?_action=logout</entry>

</row>

<!--

<row>

<entry>N/A</entry>

<entry>/json/dashboard</entry>

</row>

<row>

<entry>N/A</entry>

<entry>/json/serverinfo</entry>

</row>

</tbody>

</tgroup>

</table>

<para>Find examples in the <citetitle>Developer Guide</citetitle> chapter on

<citetitle>Using RESTful Web Services</citetitle> OpenAM.</para>

<para>Support for the older REST services is likely to be removed in a

future release in favor of the newer REST services. Older REST services

will be removed only after replacement REST services are introduced.</para>

</listitem>

</itemizedlist>

</section>

<section xml:id="removed">

<title>Removed Functionality</title>

<itemizedlist>

<listitem>

<para>OpenAM Java SDK no longer supports JDK 5.</para>

</listitem>

<listitem>

<para>The <literal>iplanet-am-auth-ldap-server-check</literal> property for

LDAP and Active Directory authentication modules has been removed and

replaced with a heartbeat mechanism configurable through the LDAP Connection

Heartbeat Interval (<literal>openam-auth-ldap-heartbeat-interval</literal>)

and LDAP Connection Heartbeat Time Unit

(<literal>openam-auth-ldap-heartbeat-interval</literal>) properties for the

modules.</para>

<para>Set these new properties as necessary when you have firewalls or

load balancers that drop connections that remain idle for too long.</para>

</listitem>

<listitem>

<para>The advanced server property,

<literal>openam.session.destroy_all_sessions</literal>, has been replaced

by the built-in Global Session Service setting,

<literal>DESTROY_OLD_SESSIONS</literal>.</para>

</listitem>

<listitem>

<para>Javadoc for the client SDK is no longer delivered with the

distribution, but instead is available online.</para>

</listitem>

</itemizedlist>

</section>

</chapter>