Вы находитесь на странице: 1из 144
Installation Guide ForgeRock Access Management 5.5 ForgeRock AS 201 Mission St, Suite 2900 San Francisco,

Installation Guide

ForgeRock Access Management 5.5

ForgeRock AS 201 Mission St, Suite 2900 San Francisco, CA 94105, USA +1 415-599-1100 (US)

www.forgerock.com

Copyright © 2011-2017 ForgeRock AS.

Abstract

Guide showing you how to install ForgeRock® Access Management. ForgeRock Access Management provides authentication, authorization, entitlement, and federation software.

authorization, entitlement, and federation software. This work is licensed under the Creative Commons

To view a copy of this license, visit https://creativecommons.org/licenses/by-nc-nd/3.0/ or send a letter to Creative Commons, 444 Castro Street, Suite 900, Mountain View, California, 94041, USA.

ForgeRock® and ForgeRock Identity Platform™ are trademarks of ForgeRock Inc. or its subsidiaries in the U.S. and in other countries. Trademarks are the property of their respective owners.

UNLESS OTHERWISE MUTUALLY AGREED BY THE PARTIES IN WRITING, LICENSOR OFFERS THE WORK AS-IS AND MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND CONCERNING THE WORK, EXPRESS, IMPLIED, STATUTORY OR OTHERWISE, INCLUDING, WITHOUT LIMITATION, WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT, OR THE ABSENCE OF LATENT OR OTHER DEFECTS, ACCURACY, OR THE PRESENCE OF ABSENCE OF ERRORS, WHETHER OR NOT DISCOVERABLE. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO SUCH EXCLUSION MAY NOT APPLY TO YOU.

EXCEPT TO THE EXTENT REQUIRED BY APPLICABLE LAW, IN NO EVENT WILL LICENSOR BE LIABLE TO YOU ON ANY LEGAL THEORY FOR ANY SPECIAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR EXEMPLARY DAMAGES ARISING OUT OF THIS LICENSE OR THE USE OF THE WORK, EVEN IF LICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

DejaVu Fonts

Bitstream Vera Fonts Copyright

Copyright (c) 2003 by Bitstream, Inc. All Rights Reserved. Bitstream Vera is a trademark of Bitstream, Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy of the fonts accompanying this license ("Fonts") and associated documentation files (the "Font Software"), to reproduce and distribute the Font Software, including without limitation the rights to use, copy, merge, publish, distribute, and/or sell copies of the Font Software, and to permit persons to whom the Font Software is furnished to do so, subject to the following conditions:

The above copyright and trademark notices and this permission notice shall be included in all copies of one or more of the Font Software typefaces.

The Font Software may be modified, altered, or added to, and in particular the designs of glyphs or characters in the Fonts may be modified and additional glyphs or characters may be added to the Fonts, only if the fonts are renamed to names not containing either the words "Bitstream" or the word "Vera".

This License becomes null and void to the extent applicable to Fonts or Font Software that has been modified and is distributed under the "Bitstream Vera" names.

The Font Software may be sold as part of a larger software package but no copy of one or more of the Font Software typefaces may be sold by itself.

THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL BITSTREAM OR THE GNOME FOUNDATION BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM OTHER DEALINGS IN THE FONT SOFTWARE.

Except as contained in this notice, the names of Gnome, the Gnome Foundation, and Bitstream Inc., shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Font Software without prior written authorization from the Gnome Foundation or Bitstream Inc., respectively. For further information, contact: fonts at gnome dot org.

Arev Fonts Copyright

Copyright (c) 2006 by Tavmjong Bah. All Rights Reserved.

Permission is hereby granted, free of charge, to any person obtaining a copy of the fonts accompanying this license ("Fonts") and associated documentation files (the "Font Software"), to reproduce and distribute the modifications to the Bitstream Vera Font Software, including without limitation the rights to use, copy, merge, publish, distribute, and/or sell copies of the Font Software, and to permit persons to whom the Font Software is furnished to do so, subject to the following conditions:

The above copyright and trademark notices and this permission notice shall be included in all copies of one or more of the Font Software typefaces.

The Font Software may be modified, altered, or added to, and in particular the designs of glyphs or characters in the Fonts may be modified and additional glyphs or characters may be added to the Fonts, only if the fonts are renamed to names not containing either the words "Tavmjong Bah" or the word "Arev".

This License becomes null and void to the extent applicable to Fonts or Font Software that has been modified and is distributed under the "Tavmjong Bah Arev" names.

The Font Software may be sold as part of a larger software package but no copy of one or more of the Font Software typefaces may be sold by itself.

THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL TAVMJONG BAH BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM OTHER DEALINGS IN THE FONT SOFTWARE.

Except as contained in this notice, the name of Tavmjong Bah shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Font Software without prior written authorization from Tavmjong Bah. For further information, contact: tavmjong @ free . fr.

FontAwesome Copyright

Copyright (c) 2017 by Dave Gandy, http://fontawesome.io.

This Font Software is licensed under the SIL Open Font License, Version 1.1. This license is available with a FAQ at: http://scripts.sil.org/OFL

Table of Contents   Preface iv 1. Preparing for Installation 1 1.1. Preparing the Environment

Table of Contents

 

Preface

iv

1.

Preparing for Installation

1

1.1. Preparing the Environment

1

1.2. Preparing a Web Application Container

7

1.3. Downloading and Deploying

18

1.4. Preparing External Data Stores

21

2.

Installing and Starting Servers

41

2.1. Installing a Single Server

42

2.2. Installing Multiple Servers

57

2.3. Installing and Using the Tools

63

2.4. Starting Servers

69

3.

Implementing the Core Token Service

73

3.1. CTS Deployment Architectures

73

3.2. General Recommendations for CTS Configuration

77

3.3. CTS Deployment Steps

78

3.4. CTS Backups and Directory Services Replication Purge Delay

89

3.5. Managing CTS Tokens

90

3.6. CTS Tuning Considerations

90

4.

Securing Installations

94

4.1. Avoiding Obvious Defaults

94

4.2. Protecting Network Access

95

4.3. Securing Administration

96

4.4. Securing Communications

96

5. Removing Installations

103

6. Troubleshooting Installations

105

7. Reference

106

 

7.1. Core Token Service (CTS) Object Identifiers

106

7.2. Command-line Tool Reference

118

A. Getting Support

126

A.1. Accessing Documentation Online

126

A.2. Using the ForgeRock.org Site

126

 

A.3. Getting Support and Contacting ForgeRock

127

B. Supported Scripts

128

B.1. CTS Installation Script

128

B.2. CTS Indexing

129

C. Supported LDIF Files

132

 

Glossary

135

Preface This guide shows you how to install ForgeRock Access Management for access and federation

Preface

This guide shows you how to install ForgeRock Access Management for access and federation management.

This guide covers the install, upgrade, and uninstall procedures that you theoretically perform only once per version. This guide aims to provide you with at least some idea of what happens behind the scenes when you perform the steps.

This guide is written for anyone installing Access Management to manage and federate access to web applications and web-based resources.

Almost anyone can learn something from this guide, though a background in access management and maintaining web application software can help. You do need some background in managing services on your operating systems and in your application servers. You can nevertheless get started with this guide, and then learn more as you go along.

Unless you are planning a throwaway evaluation or test installation, read the Release Notes before you get started.

About ForgeRock Identity PlatformSoftware

ForgeRock Identity Platform™ is the only offering for access management, identity management, user-managed access, directory services, and an identity gateway, designed and built as a single, unified platform.

The platform includes the following components that extend what is available in open source projects to provide fully featured, enterprise-ready software:

• ForgeRock Access Management (AM)

• ForgeRock Identity Management (IDM)

• ForgeRock Directory Services (DS)

• ForgeRock Identity Gateway (IG)

Preparing for Installation Preparing the Environment

Preparing for Installation Preparing the Environment

Chapter 1

Preparing for Installation

This chapter covers prerequisites for installing AM software, including how to prepare your environment, how to set up your application server to run AM, how to prepare directory servers to store configuration data, and how to prepare an identity repository to handle AM identities.

1.1. Preparing the Environment

This section covers setting up the environment in which to run AM.

The topics covered in this section are:

Preparing a Fully Qualified Domain Name

Preparing a Java Environment

Setting Maximum File Descriptors

For more information about supported operating systems and Java requirements, see Section 2.2, "Operating System Requirements" and Section 2.3, "Java Requirements" in the Release Notes.

1.1.1. Preparing a Fully Qualified Domain Name

AM requires that you provide a fully qualified domain name (FQDN) when you configure it. Before

you set up AM, be sure that your system has an FQDN, such as

purposes, you can give your system an alias using the

openam.example.com . For evaluation

file on UNIX systems or

/etc/hosts
/etc/hosts

%SystemRoot%

\system32\drivers\etc\hosts

on Windows. For production deployments, make sure the FQDN is properly

assigned using DNS.

Do not use the hostname

cookies, which are returned based on the domain name. You can set the cookie domain name value to an empty string for host-only cookies or to any non-top level domain. For example, if you install AM

and use openam.example.com as the host, you can set the cookie domain name as example.com .

localhost
localhost

for AM, not even for testing purposes. AM relies on browser

Important

Do not configure a top-level domain as your cookie domain as browsers will reject them.

Top-level domains are browser-specific. Some browsers, like Firefox, also consider special domains like Amazon's web service (for example, ap-southeast-2.compute.amazonaws.com) to be a top-level domain.

Preparing for Installation Preparing a Java Environment

Preparing for Installation Preparing a Java Environment

Check the effective top-level domain list at https://publicsuffix.org/list/effective_tld_names.dat to ensure that you do not set your cookie to a domain in the list.

1.1.2. Preparing a Java Environment

AM software depends on a Java runtime environment. Check the output of the java -version command to make sure your version is supported according to Section 2.3, "Java Requirements" in the Release Notes.

The suggestions in this section pertain to AM deployments with the following characteristics:

• The deployment has a dedicated DS server for the Core Token Service. The host running this directory server is a high-end server with a large amount of memory and multiple CPUs.

• The AM server is configured to use stateful sessions.

Important

It is important to keep your Java software up-to-date with the latest supported version. Make sure that your

JAVA_HOME

environment variable always points to the latest supported Java version.

1.1.2.1. Settings For Oracle Java Environments

When using an Oracle Java environment set at least the following options:

-server Use -server rather than -client . -Xmx1g (minimum)
-server
Use
-server
rather than
-client
.
-Xmx1g
(minimum)

AM requires at least a 1 GB heap. If you are including the embedded DS, AM requires at least a 2 GB heap, as 50% of that space is allocated to DS. Higher volume and higher performance deployments require additional heap space.

-XX:MetaspaceSize=256m

Set the metaspace memory size to 256 MB.

-XX:MaxMetaspaceSize=256m

Set the maximum metaspace memory size to 256 MB.

For additional JVM tuning and security recommendations, see Section 1.1.2.4, "Tuning Java Virtual Machine Settings".

1.1.2.2. Settings For IBM Java Environments

When using an IBM Java environment, set at least the following options:

Preparing for Installation Preparing a Java Environment

Preparing for Installation Preparing a Java Environment

-DamCryptoDescriptor.provider=IBMJCE

-DamKeyGenDescriptor.provider=IBMJCE

Use the IBM Java Cryptography Extensions.

(minimum)Use the IBM Java Cryptography Extensions. AM requires at least a 1 GB heap. If you

AM requires at least a 1 GB heap. If you are including the embedded DS, AM requires at least

a 2 GB heap, as 50% of that space is allocated to DS. Higher volume and higher performance

deployments require additional heap space.

1.1.2.3. Settings for OpenJDK Java Environment

When using an OpenJDK Java environment set at least the following options.

-Xmx1024m
-Xmx1024m

(minimum)

AM requires at least a 1 GB heap. If you are including the embedded DS, AM requires at least

a 2 GB heap, as 50% of that space is allocated to DS. Higher volume and higher performance

deployments require additional heap space. Recommended:

-Xmx2048m .
-Xmx2048m
.

-XX:MetaspaceSize=256m

Set the initial metadata space size to 256 MB.

1.1.2.4. Tuning Java Virtual Machine Settings

This section gives some initial guidance on configuring the JVM for running AM. These settings provide a strong foundation to the JVM before a more detailed garbage collection tuning exercise, or as best practice configuration for production:

Table 1.1. Heap Size Settings

JVM Parameters

 

Suggested Value

Description

-Xms
-Xms

&

-Xmx
-Xmx

At least 1 GB (2 GB with embedded DS), in production environments at least 2 GB to 3 GB. This setting depends on the available physical memory, and on whether a 32- or 64-bit JVM is used.

-

-server
-server
 

-

Ensures the server JVM is used

-XX:MetaspaceSize

&

-XX:MaxMetaspaceSize

Set both to 256 MB

Controls the size of the metaspace in the JVM

 

-Dsun.net.client.defaultReadTimeout

 

60000

Controls the read timeout in the Java HTTP client implementation

 
Preparing for Installation Preparing a Java Environment

Preparing for Installation Preparing a Java Environment

JVM Parameters

Suggested Value

Description

   

This applies only to the Sun/ Oracle HotSpot JVM.

-Dsun.net.client.defaultConnectTimeout

High setting:

Controls the connect timeout in the Java HTTP client

30000

implementation

(30 seconds)

When you have hundreds of incoming requests per second, reduce this value to avoid a huge connection queue.

This applies only to the Sun/ Oracle HotSpot JVM.

Table 1.2. Security Settings

JVM Parameters

Suggested Value

Description

-Dhttps.protocols

TLSv1,TLSv1.1,TLSv1.2

Controls the protocols used for outbound HTTPS connections from AM.

 

Specify one or more of the following values, separated by commas:

• TLSv1

• TLSv1.1

• TLSv1.2

This setting applies only to Sun/Oracle Java environments.

-Dorg.forgerock.openam.ldap.secure.protocol

-

Controls the protocol AM uses to connect to various external resources.

.version
.version

Specify one or more of the following values, separated by commas:

• TLSv1

• TLSv1.1

• TLSv1.2

Note

For

-Dhttps.protocols

, specify the protocol version(s) Java clients can use to connect to AM.

For

-Dorg.forgerock.openam.ldap.secure.protocol.version

, see Section 4.4, "Securing Communications" for a

list of external resources to which communication is affected.

Preparing for Installation Setting Maximum File Descriptors

Preparing for Installation Setting Maximum File Descriptors

Specify a single protocol if AM will only use that protocol when connecting to affected external resources. For

example, a value of

TLSv1.2
TLSv1.2

configures AM to only use the TLSv1.2 protocol to connect.

Specify a comma-separated list with multiple protocols if AM will use the most secure protocol supported by the

external resources. For example, a value of

protocol to connect to external configuration and user data stores. If a TLSv1.2 connection is not supported, AM attempts to use TLSv1.1 to connect. If TLSv1.1 is not supported, AM uses TLSv1.

TLSv1,TLSv1.1,TLSv1.2

configures AM to attempt to use the TLSv1.2

Table 1.3. Garbage Collection Settings

JVM Parameters Suggested Value Description -verbose:gc - Verbose garbage collection reporting -Xloggc:
JVM Parameters
Suggested Value
Description
-verbose:gc
-
Verbose garbage collection
reporting
-Xloggc:
$CATALINA_HOME/logs/gc.log
Location of the verbose
garbage collection log file
-XX:+PrintClassHistogram
-
Prints a heap histogram when
a SIGTERM signal is received
by the JVM
-XX:+PrintGCDetails
-
Prints detailed information
about garbage collection
-XX:+PrintGCTimeStamps
-
Prints detailed garbage
collection timings
-XX:+HeapDumpOnOutOfMemoryError
-
Out of Memory errors
generate a heap dump
automatically
-XX:HeapDumpPath
$CATALINA_HOME/logs/
Location of the heap dump
heapdump.hprof
-XX:+UseConcMarkSweepGC
-
Use the concurrent mark
sweep garbage collector
-XX:+UseCMSCompactAtFullCollection
-
Aggressive compaction at full
collection
-XX:+CMSClassUnloadingEnabled
-
Allow class unloading during
CMS sweeps

1.1.3. Setting Maximum File Descriptors

If you use the embedded DS, verify that DS has enough file descriptors set in the operating system to open many files, especially when handling multiple client connections. For example, Linux systems in particular often set a limit of 1024 per user, which is too low for DS.

In general, do not set up file descriptors to a same value or higher than the maximum number allowed in the system itself. Please consult your operating system documentation for your particular deployment.

Preparing for Installation Enabling RSA SecurID Support

Preparing for Installation Enabling RSA SecurID Support

DS should have access to at least 64K (65536) file descriptors. The embedded DS runs inside the AM

process space. When running AM as user

to set user limits, you can set soft and hard limits by adding these lines to the file.

openam
openam

on a Linux system that uses

/etc/security/limits.conf

openam soft nofile 65536 openam hard nofile 131072

You can verify the new soft limit the next time you log in as user

openam
openam

with the ulimit -n command.

$ ulimit -n

65536

You can check the Linux system overall maximum as follows:

$ cat /proc/sys/fs/file-max

204252

If the overall maximum is too low, you can increase it as follows:

1. As superuser, edit the maximum.

/etc/sysctl.conf

file to set the kernel parameter

fs.file-max
fs.file-max

to a higher

2. Run the sysctl -p command to reload the settings in

/etc/sysctl.conf .

3. Open the

/proc/sys/fs/file-max

file again to confirm that it now corresponds to the new maximum.

4. If you are running a daemon process on some Linux systems, you may need to add a

LimitNOFILE
LimitNOFILE

directive. For example, if running Tomcat, under the Services section in

tomcat.service

, add the line:

/usr/lib/systemd/system/

LimitNOFILE=65536

5. To reload the daemon, run:

$ systemctl daemon-reload

6. Restart Tomcat:

$ systemctl start tomcat && journalctl --follow -u tomcat

7. Check the file descriptors:

$ cat /proc/<tomcat pid>/limit | grep 'open files'

Again, consult your operating system documentation for specifics to your deployment.

1.1.4. Enabling RSA SecurID Support

To use the SecurID authentication module, you must first build an AM war file that includes

the supporting library, for example

authapi-2005-08-12.jar

, which you must obtain from RSA. The

authapi-2005-08-12.jar

file also requires a dependency file,

crypto.jar

, which you can also obtain from

RSA.

Preparing for Installation Preparing a Web Application Container

Preparing for Installation Preparing a Web Application Container

1. Unpack the AM

 

.war

file. For example:

$ mkdir /tmp/openam

 

$ cd /tmp/openam/

$ jar -xf ~/Downloads/openam/AM-5.5.1.war

2. 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. For example:

$

cp /path/to/authapi-2005-08-12.jar WEB-INF/lib/

 

3. Pack up the AM

 

.war

file. For example:

$

jar -cf

/openam.war

*

4. Deploy the new

.war
.war

file. For more information, see Section 1.3.2, "Deploying".

In this example, the

.war
.war

file to deploy is

/tmp/openam.war

.

1.2. Preparing a Web Application Container

This section covers setting up a web application container in which to run AM.

The topics covered in this section are:

Preparing Apache Tomcat

Preparing for JBoss and WildFly

Preparing Oracle WebLogic

Preparing IBM WebSphere

Enabling CORS Support

Preparing AES Wrap Encryption

Note

If a Java Security Manager is enabled for your web application container, add permissions before installing AM.

For a list of supported web application containers, see Section 2.4, "Web Application Container Requirements" in the Release Notes.

1.2.1. Preparing Apache Tomcat

AM examples often use Apache Tomcat (Tomcat) as the deployment container. Tomcat is installed on

openam.example.com

JVM start up

, and listens on the default ports without a Java Security Manager enabled.

Preparing for Installation Preparing Apache Tomcat

Preparing for Installation Preparing Apache Tomcat

AM core services require a minimum JVM heap size of 1 GB, and a metadata space size of up to 256 MB. If you are including the embedded DS, AM requires at least a 2 GB heap, as 50% of that space is allocated to DS. See Section 1.1.2, "Preparing a Java Environment" for details.

Set the

tuning for your environment. For example:

CATALINA_OPTS

environment variable in Tomcat's start-up script or service with the appropriated

CATALINA_OPTS="-server -Xmx2g -XX:MetaspaceSize=256m -XX:MaxMetaspaceSize=256m"

Some AM resources have names that can contain slash characters (/), for example policy names, application names, and SAML v2.0 entities. These slash characters can cause unexpected behavior when running AM on Tomcat.

To work around this issue, configure Tomcat to allow encoded slash characters by adding the

org
org

.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true

property to the

CATALINA_OPTS

variable. For

example:

CATALINA_OPTS= "-server -Xmx2g -XX:MetaspaceSize=256m -XX:MaxMetaspaceSize=256m \ -Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true"

Cookie Domains

You can set the cookie domain name value to an empty string for host-only cookies or to any non-

top level domain. For example, if you install AM and use

the cookie domain name as

installation, see Procedure 2.3, "To Custom Configure an Instance".

openam.example.com

as the host, you can set

example.com

. For information about configuring the cookie domain during

Encoding and Security

ForgeRock recommends that you edit the Tomcat <Connector> configuration to set

. UTF-8 URI encoding ensures that URL-encoded characters in the paths of URIs are correctlyyou edit the Tomcat <Connector> configuration to set decoded by the container. This is particularly useful

decoded by the container. This is particularly useful if your applications use the AM REST APIs and some identifiers, such as user names, contain special characters.

URIEncoding="UTF

You should also ensure the SSL v3.0 protocol.

sslProtocol
sslProtocol

property is set to

TLS
TLS

, which disables the potentially vulnerable

<Connector> configuration elements are found in the configuration file,

/path/to/tomcat/conf/

server.xml
server.xml

. The following excerpt shows an example <Connector> with the

URIEncoding

and

sslProtocol
sslProtocol

attributes set appropriately:

<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" maxThreads="150" scheme="https" secure="true" clientAuth="false" sslProtocol="TLS" URIEncoding="UTF-8" />

Embedded DS

When you set up AM with the embedded DS, make sure that Tomcat's

autoDeploy attribute is set to

false
false

. If

autoDeploy

is set to

true .war
true
.war

, the host dynamically deploys and updates any web application, for

appBase .
appBase
.

example, when a new

file is dropped into the

Preparing for Installation Preparing for JBoss and WildFly

Preparing for Installation Preparing for JBoss and WildFly

1.2.2. Preparing for JBoss and WildFly

You can deploy AM on JBoss AS, JBoss EAP, and WildFly. The procedures listed here provide steps for configuring JBoss AS, JBoss EAP, and WildFly for AM.

After configuring JBoss or WildFly, you then prepare AM for deployment by making a few changes to

the contents of the AM

.war
.war

archive.

Procedure 1.1, "To Prepare JBoss or WildFly"

Procedure 1.2, "To Prepare for JBoss and WildFly"

Procedure 1.1. To Prepare JBoss or WildFly

1. Stop JBoss or WildFly.

2. The default JVM settings do not allocate sufficient memory to AM. This step shows one method that you can use to modify the JVM settings. For other methods, see either the JBoss Application Server Official Documentation Page or the JVM Settings page in the WildFly documentation

a. Open the

standalone.conf

standalone mode.

file in the

/path/to/jboss/bin

directory for JBoss or WildFly in

b. Check the JVM settings associated with

JAVA_OPTS .
JAVA_OPTS
.

Change the JVM heap size to

might already exceed the recommended value. If you are using the embedded version of DS, the minimum heap size may be higher. For details on the JVM options to use, see Section 1.1.2, "Preparing a Java Environment".

-Xmx1g
-Xmx1g

. The default JVM heap size for some versions of JBoss

Change the metaspace size to amount.

-XX:MaxMetaspaceSize=256m

if the default size does not exceed this

c. Set the following JVM

JAVA_OPTS
JAVA_OPTS

setting in the same file:

-Dorg.apache.tomcat.util.http.ServerCookie.ALWAYS_ADD_EXPIRES=true

Verify that the headers include the

of Internet Explorer and Microsoft Edge do not support

Expires

attribute rather than only

Max-Age .
Max-Age
.
Max-Age
Max-Age

, as some versions

3. Now deploy the

openam.war
openam.war

file into the appropriate deployment directory. The directory varies

depending on whether you are running in standalone or domain mode.

Procedure 1.2. To Prepare for JBoss and WildFly

To prepare AM to run with JBoss or WildFly, you should make a change to the AM

WildFly deploy applications from different temporary directories every time you restart the container,

which would require reconfiguring AM. To avoid problems, change the AM

war
war

file. JBoss and

war
war

file as follows:

Preparing for Installation Preparing Oracle WebLogic

Preparing for Installation Preparing Oracle WebLogic

1. If you have not already done so, create a temporary directory and expand the example:

AM-5.5.1.war

file. For

$ cd /tmp

$ mkdir /tmp/openam ; cd /tmp/openam

$ jar xvf ~/Downloads/AM-5.5.1.war

2. Locate the

bootstrap.properties

Update the

and then save the change.

# configuration.dir=

file in the

WEB-INF/classes

directory of the expanded

war
war

archive.

line in this file to specify a path with read and write permissions,

# This property should also be used when the system user that

# is running the web/application server process does not have

# a home directory. i.e. System.getProperty("user.home") returns

# null.

configuration.dir=/my/readwrite/config/dir

3. If you are deploying AM on JBoss AS or JBoss EAP, remove the

directory of the expanded war

AS or JBoss EAP, remove the directory of the expanded war archive. jboss-all.xml file from the

archive.

jboss-all.xml

file from the

WEB-INF
WEB-INF

Be sure not to remove this file if you are deploying AM on WildFly.

4.

Rebuild the

this file if you are deploying AM on WildFly. 4. Rebuild the file. $ jar cvf

file.

$ jar cvf

/openam.war

*

5. If you plan to deploy multiple cookie domains with WildFly, you must configure the

com.sun
com.sun

.identity.authentication.setCookieToAllDomains

property after you have installed the AM server. See

Section 2.2.5, "Handling Multiple Cookie Domains When Using Wildfly" for more information.

1.2.3. Preparing Oracle WebLogic

To deploy AM in WebLogic, perform the following steps:

1. Update the JVM options as described in Section 1.1.2, "Preparing a Java Environment".

2. Customize the

AM-5.5.1.war

file as described in Procedure 1.3, "To Prepare for Oracle WebLogic".

Procedure 1.3. To Prepare for Oracle WebLogic

To prepare AM to run in WebLogic, change the AM

able to find the AM configuration files. Be sure to make this change whenever you deploy a new file as part of an AM upgrade.

war
war

file to ensure that the AM upgrade process is

war
war

Change the AM

file as follows:to ensure that the AM upgrade process is war Change the AM 1. Create a temporary

1. Create a temporary directory and expand the

AM-5.5.1.war

file. For example:

Preparing for Installation Preparing IBM WebSphere

Preparing for Installation Preparing IBM WebSphere

$ cd /tmp

$ mkdir /tmp/openam ; cd /tmp/openam

$ jar xvf ~/Downloads/AM-5.5.1.war

2. Locate the

bootstrap.properties

file in the

WEB-INF/classes

directory of the expanded

file.file in the WEB-INF/classes directory of the expanded 3. Update the # configuration.dir= line in the

3. Update the

# configuration.dir=

line in the

write permissions. For example:

bootstrap.properties

file to specify a path with read and

# This property should also be used when the system user that

# is running the web/application server process does not have

# a home directory. i.e. System.getProperty("user.home") returns

# null.

configuration.dir=/my/readwrite/config/dir

If installing on Windows, the specified path should have slashes / and not backslashes \.

4.

Rebuild the AM-5.5.1.war file:

$ jar cvf

/AM-5.5.1.war

*

1.2.4. Preparing IBM WebSphere

Before you deploy AM, use the Administrator console to update JVM options as described in Section 1.1.2, "Preparing a Java Environment".

Procedure 1.4. To Prepare for IBM WebSphere

To prepare AM to run in WebSphere, change the AM

is able to find the AM configuration files. Be sure to make this change whenever you deploy a new file as part of an AM upgrade.

war
war

file to ensure that the AM upgrade process

war
war

Change the AM

file as follows:file to ensure that the AM upgrade process war Change the AM Note If installing on

Note

If installing on Windows, the specified paths should have slashes / and not backslashes \.

1. Create a temporary directory and expand the

AM-5.5.1.war

file. For example:

$ cd /tmp

$ mkdir /tmp/openam ; cd /tmp/openam

$ jar xvf ~/Downloads/AM-5.5.1.war

2. Locate the

bootstrap.properties

file in the

WEB-INF/classes

directory of the expanded

file.file in the WEB-INF/classes directory of the expanded Update the write permissions. For example: #

Update the

write permissions. For example:

# configuration.dir=

line in the

bootstrap.properties

file to specify a path with read and

Preparing for Installation Enabling CORS Support

Preparing for Installation Enabling CORS Support

# This property should also be used when the system user that

# is running the web/application server process does not have

# a home directory. i.e. System.getProperty("user.home") returns

# null.

configuration.dir=/my/readwrite/config/dir

3. (Optional) If you are using an IBM JDK, replace the default

WEB-INF/template /keystore/

keystore.jceks

steps:

keystore file with one generated using the IBM JDK, by performing the following

a. Generate a new, empty

keystore.jceks

keystore file in IBM JDK format:

$ keytool -genkey -storetype jceks -keystore keystore.jceks -storepass changeit -keypass changeit

b. Copy the new

keystore.jceks

keystore file into the expanded .war file, overwriting the existing

WEB-INF/template/keystore/keystore.jceks

keystore file:

$ cp keystore.jceks /tmp/openam/WEB-INF/template/keystore/keystore.jceks

4. Rebuild the

AM-5.5.1.war

file:

$ jar cvf

/AM-5.5.1.war

*

In addition, configure WebSphere to load classes from AM bundled libraries before loading classes from libraries delivered with WebSphere. The following steps must be completed after you deploy AM into WebSphere:

1. In WebSphere administration console, browse to Application > Application Type > WebSphere enterprise applications > AM Name > Class loading and update detection.

2. Set Class loader order > Classes loaded with local class loader first (parent last).

3. Ensure that the value of the WAR class loader policy property is set to the default value:

loader for each WAR file in application

.

4. Save your work.

1.2.5. Enabling CORS Support

Class
Class

Cross-origin resource sharing (CORS) allows requests to be made across domains from user agents. AM supports CORS, but CORS is not enabled by default.

To enable CORS support, edit the deployment descriptor file before deploying AM. CORS support is implemented as a servlet filter, and so you add the filter's configuration to the deployment descriptor file.

Preparing for Installation Enabling CORS Support

Preparing for Installation Enabling CORS Support

Procedure 1.5. To Enable CORS Support

1. If you have not yet deployed AM:

a. Unpack the AM

.war
.war

file. For example:

$ mkdir /tmp/openam

$ cd /tmp/openam/

$ jar -xf ~/Downloads/openam/AM-5.5.1.war

b. Open the deployment descriptor file

WEB-INF/web.xml in a text editor.

2. If you have already deployed AM:

• Open the deployment descriptor file

in a text editor. The location of the file dependsalready deployed AM: • Open the deployment descriptor file on your web application container, for example

on your web application container, for example in Tomcat it might be located at:

/path/to/

tomcat/webapps/openam/WEB-INF/web.xml

.

3. In the deployment descriptor file, add a

<filter-mapping>

element containing the name and a URL

pattern for the filter. The URL pattern specifies the endpoints to which AM applies the CORS

filter.

To enable CORS support for all endpoints, use the following example:

<filter-mapping> <filter-name>CORSFilter</filter-name> <url-pattern>/*</url-pattern><!-- CORS support for all endpoints --> </filter-mapping>

To enable CORS support for individual endpoints instead of all endpoints, add multiple

mapping>

elements, one for each endpoint:

<filter-
<filter-

<filter-mapping>

<filter-name>CORSFilter</filter-name>

<url-pattern>/uma/*</url-pattern>

</filter-mapping>

<filter-mapping>

<filter-name>CORSFilter</filter-name>

<url-pattern>/json/*</url-pattern>

</filter-mapping>

<filter-mapping> <filter-name>CORSFilter</filter-name>

<url-pattern>/oauth2/*</url-pattern>

</filter-mapping>

4. In the deployment descriptor file, add a

<filter>
<filter>

element to configure the filter.

The available parameters for the

<filter>
<filter>

element are as follows:

Preparing for Installation Enabling CORS Support

Preparing for Installation Enabling CORS Support

<filter-name>

Specifies the name for the filter. Must match the name specified in the elements.

<filter-mapping>

<filter-class>

Specifies the Java class the implements the CORS filter. Should be set to the default

.forgerock.openam.cors.CORSFilter

.

methods
methods

(required)

org
org

A comma-separated list of HTTP methods allowed when making CORS requests to AM.

Example:

GET,POST,PUT,PATCH,OPTIONS,DELETE

origins (required)

A comma-separated list of the origins allowed when making CORS requests to AM. Wildcards

are not supported - each value should be an exact match for the origin of the CORS request.

Example:

http://example.com,https://example.org:8433

Tip

During development you may not be using fully-qualified domain names as the origin of a CORS

request, for example using the

the list. For example,

file://
file://

protocol locally. If so, you can add these non-FQDN origins to

http://example.com,https://example.org:8433,file://,null

.

allowCredentials

(optional)

Whether to take allow requests with credentials in either HTTP cookies or HTTP

authentication information. Accepts

false
false

(the default) or

true .
true
.

Set to

information in cookies when making requests.

true
true

if you send

Authorization

headers as part of the CORS requests, or need to include

headers
headers

(optional)

A comma-separated list of request header names allowed when making CORS requests to AM.

Example:

iPlanetDirectoryPro,X-OpenAM-Username,X-OpenAM-Password,Accept-API-Version,Content-Type

,If-Match,If-None-Match

By default, the following simple headers are explicitly allowed:

the following simple headers are explicitly allowed: • Cache-Control • Content-Language Installation Guide

Cache-Control

simple headers are explicitly allowed: • Cache-Control • Content-Language Installation Guide ForgeRock Access

Content-Language

Preparing for Installation Enabling CORS Support

Preparing for Installation Enabling CORS Support

• Expires • Last-Modified • Pragma
Expires
Last-Modified
Pragma

If you do not specify a value for this property, the presence of any header in the CORS request, other than the simple headers listed above, will cause the request to be rejected.

Headers commonly used when accessing an AM server include the following:

Table 1.4. Commonly Used Headers

Header

Information

iPlanetDirectoryPro

 

Used for session information.

 

See Section 6.1, "Implementing Session State" in the Authentication and Single Sign-On Guide.

X-OpenAM-Username

,

X-OpenAM-Password

Used to pass credentials in REST calls that use the HTTP POST method.

 

See Section A.5, "Authentication and Logout" in the Authentication and Single Sign-On Guide.

Accept-API-Version

 

Used to request a specific AM endpoint version.

 

See Section A.3, "REST API Versioning" in the Authentication and Single Sign-On Guide.

Content-Type

Required for cross-origin calls to AM REST API endpoints.

If-Match , If-None-Match
If-Match
,
If-None-Match
 

Used to ensure the correct version of a resource will be affected when making a REST call, for example when updating an UMA resource set.

 

See Procedure 3.8, "To Update an UMA Resource Set" in the User-Managed Access (UMA) 2.0 Guide .

Caution

If you need to accept all origins by allowing the use of

not allow

request forgery (CSRF) attacks.

Access-Control-Allowed-Origin=*

headers, do

Content-Type

headers. Allowing the use of both types of headers exposes AM to cross-site

expectedHostname (optional)

The name of the host expected in the

be refused if the specified value does not match.

Host
Host

header of CORS requests to AM. The request will

Preparing for Installation Enabling CORS Support

Preparing for Installation Enabling CORS Support

If

not specified, any host value is accepted.

If

the AM server is behind a load-balancer, specify the public name of the load balancer.

Example:

openam.example.com:8080

exposeHeaders (optional)

A comma-separated list of response header names the AM returns in the

Headers
Headers

header.

Access-Control-Expose-

User agents can make use of any headers that are listed in this property, as well as the simple response headers, which are as follows:

Cache-Control

 

Content-Language

Expires

Last-Modified

 

Pragma
Pragma

Content-Type

 

User agents must filter out all other response headers.

Example:

Access-Control-Allow-Origin,Access-Control-Allow-Credentials,Set-Cookie

maxAge
maxAge

(optional)

The maximum length of time that the browser is allowed to cache the pre-flight response, in seconds.

The default is

600 .
600
.

The following is an example excerpt from a configured testing and development:

web.xml
web.xml

file that could be used during

<filter-mapping>

<filter-name>CORSFilter</filter-name>

<url-pattern>/uma/*</url-pattern>

</filter-mapping>

<filter-mapping>

<filter-name>CORSFilter</filter-name>

<url-pattern>/json/*</url-pattern>

</filter-mapping>

<filter-mapping>

Preparing for Installation Enabling CORS Support

Preparing for Installation Enabling CORS Support

<filter-name>CORSFilter</filter-name>

<url-pattern>/oauth2/*</url-pattern>

</filter-mapping>

<filter> <filter-name>CORSFilter</filter-name> <filter-class>org.forgerock.openam.cors.CORSFilter</filter-class> <init-param> <param-name>methods</param-name> <param-value>POST,PUT,OPTIONS</param-value> </init-param> <init-param> <param-name>origins</param-name>

<param-value>http://localhost:8000,null,file://,https://example.org:8433</param-value>

</init-param> <init-param> <param-name>allowCredentials</param-name> <param-value>true</param-value> </init-param> <init-param> <param-name>headers</param-name> <param-value>X-OpenAM-Username,X-OpenAM-Password,X-Requested-With,Accept,iPlanetDirectoryPro</ param-value> </init-param> <init-param> <param-name>expectedHostname</param-name>

<param-value>openam.example.com:8080</param-value>

</init-param> <init-param> <param-name>exposeHeaders</param-name> <param-value>Access-Control-Allow-Origin,Access-Control-Allow-Credentials,Set-Cookie</param-value> </init-param> <init-param> <param-name>maxAge</param-name>

<param-value>1800</param-value>

</init-param>

</filter>

5. Save your changes.

6. If you have not yet deployed AM:

a. Pack up the AM

file to deploy.6. If you have not yet deployed AM: a. Pack up the AM $ jar -cf

$ jar -cf

/openam.war

*

b. Deploy the new

file.to deploy. $ jar -cf /openam.war * b. Deploy the new In this example, the .war

In this example, the

.war
.war

file to deploy is

/tmp/openam.war

.

For more information, see Section 1.3.2, "Deploying".

7. If you have already deployed AM:

• Restart AM or the web container where it runs.

Preparing for Installation Preparing AES Wrap Encryption

Preparing for Installation Preparing AES Wrap Encryption

For more details on CORS, see the Cross-Origin Resource Sharing specification.

1.2.6. Preparing AES Wrap Encryption

By default, AM uses the Java Cryptography Extension (JCE) encryption class to encrypt and decrypt system password and keys in the configuration store and by other components, such as agents.

If your deployment requires a more secure encryption algorithm, AM supports the Advanced Encryption Standard (AES) Key Wrap algorithm (RFC3394). AM's implementation of AES Key Wrap uses the Password-Based Key Derivation Function 2 (PBKDF2) (RFC2898) with HMAC-SHA1. This allows administrators to choose key size hash algorithms, such as SHA256, SHA384, or SHA512.

Important

The AES Wrap Encryption algorithm is only enabled when installing AM. There is no current upgrade path for existing installations.

The Security Token Service (STS) feature does not support the AES Wrap Encryption algorithm. Make sure that you do not deploy this feature in an AM instance configured to use the AES Wrap Encryption algorithm.

Procedure 1.6. To Configure AES Key Wrap Encryption for Tomcat

• Edit your container startup scripts, for example properties in Tomcat:

setenv.sh
setenv.sh

, to set the following JVM system

JAVA_OPTS="$JAVA_OPTS -Dcom.iplanet.security.encryptor=org.forgerock.openam.shared.security.crypto .AESWrapEncryption" JAVA_OPTS="$JAVA_OPTS -Dorg.forgerock.openam.encryption.key.iterations=20000" JAVA_OPTS="$JAVA_OPTS -Dorg.forgerock.openam.encryption.key.size=256" JAVA_OPTS="$JAVA_OPTS -Dorg.forgerock.openam.encryption.key.digest=SHA512"

Only the first line in the example is required. The other lines are configurable to meet the needs of your deployment. Key sizes greater than 128 bits require that the JCE Unlimited Strength policy files be installed in your system. PBKDF2 using SHA256, SHA384, and SHA512 is only available on Java 8.

1.3. Downloading and Deploying

This section covers acquiring the AM software and deploying it into a web application container.

The topics covered in this section are:

Obtaining Software

Deploying

Preparing for Installation Obtaining Software

Preparing for Installation Obtaining Software

1.3.1. Obtaining Software

The ForgeRock BackStage website hosts downloads, including a

components, the

documentation. Verify that you review the Software License and Subscription Agreement presented before you download AM files.

.zip
.zip

file with all of the AM

.war
.war

file, AM tools, the configurator, policy agents, Identity Gateway, and

For each release of the AM, you can download the entire package as a

or only the administrative tools as a build the release.

.zip
.zip

file, only the AM

.war
.war

file,

.zip
.zip

archive. The Archives only have the AM source code used to

After you download the content.

.zip
.zip

file, create a new directory for AM, and unzip the

.zip
.zip

file to access the

$ cd ~/Downloads

$ mkdir openam ; cd openam

$ unzip ~/Downloads/AM-5.5.1.zip

When you unzip the archive of the entire package, you get ldif, license, and legal directories in addition to the following files:

Table 1.5. Distribution Files

File

Description

 

AM-5.5.1.war

 

The distribution

.war
.war

file includes the core server code with an embedded

 

DS server, which stores configuration data and simplifies deployments. The distribution includes an administrative graphical user interface (GUI)

Web console. During installation, the

.war
.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.json

file in the AM installation directory, from environment variables, or from a combination of the two. This file is also available to download individually.

Fedlet-5.5.1.zip

 

AM provides an AM 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.

IDPDiscovery-5.5.1.war

 

AM provides an IdP Discovery Profile (SAMLv2 binding profile) for its IdP Discovery service. The profile keeps track of the identity providers for each user.

 

AM-Soap-STS-Server-5.5.1.war

AM provides a SOAP-based security token service (STS) server that issues tokens based on the WS-Security protocol a .

SSOAdminTools-5.1.1.1.zip

 

AM provides an

ssoadm
ssoadm

command-line tool that allows administrators to

 

configure and maintain AM 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.

 

SSOConfiguratorTools-5.1.1.1

AM provides configuration and upgrade tools for installing and maintaining

.zip
.zip

your server. The

zip

distribution file contains libraries, legal notices, and

supported binaries for these configuration tools. Also, you can view example

Preparing for Installation Deploying

Preparing for Installation Deploying

File

Description

 

configuration and upgrade properties files that can be used as a template for your deployments.

a AM also provides REST-based STS service endpoints, which you can directly utilize on the AM server.

1.3.2. Deploying

After you have downloaded AM software, deploy it to your installed application container.

Note that deploying AM only extracts the files into the application container, prior to installation and configuration. Deploying AM also makes LDIF files available, which can be used to prepare external data stores for use with AM.

Procedure 1.7. To Deploy an Instance

The

application container.

AM-5.5.1.war

file contains the AM server. How you deploy the

1. Deploy the

.war
.war

file on your container.

.war
.war

file depends on your web

For example, copy the file to deploy on Apache Tomcat.

$ cp AM-5.5.1.war /path/to/tomcat/webapps/openam.war

During trials or development, you can change the file name to

Tomcat, so that the deployment URI is

/openam .
/openam
.
openam.war
openam.war

when deploying in

When installing AM in a production environment, do not use a predictable deployment URI such

as

/openam or /opensso .
/openam
or
/opensso
.

Note

You change the file name to something other than

deployment URI is not

"Avoiding Obvious Defaults".

openam.war
openam.war

when deploying in Tomcat so that the

/openam

. For helpful hints on avoiding obvious deployment defaults, see Section 4.1,

Important

To properly configure AM, AM requires a deployment URI with a non-empty string after

AM at the root context. Do not rename the

. Do not deploy

before deploying on Tomcat, for example.

/
/
.war file to ROOT.war
.war
file to
ROOT.war

It can take several seconds for AM to be deployed in your container.

2. Navigate to the initial configuration screen, for example

http://openam.example.com:8080/openam

.

Preparing for Installation Preparing External Data Stores

Preparing for Installation Preparing External Data Stores

Preparing for Installation Preparing External Data Stores AM is now ready for installation. to proceed, take

AM is now ready for installation. to proceed, take on of the following actions:

• Configure external data stores using the files created during deployment. See Section 1.4, "Preparing External Data Stores".

• Use the embedded data stores for evaluation purposes, and skip ahead to installing AM. See Section 2.1, "Installing a Single Server".

1.4. Preparing External Data Stores

This section covers setting up external data stores for configuration or identity data.

AM includes embedded data stores for configuration and identity data that can be used for evaluation and testing purposes. In production environments, external data stores are preferred.

The topics covered in this section are:

Preparing an External Identity Repository

Preparing an External Configuration Data Store

For a list of supported data stores, see Section 2.5, "Data Store Requirements" in the Release Notes.

Preparing for Installation Preparing an External Identity Repository

Preparing for Installation Preparing an External Identity Repository

1.4.1. Preparing an External Identity Repository

AM accesses user identity data from one or more identity repositories. AM ships with an embedded DS server that you can install as part of the AM configuration process.

In most deployments, AM connects to existing LDAP directory servers for user identity data, as it shares data in an identity repository with other applications.

If you are configuring AM to share data with other applications, or if you expect your deployment will have a large amount of users, connect AM to an external identity repository. For a list of supported external identity repositories, see Section 2.5, "Data Store Requirements" in the Release Notes.

1.4.1.1. Important Considerations for Using External Identity Repositories

AM connects to an external directory by binding to it as a user that you specify in the AM data store configuration. This user is known as the AM data store administrator.

Specifying the directory administrator, for example,

administrator is not recommended for production deployments as it will give AM directory administrator privileges to the identity repository.

Instead, create a separate AM administrator account with fewer access privileges than the directory administrator so that you can assign the appropriate level of privileges for the AM data store administrator.

You need to consider two areas of privileges for the AM data store administrator:

Schema Update Privileges

cn=Directory Manager

as the AM data store

AM needs to update the directory schema when you configure a new identity repository and when you upgrade AM software. If the AM data store administrator has schema update privileges, AM can update the schema dynamically during data store configuration and during AM upgrades. If the AM data store administrator does not have schema update privileges, you must update the schema manually before configuring a new identity repository and before upgrading AM.

Directory Read and Write Access Privileges

If you want AM to create, update, and delete user entries, then the AM data store administrator must have full read and write access to the identity data in the directory. If you are using an external identity repository as a read-only user directory, then the AM data store administrator needs read privileges only.

The level of access privileges you give the AM data store administrator is specific to each AM deployment. Work with your directory server administrator to determine the appropriate level of privileges as part of the process of preparing an external identity repository.

1.4.1.2. Preparing Your External Identity Repository

The steps for preparing an external identity repository vary depending on the schema update privileges given to the AM data store administrator.

Preparing for Installation Preparing an External Identity Repository

Preparing for Installation Preparing an External Identity Repository

• If the AM data store administrator has schema update privileges, follow the procedure in Section 1.4.1.2.1, "Preparing an Identity Repository With Dynamic Schema Updates".

• If the AM data store administrator does not have schema update privileges, follow the procedure in Section 1.4.1.2.2, "Preparing an Identity Repository With Manual Schema Updates".

After you have completed one of these two procedures, continue by configuring your external identity repository as an AM data store as described in Section 1.4.1.3, "Configuring Data Stores That Access External Identity Repositories".

Note

Example commands throughout this section use default values for user IDs and port numbers. When running similar commands, be sure to use appropriate values for your directory server.

When running the ldapmodify command, you might need to specify the

certificates if your directory server uses self-signed certificates and StartTLS or SSL.

--trustAll
--trustAll

argument to trust server

1.4.1.2.1. Preparing an Identity Repository With Dynamic Schema Updates

If the AM data store administrator has schema update privileges, you can configure the AM data store using dynamic schema updates. With dynamic schema updates, AM automatically updates the directory server schema of the external identity repository as needed. Schema updates might occur when you configure a data store as part of initial AM configuration, when you configure a data store after initial AM configuration, or when you upgrade AM.

The following procedure shows you how to prepare an identity repository with dynamic schema updates. The procedure assumes that you have already created an identity repository in DS and populated it with user data. The instructions that follow do not include steps to install DS, configure directory server backends, and implement replication. For external identity repositories other than DS, you must perform tasks that are analogous to the ones in the example procedure. Consult the documentation for your directory server software to determine the appropriate actions to take.

Procedure 1.8. To Prepare an External Directory Services Identity Repository with Dynamic Schema Updates

1. Create the AM data store administrator account.

This example uses

uid=openam,ou=admins,dc=example,dc=com

as the AM data store administrator. It is

assumed that the dc=example,dc=com

suffix already exists in the directory.

First, create an LDIF file that defines the AM data store administrator account and gives the account the following privileges:

update-schema

. Allows the account to update the directory schema.

subentry-write

. Allows the account to make directory subentry updates.

Preparing for Installation Preparing an External Identity Repository

Preparing for Installation Preparing an External Identity Repository

password-reset

. Allows the account to reset other users' passwords. Required for the AM

forgotten password feature. This privilege is not required for deployments where the AM data store will not modify user entries.

dn: ou=admins,dc=example,dc=com objectClass: top objectClass: organizationalunit ou: AM Administrator

dn: uid=openam,ou=admins,dc=example,dc=com objectClass: top objectClass: person objectClass: organizationalPerson objectClass: inetOrgPerson cn: AM Administrator sn: AM userPassword: changeMe ds-privilege-name: update-schema ds-privilege-name: subentry-write ds-privilege-name: password-reset

Then, run the ldapmodify command to create the user. The following example assumes that you are using OpenDJ 4.0 and later:

$ ldapmodify \ --hostname opendj.example.com \ --port 1389 \ --bindDN "cn=Directory Manager" \ --bindPassword password \ openam-ds-admin-account.ldif

Processing ADD request for ou=admins,dc=example,dc=com ADD operation successful for DN ou=admins,dc=example,dc=com Processing ADD request for uid=openam,ou=admins,dc=example,dc=com ADD operation successful for DN uid=openam,ou=admins,dc=example,dc=com

2. Add a global ACI that lets the AM administrator account modify the directory schema.

$ dsconfig set-access-control-handler-prop \ --hostname opendj.example.com \ --port 4444 \ --bindDN "cn=Directory Manager" \ --bindPassword password \ --no-prompt \ --add \ 'global-aci:(target="ldap:///cn=schema")(targetattr="attributeTypes||objectClasses") (version 3.0; acl "Modify schema"; allow (write) userdn="ldap:///uid=openam,ou=admins,dc=example,dc=com";)'

If you copy the text from the preceding example, make sure that the value starting with

aci
aci

is all on a single line.

'global-

To verify that you have added the global ACI correctly, list the global ACIs.

Preparing for Installation Preparing an External Identity Repository

Preparing for Installation Preparing an External Identity Repository

$ dsconfig get-access-control-handler-prop \ --port 4444 \ --hostname opendj.example.com \ --bindDN "cn=Directory Manager" \ --bindPassword password \ --property global-aci

The global ACI that allows the AM administrator account to modify schema definitions should appear in the list of global ACIs:

"(target="ldap:///cn=schema")(targetattr="attributeTypes|| objectClasses") (version 3.0; acl "Modify schema"; allow (write) userdn="ldap:///uid=openam,ou=admins,dc=example,dc=com");"

3. Allow AM to read the directory schema. AM needs to read the directory schema to ensure that changes made to identities stored in identity repositories remain compliant with the directory schema.

For DS, no actions are required. Simply retain the default "User-Visible Schema Operational Attributes" global ACI.

4. Give the AM data store administrator appropriate access rights on the directory. When AM connects to an external identity repository, it binds as the AM data store administrator.

For deployments in which AM will read and write user entries, the AM data store administrator needs privileges to create, modify, delete, search, read, and perform persistent searches on user entries in the directory. For deployments in which AM only reads user entries, the AM data store administrator needs privileges to only read, search, and perform persistent searches on user entries in the directory.

To grant the AM data store administrator account privileges to read and write user entries in DS, create a file with the following LDIF:

dn: dc=example,dc=com changetype: modify add: aci aci: (targetattr="* || aci")(version 3.0;acl "Allow identity modification"; allow (write)(userdn = "ldap:///uid=openam,ou=admins,dc=example,dc=com");) aci: (targetattr!="userPassword||authPassword")(version 3.0; acl "Allow identity search"; allow (search, read) (userdn = "ldap:///uid=openam,ou=admins,dc=example,dc=com");) aci: (targetcontrol="2.16.840.1.113730.3.4.3") (version 3.0;acl "Allow persistent search"; allow (search, read) (userdn = "ldap:///uid=openam,ou=admins,dc=example,dc=com");) aci: (version 3.0;acl "Add or delete identities"; allow (add, delete) (userdn = "ldap:///uid=openam,ou=admins,dc=example,dc=com");)

To grant the AM data store administrator account privileges to read (but not write) user entries in DS, create a file with the following LDIF:

Preparing for Installation Preparing an External Identity Repository

Preparing for Installation Preparing an External Identity Repository

dn: dc=example,dc=com changetype: modify add: aci aci: (targetattr!="userPassword||authPassword")(version 3.0; acl "Allow identity search"; allow (search, read) (userdn = "ldap:///uid=openam,ou=admins,dc=example,dc=com");) aci: (targetcontrol="2.16.840.1.113730.3.4.3") (version 3.0;acl "Allow persistent search"; allow (search, read) (userdn = "ldap:///uid=openam,ou=admins,dc=example,dc=com");)

Then, run the ldapmodify command to implement the ACIs. The following example assumes that you are using OpenDJ 4.0 and later:

$ ldapmodify \ --hostname opendj.example.com \ --port 1389 \ --bindDN "cn=Directory Manager" \ --bindPassword password \ add-acis-for-openam-ds-admin-access.ldif

Processing MODIFY request for dc=example,dc=com MODIFY operation successful for DN dc=example,dc=com

Continue by configuring your external identity repository as an AM data store as described in Section 1.4.1.3, "Configuring Data Stores That Access External Identity Repositories".

1.4.1.2.2. Preparing an Identity Repository With Manual Schema Updates

If the AM data store administrator does not have schema update privileges, you must configure the AM data store by using manual schema updates. To do this, update the directory server schema of the external identity repository manually before you configure a data store as part of initial AM configuration, before you configure a data store after initial AM configuration, and whenever you upgrade AM.

The following procedure shows you how to prepare an identity repository with manual schema updates. The procedure assumes that you have already deployed DS as a identity repository and populated it with user data. It therefore does not include steps to install DS, configure directory server backends, and implement replication. For external identity repositories other than DS, you must perform tasks that are analogous to the ones in the example procedure. Consult the documentation for your directory server software to determine the appropriate actions to take.

Procedure 1.9. To Prepare an External Directory Services Identity Repository With Manual Schema Updates

1. Create the AM data store administrator account.

This example uses uses

It is assumed that the

First, create an LDIF file that defines the AM data store administrator account and gives the account the following privilege:

uid=openam,ou=admins,dc=example,dc=com

dc=example,dc=com

as the AM data store administrator.

suffix already exists in the directory.

Preparing for Installation Preparing an External Identity Repository

Preparing for Installation Preparing an External Identity Repository

password-reset

. Allows the account to reset other users' passwords. Required for the AM

forgotten password feature. For deployments in which AM will not modify user entries, the AM data store administrator does not require this privilege.

dn: ou=admins,dc=example,dc=com objectClass: top objectClass: organizationalunit ou: AM Administrator

dn: uid=openam,ou=admins,dc=example,dc=com objectClass: top objectClass: person objectClass: organizationalPerson objectClass: inetOrgPerson cn: AM Administrator sn: AM userPassword: changeMe ds-privilege-name: password-reset

Then, run the ldapmodify command to create the user. The following example assumes that you are using OpenDJ 4.0 and later:

$ ldapmodify \ --hostname opendj.example.com \ --port 1389 \ --bindDN "cn=Directory Manager" \ --bindPassword password \ openam-ds-admin-account.ldif

Processing ADD request for ou=admins,dc=example,dc=com ADD operation successful for DN ou=admins,dc=example,dc=com Processing ADD request for uid=openam,ou=admins,dc=example,dc=com ADD operation successful for DN uid=openam,ou=admins,dc=example,dc=com

2. Using the directory administrator account, add the AM schema extensions to your external identity repository.

First, identify the path that contains LDIF file for AM schema extensions. The path is

openam/WEB-INF/template/ldif/directory_type

, where directory_type

is one of the following:

• for Microsoft Active Directory

ad
ad

• for Microsoft Active Directory Lightweight Directory Services

adam
adam

• for Oracle Directory Server Enterprise Edition

odsee
odsee

opendj

for ForgeRock Directory Services and Oracle Unified Directory

• for IBM Tivoli Directory Server

tivoli
tivoli

/path/to/

Run the ldapmodify command to import the user, device print, and dashboard schema extensions. (For more information on the supported LDIF files, see Appendix C, "Supported LDIF Files".)

Preparing for Installation Preparing an External Identity Repository

Preparing for Installation Preparing an External Identity Repository

For example, add schema extensions to DS by running the following ldapmodify commands. The following examples assume that you are using OpenDJ 4.0 and later:

$ cd /path/to/openam/WEB-INF/template/ldif/opendj

$ ldapmodify \ --hostname opendj.example.com \ --port 1389 \ --bindDN "cn=Directory Manager" \ --bindPassword password \ opendj_user_schema.ldif

$ ldapmodify \ --hostname opendj.example.com \ --port 1389 \ --bindDN "cn=Directory Manager" \ --bindPassword password \ opendj_deviceprint.ldif

$ ldapmodify \ --hostname opendj.example.com \ --port 1389 \ --bindDN "cn=Directory Manager" \ --bindPassword password \ opendj_dashboard.ldif

3. Allow AM to read the directory schema. AM needs to read the directory schema to ensure that changes made to identities stored in identity repositories remain compliant with the directory schema.

For DS, no actions are required. Simply retain the default User-Visible Schema Operational Attributes global ACI.

4. Give the AM data store administrator appropriate access rights on the directory. When AM connects to an external identity repository, it binds as the AM data store administrator.

For deployments in which AM will read and write user entries, the AM data store administrator needs privileges to create, modify, delete, search, read, and perform persistent searches on user entries in the directory. For deployments in which AM only reads user entries, the AM data store administrator needs privileges to only read, search, and perform persistent searches on user entries in the directory.

To grant the AM data store administrator account privileges to read and write user entries in DS, create a file with the following LDIF:

Preparing for Installation Preparing an External Identity Repository

Preparing for Installation Preparing an External Identity Repository

dn: dc=example,dc=com changetype: modify add: aci aci: (targetattr="* || aci")(version 3.0;acl "Allow identity modification"; allow (write)(userdn = "ldap:///uid=openam,ou=admins,dc=example,dc=com");) aci: (targetattr!="userPassword||authPassword")(version 3.0; acl "Allow identity search"; allow (search, read) (userdn = "ldap:///uid=openam,ou=admins,dc=example,dc=com");) aci: (targetcontrol="2.16.840.1.113730.3.4.3") (version 3.0;acl "Allow persistent search"; allow (search, read) (userdn = "ldap:///uid=openam,ou=admins,dc=example,dc=com");) aci: (version 3.0;acl "Add or delete identities"; allow (add, delete) (userdn = "ldap:///uid=openam,ou=admins,dc=example,dc=com");)

To grant the AM data store administrator account privileges to read (but not write) user entries in DS, create a file with the following LDIF:

dn: dc=example,dc=com changetype: modify add: aci aci: (targetattr!="userPassword||authPassword")(version 3.0; acl "Allow identity search"; allow (search, read) (userdn = "ldap:///uid=openam,ou=admins,dc=example,dc=com");) aci: (targetcontrol="2.16.840.1.113730.3.4.3")(version 3.0; acl "Allow persistent search"; allow (search, read) (userdn = "ldap:///uid=openam,ou=admins,dc=example,dc=com");)

Run the ldapmodify command to implement the ACIs:

$ ldapmodify \ --hostname opendj.example.com \ --port 1389 \ --bindDN "cn=Directory Manager" \ --bindPassword password \ add-acis-for-openam-ds-admin-access.ldif

Processing MODIFY request for dc=example,dc=com MODIFY operation successful for DN dc=example,dc=com

1.4.1.3. Configuring Data Stores That Access External Identity Repositories

Now that you have prepared your external identity repository, you can configure the directory as an AM data store by using one of the following methods:

• By specifying your user directory in the User Data Store Settings dialog box when installing AM core services.

If you are using dynamic schema updates, the AM configurator loads required schema definitions into your user directory. If you are using manual schema updates, you already loaded the required schema definitions into your user directory.

For more information about running the AM configurator, see Section 2.1, "Installing a Single Server".

Preparing for Installation Preparing an External Identity Repository

Preparing for Installation Preparing an External Identity Repository

• By defining a data store after you have installed AM core services.

If you are using dynamic schema updates and you specify the Load schema when finished option, AM loads required schema definitions into your user directory. If you are using manual schema updates, you will have already loaded the required schema definitions into your user directory.

For more information about defining AM data stores, see Chapter 3, "Setting Up Identity Data Stores" in the Setup and Maintenance Guide.

1.4.1.4. Indexing External Identity Repositories Attributes

After you have configured a data store to access an external identity repository, you must complete identity repository preparation by indexing several attributes.

Procedure 1.10. To Index External Identity Repository Attributes

• Create equality indexes for the

iplanet-am-user-federation-info-key

and

sun-fm-saml2-nameid-infokey

attributes. To create the indexes, run the dsconfig command twice. Bind to your user directory as the directory administrator.

The dsconfig subcommand used to create the index depends on the version of DS.

• Use the following commands with OpenDJ 2.6:

$ dsconfig \ create-local-db-index \ --port 4444 \ --hostname opendj.example.com \ --bindDN "cn=Directory Manager" \ --bindPassword password \ --backend-name userRoot \ --index-name iplanet-am-user-federation-info-key \ --set index-type:equality \ --no-prompt

$ dsconfig \ create-local-db-index \ --port 4444 \ --hostname opendj.example.com \ --bindDN "cn=Directory Manager" \ --bindPassword password \ --backend-name userRoot \ --index-name sun-fm-saml2-nameid-infokey \ --set index-type:equality \ --no-prompt

• Use the following commands with OpenDJ 3 and later:

Preparing for Installation Preparing an External Identity Repository

Preparing for Installation Preparing an External Identity Repository

$ dsconfig \ create-backend-index \ --port 4444 \ --hostname opendj.example.com \ --bindDN "cn=Directory Manager" \ --bindPassword password \ --backend-name userRoot \ --index-name iplanet-am-user-federation-info-key \ --set index-type:equality \ --no-prompt

$ dsconfig \ create-backend-index \ --port 4444 \ --hostname opendj.example.com \ --bindDN "cn=Directory Manager" \ --bindPassword password \ --backend-name userRoot \ --index-name sun-fm-saml2-nameid-infokey \ --set index-type:equality \ --no-prompt

1.4.1.5. Testing External Identity Repository Access

Prior to working actively with external identity repositories, you should verify that you have configured the repository and administrator privileges correctly. You can test configuration as follows:

• Attempt to create an AM user from the Realms > Realm Name > Subjects tab in the AM console. Run this test only if you have given the AM data store administrator write privileges to your identity repository.

For example, create a

AM software, the setup process creates a

documentation. This user does not exist by default in an external identity repository. When creating

demo
demo

user. When you use the embedded identity repository to evaluate

demo
demo

user that is used in many examples in the AM

a

demo
demo

user's account, set the fields as follows:

 

Table 1.6. Demo User Account Settings

Field

 

Value

ID

 
demo
demo

First Name

Leave this field blank.

Last Name

 
demo
demo

Full Name

 
demo
demo

Password

 

changeit

User Status

Active

• Attempt to access an AM user from the Realms > Realm Name > Subjects tab in the AM console.

Preparing for Installation Preparing an External Configuration Data Store

Preparing for Installation Preparing an External Configuration Data Store

If you receive an LDAP error code 65 while attempting to create a user, it indicates that you did not correctly prepare the external identity repository. Error code 65 is an LDAP object class violation and often indicates a problem with the directory schema. Common reasons for this error while attempting to create a user include the following:

• If you configured the external data store after initial configuration, you might have simply forgotten to check the "Load schema when finished" option. In this case, select this option and resave the data store configuration.

• The AM administrator account might not have adequate rights to update the directory schema.

Review the DS

DS's access rights.

access
access

log and locate the log records for the schema update operation to determine

1.4.2. Preparing an External Configuration Data Store

AM stores its configuration in an LDAP directory server. AM ships with an embedded DS server that you can install as part of the AM configuration process. By default, AM installs the embedded

directory server and its configuration settings in the

the embedded directory server in the same JVM memory space as AM.

$HOME
$HOME

directory of the user running AM and runs

AM connects to the embedded DS server as directory superuser, bypassing access control evaluation because AM manages the directory as its private store. Be aware that you cannot configure directory failover and replication when using the embedded store.

When AM starts up, it requires the password of the

configuration data store. This password is stored in AM's JCEKS keystore as the

password-protected string alias, and it must be updated every time the

password changes. For more information about the

Password String Aliases" in the Setup and Maintenance Guide.

cn="Directory Manager"

configstorepwd

user to unlock the

configstorepwd

cn="Directory Manager"

user's

alias, see Section 5.4, "Configuring

By default, AM also stores data managed by the Core Token Service (CTS) pertaining to user logins —AM stateful sessions, logout blacklists, and several types of authentication tokens—in the same embedded DS server that holds the AM configuration. You can choose to create a separate directory store for CTS data. For information about creating a separate directory store for CTS data, see the chapter, Chapter 3, "Implementing the Core Token Service".

Before deploying AM in production, measure the impact of using the embedded directory not only for relatively static configuration data, but also for volatile session and token data. Your tests should subject AM to the same load patterns you expect in production. If it looks like a better choice to use an external directory server, then deploy AM with an external configuration store.

Preparing for Installation Preparing an External Configuration Data Store

Preparing for Installation Preparing an External Configuration Data Store

Tip

If you are the directory administrator and do not yet know directory servers very well, take some time to read the documentation for your directory server, especially the sections covering directory schema and procedures on how to configure access to directory data.

Procedure 1.11. To Install an External OpenDJ Directory Server

The following example procedure shows how to prepare a single DS server as an external configuration data store. The DS instance implements a single backend for the AM configuration data. The procedure assumes that you have also prepared an external identity repository and an external CTS store, separate from the configuration data store.

Note

Example commands throughout this section use example values for user IDs and port numbers. When running similar commands, be sure to use appropriate values for your directory server.

When running the ldapmodify or dsconfig commands, you might need to specify the

trust server certificates if your directory server uses self-signed certificates and StartTLS or SSL.

--trustAll
--trustAll

argument to

1. Prepare your DS installation, then download the DS software. See the DS documentation about Installing OpenDJ Servers.

$ cd /path/to/opendj

$ ./setup --cli

Example options are as follows:

Table 1.7. Example DS Setup Parameters

Parameter

Example Inputs

Accept License

 

Yes

Root User DN

 

cn=Directory Manager

Root User DN Password

 

(arbitrary)

Fully Qualified Domain Name

 

opendj.example.com

LDAP Port
LDAP Port

1389

Administration Connector Port

4444

Create Base DN

 

No. This will be created in a later step.

Enable SSL
Enable SSL

If you choose this option, make sure that AM can trust the DS certificate.

Enable TLS
Enable TLS

If you choose this option, make sure that AM can trust the DS certificate.

Start Server After Config

 

Yes

Preparing for Installation Preparing an External Configuration Data Store

Preparing for Installation Preparing an External Configuration Data Store

2. Change to the directory containing DS's binaries.

$ cd /path/to/opendj/bin

3. Create a directory server backend, and call it

cfgStore .

The dsconfig command used to create the backend depends on the version of DS.

• Use the following command with OpenDJ 2.6:

$ dsconfig create-backend \ --backend-name cfgStore \ --set base-dn:dc=example,dc=com \ --set enabled:true \ --type local-db \ --port 4444 \ --bindDN "cn=Directory Manager" \ --bindPassword password \ --no-prompt

• Use the following command with OpenDJ 3.0 and later to create a backend:

$ dsconfig create-backend \ --backend-name cfgStore \ --set base-dn:dc=example,dc=com \ --set enabled:true \ --type je \ --port 4444 \ --bindDN "cn=Directory Manager" \ --bindPassword password \ --no-prompt

4. Create an LDIF file to add the initial entries for the configuration store, and save the file as

add-
add-

config-entries.ldif

. The entries include the base DN suffix, an organizational unit entry, and the

AM user entry needed to access the directory server.

When AM connects as

its data, it requires read, write, persistent search, and server-side sorting access privileges. You add these privileges by setting access control instructions (ACIs) on the base distinguished name

uid=openam,ou=admins,dc=example,dc=com

to an external directory server to store

(DN) entry ( dc=example,dc=com

). If your AM user has a DN other than

,dc=com
,dc=com

, adjust the ACIs where appropriate.

uid=openam,ou=admins,dc=example

You must also give privileges to the AM user to modify the schema and write to subentries, such as the schema entry. To grant these privileges, you include the following attributes on the AM

user entry:

ds-privilege-name: subentry-write

and

ds-privilege-name: update-schema

.

Preparing for Installation Preparing an External Configuration Data Store

Preparing for Installation Preparing an External Configuration Data Store

dn: dc=example,dc=com objectclass: top objectclass: domain dc: example aci: (targetattr="*")(version 3.0;acl "Allow CRUDQ operations"; allow (search, read, write, add, delete) (userdn = "ldap:///uid=openam,ou=admins,dc=example,dc=com");) aci: (targetcontrol="2.16.840.1.113730.3.4.3")(version 3.0; acl "Allow persistent search"; allow (search, read) (userdn = "ldap:///uid=openam,ou=admins,dc=example,dc=com");) aci: (targetcontrol="1.2.840.113556.1.4.473")(version 3.0; acl "Allow server-side sorting"; allow (read) (userdn = "ldap:///uid=openam,ou=admins,dc=example,dc=com");)

dn: ou=admins,dc=example,dc=com objectclass: top objectclass: organizationalUnit ou: admins

dn: uid=openam,ou=admins,dc=example,dc=com objectclass: top objectclass: person objectclass: organizationalPerson objectclass: inetOrgPerson cn: openam sn: openam uid: openam userPassword: secret12 ds-privilege-name: subentry-write ds-privilege-name: update-schema

5. Add the initial entries LDIF file using the ldapmodify command. The following example assumes that you are using OpenDJ 4.0 and later:

If you are having trouble with the preceding LDIF file, consider removing the line feeds for the ACI attributes and let it wrap to the next line. If you are still having trouble using the ldapmodify command, you can use the import-ldif command, although you may have to re-apply

the targetcontrol ACI attribute.

$ bin/ldapmodify \ --port 1389 \ --bindDN "cn=Directory Manager" \ --bindPassword password \ add-config-entries.ldif

6. Add the Global Access Control Instruction (ACI) to the access control handler. The Global ACI gives AM the privileges to modify the schema definitions for the custom configuration where the

AM entry has DN

uid=openam,ou=admins,dc=example,dc=com

.

Preparing for Installation Preparing an External Configuration Data Store

Preparing for Installation Preparing an External Configuration Data Store

Note

These access rights are only required during configuration, and only if the directory administrator does not add the AM directory schema definitions manually.

If you copy the text from the following example, make sure that the value of single line.

global-aci is all on a

$ bin/dsconfig set-access-control-handler-prop \ --add global-aci:'(target = "ldap:///cn=schema")(targetattr = "attributeTypes || objectClasses")(version 3.0; acl "Modify schema"; allow (write) (userdn = "ldap:///uid=openam,ou=admins,dc=example,dc=com");)' --port 4444 \ --bindDN "cn=Directory Manager" \ --bindPassword password \ --no-prompt

7. At this point, deploy the AM server if you have not done so already. For additional details on deploying AM, see Section 1.3.2, "Deploying".

8. AM requires additional schema definitions for attributes used to search for user and configuration data:

Table 1.8. Configuration Data Store Attributes

Attribute Index Type Description CTS attributes Specifies the CTS attributes required for stateful session high
Attribute
Index Type
Description
CTS attributes
Specifies the CTS attributes required
for stateful session high availability and
persistence. Located in the
WEB-INF/
template/ldif/sfha/cts-add-schema.ldif
file.
iplanet-am-user-federation-info-key
equality
Specifies a configuration setting to store
an account's federation information
key, which is used internally. Located
in
WEB-INF/template/ldif/opendj/
opendj_user_schema.ldif
file.
sun-fm-saml2-nameid-infokey
equality
Specifies an information key common to
an IdP and SP to link accounts. Located
in
WEB-INF/template/ldif/opendj/
opendj_user_schema.ldif
file.
sunxmlkeyvalue
equality, substring
Stores configuration values that may be
looked up through searches. Located
in
WEB-INF/template/ldif/opendj/
opendj_config_schema.ldif
.

Add the required CTS schema definitions. You can find the CTS schema definitions at

/path/to/

tomcat/webapps/openam/WEB-INF/template/ldif/sfha/cts-add-schema.ldif

.

Preparing for Installation Preparing an External Configuration Data Store

Preparing for Installation Preparing an External Configuration Data Store

$ cp /path/to/tomcat/webapps/openam/WEB-INF/template/ldif/sfha/cts-add-schema.ldif /tmp

9. Add the schema file to the directory server.

$ bin/ldapmodify \ --port 1389 \ --bindDN "cn=Directory Manager" \ --bindPassword password \ /tmp/cts-add-schema.ldif

10. Add the required user store schema definitions. You can find the schema definitions at

/path/to/

tomcat/webapps/openam/WEB-INF/template/ldif/opendj/opendj_user_schema.ldif

.

$ cp /path/to/tomcat/webapps/openam/WEB-INF/template/ldif/opendj/opendj_user_schema.ldif /tmp

11. Add the schema file to the directory server.

$ bin/ldapmodify \ --port 1389 \ --bindDN "cn=Directory Manager" \ --bindPassword password \ /tmp/opendj_user_schema.ldif

12. Add the schema definitions to the configuration repository. You can find the schema definitions at

/path/to/tomcat/webapps/openam/WEB-INF/template/ldif/opendj/opendj_config_schema.ldif

.

$ cp /path/to/tomcat/webapps/openam/WEB-INF/template/ldif/opendj/opendj_config_schema.ldif /tmp

13. Add the schema file to the directory server.

$ bin/ldapmodify \ --port 1389 \ --bindDN "cn=Directory Manager" \ --bindPassword password \ /tmp/opendj_config_schema.ldif

14. AM uses the attributes in Table 1.8, "Configuration Data Store Attributes" to search for configuration data. On the DS server, use the dsconfig command to add these indexes to your

external configuration store. Repeat this step to index the

iplanet-am-user-federation-info-key

sun-fm-saml2-nameid-infokey

attributes if you are deploying federation.

and

The dsconfig subcommand used to create the index depends on the version of DS.

• Use the following commands with OpenDJ 2.6.x:

Preparing for Installation Preparing an External Configuration Data Store

Preparing for Installation Preparing an External Configuration Data Store

$ dsconfig create-local-db-index \ --port 4444 \ --hostname opendj.example.com \ --bindDN "cn=Directory Manager" \ --bindPassword password \ --backend-name cfgStore \ --index-name sunxmlkeyvalue \ --set index-type:equality \ --set index-type:substring \ --no-prompt

$ dsconfig create-local-db-index \ --port 4444 \ --hostname opendj.example.com \ --bindDN "cn=Directory Manager" \ --bindPassword password \ --backend-name cfgStore \ --index-name iplanet-am-user-federation-info-key \ --set index-type:equality \ --no-prompt

$ dsconfig create-local-db-index \ --port 4444 \ --hostname opendj.example.com \ --bindDN "cn=Directory Manager" \ --bindPassword password \ --backend-name cfgStore \ --index-name sun-fm-saml2-nameid-infokey \ --set index-type:equality \ --no-prompt

• Use the following commands with OpenDJ 3 and later:

Preparing for Installation Setting the Configuration Store Heartbeat

Preparing for Installation Setting the Configuration Store Heartbeat

$ dsconfig create-backend-index \ --port 4444 \ --hostname opendj.example.com \ --bindDN "cn=Directory Manager" \ --bindPassword password \ --backend-name cfgStore \ --index-name sunxmlkeyvalue \ --set index-type:equality \ --set index-type:substring \ --no-prompt

$ dsconfig create-backend-index \ --port 4444 \ --hostname opendj.example.com \ --bindDN "cn=Directory Manager" \ --bindPassword password \ --backend-name cfgStore \ --index-name iplanet-am-user-federation-info-key \ --set index-type:equality \ --no-prompt

$ dsconfig create-backend-index \ --port 4444 \ --hostname opendj.example.com \ --bindDN "cn=Directory Manager" \ --bindPassword password \ --backend-name cfgStore \ --index-name sun-fm-saml2-nameid-infokey \ --set index-type:equality \ --no-prompt

15. Rebuild the indexes using the

index
index
rebuild-index rebuild-index
rebuild-index
rebuild-index

command. You can stop the server and run

online using a task as follows:

in offline mode, or you can run

rebuild-
rebuild-

$ bin/rebuild-index --port 4444 --hostname opendj.example.com \ --bindDN "cn=Directory Manager" --bindPassword password \ --baseDN dc=example,dc=com --rebuildAll \ --start 0

16. Verify the indexes. Note that if you are running OpenDJ 3 and later, you need to stop the server before running this command.

$ bin/verify-index --baseDN dc=example,dc=com

You have successfully installed and prepared the directory server for an external configuration store. When installing the AM server, you need to specify the host name, port and root suffix of the external directory server on the Configuration Data Store Settings screen of the AM Configurator. See Procedure 2.3, "To Custom Configure an Instance" for more information.

1.4.3. Setting the Configuration Store Heartbeat

AM supports heartbeat monitoring for the configuration data store to prevent idle connections. Idle connections may occur if the external data store is behind a load balancer or firewall. Once the

Preparing for Installation Setting the Configuration Store Heartbeat

Preparing for Installation Setting the Configuration Store Heartbeat

connection is in an idle state, AM no longer receive notification of configuration changes and may become out-of-sync with other servers sharing the configuration store.

By default, AM issues a heartbeat every ten seconds to monitor for idle connections to the configuration data store.

Two JVM options can be used to override the default heartbeat interval or to disable it completely:

org.forgerock.openam.ldap.sm.heartbeat.interval. Sets the heartbeat interval. The default interval is 10 seconds. If you set the JVM property to 0, it will disable the heartbeat.

org.forgerock.openam.ldap.sm.heartbeat.unit. Sets the time unit of the heartbeat interval. Default

is SECONDS SECONDS .
is
SECONDS
SECONDS
.

. Possible values also include:

DAYS , HOURS , MICROSECONDS , MILLISECONDS , MINUTES , NANOSECONDS
DAYS
, HOURS
, MICROSECONDS
, MILLISECONDS
, MINUTES
, NANOSECONDS

, and

Important

You must grant access permissions to all heartbeat requests to the configuration stores that go through firewalls or load balancers.

Procedure 1.12. To Set the Heartbeat Interval

1. Set the heartbeat interval using the JVM startup property

.interval
.interval

in your container.

org.forgerock.openam.ldap.sm.heartbeat

For example, to set the heartbeat interval to 20 seconds, edit

or

%CATALINA_HOME%/bin/setenv.sh

%CATALINA_HOME%\bin\setenv.bat

(Windows) on Tomcat by adding the following line:

(Unix)

set CATALINA_OPTS=-Dorg.forgerock.openam.ldap.sm.heartbeat.interval=20

2. Make sure that the heartbeat requests have the permissions necessary for a firewall or load balancer.

Procedure 1.13. To Disable the Heartbeat Interval

• Disable the heartbeat interval by setting the JVM startup property

.heartbeat.interval

to 0.

org.forgerock.openam.ldap.sm

For example, edit

on Tomcat by adding the following line:

%CATALINA_HOME%/bin/setenv.sh

(Unix) or

%CATALINA_HOME%\bin\setenv.bat

(Windows)

set CATALINA_OPTS=-Dorg.forgerock.openam.ldap.sm.heartbeat.interval=0

Installing and Starting Servers

Installing and Starting Servers

Chapter 2

Installing and Starting Servers

This chapter covers installation and startup.

The chapter includes procedures for installing AM on a single server, installing AM on multiple servers, and installing AM's administrative tools. It also covers how to start AM, including overriding default startup options.

The following table contains a list of activities you might perform while installing and starting AM:

Table 2.1. Installation Options

Installation Action

Documentation Reference

Install quickly for evaluation using default settings

Procedure 2.1, "To Configure With Defaults"

Alternatively, follow the full example in Quick Start Guide.

Install AM server, choosing settings

Procedure 2.3, "To Custom Configure an Instance"

Start an AM