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

<chapter xml:id='chap-auth-services'

xmlns='http://docbook.org/ns/docbook'

version='5.0' xml:lang='en'

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

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

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

<title>Defining Authentication Services</title>

<para>An <firstterm>authentication</firstterm> service confirms the identity

of a user or a client application.</para>

<para>This chapter describes how to configure authentication in OpenAM.</para>

<section xml:id="what-is-authn">

<title>About Authentication in OpenAM</title>

<indexterm><primary>Authentication</primary></indexterm>

<para>Access management is about controlling access to resources. OpenAM

plays a role similar to border control at an international airport. Instead

of having each and every airline company deal with access to each

destination, all airlines redirects passengers to border control. Border

control then determines who each passenger is according to passport

credentials. Border control also checks whether the identified passenger

is authorized to fly to the destination corresponding to the ticket, perhaps

based on visa credentials. Then, at the departure gate, an agent enforces

the authorization from border control, allowing the passenger to board the

plane as long as the passenger has not gotten lost, or tried to board the

wrong plane, or swapped tickets with someone else. Thus, border control

handles access management at the airport.</para>

<para>OpenAM is most frequently used to protect web-accessible resources.

Users browse to a protected web application page. An agent installed on the

server with the web application redirects the user to OpenAM for access management.

OpenAM determines who the user is, and whether the user has the right to

access the protected page. OpenAM then redirects the user back to the

protected page, with authorization credentials that can be verified by the agent.

The agent allows OpenAM authorized users access the page.</para>

<para>Notice that OpenAM basically needs to determine two things for

access management: the identity of the user, and whether the user has access rights

to the protected page. <firstterm>Authentication</firstterm> is how OpenAM identifies

the user. This chapter covers how to set up the

authentication process. <firstterm>Authorization</firstterm> is how OpenAM determines

whether a user has access to a protected resource. Authorization is covered later.</para>

<para>For authentication, OpenAM uses credentials from the user or

client application. It then uses defined mechanisms to

validate credentials and complete the authentication. The authentication

methods can vary. For example, passengers travelling on international flights authenticate

with passports and visas. In contrast, passengers travelling on domestic flights might

authenticate with an identity card or a driver's license. Customers withdrawing

cash from an ATM authenticate with a card and a PIN. </para>

<indexterm>

<primary>Authentication</primary>

<secondary>Modules</secondary>

</indexterm>

<indexterm>

<primary>Authentication</primary>

<secondary>Chains</secondary>

</indexterm>

<para>OpenAM allows you to configure authentication processes and then customize

how they are applied. OpenAM uses <firstterm>authentication

modules</firstterm> to handle different ways of authenticating. Basically,

each authentication module handles one way of obtaining and verifying

credentials. You can chain different authentication modules together.

In OpenAM, this is called <firstterm>authentication chaining</firstterm>.

Each authentication module can be configured to specify the continuation and

failure semantics with one of the following four flags:

required, optional, requisite, or sufficient.<footnote>

<para>The four flags, required, optional, requisite, and sufficient, come from

the standards created for the Java Authentication and Authorization Service

(JAAS).</para></footnote></para>

<itemizedlist>

<listitem>

<para>When a <firstterm>required</firstterm> module fails, the rest of

the chain is processed, but the authentication fails.</para>

<para>A required module might be used for login with email and password,

but then fall through to another module to handle new users who have not

yet signed up.</para>

</listitem>

<listitem>

<para>When an <firstterm>optional</firstterm> module fails,

authentication continues.</para>

<para>An optional module might be used to permit a higher level of access

if the user can present a X.509 certificate for example.</para>

</listitem>

<listitem>

<para>When a <firstterm>requisite</firstterm> module fails, authentication

fails and authentication processing stops.</para>

<para>A requisite module might be used with exclusive SSO.</para>

</listitem>

<listitem>

<para>When a <firstterm>sufficient</firstterm> succeeds, authentication

is successful and later modules in the chain are skipped.</para>

<para>You could set Windows Desktop SSO as sufficient, so authenticated

Windows users are let through, whereas web users have to traverse another

authentication module such as one requiring an email address and a

password.</para>

</listitem>

</itemizedlist>

<indexterm>

<primary>Authentication</primary>

<secondary>Levels</secondary>

</indexterm>

<para>With OpenAM, you can further set <firstterm>authentication

levels</firstterm> per module, with higher levels being used typically

to allow access to more restricted resources. The OpenAM SPIs also let you

develop your own authentication modules, and post-authentication plugins.

Client applications can specify the authentication level, module, user, and

authentication service to use among those you have configured. As described

later in this guide, you can use <firstterm>realms</firstterm> to organize

which authentication process applies for different applications or different

domains, perhaps managed by different people.</para>

<para>When a user successfully authenticates, OpenAM creates a session, which

allows OpenAM to manage that user's access to resources. In some deployments

you need to limit how many active sessions a user can have at a given time.

For example, you might want to prevent a user from using more than two devices

at once. See <xref linkend="configure-session-quotas" /> for

instructions.</para>

<para>OpenAM leaves the authentication process flexible so that you can adapt

how it works to your situation. Although at first the number of choices

can seem daunting, now that you understand the basic process, you begin to

see how choosing authentication modules and arranging them in authentication

chains lets you use OpenAM to protect access to a wide range of applications

used in your organization.</para>

</section>

<section xml:id="configure-authn-modules">

<title>Configuring Authentication Modules</title>

<para>The OpenAM console provides two places where the OpenAM administrator

can configure authentication modules.</para>

<orderedlist>

<listitem>

<para>Under Configuration &gt; Authentication, you configure available

modules for use throughout OpenAM. What you set up here is inherited

for use elsewhere.</para>

</listitem>

<listitem>

<para>Under Access Control &gt; <replaceable>Realm Name</replaceable> &gt;

Authentication, you configure modules for your realm. What you set up

at this level inherits from the global configuration, but you can override

what is inherited. You can also add your own modules if necessary.</para>

</listitem>

</orderedlist>

<para>The configuration of individual modules depend on its function.

The configuration of an Active Directory over LDAP user authentication module

requires connection information and details about where to search for users.

In contrast, the configuration of the HOTP module for OTP authentication

requires data about the password length and the mail server or SMS gateway for

to send the password during authentication.</para>

<section xml:id="ad-module-conf-hints">

<title>Hints For the Active Directory Authentication Module</title>

<para>OpenAM connects to Active Directory over Lightweight Directory Access

Protocol (LDAP). OpenAM provides separate Active Directory and LDAP

modules to support the use of both Active Directory and

another directory service in an authentication chain.</para>

<indexterm>

<primary>Authentication</primary>

<secondary>Active Directory</secondary>

</indexterm>

<para><command>ssoadm</command> service name:

<literal>sunAMAuthADService</literal></para>

<variablelist>

<varlistentry>

<term>Primary Active Directory Server</term>

<term>Secondary Active Directory Server</term>

<listitem>

<para>The default port for LDAP is 389. If you are connecting to

Active Directory over SSL, the default port for LDAP/SSL is 636.</para>

<para>To allow users to change passwords through OpenAM, Active Directory

requires that you connect over SSL.</para>

<para>If you want to use SSL or TLS for security, then scroll down to

enable SSL/TLS Access to Active Directory Server. Make sure that OpenAM

can trust the Active Directory certificate when using this option.</para>

<para>OpenAM first attempts to contact primary servers. If no primary

server is available, then OpenAM attempts to contact secondaries.</para>

<para>When authenticating users from a directory server that is remote

from OpenAM, set both the primary and secondary server values.</para>

<para><command>ssoadm</command> attributes: primary is

<literal>iplanet-am-auth-ldap-server</literal>; secondary is

<literal>iplanet-am-auth-ldap-server2</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>DN to Start User Search</term>

<listitem>

<para>LDAP data is organized hierarchically, a bit like a file system

on Windows or UNIX. More specific DNs likely result in better performance.

When configuring the module for a particular part of the organization,

you can perhaps start searches from a specific organizational unit such as

<literal>OU=sales,DC=example,DC=com</literal>.</para>

<para>If multiple entries exist with identical search attribute values,

make this value specific enough to return only one entry.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-ldap-base-dn</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Bind User DN, Bind User Password</term>

<listitem>

<para>If OpenAM stores attributes in Active Directory, for example to

manage account lockout, or if Active Directory requires that OpenAM

authenticate in order to read users' attributes, then OpenAM needs the

DN and password to authenticate to Active Directory.</para>

<para>The default is <literal>amldapuser</literal>. If the administrator

authentication chain (default: <literal>ldapService</literal>) has been

configured to include only the Active Directory module, then make sure

that the password is correct before you logout. If it is incorrect, you

will be locked out. If you do get locked out, you can login with the

super user DN, which by default is

<literal>uid=amAdmin,ou=People,<replaceable>OpenAM-deploy-base</replaceable></literal>,

where <replaceable>OpenAM-deploy-base</replaceable> was set during

OpenAM configuration.</para>

<para><command>ssoadm</command> attributes:

<literal>iplanet-am-auth-ldap-bind-dn</literal> and

<literal>iplanet-am-auth-ldap-bind-passwd</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Attributes Used to Retrieve User Profile</term>

<term>Attributes Used to Search for a User to be Authenticated</term>

<term>User Search Filter</term>

<term>Search Scope</term>

<listitem>

<para>LDAP searches for user entries return entries with attribute

values matching the filter you provide. For example if you search under

<literal>CN=Users,DC=example,DC=com</literal> with a filter

<literal>"(MAIL=bjensen@example.com)"</literal>, then the directory

returns the entry that has <literal>MAIL=bjensen@example.com</literal>.

In this example the attribute used to search for a user is

<literal>mail</literal>. Multiple attribute values mean the user can

authenticate with any one of the values. For example, if you have

both <literal>uid</literal> and <literal>mail</literal>, then Barbara

Jensen can authenticate with either <literal>bjensen</literal> or

<literal>bjensen@example.com</literal>.</para>

<para>The User Search Filter text box provides a more complex filter. For example,

if you search on <literal>mail</literal> and add User Search Filter

<literal>(objectClass=inetOrgPerson)</literal>, then OpenAM uses the resulting

search filter <literal>(&amp;(mail=<replaceable>address</replaceable>)

(objectClass=inetOrgPerson))</literal>, where <replaceable>address</replaceable>

is the mail address provided by the user.</para>

<para>This controls how and the level of the directory that will be searched.

You can set the search to run at a high level or against a specific area.</para>

<itemizedlist>

<listitem>

<para>OBJECT will search only for the entry specified as the DN to Start User

Search.</para>

</listitem>

<listitem>

<para>ONELEVEL will search only the entries that are directly children of that

object.</para>

</listitem>

<listitem>

<para>SUBTREE will search the entry specified and every entry under it.</para>

</listitem>

</itemizedlist>

<para><command>ssoadm</command> attributes:

<literal>iplanet-am-auth-ldap-user-naming-attribute</literal>,

<literal>iplanet-am-auth-ldap-user-search-attributes</literal>,

<literal>iplanet-am-auth-ldap-search-filter</literal>, and

<literal>iplanet-am-auth-ldap-search-scope</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>SSL/TLS Access to Active Directory Server</term>

<listitem>

<para>If you enable SSL/TLS, OpenAM must be able to trust Active Directory

certificates, either because the Active Directory certificates were

signed by a CA whose certificate is already included in the trust store

used by the container where OpenAM runs, or because you imported the

certificates into the trust store.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-ldap-ssl-enabled</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Return User DN to DataStore</term>

<listitem>

<para>When enabled, and OpenAM uses Active Directory as the user store,

the module returns the DN rather than the User ID, so the bind for

authentication can be completed without a search to retrieve

the DN.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-ldap-return-user-dn</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>User Creation Attributes</term>

<listitem>

<para>This list lets you map (external) attribute names from Active

Directory to (internal) attribute names used by OpenAM.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-ldap-user-creation-attr-list</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>LDAP Connection Heartbeat Interval</term>

<listitem>

<para>Specifies how often OpenAM should send a heartbeat request to the

directory server to ensure that the connection does not remain idle. Some

network administrators configure firewalls and load balancers to drop

connections that are idle for too long. You can turn this off by setting

the value to 0 or to a negative number. To set the units for the interval

use LDAP Connection Heartbeat Time Unit.</para>

<para>Default: 1</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-ldap-heartbeat-interval</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>LDAP Connection Heartbeat Time Unit</term>

<listitem>

<para>Specifies the time unit corresponding to LDAP Connection Heartbeat

Interval.</para>

<para>Default: minute</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-ldap-heartbeat-interval</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Authentication Level</term>

<listitem>

<para>Sets the authentication level used to indicate the level of security

associated with the module. The value can range from 0 to any positive integer.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthADAuthLevel</literal></para></listitem>

</varlistentry>

</variablelist>

</section>

<section xml:id="adaptive-auth-module-conf-hints">

<title>Hints For the Adaptive Risk Authentication Module</title>

<para>The Adaptive Risk module is designed to assess risk during

authentication so that OpenAM can determine whether to require the

user to complete further authentication steps. After configuring the

Adaptive Risk module, insert it in your authentication chain with criteria

set to sufficient as shown in the following example.</para>

<mediaobject xml:id="figure-adaptive-auth-module">

<alt>Including the Adaptive Risk module in an authentication chain</alt>

<imageobject>

<imagedata fileref="images/adaptive-auth-module.png" format="PNG" />

</imageobject>

<textobject><para>With the Adaptive Risk module as sufficient, OpenAM

continues to the next module in the chain should the Adaptive Risk module

return failure.</para></textobject>

</mediaobject>

<para>In the example authentication chain shown, OpenAM has users

authenticate first using the LDAP module providing a user ID and password

combination. Upon success, OpenAM calls the Adaptive Risk module. The

Adaptive Risk module assesses the risk based on your configured parameters.

If the Adaptive Risk module calculates a total score below the threshold you

set, the module returns success, and OpenAM finishes authentication

processing without requiring further credentials. Otherwise the Adaptive

Risk module evaluates the score to be above the risk threshold, and returns

failure. OpenAM then calls the HOTP module, requiring the user to

authenticate with a one-time password delivered to her by email or by SMS

to her mobile phone.</para>

<para>When you configure the Adaptive Risk module to save cookies and

profile attributes after successful authentication, OpenAM performs the

save as post-authentication processing, only after the entire authentication

chain returns success. You must set up OpenAM to save the data as part of

post-authentication processing by editing the authentication chain to add

<literal>org.forgerock.openam.authentication.modules.adaptive.Adaptive</literal>

to the list of post authentication plugins.</para>

<indexterm>

<primary>Authentication</primary>

<secondary>Adaptive risk</secondary>

</indexterm>

<para>

When the Adaptive Risk module relies on the client IP address,

and OpenAM lies behind a load balancer or proxy layer,

configure the load balancer or proxy to send the address

by using the <literal>X-Forwarded-For</literal> header,

and configure OpenAM to consume and forward the header as necessary.

For details, see the <citetitle>Installation Guide</citetitle> section,

<link

xlink:show="new"

xlink:href="install-guide#handle-request-headers"

xlink:role="http://docbook.org/xlink/role/olink"

><citetitle>Handling HTTP Request Headers</citetitle></link>.

</para>

<para><command>ssoadm</command> service name:

<literal>sunAMAuthAdaptiveService</literal></para>

<variablelist>

<title>General</title>

<varlistentry>

<term>Authentication Level</term>

<listitem>

<para>Sets the authentication level used to indicate the level of security

associated with the module. The value can range from 0 to any positive integer.</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-auth-level</literal></para></listitem>

</varlistentry>

<varlistentry>

<term>Risk Threshold</term>

<listitem>

<para>Risk threshold score. If the sum of the Scores is greater than the

threshold, the Adaptive Risk module returns failure. Default: 1</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-auth-threshold</literal></para>

</listitem>

</varlistentry>

</variablelist>

<variablelist>

<title>Failed Authentications</title>

<varlistentry>

<term>Failed Authentication Check</term>

<listitem>

<para>When enabled, check the user profile for authentication failures

since the last successful login. This check therefore requires

OpenAM to have access to the user profile, and Account Lockout to be

enabled (otherwise OpenAM does not record authentication

failures).</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-failure-check</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Score</term>

<listitem>

<para>Value to add to the total score if the user fails the Failed

Authentication Check. Default: 1</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-failure-score</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Invert Result</term>

<listitem>

<para>When selected, add the Score to the total score if the user

passes the Failed Authentication Check.</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-failure-invert</literal></para>

</listitem>

</varlistentry>

</variablelist>

<variablelist>

<title>IP Address Range</title>

<varlistentry>

<term>IP Range Check</term>

<listitem>

<para>When enabled, check whether the client IP address is within one

of the specified IP Ranges.</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-ip-range-check</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>IP Range</term>

<listitem>

<para>For IPv4, specifies a list of IP ranges either in CIDR-style notation

(<literal><replaceable>x.x.x.x</replaceable>/<replaceable>YY</replaceable></literal>)

or as a range from one address to another

(<literal><replaceable>x.x.x.x</replaceable>-<replaceable>y.y.y.y</replaceable></literal>,

meaning from <replaceable>x.x.x.x</replaceable> to

<replaceable>y.y.y.y</replaceable>).</para>

<para>For IPv6, specifies a list of IP ranges either in CIDR-style notation

(<literal><replaceable>X:X:X:X:X:X:X:X</replaceable>/<replaceable>YY</replaceable></literal>)

or as a range from one address to another

(<literal><replaceable>X:X:X:X:X:X:X:X</replaceable>-<replaceable>Y:Y:Y:Y:Y:Y:Y:Y</replaceable></literal>,

meaning from <replaceable>X:X:X:X:X:X:X:X</replaceable> to

<replaceable>Y:Y:Y:Y:Y:Y:Y:Y</replaceable>).</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-ip-range-range</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Score</term>

<listitem>

<para>Value to add to the total score if the user fails the IP Range

Check. Default: 1</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-ip-range-score</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Invert Result</term>

<listitem>

<para>When selected, add the Score to the total score if the user

passes the IP Range Check.</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-ip-range-invert</literal></para>

</listitem>

</varlistentry>

</variablelist>

<variablelist>

<title>IP Address History</title>

<varlistentry>

<term>IP History Check</term>

<listitem>

<para>When enabled, check whether the client IP address matches one of

the known values stored on the profile attribute you specify. This check

therefore requires that OpenAM have access to the user profile.</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-ip-history-check</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>History Size</term>

<listitem>

<para>Specifies how many IP address values to retain on the profile

attribute you specify. Default: 5</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-ip-adaptive-history-count</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Profile Attribute Name</term>

<listitem>

<para>Name of the user profile attribute on which to store known IP

addresses. Default: <literal>iphistory</literal></para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-ip-history-attribute</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Save Successful IP Address</term>

<listitem>

<para>When enabled, save new client IP addresses to the known IP address

list following successful authentication.</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-ip-history-save</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Score</term>

<listitem>

<para>Value to add to the total score if the user fails the IP History

Check. Default: 1</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-ip-history-score</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Invert Result</term>

<listitem>

<para>When selected, add the Score to the total score if the user

passes the IP History Check.</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-ip-history-invert</literal></para>

</listitem>

</varlistentry>

</variablelist>

<variablelist>

<title>Known Cookie</title>

<varlistentry>

<term>Cookie Value Check</term>

<listitem>

<para>When enabled, check whether the client browser request has the

specified cookie and optional cookie value.</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-known-cookie-check</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Cookie Name</term>

<listitem>

<para>Specifies the name of the cookie for which OpenAM checks when

you enable the Cookie Value Check.</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-known-cookie-name</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Cookie Value</term>

<listitem>

<para>Specifies the value of the cookie for which OpenAM checks. If

no value is specified, OpenAM does not check the cookie value.</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-known-cookie-value</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Save Cookie Value on Successful Login</term>

<listitem>

<para>When enabled, save the cookie as specified in the client's browser

following successful authentication. If no Cookie Value is specified,

the value is set to 1.</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-known-cookie-save</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Score</term>

<listitem>

<para>Value to add to the total score if user passes the Cookie Value

Check. Default: 1</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-known-cookie-score</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Invert Result</term>

<listitem>

<para>When selected, add the Score to the total score if the user

passes the Cookie Value Check.</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-known-cookie-invert</literal></para>

</listitem>

</varlistentry>

</variablelist>

<variablelist>

<title>Device Cookie</title>

<varlistentry>

<term>Device Registration Cookie Check</term>

<listitem>

<para>When enabled, check whether the client browser request has the

specified cookie with the correct device registration identifier as

the value.</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-device-cookie-check</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Cookie Name</term>

<listitem>

<para>Specifies the name of the cookie for the Device Registration Cookie

Check. Default: Device</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-device-cookie-name</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Save Device Registration on Successful Login</term>

<listitem>

<para>When enabled, save the specified cookie with a hashed device

identifier value in the client's browser following successful

authentication.</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-device-cookie-save</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Score</term>

<listitem>

<para>Value to add to the total score if the user fails the Device

Registration Cookie Check. Default: 1</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-device-cookie-score</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Invert Result</term>

<listitem>

<para>When selected, add the Score to the total score if the user

passes the Device Registration Cookie Check.</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-device-cookie-invert</literal></para>

</listitem>

</varlistentry>

</variablelist>

<variablelist>

<title>Time Since Last Login</title>

<varlistentry>

<term>Time Since Last Login Check</term>

<listitem>

<para>When enabled, check whether the client browser request has the

specified cookie that holds the encrypted last login time, and check

that the last login time is more recent than a maximum number of days you

specify.</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-time-since-last-login-check</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Cookie Name</term>

<listitem>

<para>Specifies the name of the cookie holding the encrypted last login

time value.</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-time-since-last-login-cookie-name</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Max Time since Last Login</term>

<listitem>

<para>Specifies a threshold age of the last login time in days. If the

client's last login time is more recent than the number of days specified,

then the client successfully passes the check.</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-time-since-last-login-value</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Save time of Successful Login</term>

<listitem>

<para>When enabled, save the specified cookie with the current time

encrypted as the last login value in the client's browser following

successful authentication.</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-time-since-last-login-save</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Score</term>

<listitem>

<para>Value to add to the total score if the user fails the Time Since

Last Login Check. Default: 1</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-time-since-last-login-score</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Invert Result</term>

<listitem>

<para>When selected, add the Score to the total score if the user

passes the Time Since Last Login Check.</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-time-since-last-login-invert</literal></para>

</listitem>

</varlistentry>

</variablelist>

<variablelist>

<title>Profile Attribute</title>

<varlistentry>

<term>Profile Risk Attribute check</term>

<listitem>

<para>When enabled, check whether the user profile contains the specified

attribute and value.</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-risk-attribute-check</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Attribute Name</term>

<listitem>

<para>Specifies the attribute to check on the user profile for the

specified value.</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-risk-attribute-name</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Attribute Value</term>

<listitem>

<para>Specifies the value to match on the profile attribute. If the

attribute is multi-valued, a single match is sufficient to pass the

check.</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-risk-attribute-value</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Score</term>

<listitem>

<para>Value to add to the total score if the user fails the Profile Risk

Attribute Check. Default: 1</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-risk-attribute-score</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Invert Result</term>

<listitem>

<para>When selected, add the Score to the total score if the user

passes the Profile Risk Attribute Check.</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-risk-attribute-invert</literal></para>

</listitem>

</varlistentry>

</variablelist>

<variablelist>

<title>Geo Location</title>

<varlistentry>

<term>Geolocation Country Code Check</term>

<listitem>

<para>When enabled, check whether the client IP address location matches

a country specified in the Valid Country Codes list. The </para>

<para><command>ssoadm</command> attribute:

<literal>forgerock-am-auth-adaptive-geo-location-check</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Geolocation Database location</term>

<listitem>

<para>Path to GeoIP data file used to convert IP addresses to

country locations. The geolocation database is not packaged with OpenAM.

You can downloaded the GeoIP Country database from <link

xlink:href="http://www.maxmind.com/en/country">MaxMind</link>. Use the binary

.dat file format, rather than .csv. You can use the GeoLite Country database

for testing.</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-geo-location-database</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Valid Country Codes</term>

<listitem>

<para>Specifies the list of country codes to match. Use

<literal>|</literal> to separate multiple values.</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-geo-location-values</literal>.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Score</term>

<listitem>

<para>Value to add to the total score if the user fails the Geolocation

Country Code Check. Default: 1</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-geo-location-score</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Invert Result</term>

<listitem>

<para>When selected, add the Score to the total score if the user

passes the Geolocation Country Code Check.</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-geo-location-invert</literal></para>

</listitem>

</varlistentry>

</variablelist>

<variablelist>

<title>Request Header</title>

<varlistentry>

<term>Request Header Check</term>

<listitem>

<para>When enabled, check whether the client browser request has the

specified header with the correct value.</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-req-header-check</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Request Header Name</term>

<listitem>

<para>Specifies the name of the request header for the Request Header

Check.</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-req-header-name</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Request Header Value</term>

<listitem>

<para>Specifies the value of the request header for the Request Header

Check.</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-req-header-value</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Score</term>

<listitem>

<para>Value to add to the total score if the user fails the Request

Header Check. Default: 1</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-req-header-score</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Invert Result</term>

<listitem>

<para>When selected, add the Score to the total score if the user

passes the Request Header Check.</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-req-header-invert</literal></para>

</listitem>

</varlistentry>

</variablelist>

</section>

<section xml:id="anon-module-conf-hints">

<title>Hints For the Anonymous Authentication Module</title>

<para>This module lets you configure and track anonymous users, who can log in

to your application or web site without login credentials.

Typically, you would provide such users with very limited access,

for example, an anonymous user may have access to public downloads on your site.

When the user attempts to access resources that require more protection,

the module can force further authentication for those resources.</para>

<para>You can configure the Anonymous Authentication Module

by specifying the <command>ssoadm</command> service name and Anonymous

Authentication realm attributes: Valid Anonymous Users, Default User Name,

Case Sensitive User IDs, and Authentication Level.

</para>

<para><command>ssoadm</command> service name:

<literal>iPlanetAMAuthAnonymousService</literal></para>

<indexterm>

<primary>Authentication</primary>

<secondary>Anonymous</secondary>

</indexterm>

<variablelist>

<varlistentry>

<term>Valid Anonymous Users</term>

<listitem>

<para>Specifies the list of valid anonymous user IDs that can log in without

submitting a password.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-anonymous-users-list</literal></para>

<para>When user accesses the default module instance login URL, then the

module prompts the user to enter a valid anonymous user name.</para>

<para>The default module instance login URL is defined as follows:</para>

<literallayout class="monospaced">protocol://hostname:port/deploy_URI/UI/Login?module=Anonymous&amp;org=org_name</literallayout>

<para>Next, OpenAM checks that the user ID is a valid anonymous user name.

If the valid anonymous user ID exists in the list, the user is granted access to

the application and the session is assigned to the user.

The valid user can bypass the Login page at the following URL:</para>

<literallayout class="monospaced">protocol://hostname:port/deploy_URI/UI/Login?module=Anonymous&amp;org=org_name&amp;

IDToken1=&lt;valid anonymous username&gt;</literallayout>

<para>If the valid anonymous user ID does not exist in the list,

the user will be authenticated as the Default Anonymous User Name (see below).</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Default Anonymous User Name</term>

<listitem>

<para>Specifies the user ID assigned by the module if the Valid

Anonymous Users list is empty. The default value is <literal>anonymous</literal>.

Note that the anonymous user must be defined in the realm.</para>

<literallayout class="monospaced">protocol://hostname:port/deploy_URI/UI/Login?module=Anonymous&amp;org=orgName

&amp;IDToken1=&lt;Default Anonymous User Name&gt;</literallayout>

<para>For example, the user can bypass the Login page by accessing the URL

as the default anonymous user using the value of <literal>anonymous</literal>:</para>

<literallayout class="monospaced">http://openam.example.com:8080/openam/UI/Login?module=Anonymous&amp;org=example.com

&amp;IDToken1=anonymous</literallayout>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-anonymous-default-user-name</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Case Sensitive User IDs</term>

<listitem>

<para>Determines whether case matters for anonymous user IDs.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-anonymous-case-sensitive</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Authentication Level</term>

<listitem>

<para>Sets the authentication level used to indicate the level of security

associated with the module. The value can range from 0 (default) to any

positive integer and is set for each authentication method.

The higher number corresponds to a higher level of authentication.

If you configured your authentication levels from a 0 to 5 scale, then an

authentication level of 5 will require the highest level of authentication.</para>

<para>After a user has authenticated, OpenAM stores the authentication level in

the session token.

When the user attempts to access a protected resource, the token is

presented to the application.

The application uses the token's value to determine if the user has the

correct authentication level required to access the resource.

If the user does not have the required authentication level,

the application can prompt the user to authenticate with a higher

authentication level. </para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-anonymous-auth-level</literal></para>

</listitem>

</varlistentry>

</variablelist>

<note><para>You can configure the Anonymous Authentication Module using the

OpenAM Console by clicking <literal>Configuration</literal> &gt;

<literal>Authentication</literal> &gt; <literal>Anonymous</literal>.</para></note>

</section>

<section xml:id="cert-module-conf-hints">

<title>Hints For the Certificate Authentication Module</title>

<para>X.509 digital certificates can enable secure authentication without

the need for user names and passwords or other credentials. Certificate

authentication can be handy to manage authentication by applications.

If all certificates are signed by a recognized Certificate Authority (CA),

then you might get away without additional configuration. If you need to

look up public keys of OpenAM clients, this module can also look up public

keys in an LDAP directory server.</para>

<para>When you store certificates and certificate revocation lists (CRL)

in an LDAP directory service, you must configure both how to access the

directory service and also how to look up the certificates and CRLs,

based on the fields in the certificates that OpenAM clients present to

authenticate.</para>

<para>Access to the LDAP server and how to search for users is similar

to LDAP module configuration as in <xref linkend="ldap-module-conf-hints" />.

The primary difference is that, unlike for LDAP configuration, OpenAM

retrieves the user identifier from a field in the certificate that the

client application presents, then uses that identifier to search for the

LDAP directory entry that holds the certificate, which should match the

certificate presented. For example, if the Subject field of a typical

certificate has a DN <literal>C=FR, O=Example Corp, CN=Barbara

Jensen</literal>, and Barbara Jensen's entry in the directory has

<literal>cn=Barbara Jensen</literal>, then you can use <literal>CN=Barbara

Jensen</literal> from the Subject DN to search for the entry with

<literal>cn=Barbara Jensen</literal> in the directory.</para>

<indexterm>

<primary>Authentication</primary>

<secondary>X509 certificate based</secondary>

</indexterm>

<para><command>ssoadm</command> service name:

<literal>iPlanetAMAuthCertService</literal></para>

<variablelist>

<varlistentry>

<term>Match Certificate in LDAP</term>

<listitem>

<para>When enabled, OpenAM searches for a match for the user's

certificate in the LDAP directory. If a match is found and not revoked

according to a CRL or OCSP validation, then authentication succeeds.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-cert-check-cert-in-ldap</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Subject DN Attribute Used to Search LDAP for Certificates</term>

<listitem>

<para>Indicates which attribute and value in the certificate Subject DN

is used to find the LDAP entry holding the certificate.</para>

<para>Default: CN</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-cert-attr-check-ldap</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Match Certificate to CRL</term>

<listitem>

<para>When enabled, OpenAM checks whether the certificate has been

revoked according to a CRL in the LDAP directory.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-cert-check-crl</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Issuer DN Attribute Used to Search LDAP for CRLs</term>

<listitem>

<para>Indicates which attribute and value in the certificate Issuer DN

is used to find the CRL in the LDAP directory.</para>

<para>Default: CN</para>

<para>If only one attribute is specified, the LDAP search filter used to

find the CRL based on the Subject DN of the CA certificate is

<literal>(<replaceable>attr-name</replaceable>=<replaceable

>attr-value-in-subject-DN</replaceable>)</literal>.</para>

<para>For example, if the subject DN of the issuer certificate is

<literal>C=US, CN=Some CA, serialNumber=123456</literal>, and the

attribute specified is <literal>CN</literal>, then the LDAP search filter

used to find the CRL is <literal>(CN=Some CA)</literal>.</para>

<para>In order to distinguish among different CRLs for the same CA issuer,

specify multiple attributes separated by commas (<literal>,</literal>) in

the same order they occur in the subject DN. When multiple attribute names

are provided in a comma-separated list, the LDAP search filter used is

<literal>(cn=<replaceable>attr1</replaceable>=<replaceable

>attr1-value-in-subject-DN</replaceable>,<replaceable

>attr2</replaceable>=<replaceable

>attr2-value-in-subject-DN</replaceable

>,...,<replaceable>attrN</replaceable

>=<replaceable>attrN-value-in-subject-DN</replaceable>)</literal>.</para>

<para>For example, if the subject DN of the issuer certificate is

<literal>C=US, CN=Some CA, serialNumber=123456</literal>, and the

attributes specified are <literal>CN,serialNumber</literal>, then

the LDAP search filter used to find the CRL is

<literal>(cn=CN=Some CA,serialNumber=123456)</literal>.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-cert-attr-check-crl</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>HTTP Parameters for CRL Update</term>

<listitem>

<para>Your certificate authority should provide the URL to use here,

from which OpenAM can get CRL updates.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-cert-param-get-crl</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Match CA Certificate to CRL</term>

<listitem>

<para>When enabled, OpenAM checks the CRL against the CA certificate to

ensure it has not been compromised.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMValidateCACert</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Cache CRLs in Memory</term>

<listitem>

<para>When enabled, CRLs will be cached.</para>

<para><command>ssoadm</command> attribute:

<literal>openam-am-auth-cert-attr-cache-crl</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Update CA CRLs from CRLDistributionPoint</term>

<listitem>

<para>When enabled, OpenAM updates CRLs from the LDAP directory store.</para>

<para><command>ssoadm</command> attribute:

<literal>openam-am-auth-cert-update-crl</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>OCSP Validation</term>

<listitem>

<para>Enable this to use Online Certificate Status Protocol (OCSP)

instead of CRLs to check certificates' revocation status.</para>

<para>If you enable this, you also must configure OSCP for OpenAM

under Configuration &gt; Server and Sites &gt; Default Server Settings,

or Configuration &gt; Server and Sites &gt; <replaceable>Server

Name</replaceable> &gt; Security.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-cert-check-ocsp</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>LDAP Server Where Certificates are Stored</term>

<listitem>

<para>Identifies the LDAP server with certificates. Remember to specify URLs

with appropriate port numbers (389 for unencrypted LDAP, 636 for LDAP over SSL).

When configuring a secure connection, scroll down to enable Use SSL/TLS for LDAP

Access.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-cert-ldap-provider-url</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>LDAP Search Start or Base DN</term>

<listitem>

<para>Valid base DN for the LDAP search, such as

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

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-cert-start-search-loc</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>LDAP Server Authentication User, LDAP Server Authentication Password</term>

<listitem>

<para>If OpenAM stores attributes in the LDAP directory, for example to

manage account lockout, or if the LDAP directory requires that OpenAM

authenticate in order to read users' attributes, then OpenAM needs the

DN and password to authenticate to the LDAP directory.</para>

<para><command>ssoadm</command> attributes:

<literal>iplanet-am-auth-cert-principal-user</literal>, and

<literal> iplanet-am-auth-cert-principal-passwd</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Use SSL/TLS for LDAP Access</term>

<listitem>

<para>If you use SSL/TLS for LDAP access, OpenAM must be able to trust the

LDAP server certificate.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-cert-use-ssl</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Certificate Field Used to Access User Profile</term>

<listitem>

<para>If the user profile is in a different entry from the user

certificate, then this can be different from subject DN attribute

used to find the entry with the certificate. When you select other,

provide an attribute name in the Other Certificate Field Used to Access

User Profile text box.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-cert-user-profile-mapper</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Other Certificate Field Used to Access User Profile</term>

<listitem>

<para>This field is only used if the Certificate Field Used to Access

User Profile attribute is set to other. This field allows a custom

certificate field to be used as the basis of the user search.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-cert-user-profile-mapper-other</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>SubjectAltNameExt Value Type to Access User Profile</term>

<listitem>

<para>Use this if you want to look up the user profile from an RFC 822

style name, or a User Principal Name as used in Active Directory.</para>

<para><command>ssoadm</command> attribute:

<literal> iplanet-am-auth-cert-user-profile-mapper-ext</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Trusted Remote Hosts</term>

<listitem>

<para>Hosts trusted to send certificates to OpenAM, such as load balancers

doing SSL termination, or OpenAM distributed authentication UI

instances.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-cert-gw-cert-auth-enabled</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>HTTP Header Name for Client Certificate</term>

<listitem>

<para>If you configure trusted hosts, specify the HTTP header name for

the client certificate inserted by the trusted host.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMHttpParamName</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Authentication Level</term>

<listitem>

<para>Sets the authentication level used to indicate the level of security

associated with the module. The value can range from 0 to any positive integer.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-cert-auth-level</literal></para></listitem>

</varlistentry>

</variablelist>

</section>

<section xml:id="core-module-conf-hints">

<title>Hints For the Core Authentication Module</title>

<para>The Core module is a meta-module.</para>

<para>The Core module lets you set up the list of modules available,

and specify what types of client applications can authenticate with which

modules. It also lets you configure connection pools for access to

directory servers, and whether to retain objects used during authentication

for use during logout. Furthermore, the Core module lets you set defaults

used when configuring authentication in a particular realm.</para>

<indexterm>

<primary>Authentication</primary>

<secondary>Core</secondary>

</indexterm>

<itemizedlist>

<para>The Core Authentication module is divided into seven sections:</para>

<listitem>

<para><xref linkend="auth-core-global" /></para>

</listitem>

<listitem>

<para><xref linkend="auth-core-realm-attributes" /></para>

</listitem>

<listitem>

<para><xref linkend="auth-core-persistent-cookie" /></para>

</listitem>

<listitem>

<para><xref linkend="auth-core-account-lockout" /></para>

</listitem>

<listitem>

<para><xref linkend="auth-core-general" /></para>

</listitem>

<listitem>

<para><xref linkend="auth-core-security" /></para>

</listitem>

<listitem>

<para><xref linkend="auth-core-post-auth" /></para>

</listitem>

</itemizedlist>

<para><command>ssoadm</command> service name:

<literal>iPlanetAMAuthService</literal></para>

<section xml:id="auth-core-global">

<title>Core - Global Attributes</title>

<para>The Global Attributes includes the list of available modules, LDAP connection

settings, authentication process options, and an option to make the XUI the

default interface. The Global Attributes are defined in the

<link xlink:href="reference#authentication-configuration" xlink:show="new"

xlink:role="http://docbook.org/xlink/role/olink">

<citetitle>Authentication Configuration</citetitle></link> section of the

OpenAM Reference Guide.</para>

<!-- This was the only way I could keep the other variablelist's from errors -->

<!-- New "XUI Interface" option added to that section of the Reference Guide -->

</section>

<section xml:id="auth-core-realm-attributes">

<title>Core - Realm Attributes</title>

<para>This section of the Core Authentication module is on the Realm Attributes section

page before options for Persistent Cookies.</para>

<variablelist>

<varlistentry>

<term><emphasis>User Profile</emphasis></term>

<term>User Profile</term>

<listitem>

<para>Whether a user profile needs to exist in the user data store,

or should be created on successful authentication.</para>

<variablelist>

<varlistentry>

<term>Dynamic</term>

<listitem>

<para>Specifies that on successful authentication the Authentication

Service creates a user profile if one does not already exist.

OpenAM then issues the SSOToken. OpenAM creates the user profile

in the user data store configured for the realm.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Dynamic with User Alias</term>

<listitem>

<para>Specifies that on successful authentication the Authentication

Service creates a user profile that contains the User Alias List

attribute which defines one or more aliases that for mapping a

user's multiple profiles.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Ignored</term>

<listitem>

<para>Specifies that a user profile is not required for the

Authentication Service to issue an SSOToken after a successful

authentication.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Required</term>

<listitem>

<para>Specifies that on successful authentication the user must have

a user profile in the user data store configured for the realm in

order for the Authentication Service to issue an SSOToken.</para>

</listitem>

</varlistentry>

</variablelist>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-dynamic-profile-creation</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>User Profile Dynamic Creation Default Roles</term>

<listitem>

<para>Specifies the Distinguished Name (DN) of a role to be assigned to

a new user whose profile is created when either of the Dynamic options

is selected under the User Profile attribute. There are no default

values. The role specified must be within the realm for which the

authentication process is configured.</para>

<para>This role can be either an OpenAM or Sun DSEE role, but it cannot

be a filtered role. If you wish to automatically assign specific services

to the user, you have to configure the Required Services attribute in

the User Profile.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-default-role</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Alias Search Attribute Name</term>

<listitem>

<para>After a user is successfully authenticated, the user's profile is

retrieved. OpenAM first searches for the user based on the data store settings.

If that fails to find the user, OpenAM will use the attributes listed here to

lookup the user profile. This setting accepts any data store specific attribute

name.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-alias-attr-name</literal></para>

</listitem>

</varlistentry>

</variablelist>

</section>

<section xml:id="auth-core-persistent-cookie">

<title>Core - Persistent Cookie (Legacy)</title>

<para>This section of the Core Authentication module covers the Persistent Cookie options.</para>

<note><para>Two methods are available in OpenAM to configure persistent cookies. The options described

here and in <xref linkend="authn-from-browser" /> specify one method. There is also a new module,

described in <xref linkend="persistent-cookie" />. If you want to set up persistent cookies, you are

encouraged to use the new module. The options described here have no effect on that module.</para></note>

<variablelist>

<varlistentry>

<term>Persistent Cookie Mode</term>

<listitem>

<para>Determines whether users can return to their authenticated session

after restarting the browser. When enabled, the persistent cookie can be

used to reauthenticate until the persistent cookie expires (as specified

by the value of the Persistent Cookie Maximum Time attribute), or until

the user explicitly logs out. By default, the Authentication Service uses

only memory cookies (expires when the browser is closed).</para>

<para>The client must explicitly request a persistent cookie by adding

<literal>iPSPCookie=yes</literal> as a parameter to the login URL. OpenAM

sets a <literal>DProPCookie</literal> as described in

<xref linkend="authn-from-browser" />.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-persistent-cookie-mode</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Persistent Cookie Maximum Time</term>

<listitem>

<para>Specifies the interval after which a persistent cookie expires.

The interval begins when the user's session is successfully authenticated.

The maximum value is 2147483647 (in seconds, so a bit more than 68 years).

The field accepts any integer value less than the maximum.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-persistent-cookie-time</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Persistent Cookie Authentication Level</term>

<listitem>

<para>Sets the authentication level used to indicate the level of security

associated with the module. The value can range from 0 to any positive integer.</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-pcookie-auth-level</literal></para>

</listitem>

</varlistentry>

</variablelist>

</section>

<section xml:id="auth-core-account-lockout">

<title>Core - Account Lockout</title>

<para>This section of the Core Authentication module

includes details on how account lockouts can be configured.</para>

<variablelist>

<varlistentry>

<term>Login Failure Lockout Mode</term>

<listitem>

<para>Selecting this attribute enables a physical lockout. Physical

lockout will inactivate an LDAP attribute (defined in the Lockout

Attribute Name property) in the user's profile. This attribute works in

conjunction with several other lockout and notification attributes.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-login-failure-lockout-mode</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Login Failure Lockout Count</term>

<listitem>

<para>Defines the number of attempts that a user has to authenticate,

within the time interval defined in Login Failure Lockout Interval,

before being locked out.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-login-failure-count</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Login Failure Lockout Interval</term>

<listitem>

<para>Defines the time in minutes during which failed login attempts are

counted. If one failed login attempt is followed by a second failed

attempt, within this defined lockout interval time, the lockout count

starts, and the user is locked out if the number of attempts reaches

the number defined in Login Failure Lockout Count. If an attempt within

the defined lockout interval time proves successful before the number of

attempts reaches the number defined in Login Failure Lockout Count, the

lockout count is reset.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-login-failure-duration</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Email Address to Send Lockout Notification</term>

<listitem>

<para>Specify one (or more) email address(es) to which notification is

sent if a user lockout occurs.</para>

<para>Separate multiple addresses with spaces, and append

<literal>|<replaceable>locale</replaceable>|<replaceable>charset</replaceable></literal>

to addresses for recipients in non-English locales.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-lockout-email-address</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Warn User After N Failures</term>

<listitem>

<para>The number of authentication failures after which OpenAM displays

a warning message that the user will be locked out.</para>

<para><command>ssoadm</command> attribute:

<literal> iplanet-am-auth-lockout-warn-user</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Login Failure Lockout Duration</term>

<listitem>

<para>Defines how many minutes a user must wait after a lockout before

attempting to authenticate again. Entering a value greater than 0 enables

memory lockout and disables physical lockout. Memory lockout means

the user's account is locked in memory for the number of minutes

specified. The account is unlocked after the time period has passed.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-lockout-duration</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Lockout Duration Multiplier</term>

<listitem>

<para>Defines a value with which to multiply the value of the Login

Failure Lockout Duration attribute for each successive lockout. For

example, if Login Failure Lockout Duration is set to 3 minutes, and the

Lockout Duration Multiplier is set to 2, the user is locked out of the

account for 6 minutes. Once the 6 minutes has elapsed, if the user again

provides the wrong credentials, the lockout duration is then 12 minutes.

With the Lockout Duration Multiplier, the lockout duration is

incrementally increased based on the number of times the user has been

locked out.</para>

<para><command>ssoadm</command> attribute:

<literal>sunLockoutDurationMultiplier</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Lockout Attribute Name</term>

<listitem>

<para>Defines the LDAP attribute used for physical lockout. The default

value is <literal>inetuserstatus</literal>, although the field in the

OpenAM console is empty. The Lockout Attribute Value field must also

contain an appropriate value.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-lockout-attribute-name</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Lockout Attribute Value</term>

<listitem>

<para>Specifies the action to take on the attribute defined in Lockout

Attribute Name. The default value is <literal>inactive</literal>,

although the field in the OpenAM console is empty. The Lockout Attribute

Name field must also contain an appropriate value.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-lockout-attribute-value</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Invalid Attempts Data Attribute Name</term>

<listitem>

<para>Specifies the LDAP attribute used to hold the number of failed

authentication attempts towards Login Failure Lockout Count.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthInvalidAttemptsDataAttrName</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Store Invalid Attempts in Data Store</term>

<listitem>

<para>Enables the storage of information regarding failed authentication

attempts as the value of the Invalid Attempts Data Attribute Name in

the user data store. In order to store data in this attribute, the

OpenAM schema has to be loaded. Information stored includes number of

invalid attempts, time of last failed attempt, lockout time and lockout

duration. Storing this information in the identity repository allows it

to be shared among multiple instances of OpenAM.</para>

<para><command>ssoadm</command> attribute:

<literal>sunStoreInvalidAttemptsInDS</literal></para>

</listitem>

</varlistentry>

</variablelist>

</section>

<section xml:id="auth-core-general">

<title>Core - General</title>

<para>This section of the Core Authentication module includes general options.</para>

<variablelist>

<varlistentry>

<term>Default Authentication Locale</term>

<listitem>

<para>Specifies the default language subtype to be used by the

Authentication Service. The default value is

<literal>en_US</literal>.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-locale</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Identity Types</term>

<listitem>

<para>Lists the type or types of identities used during a profile lookup. You can

choose more than one to search on multiple types if you would like OpenAM to

conduct a second lookup if the first lookup fails. Default: Agent and User</para>

<variablelist>

<varlistentry>

<term>Agent</term>

<listitem>

<para>Searches for identities under your agents.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>agentgroup</term>

<listitem>

<para>Searches for identities according to your established agent group.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>agentonly</term>

<listitem>

<para>Searches for identities only under your agents.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Group</term>

<listitem>

<para>Searches for identities according to your established groups.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>User</term>

<listitem>

<para>Searches for identities according to your users.</para>

</listitem>

</varlistentry>

</variablelist>

<para><command>ssoadm</command> attribute:

<literal>sunAMIdentityType</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Pluggable User Status Event Classes</term>

<listitem>

<para>Specifies one or more Java classes used to provide a callback

mechanism for user status changes during the authentication process.

The Java class must implement the

<literal>com.sun.identity.authentication.spi.AMAuthCallBack</literal>

OpenAM interface. OpenAM supports account lockout and password changes.

OpenAM supports password changes through the LDAP authentication module,

and so the feature is only available for the LDAP module.</para>

<para>A .jar containing the user status event class belongs in

the <filename>WEB-INF/lib</filename> directory of the deployed OpenAM

instance. If you do not build a .jar, add the class files under

<filename>WEB-INF/classes</filename>. <!--For deployment, add the .jar or

classes into a custom OpenAM .war file.--></para>

<para><command>ssoadm</command> attribute:

<literal>sunAMUserStatusCallbackPlugins</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Default Authentication Level</term>

<listitem>

<para>Specifies the default authentication level for authentication modules.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-default-auth-level</literal></para>

</listitem>

</varlistentry>

</variablelist>

</section>

<section xml:id="auth-core-security">

<title>Core - Security</title>

<para>This section of the Core Authentication module

includes basic security options.</para>

<variablelist>

<varlistentry>

<term>Module Based Authentication</term>

<listitem>

<para>Enables users to authenticate using module-based authentication.

Otherwise, all attempts at authentication using the

<literal>module=<replaceable>module-name</replaceable></literal> login

parameter result in failure. It is recommended that this be turned off in

a production environment.</para>

<para><command>ssoadm</command> attribute:

<literal>sunEnableModuleBasedAuth</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Zero Page Login</term>

<listitem>

<para>Enables the administrator to allow users to authenticate to a single

authentication screen using GET request parameters. Enable this with

caution as it can allow credentials to be cached.</para>

<para><command>ssoadm</command> attribute:

<literal>openam.auth.zero.page.login.enabled</literal></para>

</listitem>

</varlistentry>

</variablelist>

</section>

<section xml:id="auth-core-post-auth">

<title>Core - Post Authentication Processing</title>

<para>This section of the Core Authentication module

specifies options for post authentication processing.</para>

<variablelist>

<varlistentry>

<term>Default Success Login URL</term>

<listitem>

<para>Accepts a list of values that specifies where users are directed

after successful authentication. The format of this attribute is

<literal><replaceable>client-type</replaceable>|<replaceable>URL</replaceable></literal>

although the only value you can specify at this time is a URL

which assumes the type HTML. The default value is

<literal>/openam/console</literal>. Values that do not specify HTTP have

that appended to the deployment URI.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-login-success-url</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Default Failure Login URL</term>

<listitem>

<para>Accepts a list of values that specifies where users are directed

after authentication has failed. The format of this attribute is

<literal><replaceable>client-type</replaceable>|<replaceable>URL</replaceable></literal>

although the only value you can specify at this time is a URL

which assumes the type HTML. Values that do not specify HTTP have

that appended to the deployment URI.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-login-failure-url</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Authentication Post Processing Classes</term>

<listitem>

<para>Specifies one or more Java classes used to customize post

authentication processes for successful or unsuccessful logins.

The Java class must implement the

<literal>com.sun.identity.authentication.spi.AMPostAuthProcessInterface</literal>

OpenAM interface.</para>

<para>A .jar containing the post processing class belongs in

the <filename>WEB-INF/lib</filename> directory of the deployed OpenAM

instance. If you do not build a .jar, add the class files under

<filename>WEB-INF/classes</filename>. For deployment, add the .jar or

classes into a custom OpenAM .war file.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-post-login-process-class</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Generate UserID Mode</term>

<listitem>

<para>When enabled, the Membership module generates a list of alternate

user identifiers if the one entered by a user during the

self-registration process is not valid or already exists. The user

identifiers are generated by the class specified in the Pluggable User

Name Generator Class property.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-username-generator-enabled</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Pluggable User Name Generator Class</term>

<listitem>

<para>Specifies the name of the class used to generate alternate user

identifiers when Generate UserID Mode is enabled. The default value is

<literal>com.sun.identity.authentication.spi.DefaultUserIDGenerator</literal>.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-username-generator-class</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>User Attribute Mapping to Session Attribute</term>

<listitem>

<para>Enables the authenticating user's identity attributes (stored in

the identity repository) to be set as session properties in the user's

SSOToken. The value takes the format

<literal><replaceable>User-Profile-Attribute</replaceable>|<replaceable>Session-Attribute-Name</replaceable></literal>.

If <replaceable>Session-Attribute-Name</replaceable> is not specified,

the value of <replaceable>User-Profile-Attribute</replaceable> is used.

All session attributes contain the <literal>am.protected</literal> prefix

to ensure that they cannot be edited by the Client SDK.</para>

<para>For example, if you define the user profile attribute as mail and

the user's email address (available in the user session) as

<literal>user.mail</literal>, the entry for this attribute would be

<literal>mail|user.mail</literal>. After a successful authentication,

the <literal>SSOToken.getProperty(String)</literal> method is used to

retrieve the user profile attribute set in the session. The user's email

address is retrieved from the user's session using the

<literal>SSOToken.getProperty("am.protected.user.mail")</literal> method

call.</para>

<para>Properties that are set in the user session using User Attribute

Mapping to Session Attributes can not be modified (for example,

<literal>SSOToken.setProperty(String, String)</literal>). This results in

an <literal>SSOException</literal>. Multi-value attributes, such as

<literal>memberOf</literal>, are listed as a single session variable

with a <literal>|</literal> separator.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMUserAttributesSessionMapping</literal></para>

</listitem>

</varlistentry>

</variablelist>

</section>

</section>

<section xml:id="datastore-module-conf-hints">

<title>Hints For the Data Store Authentication Module</title>

<para>The Data Store authentication module allows a login using the Identity

Repository of the realm to authenticate users. Using the Data Store module

removes the requirement to write an authentication plug-in module, load,

and then configure the authentication module if you need to authenticate

against the same data store repository. Additionally, you do not need to

write a custom authentication module where flat-file authentication is

needed for the corresponding repository in that realm.</para>

<para>Yet, the Data Store module is generic. It does not implement data

store-specific capabilities such as the password policy and password reset

features provided by LDAP modules. Therefore the Data Store module returns

failure when such capabilities are invoked.</para>

<indexterm>

<primary>Authentication</primary>

<secondary>Data Store</secondary>

</indexterm>

<para><command>ssoadm</command> service name:

<literal>sunAMAuthDataStoreService</literal></para>

<variablelist>

<varlistentry>

<term>Authentication Level</term>

<listitem>

<para>Sets the authentication level used to indicate the level of security

associated with the module. The value can range from 0 to any positive integer.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthDataStoreAuthLevel</literal></para></listitem>

</varlistentry>

</variablelist>

</section>

<section xml:id="device-print-auth-module-conf-hints">

<title>Hints For the Device Print Authentication Module</title>

<para>The Device Print module is a device fingerprinter. It collects information about client

device locations, fonts, plugins, and more through their browsers. This module does not

stand on its own, as it uses authentication information from a service to validate a username.

The Device Print module then validates other characteristics of the user's system.</para>

<para>If no device print profile is stored for a user, then the user is prompted to fill in an

HMAC One-Time Password (HOTP),

sent by email or text. The user can then save that device print profile. On subsequent requests

the user's device profile is recalled. Each of the device print attributes from the client

are compared against each of the stored attributes. If the differences exceed a configured

number of penalty points, the user is asked for another HOTP.</para>

<!-- change here addresses OPENAM-3058, OPENAM-3069 -->

<para>If you know the HOTP module, some of the attributes in this section may seem familiar. That

is intentional, as the Device Print module includes all HOTP attributes, though not in the same

order.</para>

<note><para>The following example

assumes that the Device Print module comes after LDAP authentication. Alternatively, you could

set it up after another directory service module such as Active Directory, Data Store, RADIUS, or

Windows NT.</para></note>

<indexterm>

<primary>Device</primary>

<secondary>Fingerprinting</secondary>

</indexterm>

<mediaobject xml:id="figure-device-print-module">

<alt>Including the Device Print module in an authentication chain</alt>

<imageobject>

<imagedata fileref="images/device-print-module.png" format="PNG" />

</imageobject>

<textobject><para>The Device Print module must come after another module that validates the associated

username. Appropriate modules include Active Directory, Data Store, LDAP, RADIUS, and Windows NT.

</para></textobject>

</mediaobject>

<para>

When you use the Device Print authentication module in an OpenAM site,

where requests are load balanced across multiple servers,

then you must also edit the advanced OpenAM server property,

<literal>openam.retained.http.request.headers</literal>,

to include the <literal>User-Agent</literal> header.

This ensures that OpenAM correctly identifies the user agent

to the Device Print authentication module

when requests are forwarded between OpenAM servers in the site.

</para>

<para>

For more information on the advanced server property,

<literal>openam.retained.http.request.headers</literal>,

see the <citetitle>Reference</citetitle> section,

<link

xlink:show="new"

xlink:href="reference#servers-advanced-configuration"

xlink:role="http://docbook.org/xlink/role/olink"

><citetitle>Servers > Advanced</citetitle></link>.

</para>

<para>A device fingerprint is based on the unique characteristics of a user like yourself and your

associated device. You can configure the characteristics that should be part of the fingerprint.

These characteristics can include:</para>

<itemizedlist>

<listitem>

<para>User agents, associated with the configuration of a web browser.</para>

</listitem>

<listitem>

<para>Installed fonts.</para>

</listitem>

<listitem>

<para>The plugins installed for the web browser.</para>

</listitem>

<listitem>

<para>The resolution and color depth associated with a display</para>

</listitem>

<listitem>

<para>The timezone or even the geolocation of a device.</para>

</listitem>

</itemizedlist>

<para>You can specify <literal>penalty points</literal> when characteristics of the fingerprint have

changed. If the total <literal>penalty points</literal> exceeds some configured score, the user may

be asked to verify their identity using HOTP.</para>

<para>The default value for each <literal>*-penalty-points</literal>

attribute is 35, with a <literal>*-max-tolerated-penalty-points</literal> of 50.

In other words, if more than one characteristic of the device fingerprint has changed, the

module assumes that the user is trying to connect from a different system.</para>

<para><command>ssoadm</command> service name:

<literal>iPlanetAMAuthDevicePrintModuleService</literal></para>

<variablelist>

<varlistentry>

<term>Authentication Level</term>

<listitem>

<para>Sets the authentication level used to indicate the level of security

associated with the module. The value can range from 0 to any positive integer.</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-adaptive-auth-level</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Profile expiration days</term>

<listitem>

<para>The list of device attributes is collected in a profile, which automatically expires

in a given number of days. Default: 30.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-adaptive-device-print-profile-expiration-days</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Maximum stored profile quantity</term>

<listitem>

<para>The number of device profiles may be limited by user. Default: 5.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-adaptive-device-print-maximum-profiles-stored-quantity</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Automatically store new profiles</term>

<listitem>

<para>When enabled, new device profiles are automatically stored, once the HOTP is verified.

Otherwise, the user is prompted for confirmation.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-adaptive-device-print-store-profiles-without-confirmation</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>User agent penalty points</term>

<listitem>

<para>Specifies the number of penalty points added when there is a difference between the current

and stored user agent. The module adds a fixed number of points if the web browser or

related fields are changed. Version differences are ignored if the

<literal>User-Agent version ignore</literal> attribute is active. Default: 35.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-adaptive-device-print-user-agent-penalty-points</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Installed fonts penalty points</term>

<listitem>

<para>Frequently, when a user installs a new software component, additional fonts are installed.

The Device Print module adds a fixed number of penalty points if there is a change in the

installed fonts since the last login beyond some maximum tolerated level, and the

<literal>Installed fonts required</literal> attribute is enabled. Default: 35.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-adaptive-device-print-installed-fonts-penalty-points</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Installed plugins penalty points</term>

<listitem>

<para>Most devices have a number of plugins installed on their browsers, such as Java, Flash, and

document readers. If the plugins feature is enabled, and there is a change beyond a maximum

tolerated level, a fixed number of penalty points is added. Default: 35.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-adaptive-device-print-installed-plugins-penalty-points</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Screen color depth penalty points</term>

<listitem>

<para>Most client devices are connected to a color monitor, or at least have settings related to

such a device. If the <literal>Screen parameters</literal> feature is enabled, and a change in

color depth is detected, a fixed number of penalty points is added. Default: 35.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-adaptive-device-print-screen-color-depth-penalty-points</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Screen resolution penalty points</term>

<listitem>

<para>Differences in screen resolution sometimes indicate that the user has changed monitors, or

perhaps is adjusting to changing eyesight. Whenever a different screen resolution is detected,

a fixed number of penalty points is added. Default: 35.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-adaptive-device-print-screen-resolution-penalty-points</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Timezone penalty points</term>

<listitem>

<para>Whenever a connection is made from a different timezone, the Device Print module normally

adds a fixed number of penalty points. Organizations where most users travel may want to set

this attribute to a lower value. Default: 35.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-adaptive-device-print-timezone-penalty-points</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Allowed location range</term>

<listitem>

<para>If geolocation is enabled, each profile should include a geographic location. The allowed

location range specifies a maximum distance, in miles. If a user has travelled beyond that distance,

the <literal>Location penalty points</literal> is added to the total. Default: 100.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-adaptive-device-print-location-allowed-range</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>User-Agent version ignore</term>

<listitem>

<para>Upgrades change the version associated with a user agent. Unless this option is enabled, every

change in the version of a browser or related fields is detected as a difference with the stored

profile.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-adaptive-device-print-ignore-version-in-user-agent</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Max number of tolerated different installed fonts</term>

<listitem>

<para>If the <literal>Installed fonts required</literal> attribute is enabled, a comparison is made

in installed fonts between the existing and stored profiles.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-adaptive-device-print-max-tolerated-diffs-in-installed-fonts</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Max tolerated percentage difference between installed fonts</term>

<listitem>

<para>If the <literal>Installed fonts required</literal> attribute is enabled, a comparison is made

in installed fonts between the existing and stored profiles. Any differences in number of fonts

is noted in percent.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-adaptive-device-print-max-tolerated-percentage-to-mark-as-different-installed-fonts</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Max number of tolerated different installed plugins</term>

<listitem>

<para>If the <literal>Installed plugins required</literal> attribute is enabled, a comparison is made

between the installed plugins defined in the existing and stored profiles.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-adaptive-device-print-max-tolerated-diffs-in-installed-plugins</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Max tolerated percentage difference between installed plugins</term>

<listitem>

<para>If the <literal>Installed plugins required</literal> attribute is enabled, a comparison is

made between the installed plugins defined in the existing and stored profiles. Any differences

in number of plugins is noted in percent.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-adaptive-device-print-max-tolerated-percentage-to-mark-as-different-plugins</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>User agent required</term>

<listitem>

<para>The user agent, as defined by <link xlink:show="new"

xlink:href="http://tools.ietf.org/html/rfc4226#section-14.43">RFC 4226 Section 14.43</link>

provides information about the browser, and frequently on the operating system. Default:

enabled.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-adaptive-device-print-user-agent-required</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Installed plugins required</term>

<listitem>

<para>Plugins are components that add a specific feature to an existing application. In this

context, examples of browser plugins are flash, java, and shockwave.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-adaptive-device-print-plugins-required</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Installed fonts required</term>

<listitem>

<para>Fonts are frequently added to an operating system when new applications are installed. If

enabled, installed font information is stored as part of the profile, and checked upon

reconnection for comparison.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-adaptive-device-print-fonts-required</literal></para>

</listitem>

</varlistentry>

<!-- see OPENAM-2492; this should be changed (IMO) to "Geolocation required" -->

<varlistentry>

<term>Geolocation required</term>

<listitem>

<para>The geographic location of a device can be tracked. Can be used to limit access from this device to a

specified range.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-adaptive-device-print-geolocation-required</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Screen parameters required</term>

<listitem>

<para>Display parameters can be used to help differentiate a profile. If enabled, the Device Print module uses

screen color depth and resolution.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-adaptive-device-print-screen-params-required</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Time zone required</term>

<listitem>

<para>The time zone of the current and stored profiles can be collected and compared.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-adaptive-device-print-timezone-required</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Location penalty points</term>

<listitem>

<para>If geo-location has been enabled, and the current location does not match the value stored in

the profile this many points are added as a penalty. Default: 35.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-adaptive-device-print-location-penalty-points</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Maximum tolerated penalty points</term>

<listitem>

<para>A limit, in number of points, between the current and stored Device Print profiles. If the

total is below that value, the Device Print module sees a match. Default: 50.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-adaptive-device-print-max-tolerated-penalty-points</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>SMS Gateway Implementation Class</term>

<listitem>

<para>Change this if you must customize the SMS gateway implementation.

The default class sends an SMS or email, depending on the

configuration.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthHOTPSMSGatewayImplClassName</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Mail Server Host Name</term>

<listitem>

<para>Host name of the mail server supporting Simple Message Transfer

Protocol for electronic mail.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthHOTPSMTPHostName</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Mail Server Host Port</term>

<listitem>

<para>The default outgoing mail server port is 25, 465

(when connecting over SSL).</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthHOTPSMTPHostPort</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Mail Server Authentication Username</term>

<listitem>

<para>User name for OpenAM to connect to the mail server.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthHOTPSMTPUserName</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Mail Server Authentication Password</term>

<listitem>

<para>Password for OpenAM to connect to the mail server.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthHOTPSMTPUserPassword</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Mail Server Secure Connection</term>

<listitem>

<para>If OpenAM connects to the mail server securely, OpenAM must be able

to trust the server certificate.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthHOTPSMTPSSLEnabled</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Email From Address</term>

<listitem>

<para>The <literal>From:</literal> address when sending a one-time

password by mail.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthHOTPSMTPFromAddress</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>One Time Password Validity Length (in minutes)</term>

<listitem>

<para>One-time passwords are valid for 5 minutes after they are generated

by default.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthHOTPPasswordValidityDuration</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>One Time Password Length (in digits)</term>

<listitem>

<para>Set the length of the one-time password to 6 or 8 digits.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthHOTPPasswordLength</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>One Time Password Delivery</term>

<listitem>

<para>Send the one-time password by SMS, by mail, or both.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthHOTPasswordDelivery</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Mobile Phone Number Attribute Names</term>

<listitem>

<para>Provides the attribute name used for the text message. The

default value is <literal>telephoneNumber</literal>.</para>

<para><command>ssoadm</command> attribute:

<literal>openamTelephoneAttribute</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Mobile Carrier Attribute Name</term>

<listitem>

<para>Provides the name of the carrier that will send the text

message.</para>

<para>Every carrier has their own attribute name ending, for example Verizon

uses @vtext.com or vtext.com. Contact your mobile carrier to find out what their

attribute name is. If you will be sending international texts, ask your carrier

if a country code is a required.</para>

<para><command>ssoadm</command> attribute:

<literal>openamSMSCarrierAttribute</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Email Attribute Name</term>

<listitem>

<para>Provides the attribute name used to email the OTP. The

default value is <literal>mail</literal> (email).</para>

<para><command>ssoadm</command> attribute:

<literal>openamEmailAttribute</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Auto Send OTP Code</term>

<listitem>

<para>Setup the HOTP module to automatically generate an email

or text message when users begin the login process. </para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthHOTPAutoClicking</literal></para>

</listitem>

</varlistentry>

</variablelist>

</section>

<section xml:id="federation-module-conf-hints">

<title>Hints For the Federation Authentication Module</title>

<para>The Federation authentication module is used by a service provider

to create a user session after validating single sign-on protocol messages.

This authentication module is used by the SAML, SAMLv2, ID-FF, and

WS-Federation protocols.</para>

<indexterm>

<primary>Authentication</primary>

<secondary>Federation</secondary>

</indexterm>

<para><command>ssoadm</command> service name:

<literal>sunAMAuthFederationService</literal></para>

<variablelist>

<varlistentry>

<term>Authentication Level</term>

<listitem>

<para>Sets the authentication level used to indicate the level of security

associated with the module. The value can range from 0 to any positive integer.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthFederationAuthLevel</literal></para></listitem>

</varlistentry>

</variablelist>

</section>

<section xml:id="hotp-module-conf-hints">

<title>Hints For the HOTP Authentication Module</title>

<para>The HMAC One-Time Password authentication module works together with

the Data Store module to retrieve a user's mail address or telephone number

to send a one-time password to complete authentication.</para>

<para>To use HOTP you set up an authentication chain with the Data Store

module as the <literal>requisite</literal> first module, and the HOTP module

as the second <literal>requisite</literal> module. When authentication

succeeds against the Data Store module, OpenAM passes the Email Address

and Telephone Number attributes from the user profile to the HOTP module.

For the HOTP module to use either attribute, the Email Address must contain

a valid email address, or the Telephone Number must contain a valid

SMS telephone number.</para>

<para>You can set the HOTP module to automatically generate a password when

users begin logging into the system. You can also setup a mobile phone,

mobile carrier, and email attributes for tighter controls over where

the messages are generated and what provider the messages go through to reach

the user.</para>

<indexterm>

<primary>Authentication</primary>

<secondary>HMAC One-Time Password (HOTP)</secondary>

</indexterm>

<para><command>ssoadm</command> service name:

<literal>sunAMAuthHOTPService</literal></para>

<variablelist>

<varlistentry>

<term>Authentication Level</term>

<listitem>

<para>Sets the authentication level used to indicate the level of security

associated with the module. The value can range from 0 to any positive integer.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthHOTPAuthLevel</literal></para></listitem>

</varlistentry>

<varlistentry>

<term>SMS Gateway Implementation Class</term>

<listitem>

<para>Change this if you must customize the SMS gateway implementation.

The default class sends an SMS or email, depending on the

configuration.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthHOTPSMSGatewayImplClassName</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Mail Server Host Name</term>

<listitem>

<para>Host name of the mail server supporting Simple Message Transfer

Protocol for electronic mail.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthHOTPSMTPHostName</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Mail Server Host Port</term>

<listitem>

<para>The default outgoing mail server port is 25, 465 (when connecting over SSL).</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthHOTPSMTPHostPort</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Mail Server Authentication Username</term>

<listitem>

<para>User name for OpenAM to connect to the mail server.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthHOTPSMTPUserName</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Mail Server Authentication Password</term>

<listitem>

<para>Password for OpenAM to connect to the mail server.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthHOTPSMTPUserPassword</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Mail Server Secure Connection</term>

<listitem>

<para>If OpenAM connects to the mail server securely, OpenAM must be able

to trust the server certificate.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthHOTPSMTPSSLEnabled</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Email From Address</term>

<listitem>

<para>The <literal>From:</literal> address when sending a one-time

password by mail.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthHOTPSMTPFromAddress</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>One Time Password Validity Length (in minutes)</term>

<listitem>

<para>One-time passwords are valid for 5 minutes after they are generated

by default.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthHOTPPasswordValidityDuration</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>One Time Password Length (in digits)</term>

<listitem>

<para>Set the length of the one-time password to 6 or 8 digits.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthHOTPPasswordLength</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>One Time Password Delivery</term>

<listitem>

<para>Send the one-time password by SMS, by mail, or both.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthHOTPasswordDelivery</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Mobile Phone Number Attribute Names</term>

<listitem>

<para>Provides the attribute name used for the text message. The

default value is <literal>telephoneNumber</literal>.</para>

<para><command>ssoadm</command> attribute:

<literal>openamTelephoneAttribute</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Mobile Carrier Attribute Name</term>

<listitem>

<para>Provides the name of the carrier that will send the text

message.</para>

<para>Every carrier has their own attribute name ending, for example Verizon

uses @vtext.com or vtext.com. Contact your mobile carrier to find out what their

attribute name is. If you will be sending international texts, ask your carrier

if a country code is a required.</para>

<para><command>ssoadm</command> attribute:

<literal>openamSMSCarrierAttribute</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Email Attribute Name</term>

<listitem>

<para>Provides the attribute name used to email the OTP. The

default value is <literal>mail</literal> (email).</para>

<para><command>ssoadm</command> attribute:

<literal>openamEmailAttribute</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Auto Send OTP Code</term>

<listitem>

<para>Setup the HOTP module to automatically generate an email

or text message when users begin the login process. </para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthHOTPAutoClicking</literal></para>

</listitem>

</varlistentry>

</variablelist>

</section>

<section xml:id="http-module-conf-hints">

<title>Hints For the HTTP Basic Authentication Module</title>

<para>HTTP basic authentication takes a user name and password from HTTP

authentication and tries authentication against the backend module in OpenAM,

depending on what you configure as the Backend Module Name.</para>

<indexterm>

<primary>Authentication</primary>

<secondary>HTTP Basic</secondary>

</indexterm>

<para><command>ssoadm</command> service name:

<literal>iPlanetAMAuthHTTPBasicService</literal></para>

<variablelist>

<varlistentry>

<term>Backend Module Name</term>

<listitem>

<para>Specifies the module that checks the user credentials. The credentials are

then supplied to either a Data Store or other identity repository module for authentication.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-http-basic-module-configured</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Authentication Level</term>

<listitem>

<para>Sets the authentication level used to indicate the level of security

associated with the module. The value can range from 0 to any positive integer.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-httpbasic-auth-level</literal></para></listitem>

</varlistentry>

</variablelist>

</section>

<section xml:id="jdbc-module-conf-hints">

<title>Hints For the JDBC Authentication Module</title>

<para>The Java Database Connectivity (JDBC) module lets OpenAM connect to

a database such as MySQL or Oracle DB to authenticate users.</para>

<indexterm>

<primary>Authentication</primary>

<secondary>JDBC</secondary>

</indexterm>

<para><command>ssoadm</command> service name:

<literal>sunAMAuthJDBCService</literal></para>

<variablelist>

<varlistentry>

<term>Connection Type</term>

<listitem>

<para>Choose Connection pool is retrieved via JNDI to connect using the

Java Naming and Directory Interface connection pool supported by the web

container in which OpenAM runs. Choose Non-persistent JDBC connection to

connect directly through the JDBC driver.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthJDBCConnectionType</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Connection Pool JNDI Name</term>

<listitem>

<para>When using Connection pool is retrieved via JNDI, this specifies

the pool. How you configure connection pooling depends on the web

container where you run OpenAM. Refer to the documentation for your

web container for instructions on setting up connection pooling.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthJDBCJndiName</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>JDBC Driver</term>

<listitem>

<para>When using Non-persistent JDBC connection, this specifies the JDBC

driver provided by the database.</para>

<para>The .jar containing the JDBC driver belongs in the

<filename>WEB-INF/lib</filename> directory of the deployed OpenAM

instance, and so you should add it to a custom OpenAM .war file that you

deploy.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthJDBCDriver</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>JDBC URL</term>

<listitem>

<para>When using Non-persistent JDBC connection, this specifies the URL

to connect to the database.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthJDBCUrl</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Database Username</term>

<listitem>

<para>Specify the user name to open the database connection.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthJDBCDbuser</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Database Password</term>

<listitem>

<para>Specify the password for the user opening the database connection.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthJDBCDbpassword</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Password Column Name</term>

<listitem>

<para>Specify the database column name where passwords are stored.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthJDBCPasswordColumn</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Prepared Statement</term>

<listitem>

<para>Specify the SQL query to return the password corresponding to the

user to authenticate.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthJDBCStatement</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Class to Transform Password Syntax</term>

<listitem>

<para>Specify the class that transforms the password retrieved to the

same format as provided by the user.</para>

<para>The default class expects the password in clear text. Custom

classes must implement the

<literal>JDBCPasswordSyntaxTransform</literal> interface.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthJDBCPasswordSyntaxTransformPlugin</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Authentication Level</term>

<listitem>

<para>Sets the authentication level used to indicate the level of security

associated with the module. The value can range from 0 to any positive integer.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthJDBCAuthLevel</literal></para></listitem>

</varlistentry>

</variablelist>

</section>

<section xml:id="ldap-module-conf-hints">

<title>Hints For the LDAP Authentication Module</title>

<para>OpenAM connects to directory servers using Lightweight Directory

Access Protocol (LDAP). To build an easy-to-manage, high performance, pure

Java, open source directory service, try

<link xlink:href="http://opendj.org">OpenDJ</link> directory services.</para>

<indexterm>

<primary>Authentication</primary>

<secondary>LDAP</secondary>

</indexterm>

<para><command>ssoadm</command> service name:

<literal>iPlanetAMAuthLDAPService</literal></para>

<variablelist>

<varlistentry>

<term>Primary LDAP Server</term>

<term>Secondary LDAP Server</term>

<listitem>

<para>Directory servers generally use built-in data replication for high

availability. Thus a directory service likely consists of a pool of

replicas to which OpenAM can connect to retrieve and update directory

data. You set up primary and secondary servers in case a replica is down

due to maintenance or to a problem with a particular server.</para>

<para>Set one primary and optionally one secondary directory server for

each OpenAM server. For the current OpenAM server, specify each directory

server as a

<literal><replaceable>host</replaceable>:<replaceable>port</replaceable></literal>

combination. For other OpenAM servers in the deployment, you can specify

each directory server as

<literal><replaceable>server-name</replaceable>|<replaceable>host</replaceable>:<replaceable>port</replaceable></literal>,

where <replaceable>server-name</replaceable> is the FQDN portion of the

OpenAM server from the list under Configuration &gt; Servers and

Sites, and <replaceable>host</replaceable>:<replaceable>port</replaceable>

identifies the directory server.</para>

<para>For example, if the <replaceable>server-name</replaceable>

that is listed is <literal>http://openam.example.com:8080/openam</literal>

and the directory server is accessible at <literal>opendj.example.com:1389</literal>,

you would enter <literal>openam.example.com|opendj.example.com:1389</literal>.</para>

<!-- Possible future change per OPENAM-1361 -->

<para>When authenticating users from a directory service that is remote

from OpenAM, set both the primary and secondary server values.</para>

<para>If you want to use SSL or TLS for security, then scroll down to

enable SSL/TLS Access to LDAP Server. Make sure that OpenAM

can trust the servers' certificates when using this option.</para>

<para><command>ssoadm</command> attributes:

primary is <literal>iplanet-am-auth-ldap-server</literal>,

secondary is <literal>iplanet-am-auth-ldap-server2</literal>, and

<literal>iplanet-am-auth-ldap-ssl-enabled</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>DN to Start User Search</term>

<listitem>

<para>LDAP data is organized hierarchically, a bit like a file system

on Windows or UNIX. More specific DNs likely result in better search

performance. When configuring the module for a particular part of the

organization, you can perhaps start searches from a specific

organizational unit such as

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

<para>If multiple entries exist with identical search attribute values,

make this value specific enough to return only one entry.</para>

<para><command>ssoadm</command> attribute:

<literal> iplanet-am-auth-ldap-base-dn</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Bind User DN, Bind User Password</term>

<listitem>

<para>If OpenAM stores attributes in the directory, for example to

manage account lockout, or if the directory requires that OpenAM

authenticate in order to read users' attributes, then OpenAM needs the

DN and password to authenticate to the directory.</para>

<para>The default is <literal>cn=Directory Manager</literal>. Make sure

that password is correct before you logout. If it is incorrect, you will

be locked out. If this should occur, you can login with the super user DN,

which by default is

<literal>uid=amAdmin,ou=People,<replaceable>OpenAM-deploy-base</replaceable></literal>,

where <replaceable>OpenAM-deploy-base</replaceable> you set during

OpenAM configuration.</para>

<para><command>ssoadm</command> attributes:

<literal>iplanet-am-auth-ldap-bind-dn</literal>,

<literal>iplanet-am-auth-ldap-bind-passwd</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Attributes Used to Retrieve User Profile</term>

<term>Attributes Used to Search for a User to be Authenticated</term>

<term>User Search Filter</term>

<term>Search Scope</term>

<listitem>

<para>LDAP searches for user entries return entries with attribute

values matching the filter you provide. For example if you search under

<literal>ou=people,dc=example,dc=com</literal> with a filter

<literal>"(mail=bjensen@example.com)"</literal>, then the directory

returns the entry that has <literal>mail=bjensen@example.com</literal>.

In this example the attribute used to search for a user is

<literal>mail</literal>. Multiple attribute values mean the user can

authenticate with any one of the values. For example, if you have

both <literal>uid</literal> and <literal>mail</literal>, then Barbara

Jensen can authenticate with either <literal>bjensen</literal> or

<literal>bjensen@example.com</literal>.</para>

<para>Should you require a more complex filter for performance, you

add that to the User Search Filter text box. For example, if you search

on <literal>mail</literal> and add User Search Filter

<literal>(objectClass=inetOrgPerson)</literal>, then OpenAM uses the

resulting search filter

<literal>(&amp;(mail=<replaceable>address</replaceable>)(objectClass=inetOrgPerson))</literal>,

where <replaceable>address</replaceable> is the mail address provided

by the user.</para>

<para>Scope OBJECT means search only the entry specified as the DN to

Start User Search, whereas ONELEVEL means search only the entries

that are directly children of that object. SUBTREE means search the

entry specified and every entry under it.</para>

<para><command>ssoadm</command> attributes:

<literal>iplanet-am-auth-ldap-user-naming-attribute</literal>,

<literal>iplanet-am-auth-ldap-user-search-attributes</literal>,

<literal>iplanet-am-auth-ldap-search-filter</literal>, and

<literal>iplanet-am-auth-ldap-search-scope</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>SSL/TLS Access to LDAP Server</term>

<listitem>

<para>If you enable SSL/TLS, OpenAM must be able to trust LDAP certificates, either because the certificates were

signed by a CA whose certificate is already included in the trust store

used by the container where OpenAM runs, or because you imported the

certificates into the trust store.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-ldap-ssl-enabled</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Return User DN to Authenticate</term>

<listitem>

<para>When enabled, and OpenAM uses the directory service as the user

store, the module returns the DN rather than the rather than the User ID,

so the bind for authentication can be completed without a search to

retrieve the DN.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-ldap-return-user-dn</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>User Creation Attributes</term>

<listitem>

<para>

This list lets you map (external) attribute names

from the LDAP directory server

to (internal) attribute names used by OpenAM.

</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-ldap-user-creation-attr-list</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Minimum Password Length</term>

<listitem>

<para>Specify the minimum acceptable password length.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-ldap-min-password-length</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>LDAP Behera Password Policy Support</term>

<listitem>

<para>When enabled, support interoperability with servers that implement

the Internet-Draft, <link

xlink:href="http://tools.ietf.org/html/draft-behera-ldap-password-policy-09"

>Password Policy for LDAP Directories</link>.</para>

<para>Support for this Internet-Draft is limited to the LDAP

authentication module. Other components of OpenAM, such as the password

change functionality in the <literal>/idm/EndUser</literal> page, do

not support the Internet-Draft. In general, outside of the LDAP

authentication module, OpenAM binds to the directory server as an

administrator, such as Directory Manager. When OpenAM binds to the

directory server as an administrator rather than as an end user, many

features of the Internet-Draft password policies do not apply.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-ldap-behera-password-policy-enabled</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Trust All Server Certificates</term>

<listitem>

<para>When enabled, blindly trust server certificates, including

self-signed test certificates.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-ldap-ssl-trust-all</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>LDAP Connection Heartbeat Interval</term>

<listitem>

<para>Specifies how often OpenAM should send a heartbeat request to the

directory server to ensure that the connection does not remain idle. Some

network administrators configure firewalls and load balancers to drop

connections that are idle for too long. You can turn this off by setting

the value to 0 or to a negative number. To set the units for the interval

use LDAP Connection Heartbeat Time Unit.</para>

<para>Default: 1</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-ldap-heartbeat-interval</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>LDAP Connection Heartbeat Time Unit</term>

<listitem>

<para>Specifies the time unit corresponding to LDAP Connection Heartbeat

Interval.</para>

<para>Default: minute</para>

<para><command>ssoadm</command> attribute:

<literal>openam-auth-ldap-heartbeat-interval</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Authentication Level</term>

<listitem>

<para>Sets the authentication level used to indicate the level of security

associated with the module. The value can range from 0 to any positive integer.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-ldap-auth-level</literal></para></listitem>

</varlistentry>

</variablelist>

</section>

<section xml:id="membership-module-conf-hints">

<title>Hints For the Membership Authentication Module</title>

<para>The Membership module permits self-registration for new users. You

can then have OpenAM create new user profiles in the identity

repository.</para>

<indexterm>

<primary>Authentication</primary>

<secondary>Membership (&amp; self-registration)</secondary>

</indexterm>

<para><command>ssoadm</command> service name:

<literal>iPlanetAMAuthMembershipService</literal></para>

<variablelist>

<varlistentry>

<term>Minimum Password Length</term>

<listitem>

<para>Specify the minimum acceptable number of characters in the password

provided during self-registration.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-membership-min-password-length</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Default User Roles</term>

<listitem>

<para>Specifies the Distinguished Name (DN) of a role to be assigned to

a new user whose profile is created. There are no default values. The

role specified must be within the realm for which the authentication

process is configured.</para>

<para>This role can be either an OpenAM or Sun DSEE role, but it cannot

be a filtered role. If you wish to automatically assign specific services

to the user, you have to configure the Required Services attribute in

the User Profile.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-membership-default-roles</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>User Status After Registration</term>

<listitem>

<para>If you choose Inactive, then the new user has no access to services

until an administrator activates the account.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-membership-default-user-status</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Authentication Level</term>

<listitem>

<para>Sets the authentication level used to indicate the level of security

associated with the module. The value can range from 0 to any positive integer.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-membership-auth-level</literal></para></listitem>

</varlistentry>

</variablelist>

</section>

<section xml:id="msisdn-module-conf-hints">

<title>Hints For the MSISDN Authentication Module</title>

<para>The Mobile Station Integrated Services Digital Network (MSISDN)

authentication module enables non-interactive authentication using a mobile

subscriber ISDN associated with a terminal such as a mobile phone.

The module checks the subscriber ISDN against the value found on a user's

entry in an LDAP directory service.</para>

<indexterm>

<primary>Authentication</primary>

<secondary>MSISDN</secondary>

</indexterm>

<para><command>ssoadm</command> service name:

<literal>sunAMAuthMSISDNService</literal></para>

<variablelist>

<varlistentry>

<term>Trusted Gateway IP Address</term>

<listitem>

<para>Specifies a list of IP addresses of trusted clients that can access

MSIDSN modules. Either restrict the clients allowed to access the MSISDN

module by adding each IPv4 or IPv6 address here, or leave the list empty to allow

all clients to access the module. If you specify the value

<literal>none</literal>, no clients are allowed access.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthMSISDNTrustedGatewayList</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>MSISDN Number Search Parameter Name</term>

<listitem>

<para>Specifies a list of parameter names that identify which parameters

to search in the request header or cookie header for the MSISDN number.

For example, if you define x-Cookie-Param, AM_NUMBER, and COOKIE-ID,

the MSISDN authentication service checks those parameters for the

MSISDN number.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthMSISDNParameterNameList</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>LDAP Server and Port</term>

<listitem>

<para>If you want to use SSL or TLS for security, then scroll down to

enable SSL/TLS Access to LDAP. Make sure that OpenAM can trust the

servers' certificates when using this option.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthMSISDNLdapProviderUrl</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>LDAP Start Search DN</term>

<listitem>

<para>Specify the DN of the entry where the search for the user's MSISDN

number should start.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthMSISDNBaseDn</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Attribute To Use To Search LDAP</term>

<listitem>

<para>Specify the name of the attribute in the user's profile that

contains the MSISDN number to search for the user. The default is

<literal>sunIdentityMSISDNNumber</literal>.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthMSISDNUserSearchAttribute</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>LDAP Server Authentication User</term>

<listitem>

<para>If OpenAM must authenticate to the directory server in order to

search, then specify the bind DN. The default is

<literal>cn=amldapuser,ou=DSAME Users,dc=example,dc=com</literal>.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthMSISDNPrincipalUser</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>LDAP Server Authentication Password</term>

<listitem>

<para>Specify the password corresponding to the bind DN.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthMSISDNPrincipalPasswd</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>SSL/TLS for LDAP Access</term>

<listitem>

<para>If you choose to enable SSL or TLS, then make sure that

OpenAM can trust the servers' certificates.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthMSISDNUseSsl</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>MSISDN Header Search Attribute</term>

<listitem>

<para>Specify the headers to use for searching the request for the

MSISDN number.</para>

<itemizedlist>

<listitem>

<para>Cookie Header tells OpenAM to search the cookie.</para>

</listitem>

<listitem>

<para>Request Header tells OpenAM to search the request header.</para>

</listitem>

<listitem>

<para>Request Parameter tells OpenAM to search the request parameters.</para>

</listitem>

</itemizedlist>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthMSISDNHeaderSearch</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>LDAP Attribute Used to Retrieve User Profile</term>

<listitem>

<para>Specify the LDAP attribute that is used during a search to return

the user profile for MSISDN authentication service. The default is

<literal>uid</literal>.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthMSISDNUserNamingAttribute</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Return User DN to DataStore</term>

<listitem>

<para>Enable this option only when the OpenAM directory is the same as

the directory configured for MSISDN searches. When enabled, this option

allows the authentication module to return the DN instead of the User ID.

OpenAM thus does not need to perform an additional search with the user

ID to find the user's entry.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthMSISDNReturnUserDN</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Authentication Level</term>

<listitem>

<para>Sets the authentication level used to indicate the level of security

associated with the module. The value can range from 0 to any positive integer.</para>

<para><command>ssoadm</command> attribute:

<literal>sunAMAuthMSISDNAuthLevel</literal></para></listitem>

</varlistentry>

</variablelist>

</section>

<section xml:id="OATH-module-conf-hints">

<title>Hints For the OATH Module</title>

<para>The Open Authentication (OATH) module provides a more secure method for users to

access their accounts with the help of a device, such as their mobile phone or

Yubikey. Users can log into OpenAM and update their information more securely from

a one-time password (OTP) displayed on their device. The OATH module includes the

<link xlink:show="new" xlink:href="http://www.openauthentication.org/about/"

>OATH standard protocols</link> (<link xlink:show="new"

xlink:href="http://tools.ietf.org/html/rfc4226">RFC 4226</link> and

<link xlink:show="new" xlink:href="http://tools.ietf.org/html/rfc6238">

RFC 6238</link>). The OATH module has several enhancements to the

HMAC One-Time Password (HOTP) Authentication Module, but does not replace the original

module for those already using HOTP prior to the 10.1.0 release. The OATH module includes

HOTP authentication and Time-Based One-Time Password (TOTP) authentication. Both types

of authentication require an OATH compliant device that can provide the OTP.</para>

<indexterm>

<primary>Authentication</primary>

<secondary>Open Authentication (OATH)</secondary>

</indexterm>

<para> HOTP authentication generates the OTP every time the user requests a new OTP

on their device. The device tracks the number of times the user requests a new OTP, called

the counter. The OTP displays for a period of time you designate in the setup, so the

user may be further in the counter on their device than on their account. OpenAM will resynchronize

the counter when the user finally logs in. To accommodate this, you set the number of

passwords a user can generate before their device cannot be resynchronized. For example, if

you set the number of HOTP Window Size to 50 and someone presses the button 30 on the

user's device to generate a new OTP, the counter in OpenAM will review the OTPs until

it reaches the OTP entered by the user. If someone presses the button 51 times,

you will need to reset the counter to match the number on the device's counter before the

user can login to OpenAM. HOTP authentication does not check earlier passwords, so if the

user attempts to reset the counter on their device, they will not be able to login until

you reset the counter in OpenAM to match their device.</para>

<para>TOTP authentication constantly generates a new OTP based on a time interval you specify.

The device tracks the last two passwords generated and the current password. The Last Login Time

monitors the time when a user logs in to make sure that user is not logged in several times

within the present time period. Once a user log into OpenAM, they must wait for the time it

takes TOTP to generate the next two passwords and display them. This prevents others from

being able to access the users account using the OTP they entered. The user's account can be

accessed again after the generation of the third new OTP is generated and displayed on their

device. For this reason, the TOTP Time-Step Interval should not be so long as to

lock users out, with a recommended time of 30 seconds.</para>

<para>An authentication chain can be created to generate an OTP from

either HOTP or TOTP.</para>

<para><command>ssoadm</command> service name:

<literal>iPlanetAMAuthOATHService</literal></para>

<variablelist>

<varlistentry>

<term>Authentication Level</term>

<listitem>

<para>Sets the authentication level used to indicate the level of security

associated with the module. The value can range from 0 to any positive integer.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-oath-auth-level</literal></para></listitem>

</varlistentry>

<varlistentry>

<term>One Time Password Length (in digits)</term>

<listitem>

<para>Set the length of the OTP between 6 and 9 digits long. The default value is 6 digits.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-oath-password-length</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Minimum Secret Key Length</term>

<listitem>

<para>The minimal number of characters required to set the Secret Key.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-oath-min-secret-key-length</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Secret Key Attribute Name</term>

<listitem>

<para>The name of the attribute where the key will be stored in the user profile.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-oath-secret-key-attribute</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>OATH Algorithm to Use</term>

<listitem>

<para>Select whether to use HOTP or TOTP. You can create an authentication chain to

allow for a greater variety of devices. The default value is HOTP.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-oath-algorithm</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>HOTP Window Size</term>

<listitem>

<para>The number of requests that the system and the device can be off to resynchronize

the password. If a user passes this number of requests before logging

into the system, the password will not work. The default value is 100.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-oath-hotp-window-size</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Counter Attribute Name</term>

<listitem>

<para>The name of the HOTP attribute where the counter will be stored in the user profile.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-oath-hotp-counter-attribute</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Add Checksum Digit</term>

<listitem>

<para>Adds a checksum digit at the end of the HOTP password to verify it was entered correctly.

The default value is No.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-oath-add-checksum</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Truncation Offset</term>

<listitem>

<para>Advanced feature that is device specific. Any value below 0 or above 15 will turn off

the functionality. The default value is -1. If not required by the device, leave at the default

setting.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-oath-truncation-offset</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>TOTP Time Step Interval</term>

<listitem>

<para>Defines how long the password will appear on the user's device (in seconds).

We recommend keeping this number low, for example 30 seconds, because once a user

logs out, they will not be able to login again until two full time cycles have passed.

The default value is 30 seconds.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-oath-size-of-time-step</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>TOTP Time Steps</term>

<listitem>

<para>The number of requests that the system and the device can be off to resynchronize

the password. If a user passes this number of requests before logging into the system,

the password will not work. The default value is 2.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-oath-steps-in-window</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Last Login Time Attribute</term>

<listitem>

<para>The name of the attribute where both HOTP and TOTP authentication will store information

on when a person last logged in.</para>

<para><command>ssoadm</command> attribute:

<literal>iplanet-am-auth-oath-last-login-time-attribute-name</literal></para>

</listitem>

</varlistentry>

</variablelist>

<para>If you plan to use Yubikey for your OATH module, you will need to take some

time to set it up. Go to the <link xlink:show="new"

xlink:href="http://www.yubico.com/products/services-software/personalization-tools/use/">

YubiKey website</link> to configure your YubiKey device. If you do not have a

YubiKey device, you can purchase them from this page as well.</para>

<para>Select the appropriate instructions, keeping in mind that the cross-platform