Authentication Module Properties

This section provides a reference to configuration properties for AM authentication modules.

Active Directory Module Properties

amster service name: ActiveDirectoryModule

ssoadm service name: sunAMAuthADService

Primary Active Directory Server, Secondary Active Directory Server

Specify the primary and secondary Active Directory server(s). AM attempts to contact the primary server(s) first, If no primary server is available, then AM attempts to contact the secondary server(s).

When authenticating users from a directory server that is remote to AM, set the primary server values, and optionally the secondary server values. Primary servers have priority over secondary servers.

To allow users to change passwords through AM, Active Directory requires that you connect over SSL. The default port for LDAP is 389. If you are connecting to Active Directory over SSL, the default port for LDAP/SSL is 636.

For SSL or TLS security, enable the SSL/TLS Access to Active Directory Server property. Make sure that AM can trust the Active Directory certificate when using this option.

ssoadm attributes are: primary is iplanet-am-auth-ldap-server; secondary is iplanet-am-auth-ldap-server2.

Both properties may take a single value in the form of server:port, or more than one value in the form of openam_full_server_name | server:port; thus, allowing more than one primary or secondary remote server, respectively.

Assuming a multi-data center environment, AM determines priority within the primary and secondary remote servers as follows:

  • Every LDAP server that is mapped to the current AM instance has highest priority.

    For example, if you are connected to openam1.example.com and ldap1.example.com is mapped to that AM instance, then AM uses ldap1.example.com.

  • Every LDAP server that was not specifically mapped to a given AM instance has the next highest priority.

    For example, if you have another LDAP server, ldap2.example.com, that is not connected to a specific AM server and if ldap1.example.com is unavailable, AM connects to the next highest priority LDAP server, ldap2.example.com.

  • LDAP servers that are mapped to different AM instances have the lowest priority.

    For example, if ldap3.example.com is connected to openam3.example.com and ldap1.example.com and ldap2.example.com are unavailable, then openam1.example.com connects to ldap3.example.com.

DN to Start User Search

Specifies the base DN from which AM searches for users to authenticate.

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 OU=sales,DC=example,DC=com.

If multiple entries exist with identical search attribute values, make this value specific enough to return only one entry.

amster attribute: userSearchStartDN

ssoadm attribute: iplanet-am-auth-ldap-base-dn

Bind User DN, Bind User Password

Specify the user and password to authenticate to Active Directory.

If AM stores attributes in Active Directory, for example to manage account lockout, or if Active Directory requires that AM authenticate in order to read users' attributes, then AM needs the DN and password to authenticate to Active Directory.

If the administrator authentication chain (default: ldapService) 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 superuser DN, which by default is uid=amAdmin,ou=People,AM-deploy-base, where AM-deploy-base was set during AM configuration.

ssoadm attributes: iplanet-am-auth-ldap-bind-dn and iplanet-am-auth-ldap-bind-passwd

Attribute Used to Retrieve User Profile, Attributes Used to Search for a User to be Authenticated, User Search Filter, Search Scope

LDAP searches for user entries with attribute values matching the filter you provide. For example, if you search under CN=Users,DC=example,DC=com with a filter "(MAIL=bjensen@example.com)", then the directory returns the entry that has MAIL=bjensen@example.com. In this example the attribute used to search for a user is mail. Multiple attribute values mean the user can authenticate with any one of the values. For example, if you have both uid and mail, then Barbara Jensen can authenticate with either bjensen or bjensen@example.com.

The User Search Filter text box provides a more complex filter. For example, if you search on mail and add User Search Filter (objectClass=inetOrgPerson), then AM uses the resulting search filter (&(mail=address) (objectClass=inetOrgPerson)), where address is the mail address provided by the user.

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:

  • OBJECT will search only for the entry specified as the DN to Start User Search.

  • ONELEVEL will search only the entries that are directly children of that object.

  • SUBTREE will search the entry specified and every entry under it.

ssoadm attributes: iplanet-am-auth-ldap-user-naming-attribute, iplanet-am-auth-ldap-user-search-attributes, iplanet-am-auth-ldap-search-filter, and iplanet-am-auth-ldap-search-scope

LDAP Connection Mode

If you want to initiate secure communications to data stores using SSL or StartTLS, AM 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 AM runs, or because you imported the certificates into the trust store.

ssoadm attribute: openam-auth-ldap-connection-mode

Possible values: LDAP, LDAPS, and StartTLS

Return User DN to DataStore

When enabled, and AM 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.

amster attribute: returnUserDN

ssoadm attribute: iplanet-am-auth-ldap-return-user-dn

User Creation Attributes

Maps internal attribute names used by AM to external attribute names from Active Directory for dynamic profile creation. Values are of the format internal_attr1|external_attr1.

amster attribute: profileAttributeMappings

ssoadm attribute: iplanet-am-ldap-user-creation-attr-list

Trust All Server Certificates

When enabled, the module trusts all server certificates, including self-signed certificates.

amster attribute: trustAllServerCertificates

ssoadm attribute: iplanet-am-auth-ldap-ssl-trust-all

LDAP Connection Heartbeat Interval

Specifies how often AM 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.

Default: 1

amster attribute: connectionHeartbeatInterval

ssoadm attribute: openam-auth-ldap-heartbeat-interval

LDAP Connection Heartbeat Time Unit

Specifies the time unit corresponding to LDAP Connection Heartbeat Interval. Possible values are SECONDS, MINUTES, and HOURS.

amster attribute: connectionHeartbeatTimeUnit

ssoadm attribute: openam-auth-ldap-heartbeat-timeunit

LDAP operations timeout

Defines the timeout in milliseconds that AM should wait for a response from the directory server.

Default: 0 (means no timeout)

amster attribute: operationTimeout

ssoadm attribute: openam-auth-ldap-operation-timeout

Authentication Level

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.

amster attribute: authenticationLevel

ssoadm attribute: sunAMAuthADAuthLevel

Adaptive Risk Authentication Module Properties

amster service name: AdaptiveRiskModule

ssoadm service name: sunAMAuthAdaptiveService

General

The following properties are available under the General tab:

Authentication Level

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.

amster attribute: authenticationLevel

ssoadm attribute: openam-auth-adaptive-auth-level

Risk Threshold

Sets the risk threshold score. If the sum of the scores is greater than the threshold, the Adaptive Risk module fails.

Default: 1

amster attribute: riskThreshold

ssoadm attribute: openam-auth-adaptive-auth-threshold

Failed Authentications

The following properties are available under the Failed Authentications tab:

Failed Authentication Check

When enabled, checks the user profile for authentication failures since the last successful login. This check therefore requires AM to have access to the user profile, and Account Lockout to be enabled (otherwise, AM does not record authentication failures).

amster attribute: failedAuthenticationCheckEnabled

ssoadm attribute: openam-auth-adaptive-failure-check

Score

Sets the value to add to the total score if the user fails the Failed Authentication Check. Default: 1

amster attribute: failureScore

ssoadm attribute: openam-auth-adaptive-failure-score

Invert Result

When enabled, adds the score to the total score if the user passes the Failed Authentication Check.

amster attribute: invertFailureScore

ssoadm attribute: openam-auth-adaptive-failure-invert

IP Address Range

The following properties are available under the IP Address Range tab:

IP Range Check

When enabled, checks whether the client IP address is within one of the specified IP Ranges.

amster attribute: ipRangeCheckEnabled

ssoadm attribute: openam-auth-adaptive-ip-range-check

IP Range

For IPv4, specifies a list of IP ranges either in CIDR-style notation (x.x.x.x/YY) or as a range from one address to another (x.x.x.x-y.y.y.y, meaning from x.x.x.x to y.y.y.y).

For IPv6, specifies a list of IP ranges either in CIDR-style notation (X:X:X:X:X:X:X:X/YY) or as a range from one address to another (X:X:X:X:X:X:X:X-Y:Y:Y:Y:Y:Y:Y:Y, (X:X:X:X:X:X:X:X-Y:Y:Y:Y:Y:Y:Y:Y, meaning from X:X:X:X:X:X:X:X to Y:Y:Y:Y:Y:Y:Y:Y).

amster attribute: ipRange

ssoadm attribute: openam-auth-adaptive-ip-range-range

Score

Sets the value to add to the total score if the user fails the IP Range Check.

amster attribute: ipRangeScore

ssoadm attribute: openam-auth-adaptive-ip-range-score

Invert Result

When enabled, adds the Score to the total score if the user passes the IP Range Check.

amster attribute: invertIPRangeScoreEnabled

ssoadm attribute: openam-auth-adaptive-ip-range-invert

IP Address History

The following properties are available under the IP Address History tab:

IP History Check

When enabled, checks whether the client IP address matches one of the known values stored on the profile attribute you specify. This check therefore requires that AM have access to the user profile.

amster attribute: ipHistoryCheckEnabled

ssoadm attribute: openam-auth-adaptive-ip-history-check

History size

Specifies how many IP address values to retain on the profile attribute you specify.

Default: 5

amster attribute: ipHistoryCount

ssoadm attribute: openam-auth-ip-adaptive-history-count

Profile Attribute Name

Specifies the name of the user profile attribute in which to store known IP addresses. Ensure the specified attribute exists in your user data store; the iphistory attribute does not exist by default, and it is not created when performing AM schema updates.

Default: iphistory

amster attribute: ipHistoryProfileAttribute

ssoadm attribute: openam-auth-adaptive-ip-history-attribute

Save Successful IP Address

When enabled, saves new client IP addresses to the known IP address list following successful authentication.

amster attribute: saveSuccessfulIP

ssoadm attribute: openam-auth-adaptive-ip-history-save

Score

Sets the value to add to the total score if the user fails the IP History Check.

Default: 1

amster attribute: ipHistoryScore

ssoadm attribute: openam-auth-adaptive-ip-history-score

Invert Result

When enabled, adds the Score to the total score if the user passes the IP History Check.

amster attribute: invertIPHistoryScore

ssoadm attribute: openam-auth-adaptive-ip-history-invert

Known Cookie

The following properties are available under the Known Cookie tab:

Cookie Value Check

When enabled, checks whether the client browser request has the specified cookie and optional cookie value.

amster attribute: knownCookieCheckEnabled

ssoadm attribute: openam-auth-adaptive-known-cookie-check

Cookie Name

Specifies the name of the cookie for which AM checks when you enable the Cookie Value Check.

amster attribute: knownCookieName

ssoadm attribute: openam-auth-adaptive-known-cookie-name

Cookie Value

Specifies the value of the cookie for which AM checks. If no value is specified, AM does not check the cookie value.

amster attribute: knownCookieValue

ssoadm attribute: openam-auth-adaptive-known-cookie-value

Save Cookie Value on Successful Login

When enabled, saves the cookie as specified in the client's browser following successful authentication. If no Cookie Value is specified, the value is set to 1.

amster attribute: createKnownCookieOnSuccessfulLogin

ssoadm attribute: openam-auth-adaptive-known-cookie-save

Score

Sets the value to add to the total score if user passes the Cookie Value Check.

Default: 1

amster attribute: knownCookieScore

ssoadm attribute: openam-auth-adaptive-known-cookie-score

Invert Result

When enabled, adds the Score to the total score if the user passes the Cookie Value Check.

amster attribute: invertKnownCookieScore

ssoadm attribute: openam-auth-adaptive-known-cookie-invert

Device Cookie

The following properties are available under the Device Cookie tab:

Device Registration Cookie Check

When enabled, the cookie check passes if the client request contains the cookie specified in Cookie Name.

amster attribute: deviceCookieCheckEnabled

ssoadm attribute: openam-auth-adaptive-device-cookie-check

Cookie Name

Specifies the name of the cookie for the Device Registration Cookie Check.

Default: Device

amster attribute: deviceCookieName

ssoadm attribute: openam-auth-adaptive-device-cookie-name

Save Device Registration on Successful Login

When enabled, saves the specified cookie with a hashed device identifier value in the client's browser following successful authentication.

amster attribute: saveDeviceCookieValueOnSuccessfulLogin

ssoadm attribute: openam-auth-adaptive-device-cookie-save

Score

Sets the value to add to the total score if the user fails the Device Registration Cookie Check.

Default: 1

amster attribute: deviceCookieScore

ssoadm attribute: openam-auth-adaptive-device-cookie-score

Invert Result

When enabled, adds the Score to the total score if the user passes the Device Registration Cookie Check.

amster attribute: invertDeviceCookieScore

ssoadm attribute: openam-auth-adaptive-device-cookie-invert

Time Since Last Login

The following properties are available under the Time Since Last Login tab:

Time since Last login Check

When enabled, checks 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.

amster attribute: timeSinceLastLoginCheckEnabled

ssoadm attribute: openam-auth-adaptive-time-since-last-login-check

Cookie Name

Specifies the name of the cookie holding the encrypted last login time value.

amster attribute: timeSinceLastLoginCookieName

ssoadm attribute: openam-auth-adaptive-time-since-last-login-cookie-name

Max Time since Last login

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.

amster attribute: maxTimeSinceLastLogin

ssoadm attribute: openam-auth-adaptive-time-since-last-login-value

Save time of Successful Login

When enabled, saves the specified cookie with the current time encrypted as the last login value in the client's browser following successful authentication.

amster attribute: saveLastLoginTimeOnSuccessfulLogin

ssoadm attribute: openam-auth-adaptive-time-since-last-login-save

Score

Sets the value to add to the total score if the user fails the Time Since Last Login Check.

Default: 1

amster attribute: timeSinceLastLoginScore

ssoadm attribute: openam-auth-adaptive-time-since-last-login-score

Invert Result

When enabled, adds the Score to the total score if the user passes the Time Since Last Login Check.

amster attribute: invertTimeSinceLastLoginScore

ssoadm attribute: openam-auth-adaptive-time-since-last-login-invert

Profile Attribute

The following properties are available under the Profile Attribute tab:

Profile Risk Attribute check

When enabled, checks whether the user profile contains the specified attribute and value.

amster attribute: profileRiskAttributeCheckEnabled

ssoadm attribute: openam-auth-adaptive-risk-attribute-check

Attribute Name

Specifies the attribute to check on the user profile for the specified value.

amster attribute: profileRiskAttributeName

ssoadm attribute: openam-auth-adaptive-risk-attribute-name

Attribute Value

Specifies the value to match on the profile attribute. If the attribute is multi-valued, a single match is sufficient to pass the check.

amster attribute: profileRiskAttributeValue

ssoadm attribute: openam-auth-adaptive-risk-attribute-value

Score

Sets the value to add to the total score if the user fails the Profile Risk Attribute Check.

Default: 1

amster attribute: profileRiskAttributeScore

ssoadm attribute: openam-auth-adaptive-risk-attribute-score

Invert Result

When enabled, adds the Score to the total score if the user passes the Profile Risk Attribute Check.

amster attribute: invertProfileRiskAttributeScore

ssoadm attribute: openam-auth-adaptive-risk-attribute-invert

Geo Location

The following properties are available under the Geo Location tab:

Geolocation Country Code Check

When enabled, checks whether the client IP address location matches a country specified in the Valid Country Codes list.

ssoadm attribute: forgerock-am-auth-adaptive-geo-location-check

Geolocation Database Location

Path to GeoIP data file used to convert IP addresses to country locations. The geolocation database is not packaged with AM. You can download the GeoIP Country database from MaxMind. Use the binary .mmdb file format, rather than .csv. You can use the GeoLite Country database for testing.

amster attribute: geolocationDatabaseLocation

ssoadm attribute: openam-auth-adaptive-geo-location-database

Valid Country Codes

Specifies the list of country codes to match. Use | to separate multiple values.

ssoadm attribute: openam-auth-adaptive-geo-location-values.

Score

Value to add to the total score if the user fails the Geolocation Country Code Check.

Default: 1

amster attribute: geolocationScore

ssoadm attribute: openam-auth-adaptive-geo-location-score

Invert Result

When enabled, adds the Score to the total score if the user passes the Geolocation Country Code Check.

amster attribute: invertGeolocationScore

ssoadm attribute: openam-auth-adaptive-geo-location-invert

Request Header

The following properties are available under the Request Header tab:

Request Header Check

When enabled, checks whether the client browser request has the specified header with the correct value.

amster attribute: requestHeaderCheckEnabled

ssoadm attribute: openam-auth-adaptive-req-header-check

Request Header Name

Specifies the name of the request header for the Request Header Check.

amster attribute: requestHeaderName

ssoadm attribute: openam-auth-adaptive-req-header-name

Request Header Value

Specifies the value of the request header for the Request Header Check.

amster attribute: requestHeaderValue

ssoadm attribute: openam-auth-adaptive-req-header-value

Score

Value to add to the total score if the user fails the Request Header Check.

Default: 1

amster attribute: requestHeaderScore

ssoadm attribute: openam-auth-adaptive-req-header-score

Invert Result

When enabled, adds the Score to the total score if the user passes the Request Header Check.

amster attribute: invertRequestHeaderScore

ssoadm attribute: openam-auth-adaptive-req-header-invert

Anonymous Authentication Module Properties

amster service name: AnonymousModule

ssoadm service name: iPlanetAMAuthAnonymousService

Valid Anonymous Users

Specifies the list of valid anonymous user IDs that can log in without submitting a password.

amster attribute: validAnonymousUsers

ssoadm attribute: iplanet-am-auth-anonymous-users-list

When user accesses the default module instance login URL, then the module prompts the user to enter a valid anonymous user name.

The default module instance login URL is defined as follows:

protocol://hostname:port/deploy_URI/XUI/?module=Anonymous&org=org_name#login
Default Anonymous User Name

Specifies the user ID assigned by the module if the Valid Anonymous Users list is empty. The default value is anonymous. Note that the anonymous user must be defined in the realm.

amster attribute: defaultAnonymousUsername

ssoadm attribute: iplanet-am-auth-anonymous-default-user-name

Case Sensitive User IDs

When enabled, determines whether case matters for anonymous user IDs.

amster attribute: caseSensitiveUsernameMatchingEnabled

ssoadm attribute: iplanet-am-auth-anonymous-case-sensitive

Authentication Level

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.

After a user has authenticated, AM 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.

amster attribute: authenticationLevel

ssoadm attribute: iplanet-am-auth-anonymous-auth-level

Certificate Authentication Module Properties

amster service name: CertificateModule

ssoadm service name: iPlanetAMAuthCertService

Match Certificate in LDAP

When enabled, AM 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.

amster attribute: matchCertificateInLdap

ssoadm attribute: iplanet-am-auth-cert-check-cert-in-ldap

Subject DN Attribute Used to Search LDAP for Certificates

Indicates which attribute and value in the certificate Subject DN is used to find the LDAP entry holding the certificate.

Default: CN

amster attribute: ldapCertificateAttribute

ssoadm attribute: iplanet-am-auth-cert-attr-check-ldap

Match Certificate to CRL

When enabled, AM checks whether the certificate has been revoked according to a CRL in the LDAP directory.

amster attribute: matchCertificateToCRL

ssoadm attribute: iplanet-am-auth-cert-check-crl

Issuer DN Attribute Used to Search LDAP for CRLs

Indicates which attribute and value in the certificate Issuer DN is used to find the CRL in the LDAP directory.

Default: CN

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 (attr-name=attr-value-in-subject-DN).

For example, if the subject DN of the issuer certificate is C=US, CN=Some CA, serialNumber=123456, and the attribute specified is CN, then the LDAP search filter used to find the CRL is (CN=Some CA).

In order to distinguish among different CRLs for the same CA issuer, specify multiple attributes separated by commas (,) 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 (cn=attr1=attr1-value-in-subject-DN,attr2=attr2-value-in-subject-DN,...,attrN=attrN-value-in-subject-DN).

For example, if the subject DN of the issuer certificate is C=US, CN=Some CA, serialNumber=123456, and the attributes specified are CN,serialNumber, then the LDAP search filter used to find the CRL is (cn=CN=Some CA,serialNumber=123456).

amster attribute: crlMatchingCertificateAttribute

ssoadm attribute: iplanet-am-auth-cert-attr-check-crl

HTTP Parameters for CRL Update

Specifies parameters to be included in any HTTP CRL call to the CA that issued the certificate.

This property supports key pairs of values separated by commas, for example, param1=value1,param2=value2.

If the client or CA contains the Issuing Distribution Point Extension, AM uses this information to retrieve the CRL from the distribution point.

amster attribute: crlHttpParameters

ssoadm attribute: iplanet-am-auth-cert-param-get-crl

Match CA Certificate to CRL

When enabled, AM checks the CRL against the CA certificate to ensure it has not been compromised.

amster attribute: matchCACertificateToCRL

ssoadm attribute: sunAMValidateCACert

Cache CRLs in memory

(LDAP distribution points only) When enabled, AM caches CRLs.

amster attribute: cacheCRLsInMemory

ssoadm attribute: openam-am-auth-cert-attr-cache-crl

Update CA CRLs from CRLDistributionPoint

When enabled, AM updates the CRLs stored in the LDAP directory store.

amster attribute: updateCRLsFromDistributionPoint

ssoadm attribute: openam-am-auth-cert-update-crl

OCSP Validation

When enabled, AM checks the revocation status of certificates using the Online Certificate Status Protocol (OCSP).

You must configure OSCP for AM under Configure > Server Defaults or Deployment > Servers > Server Name > Security.

amster attribute: ocspValidationEnabled

ssoadm attribute: iplanet-am-auth-cert-check-ocsp

LDAP Server Where Certificates are Stored

Identifies the LDAP server that holds users; certificates. The property has the format ldap_server:port, for example, ldap1.example.com:636. To configure a secure connection, enable the Use SSL/TLS for LDAP Access property.

AM servers can be associated with LDAP servers by writing multiple chains with the format openam_server|ldapserver:port, for example, openam.example.com|ldap1.example.com:636.

amster attribute: certificateLdapServers

ssoadm attribute: iplanet-am-auth-cert-ldap-provider-url

LDAP Search Start or Base DN

Valid base DN for the LDAP search, such as dc=example,dc=com. To associate AM servers with§ different search base DNs, use the format openam_server|base_dn, for example, openam.example.com|dc=example,dc=com openam1.test.com|dc=test, dc=com

amster attribute: ldapSearchStartDN

ssoadm attribute: iplanet-am-auth-cert-start-search-loc

LDAP Server Authentication User, LDAP Server Authentication Password

If AM stores attributes in the LDAP directory, for example to manage account lockout, or if the LDAP directory requires that AM authenticate in order to read users' attributes, then AM needs the DN and password to authenticate to the LDAP directory.

ssoadm attributes: iplanet-am-auth-cert-principal-user, and iplanet-am-auth-cert-principal-passwd

Use SSL/TLS for LDAP Access

If you use SSL/TLS for LDAP access, AM must be able to trust the LDAP server certificate.

amster attribute: sslEnabled

ssoadm attribute: iplanet-am-auth-cert-use-ssl

Certificate Field Used to Access User Profile

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.

amster attribute: certificateAttributeToProfileMapping

ssoadm attribute: iplanet-am-auth-cert-user-profile-mapper

Valid values: subject DN, subject CN, subject UID, email address, other, and none.

Other Certificate Field Used to Access User Profile

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.

amster attribute: otherCertificateAttributeToProfileMapping

ssoadm attribute: iplanet-am-auth-cert-user-profile-mapper-other

SubjectAltNameExt Value Type to Access User Profile

Specifies how to look up the user profile:

  • Let the property default to none to give preference to the Certificate Field Used to Access User Profile or Other Certificate Field Used to Access User Profile attributes when looking up the user profile.

  • Select RFC822Name if you want AM to look up the user profile from an RFC 822 style name.

  • Select UPN if you want AM to look up the user profile as the User Principal Name attribute used in Active Directory.

amster attribute: certificateAttributeProfileMappingExtension

ssoadm attribute: iplanet-am-auth-cert-user-profile-mapper-ext

Trusted Remote Hosts

Defines a list of hosts trusted to send certificates to AM, such as load balancers doing SSL termination.

Valid values are none, any, and IP_ADDR, where IP_ADDR is one or more IP addresses of trusted hosts that can send client certificates to AM.

amster attribute: trustedRemoteHosts

ssoadm attribute: iplanet-am-auth-cert-gw-cert-auth-enabled

HTTP Header Name for Client Certificates

Specifies the name of the HTTP request header containing the certificate, which can be in one of the following formats:

  • Raw PEM-encoded.

  • PEM-encoded first, and then URL-encoded.

If Trusted Remote Hosts is set to any or specifies the IP address of the trusted host (for example, an SSL-terminated load balancer) that can supply client certificates to AM, the administrator must specify the header name in this attribute.

amster attribute: clientCertificateHttpHeaderName

ssoadm attribute: sunAMHttpParamName

Use only Certificate from HTTP request header

When enabled, AM always uses the client certificate from the HTTP header rather than the certificate the servlet container receives during the SSL handshake.

Default: false

ssoadm attribute: iplanet-am-auth-cert-gw-cert-preferred

Authentication Level

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.

amster attribute: authenticationLevel

ssoadm attribute: iplanet-am-auth-cert-auth-level

Data Store Authentication Module Properties

amster service name: DataStoreModule

ssoadm service name: sunAMAuthDataStoreService

Authentication Level

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.

amster attribute: authenticationLevel

ssoadm attribute: sunAMAuthDataStoreAuthLevel

Device ID (Match) Authentication Module Properties

amster service name: DeviceIdMatchModule

ssoadm service name: iPlanetAMAuthDeviceIdMatchService

Client-Side Script Enabled

Enable Device ID (Match) to send JavaScript in an authentication page to the device to collect data about the device by a self-submitting form.

amster attribute: clientScriptEnabled

ssoadm attribute: iplanet-am-auth-scripted-client-script-enabled

Client-Side Script, Server-Side Script

Specify the client-side and server-side Javascript scripts to use with the Device Id (Match) module.

To view and modify the contents of the scripts, navigate to Realms > Realm Name > Scripts and select the name of the script.

If you change the client-side script, you must make a corresponding change in the server-side script to account for the specific addition or removal of an element.

ssoadm attribute: iplanet-am-auth-scripted-client-script and iplanet-am-auth-scripted-server-script

Authentication Level

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.

amster attribute: authenticationLevel

ssoadm attribute: iplanet-am-auth-scripted-auth-level

Device ID (Save) Authentication Module Properties

amster service name: DeviceIdSaveModule

ssoadm service name: iPlanetAMAuthDeviceIdSaveService

Automatically store new profiles

When enabled, AM assumes user consent to store new profiles. After successful HOTP confirmation, AM stores the new profile automatically.

amster attribute: autoStoreProfiles

ssoadm attribute: iplanet-am-auth-device-id-save-auto-store-profile

Maximum stored profile quantity

Sets the maximum number of stored profiles on the user's record.

amster attribute: maxProfilesAllowed

ssoadm attribute: iplanet-am-auth-device-id-save-max-profiles-allowed

Authentication Level

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.

amster attribute: authenticationLevel

ssoadm attribute: iplanet-am-auth-device-id-save-auth-level

Federation Authentication Module Properties

amster service name: FederationModule

ssoadm service name: sunAMAuthFederationService

Authentication Level

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.

amster attribute: authenticationLevel

ssoadm attribute: sunAMAuthFederationAuthLevel

Amster Authentication Module Properties

amster service name: AmsterModule

ssoadm service name: iPlanetAMAuthAmsterService

Authorized Keys

Specifies the location of the authorized_keys file that contains the private and public keys used to validate remote amster client connections.

The default location for the authorized_keys file is the /path/to/openam/security/keys/amster/ directory. Its content is similar to an OpenSSH authorized_keys file.

amster attribute: forgerock-am-auth-amster-authorized-keys

Enabled

When enabled, allows amster clients to authenticate using PKI. When disabled, allows amster clients to authenticate using interactive login only.

amster attribute: forgerock-am-auth-amster-enabled

Authentication Level

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.

amster attribute: forgerock-am-auth-amster-auth-level

ForgeRock Authenticator (OATH) Authentication Module Properties

amster service name: AuthenticatorOathModule

ssoadm service name: iPlanetAMAuthAuthenticatorOATHService

Authentication Level

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.

ssoadm attribute: iplanet-am-auth-fr-oath-auth-level

One-Time Password Length

Sets the length of the OTP to six digits or longer. The default value is six.

amster attribute: passwordLength

ssoadm attribute: iplanet-am-auth-fr-oath-password-length

Minimum Secret Key Length

The minimum number of hexadecimal characters allowed for the secret key.

amster attribute: minimumSecretKeyLength

ssoadm attribute: iplanet-am-auth-fr-oath-min-secret-key-length

OATH Algorithm to Use

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.

amster attribute: oathAlgorithm

ssoadm attribute: iplanet-am-auth-fr-oath-algorithm

HOTP Window Size

The window that the OTP device and the server counter can be out of sync. For example, if the window size is 100 and the server's last successful login was at counter value 2, then the server will accept an OTP from device counter 3 to 102. The default value is 100.

amster attribute: hotpWindowSize

ssoadm attribute: iplanet-am-auth-fr-oath-hotp-window-size

Add Checksum Digit

Adds a checksum digit at the end of the HOTP password to verify the OTP was generated correctly. This is in addition to the actual password length. Set this only if your device supports it. The default value is No.

amster attribute: addChecksumToOtpEnabled

ssoadm attribute: iplanet-am-auth-fr-oath-add-checksum

Truncation Offset

Advanced feature that is device-specific. Let this value default unless you know your device uses a truncation offset. The default value is -1.

amster attribute: truncationOffset

ssoadm attribute: iplanet-am-auth-fr-oath-truncation-offset

TOTP Time Step Interval

The time interval for which an OTP is valid. For example, if the time step interval is 30 seconds, a new OTP will be generated every 30 seconds, and an OTP will be valid for 30 seconds. The default value is 30 seconds.

amster attribute: totpTimeStepInterval

ssoadm attribute: iplanet-am-auth-fr-oath-size-of-time-step

TOTP Time Steps

The number of time step intervals that the system and the device can be off before password resynchronization is required. For example, if the number of TOTP time steps is 2 and the TOTP time step interval is 30 seconds, the server will allow an 89 second clock skew between the client and the server—two 30 second steps plus 29 seconds for the interval in which the OTP arrived. The default value is 2.

amster attribute: totpTimeStepsInWindow

ssoadm attribute: iplanet-am-auth-fr-oath-steps-in-window

One Time Password Max Retry

The number of times entry of the OTP may be attempted. Minimum is 1, maximum is 10.

Default: 3

amster attribute: oathOtpMaxRetry

ssoadm attribute: forgerock-oath-max-retry

Maximum Allowed Clock Drift

The maximum acceptable clock skew before authentication fails. When this value is exceeded, the user must re-register the device.

amster attribute: totpMaximumClockDrift

ssoadm attribute: openam-auth-fr-oath-maximum-clock-drift

Name of the Issuer

A value that appears as an identifier on the user's device. Common choices are a company name, a web site, or an AM realm.

amster attribute: oathIssuerName

ssoadm attribute: openam-auth-fr-oath-issuer-name

ForgeRock Authenticator (Push) Authentication Module Properties

amster service name: AuthenticatorPushModule

ssoadm service name: iPlanetAMAuthAuthenticatorPushService

Authentication Level

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.

amster attribute: authenticationLevel

ssoadm attribute: forgerock-am-auth-authenticatorpush-auth-level

Return Message Timeout (ms)

The period of time (in milliseconds) within which a push notification should be replied to.

Default: 120000

amster attribute: timeoutInMilliSecconds

ssoadm attribute: forgerock-am-auth-push-message-response-timeout

Login Message

Text content of the push message, which is used for the notification displayed on the registered device. The following variables can be used in the message:

{{user}}

Replaced with the username value of the account registered in the ForgeRock Authenticator app, for example Demo.

{{issuer}}

Replaced with the issuer value of the account registered in the ForgeRock Authenticator app, for example ForgeRock.

Default: Login attempt from {{user}} at {{issuer}}

amster attribute: pushMessage

ssoadm attribute: forgerock-am-auth-push-message

ForgeRock Authenticator (Push) Registration Authentication Module Properties

amster service name: AuthenticatorPushRegistrationModule

ssoadm service name: iPlanetAMAuthAuthenticatorPushRegistrationService

Authentication Level

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.

amster attribute: authenticationLevel

ssoadm attribute: forgerock-am-auth-push-reg-auth-level

Issuer Name

A value that appears as an identifier on the user's device. Common choices are a company name, a web site, or an AM realm.

amster attribute: issuer

ssoadm attribute: forgerock-am-auth-push-reg-issuer

Registration Response Timeout (ms)

The period of time (in milliseconds) to wait for a response to the registration QR code. If no response is received during this time the QR code times out and the registration process fails.

Default: 120000

amster attribute: timeoutInMilliSecconds

ssoadm attribute: forgerock-am-auth-push-message-registration-response-timeout

Background Color

The background color in hex notation to display behind the issuer's logo within the ForgeRock Authenticator app.

Default: #519387

amster attribute: bgcolour

ssoadm attribute: forgerock-am-auth-hex-bgcolour

Image URL

The location of an image to download and display as the issuer's logo within the ForgeRock Authenticator app.

amster attribute: imgUrl

ssoadm attribute: forgerock-am-auth-img-url

App Store App URL

URL of the app to download on the App Store.

Default: https://itunes.apple.com/app/forgerock-authenticator /id1038442926 (the ForgeRock Authenticator app)

amster attribute: appleLink

ssoadm attribute: forgerock-am-auth-apple-link

Google Play URL

URL of the app to download on Google Play.

Default: https://play.google.com/store/apps/details?id=com.forgerock.authenticator (the ForgeRock Authenticator app)

amster attribute: googleLink

ssoadm attribute: forgerock-am-auth-google-link

HOTP Authentication Module Properties

amster service name: HotpModule

ssoadm service name: sunAMAuthHOTPService

Authentication Level

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.

amster attribute: authenticationLevel

ssoadm attribute: sunAMAuthHOTPAuthLevel

SMS Gateway Implementation Class

Specifies the class the HOTP module uses to send SMS or email messages. Specify a class that implements the com.sun.identity.authentication.modules.hotp.SMSGateway interface to customize the SMS gateway implementation.

amster attribute: smsGatewayClass

ssoadm attribute: sunAMAuthHOTPSMSGatewayImplClassName

Mail Server Host Name

Specifies the hostname of the mail server supporting SMTP for electronic mail.

amster attribute: smtpHostname

ssoadm attribute: sunAMAuthHOTPSMTPHostName

Mail Server Host Port

Specifies the outgoing mail server port. The default port is 25, 465 (when connecting over SSL), or 587 (for StartTLS).

amster attribute: smtpHostPort

ssoadm attribute: sunAMAuthHOTPSMTPHostPort

Mail Server Authentication Username

Specifies the username for AM to connect to the mail server.

amster attribute: smtpUsername

ssoadm attribute: sunAMAuthHOTPSMTPUserName

Mail Server Authentication Password

Specifies the password for AM to connect to the mail server.

amster attribute: smtpUserPassword

ssoadm attribute: sunAMAuthHOTPSMTPUserPassword

Mail Server Secure Connection

Specifies whether to connect to the mail server securely. If enabled, AM must be able to trust the server certificate.

The possible values for this property are:

SSL
Non SSL
Start TLS

amster attribute: smtpSslEnabled

ssoadm attribute: sunAMAuthHOTPSMTPSSLEnabled

Email From Address

Specifies the From: address when sending a one-time password by mail.

amster attribute: smtpFromAddress

ssoadm attribute: sunAMAuthHOTPSMTPFromAddress

One-Time Password Validity Length (in minutes)

Specifies the amount of time, in minutes, the one-time passwords are valid after they are generated. The default is 5 minutes.

amster attribute: otpValidityDuration

ssoadm attribute: sunAMAuthHOTPPasswordValidityDuration

One-Time Password Length

Sets the length of one-time passwords.

amster attribute: otpLength

ssoadm attribute: sunAMAuthHOTPPasswordLength

Valid values: 6 and 8.

One Time Password Max Retry

The number of times entry of the OTP may be attempted. Minimum is 1, maximum is 10.

Default: 3

amster attribute: oathOtpMaxRetry

ssoadm attribute: forgerock-oath-max-retry

One-Time Password Delivery

Specifies whether to send the one-time password by SMS, by mail, or both.

amster attribute: otpDeliveryMethod

ssoadm attribute: sunAMAuthHOTPasswordDelivery

Valid values: SMS, E-mail, and SMS and E-mail.

Mobile Phone Number Attribute Name

Provides the attribute name used for the text message. The default value is telephoneNumber.

amster attribute: userProfileTelephoneAttribute

ssoadm attribute: openamTelephoneAttribute

Mobile Carrier Attribute Name

Specifies a user profile attribute that contains a mobile carrier domain for sending SMS messages.

The uncustomized AM user profile does not have an attribute for the mobile carrier domain. You can:

  • Customize the AM user profile by adding a new attribute to it. Then you can populate the new attribute with users' SMS messaging domains.

    All mobile carriers and bulk SMS messaging services have associated SMS messaging domains. For example, Verizon uses vtext.com, T-Mobile uses tmomail.net, and the TextMagic service uses textmagic.com. If you plan to send text messages internationally, determine whether the messaging service requires a country code.

  • Leave the value for Mobile Carrier Attribute Name blank, and let AM default to sending SMS messages using txt.att.net for all users.

amster attribute: mobileCarrierAttribute

ssoadm attribute: openamSMSCarrierAttribute

Email Attribute Name

Provides the attribute name used to email the OTP. The default value is mail (email).

amster attribute: userProfileEmailAttribute

ssoadm attribute: openamEmailAttribute

Auto Send OTP Code

When enabled, configures the HOTP module to automatically generate an email or text message when users begin the login process.

ssoadm attribute: sunAMAuthHOTPAutoClicking

HTTP Basic Authentication Module Properties

amster service name: HttpBasicModule

ssoadm service name: iPlanetAMAuthHTTPBasicService

Backend Module Name

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.

amster attribute: backendModuleName

ssoadm attribute: iplanet-am-auth-http-basic-module-configured

Valid values: LDAP and DataStore.

Authentication Level

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.

amster attribute: authenticationLevel

ssoadm attribute: iplanet-am-auth-httpbasic-auth-level

JDBC Authentication Module Properties

amster service name: JdbcModule

ssoadm service name: sunAMAuthJDBCService

Connection Type

Determines how the module obtains the connection to the database.

amster attribute: connectionType

ssoadm attribute: sunAMAuthJDBCConnectionType

Valid values: JNDI and JDBC.

Connection Pool JNDI Name

Specifies the URL of the connection pool for JNDI connections. Refer to your web container's documentation for instructions on setting up the connection pool.

amster attribute: connectionPoolJndiName

ssoadm attribute: sunAMAuthJDBCJndiName

JDBC Driver

Specifies the JDBC driver to use for JDBC connections.

Install a suitable Oracle or MySQL driver in the container where AM is installed, for example in the /path/to/tomcat/webapps/openam/WEB-INF/lib path. You can add it to the AM .war file when you deploy AM.

amster attribute: jdbcDriver

ssoadm attribute: sunAMAuthJDBCDriver

JDBC URL

Specifies the URL to connect to the database when using a JDBC connection.

amster attribute: jdbcUrl

ssoadm attribute: sunAMAuthJDBCUrl

Database Username, Database Password

Specifies the user name and password used to authenticate to the database when using a JDBC connection.

ssoadm attribute: sunAMAuthJDBCDbuser and sunAMAuthJDBCDbpassword

Password Column Name

Specifies the database column name where passwords are stored.

amster attribute: passwordColumn

ssoadm attribute: sunAMAuthJDBCPasswordColumn

Prepared Statement

Specifies the SQL query to return the password corresponding to the user to authenticate.

amster attribute: passwordStatement

ssoadm attribute: sunAMAuthJDBCStatement

Class to Transform Password Syntax

Specifies the class that transforms the password retrieved to the same format as provided by the user.

The default class expects the password in cleartext. Custom classes must implement the JDBCPasswordSyntaxTransform interface.

amster attribute: passwordTransformClass

ssoadm attribute: sunAMAuthJDBCPasswordSyntaxTransformPlugin

Authentication Level

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.

amster attribute: authenticationLevel

ssoadm attribute: sunAMAuthJDBCAuthLevel

Note

AM provides two properties, iplanet-am-admin-console-invalid-chars and iplanet-am-auth-ldap-invalid-chars, that store LDAP-related special characters that are not allowed in username searches.

When using JDBC databases, consider adding the '%' wildcard character to the iplanet-am-admin-console-invalid-chars and iplanet-am-auth-ldap-invalid-chars properties. By default, the '%' character is not included in the properties.

LDAP Authentication Module Properties

amster service name: LdapModule

ssoadm service name: iPlanetAMAuthLDAPService

Primary LDAP Server, Secondary LDAP Server

Directory servers generally use built-in data replication for high availability. Thus, a directory service likely consists of a pool of replicas to which AM 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.

Set one or more primary and optionally, one or more secondary directory server for each AM server. For the current AM server, specify each directory server as a host:port combination. For other AM servers in the deployment, you can specify each directory server as server-name|host:port, where server-name is the FQDN portion of the AM server from the list under Deployment > Servers, and host:port identifies the directory server.

For example, if the server-name that is listed is https://openam.example.com:8443/openam, and the directory server is accessible at opendj.example.com:1636, you would enter openam.example.com|opendj.example.com:1636.

When authenticating users from a directory server that is remote to AM, set the primary server values, and optionally the secondary server values. Primary servers have priority over secondary servers.

ssoadm attributes are: primary is iplanet-am-auth-ldap-server; secondary is iplanet-am-auth-ldap-server2.

Both properties take more than one value; thus, allowing more than one primary or secondary remote server, respectively. Assuming a multi-data center environment, AM determines priority within the primary and secondary remote servers, respectively, as follows:

  • Every LDAP server that is mapped to the current AM instance has highest priority.

    For example, if you are connected to openam1.example.com and ldap1.example.com is mapped to that AM instance, then AM uses ldap1.example.com.

  • Every LDAP server that was not specifically mapped to a given AM instance has the next highest priority.

    For example, if you have another LDAP server, ldap2.example.com, that is not connected to a specific AM server and if ldap1.example.com is unavailable, AM connects to the next highest priority LDAP server, ldap2.example.com.

  • LDAP servers that are mapped to different AM instances have the lowest priority.

    For example, if ldap3.example.com is connected to openam3.example.com and ldap1.example.com and ldap2.example.com are unavailable, then openam1.example.com connects to ldap3.example.com.

If you want use SSL or StartTLS to initiate a secure connection to a data store, then scroll down to enable SSL/TLS Access to LDAP Server. Make sure that AM can trust the server's certificates when using this option.

ssoadm attributes: openam-auth-ldap-connection-mode

Possible values: LDAP, LDAPS, and StartTLS

DN to Start User Search

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 ou=sales,dc=example,dc=com.

If multiple entries exist with identical search attribute values, make this value specific enough to return only one entry.

ssoadm attribute: iplanet-am-auth-ldap-base-dn

Bind User DN, Bind User Password

If AM stores attributes in the directory, for example to manage account lockout, or if the directory requires that AM authenticate in order to read users' attributes, then AM needs the DN and password to authenticate to the directory.

The default is uid=admin. Make sure that password is correct before you log out. If it is incorrect, you will be locked out. If this should occur, you can login with the superuser DN, which by default is uid=amAdmin,ou=People,AM-deploy-base, where AM-deploy-base is the value you set during AM configuration.

ssoadm attributes: iplanet-am-auth-ldap-bind-dn, iplanet-am-auth-ldap-bind-passwd

Attribute Used to Retrieve User Profile, Attributes Used to Search for a User to be Authenticated, User Search Filter, Search Scope

LDAP searches for user entries return entries with attribute values matching the filter you provide. For example, if you search under ou=people,dc=example,dc=com with a filter "(mail=bjensen@example.com)", then the directory returns the entry that has mail=bjensen@example.com. In this example the attribute used to search for a user is mail. Multiple attribute values mean the user can authenticate with any one of the values. For example, if you have both uid and mail, then Barbara Jensen can authenticate with either bjensen or bjensen@example.com.

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 mail and add User Search Filter (objectClass=inetOrgPerson), then AM uses the resulting search filter (&(mail=address)(objectClass=inetOrgPerson)), where address is the mail address provided by the user.

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.

ssoadm attributes: iplanet-am-auth-ldap-user-naming-attribute, iplanet-am-auth-ldap-user-search-attributes, iplanet-am-auth-ldap-search-filter, and iplanet-am-auth-ldap-search-scope

LDAP Connection Mode

If you want use SSL or StartTLS to initiate a secure connection to a data store, AM 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 AM runs, or because you imported the certificates into the trust store.

ssoadm attribute: openam-auth-ldap-connection-mode

Possible values: LDAP, LDAPS, and StartTLS

Return User DN to DataStore

When enabled, and AM uses the directory service as the user store, the module returns the DN, rather than the User ID. From the DN value, AM uses the RDN to search for the user profile. For example, if a returned DN value is uid=demo,ou=people,dc=openam,dc=example,dc=org, AM uses uid=demo to search the data store.

amster attribute: returnUserDN

ssoadm attribute: iplanet-am-auth-ldap-return-user-dn

User Creation Attributes

This list lets you map (external) attribute names from the LDAP directory server to (internal) attribute names used by AM.

amster attribute: profileAttributeMappings

ssoadm attribute: iplanet-am-ldap-user-creation-attr-list

Minimum Password Length

Specifies the minimum acceptable password length.

amster attribute: minimumPasswordLength

ssoadm attribute: iplanet-am-auth-ldap-min-password-length

LDAP Behera Password Policy Support

When enabled, support interoperability with servers that implement the Internet-Draft, Password Policy for LDAP Directories.

Support for this Internet-Draft is limited to the LDAP authentication module. Other components of AM, such as the password change functionality in the /idm/EndUser page, do not support the Internet-Draft. In general, outside of the LDAP authentication module, AM binds to the directory server as an administrator, such as Directory Manager. When AM 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.

amster attribute: beheraPasswordPolicySupportEnabled

ssoadm attribute: iplanet-am-auth-ldap-behera-password-policy-enabled

Trust All Server Certificates

When enabled, blindly trust server certificates, including self-signed test certificates.

amster attribute: trustAllServerCertificates

ssoadm attribute: iplanet-am-auth-ldap-ssl-trust-all

LDAP Connection Heartbeat Interval

Specifies how often AM 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.

Default: 1

amster attribute: connectionHeartbeatInterval

ssoadm attribute: openam-auth-ldap-heartbeat-interval

LDAP Connection Heartbeat Time Unit

Specifies the time unit corresponding to LDAP Connection Heartbeat Interval.

Default: minute

amster attribute: connectionHeartbeatTimeUnit

ssoadm attribute: openam-auth-ldap-heartbeat-timeunit

LDAP operations timeout

Defines the timeout in milliseconds that AM should wait for a response from the directory server.

Default: 0 (means no timeout)

amster attribute: operationTimeout

ssoadm attribute: openam-auth-ldap-operation-timeout

Authentication Level

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.

amster attribute: authenticationLevel

ssoadm attribute: iplanet-am-auth-ldap-auth-level

Legacy OAuth 2.0/OpenID Connect Authentication Module Properties

Important

This authentication module is labelled as legacy. Equivalent functionality is provided by the following authentication modules:

The Legacy OAuth 2.0/OpenID Connect Authentication Module will only be available in AM when upgrading from a previous version that was making use of the module in a chain. It is not available in new, clean installations since AM 5.5.

The default settings are for Facebook.

amster service name: OAuth2Module

ssoadm service name: sunAMAuthOAuthService

Client id

Specifies the OAuth 2.0 client_id parameter as described in section 2.2 of RFC 6749.

amster attribute: clientId

ssoadm attribute: iplanet-am-auth-oauth-client-id

Client Secret

Specifies the OAuth 2.0 client_secret parameter as described in section 2.3 of RFC 6749.

amster attribute: clientSecret

ssoadm attribute: iplanet-am-auth-oauth-client-secret

Authentication Endpoint URL

Specifies the URL to the endpoint handling OAuth 2.0 authentication as described in section 3.1 of RFC 6749.

Default:https://www.facebook.com/dialog/oauth.

amster attribute: authenticationEndpointUrl

ssoadm attribute: iplanet-am-auth-oauth-auth-service

Access Token Endpoint URL

Specifies the URL to the endpoint handling access tokens as described in section 3.2 of RFC 6749.

Default:https://graph.facebook.com/oauth/access_token.

amster attribute: accessTokenEndpointUrl

ssoadm attribute: iplanet-am-auth-oauth-token-service

User Profile Service URL

Specifies the user profile URL that returns profile information in JSON format.

Default:https://graph.facebook.com/me.

amster attribute: userProfileServiceUrl

ssoadm attribute: iplanet-am-auth-oauth-user-profile-service

Scope

Specifies a space-delimited list of user profile attributes that the client application requires, according to The OAuth 2.0 Authorization Framework. The list depends on the permissions that the resource owner, such as the end user, grants to the client application.

Some authorization servers use non-standard separators for scopes. Facebook, for example, takes a comma-separated list.

Default: email,read_stream (Facebook example)

amster attribute: scope

ssoadm attribute: iplanet-am-auth-oauth-scope

OAuth2 Access Token Profile Service Parameter name

Specifies the name of the parameter that contains the access token value when accessing the profile service.

Default: access_token.

amster attribute: accessTokenParameterName

ssoadm attribute: iplanet-am-auth-oauth-user-profile-param

Proxy URL

Sets the URL to the /oauth2c/OAuthProxy.jsp file, which provides AM with GET to POST proxying capabilities. Change this URL only if an external server performs the GET to POST proxying.

Default: @SERVER_PROTO@://@SERVER_HOST@:@SERVER_PORT@/@SERVER_URI@/oauth2c/OAuthProxy.jsp.

amster attribute: ssoProxyUrl

ssoadm attribute: iplanet-am-auth-oauth-sso-proxy-url

Account Provider

Specifies the name of the class that implements the account provider.

Default: org.forgerock.openam.authentication.modules.common.mapping.DefaultAccountProvider

amster attribute: accountProviderClass

ssoadm attribute: org-forgerock-auth-oauth-account-provider

Account Mapper

Specifies the name of the class that implements the attribute mapping for the account search.

For Google implementations, use org.forgerock.openam.authentication.modules.oidc.JwtAttributeMapper|*|Google-.

For Facebook implementations, use org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper|*|facebook-.

Default: org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper

amster attribute: accountMapperClass

ssoadm attribute: org-forgerock-auth-oauth-account-mapper

Account Mapper Configuration

Specifies the attribute configuration used to map the account of the user authenticated in the OAuth 2.0 provider to the local data store in AM. Valid values are in the form provider-attr=local-attr.

Default: email=mail and id=facebook-id.

amster attribute: accountMapperConfiguration

ssoadm attribute: org-forgerock-auth-oauth-account-mapper-configuration

Attribute Mapper

Specifies the list of fully qualified class names for implementations that map attributes from the OAuth 2.0 authorization server or OpenID Connect provider to AM profile attributes.

Default: org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper

Provided implementations are:

org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper
org.forgerock.openam.authentication.modules.oidc.JwtAttributeMapper (can only be used when using the openid scope)

Tip

You can provide string constructor parameters by appending pipe (|) separated values.

For example, the org.forgerock.openam.authentication.modules.oidc.JwtAttributeMapper class can take two constructor parameters: a comma-separated list of attributes and a prefix to apply to their values. Specify these as follows:

org.forgerock.openam.authentication.modules.oidc.JsonAttributeMapper

amster attribute: attributeMappingClasses

ssoadm attribute: org-forgerock-auth-oauth-attribute-mapper

Attribute Mapper Configuration

Map of OAuth 2.0 provider user account attributes to local user profile attributes, with values in the form provider-attr=local-attr.

Default: first_name=givenname, last_name=sn, name=cn, email=mail, id=facebook-id, first_name=facebook-fname, last_name=facebook-lname, email=facebook-email.

amster attribute: attributeMapperConfiguration

ssoadm attribute: org-forgerock-auth-oauth-attribute-mapper-configuration

Save attributes in the session

When enabled, saves the attributes in the Attribute Mapper Configuration field to the AM session.

amster attribute: saveAttributesInSession

ssoadm attribute: org-forgerock-auth-oauth-save-attributes-to-session-flag

Email attribute in OAuth2 Response

Specifies the attribute identifying the authenticated user's email address in the response from the profile service in the OAuth 2.0 provider. This setting is used to send an email message with an activation code for accounts created dynamically.

amster attribute: oauth2EmailAttribute

ssoadm attribute: org-forgerock-auth-oauth-mail-attribute

Create account if it does not exist

When enabled, AM creates an account for the user if the user profile does not exist. If the Prompt for password setting and activation code attribute is enabled, AM prompts the user for a password and activation code before creating the account.

When the OAuth 2.0/OpenID Connect client is configured to create new accounts, the SMTP settings must also be valid. As part of account creation, the OAuth 2.0/OpenID Connect client authentication module sends the resource owner an email with an account activation code. To send the mail, AM uses the SMTP settings you provide here in the OAuth 2.0/OpenID Connect client configuration.

When disabled, a user without a profile may still log into AM if the Ignore Profile attribute is set in the authentication service of the realm, or if the account is mapped to an anonymous account.

amster attribute: createAccount

ssoadm attribute: org-forgerock-auth-oauth-createaccount-flag

Prompt for password setting and activation code

When enabled, the user must set a password before AM creates an account dynamically. An activation code is also sent to the user's email address. Both the password and the code are required before the account is created.

amster attribute: promptForPassword

ssoadm attribute: org-forgerock-auth-oauth-prompt-password-flag

Map to anonymous user

When enabled, maps the OAuth 2.0 authenticated user to the specified anonymous user. If the Create account if it does not exist property is enabled, AM creates an account for the authenticated user instead of mapping the account to the anonymous user.

amster attribute: mapToAnonymousUser

ssoadm attribute: org-forgerock-auth-oauth-map-to-anonymous-flag

Anonymous User

Specifies an anonymous user that exists in the current realm. The Map to anonymous user property maps authorized users without a profile to this anonyomus user, if enabled.

Default: anonymous.

amster attribute: anonymousUserName

ssoadm attribute: org-forgerock-auth-oauth-anonymous-user

OAuth 2.0 Provider logout service

Specifies the optional URL of the OAuth 2.0 provider's logout service, if required.

amster attribute: oauth2LogoutServiceUrl

ssoadm attribute: org-forgerock-auth-oauth-logout-service-url

Logout options

Specifies whether not to log the user out without prompting from the OAuth 2.0 provider on logout, to log the user out without prompting, or to prompt the user regarding whether to log out from the OAuth 2.0 provider.

Valid values are:

  • prompt, to ask the user whether or not to log out from the OAuth 2.0 provider.

  • logout, to log the user out of the OAuth 2.0 provider without prompting.

  • donotlogout, to keep the user logged in to the OAuth 2.0 provider. There is no prompt to the user.

Default: prompt.

amster attribute: logoutBehaviour

ssoadm attribute: org-forgerock-auth-oauth-logout-behaviour

Mail Server Gateway implementation class

Specifies the class used by the module to send email. A custom subclass of org.forgerock.openam.authentication.modules.oauth2.EmailGateway class can be provided.

Default: org.forgerock.openam.authentication.modules.oauth2.DefaultEmailGatewayImpl

amster attribute: mailGatewayClass

ssoadm attribute: org-forgerock-auth-oauth-email-gwy-impl

SMTP host

Specifies the host name of the mail server.

Default: localhost.

amster attribute: smtpHostName

ssoadm attribute: org-forgerock-auth-oauth-smtp-hostname

SMTP port

Specifies the SMTP port number for the mail server.

Default: 25.

amster attribute: smtpHostPort

ssoadm attribute: org-forgerock-auth-oauth-smtp-port

SMTP User Name, SMTP User Password

Specifies the username and password AM uses to authenticate to the mail server.

ssoadm attribute: org-forgerock-auth-oauth-smtp-username and org-forgerock-auth-oauth-smtp-password.

SMTP SSL Enabled

When enabled, connects to the mail server over SSL. AM must be able to trust the SMTP server certificate.

amster attribute: smtpSslEnabled

ssoadm attribute: org-forgerock-auth-oauth-smtp-ssl_enabled

SMTP From address

Specifies the address of the email sender, such as no-reply@example.com.

Default: info@forgerock.com.

amster attribute: smtpFromAddress

ssoadm attribute: org-forgerock-auth-oauth-smtp-email-from

Authentication Level

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.

Default: 0.

amster attribute: authenticationLevel

ssoadm attribute: iplanet-am-auth-oauth-auth-level

OpenID Connect validation configuration type

Validates the ID token from the OpenID Connect provider. The module needs either a URL to get the public keys for the provider or the symmetric key for an ID token signed with a HMAC-based algorithm.

By default, the configuration type is .well-known/openid-configuration_url. This means the module should retrieve the keys based on information in the OpenID Connect provider configuration document.

You can instead configure the authentication module to validate the ID token signature with the client secret key you provide, or to validate the ID token with the keys retrieved from the URL to the OpenID Connect provider's JSON web key set.

/oauth2/realms/root/.well-known/openid-configuration_url (Default)

Retrieve the provider keys based on the information provided in the OpenID Connect Provider Configuration Document.

Specify the URL to the document as the discovery URL.

client_secret

Use the client secret that you specify as the key to validate the ID token signature according to the HMAC by using the client secret to the decrypt the hash, and then checking that the hash matches the hash of the ID token JWT.

jwk_url

Retrieve the provider's JSON web key set as the URL that you specify.

amster attribute: cryptoContextType

ssoadm attribute: openam-auth-openidconnect-crypto-context-type

OpenID Connect validation configuration value

Edit this field depending on the Configuration type you specified in the OpenId Connect validation configuration type field.

amster attribute: cryptoContextValue

ssoadm attribute: openam-auth-openidconnect-crypto-context-value

Token Issuer

Required when the openid scope is included. Value must match the iss field in the issued ID token. For example, accounts.google.com.

The issuer value MUST be provided when OAuth 2.0 Mix-Up Mitigation is enabled. For more information, see "OAuth 2.0 Mix-Up Mitigation".

amster attribute: idTokenIssuer

ssoadm attribute: openam-auth-openidconnect-issuer-name

Note

Old uses of DefaultAccountMapper are automatically upgraded to the equivalent default implementations.

The following table shows endpoint URLs for AM when configured as an OAuth 2.0 provider. For details, see the OAuth 2.0 Guide. The default endpoints are for Facebook as the OAuth 2.0 provider.

In addition to the endpoint URLs you can set other fields, like scope and attribute mapping, depending on the provider you use:

Endpoint URLs
AM FieldDetails
Authorization Endpoint URL

/oauth2/authorize under the deployment URL.[a]

Example: https://openam.example.com:8443/openam/oauth2/realms/root/authorize.

Access Token Endpoint URL

/oauth2/access_token under the deployment URL.[a]

Example: https://openam.example.com:8443/openam/oauth2/realms/root/access_token.

User Profile Service URL

/oauth2/tokeninfo under the deployment URL.

Example: https://openam.example.com:8443/openam/oauth2/realms/root/tokeninfo.

[a] This AM endpoint can take additional parameters. In particular, you must specify the realm if the AM OAuth 2.0 provider is configured for a subrealm rather than the Top Level Realm.

When making a REST API call, specify the realm in the path component of the endpoint. You must specify the entire hierarchy of the realm, starting at the Top Level Realm. Prefix each realm in the hierarchy with the realms/ keyword. For example /realms/root/realms/customers/realms/europe.

For example, if the OAuth 2.0 provider is configured for the subrealm customers within the Top Level Realm, then the authentication endpoint URL is as follows: https://openam.example.com:8443/openam/oauth2/realms/root/realms/customers/authorize

The /oauth2/authorize endpoint can also take module and service parameters. Use either as described in Authenticating (Browser), where module specifies the authentication module instance to use or service specifies the authentication chain to use when authenticating the resource owner.


OAuth 2.0 Mix-Up Mitigation

AM has added a new property to the OAuth 2.0 authentication module, openam-auth-oauth-mix-up-mitigation-enabled. This OAuth 2.0 Mix-Up Mitigation property controls whether the OAuth 2.0 authentication module carries out additional verification steps when it receives the authorization code from the authorization server. This setting should be only enabled when the authorization server also supports OAuth 2.0 Mix-Up Mitigation.

OAuth 2.0 Mix-Up Mitigation Enabled

Specifies that the client must compare the issuer identifier of the authorization server upon registration with the issuer value returned in the iss response parameter. If they do not match, the client must abort the authorization process. The client must also confirm that the authorization server's response is intended for the client by comparing the client's client identifier to the value of the client_id response parameter.

For more information, see section 4 of OAuth 2.0 Mix-Up Mitigration Draft.

Note

At the time of this release, Facebook, Google, and Microsoft identity providers do not support this draft.

amster attribute: mixUpMitigation

ssoadm attribute: openam-auth-oauth-mix-up-mitigation-enabled

On the AM console, the field Token Issuer must be provided when the OAuth 2.0 Mix-Up Mitigation feature is enabled. The authorization code response will contain an issuer value (iss) that will be validated by the client. When the module is an OAuth2-only module (that is, OIDC is not used), the issuer value needs to be explicitly set in the Token Issuer field, so that the validation can succeed.

Note

Consult with the authorization server's documentation on what value it uses for the issuer field.

MSISDN Authentication Module Properties

amster service name: MsisdnModule

ssoadm service name: sunAMAuthMSISDNService

Trusted Gateway IP Address

Specifies a list of IP addresses of trusted clients that can access MSISDN 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 none, no clients are allowed access.

amster attribute: trustedGatewayIPAddresses

ssoadm attribute: sunAMAuthMSISDNTrustedGatewayList

MSISDN Number Search Parameter Name

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.

amster attribute: msisdnParameterNames

ssoadm attribute: sunAMAuthMSISDNParameterNameList

LDAP Server and Port

Specifies the LDAP server FQDN and its port in the format ldap_server:port. AM servers can be paired with LDAP servers and ports by adding entries with the format AM_server|ldap_server:port, for example, openam.example.com|ldap1.example.com:649.

To use SSL or TLS for security, enable the SSL/TLS Access to LDAP property. Make sure that AM can trust the servers' certificates when using this option.

amster attribute: ldapProviderUrl

ssoadm attribute: sunAMAuthMSISDNLdapProviderUrl

LDAP Start Search DN

Specifies the DN of the entry where the search for the user's MSISDN number should start. AM servers can be paired with search base DNs by adding entries with the format AM_server|base_dn. For example, openam.example.com|dc=openam,dc=forgerock,dc=com .

amster attribute: baseSearchDN

ssoadm attribute: sunAMAuthMSISDNBaseDn

Attribute To Use To Search LDAP

Specifies the name of the attribute in the user's profile that contains the MSISDN number to search for the user. The default is sunIdentityMSISDNNumber.

amster attribute: userProfileMsisdnAttribute

ssoadm attribute: sunAMAuthMSISDNUserSearchAttribute

LDAP Server Authentication User, LDAP Server Authentication Password

Specifies the bind DN and password of the service account AM uses to authenticate to the directory server. The default is uid=admin.

ssoadm attribute: sunAMAuthMSISDNPrincipalUser and sunAMAuthMSISDNPrincipalPasswd.

SSL/TLS for LDAP Access

When enabled, AM uses LDAPS or StartTLS to connect to the directory server. If you choose to enable SSL or TLS, then make sure that AM can trust the servers' certificates.

amster attribute: ldapSslEnabled

ssoadm attribute: sunAMAuthMSISDNUseSsl

MSISDN Header Search Attribute

Specifies which elements are searched for the MSISDN number.The possible values are:

searchCookie

To search the cookie.

searchRequest

To search the request header.

searchParam

To search the request parameters.

amster attribute: msisdnRequestSearchLocations

ssoadm attribute: sunAMAuthMSISDNHeaderSearch

LDAP Attribute Used to Retrieve User Profile

Specify the LDAP attribute that is used during a search to return the user profile for MSISDN authentication service. The default is uid.

amster attribute: msisdnUserNamingAttribute

ssoadm attribute: sunAMAuthMSISDNUserNamingAttribute

Return User DN to DataStore

When enabled, this option allows the authentication module to return the DN instead of the User ID. AM thus does not need to perform an additional search with the user ID to find the user's entry.

Enable this option only when the AM directory is the same as the directory configured for MSISDN searches.

amster attribute: returnUserDN

ssoadm attribute: sunAMAuthMSISDNReturnUserDN

Authentication Level

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.

amster attribute: authenticationLevel

ssoadm attribute: sunAMAuthMSISDNAuthLevel

OATH Authentication Module Properties

amster service name: OathModule

ssoadm service name: iPlanetAMAuthOATHService

Authentication Level

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.

amster attribute: authenticationLevel

ssoadm attribute: iplanet-am-auth-oath-auth-level

One Time Password Length

Sets the length of the OTP to six digits or longer. The default value is six.

amster attribute: passwordLength

ssoadm attribute: iplanet-am-auth-oath-password-length

Minimum Secret Key Length

The minimum number of hexadecimal characters allowed for the secret key.

amster attribute: minimumSecretKeyLength

ssoadm attribute: iplanet-am-auth-oath-min-secret-key-length

Secret Key Attribute Name

The name of the attribute where the key will be stored in the user profile.

amster attribute: secretKeyAttribute

ssoadm attribute: iplanet-am-auth-oath-secret-key-attribute

OATH Algorithm to Use

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.

amster attribute: oathAlgorithm

ssoadm attribute: iplanet-am-auth-oath-algorithm

HOTP Window Size

The window that the OTP device and the server counter can be out of sync. For example, if the window size is 100 and the server's last successful login was at counter value 2, then the server will accept an OTP from device counter 3 to 102. The default value is 100.

amster attribute: hotpWindowSize

ssoadm attribute: iplanet-am-auth-oath-hotp-window-size

Note

For information on resetting the HOTP counter, see "Resetting Registered Devices by using REST".

Counter Attribute Name

The name of the HOTP attribute where the counter will be stored in the user profile.

amster attribute: hotpCounterAttribute

ssoadm attribute: iplanet-am-auth-oath-hotp-counter-attribute

Add Checksum Digit

Adds a checksum digit at the end of the HOTP password to verify the OTP was generated correctly. This is in addition to the actual password length. Set this only if your device supports it. The default value is No.

amster attribute: addChecksum

ssoadm attribute: iplanet-am-auth-oath-add-checksum

Truncation Offset

Advanced feature that is device-specific. Let this value default unless you know your device uses a truncation offset. The default value is -1.

amster attribute: truncationOffset

ssoadm attribute: iplanet-am-auth-oath-truncation-offset

TOTP Time Step Interval

The time interval for which an OTP is valid. For example, if the time step interval is 30 seconds, a new OTP will be generated every 30 seconds, and an OTP will be valid for 30 seconds. The default value is 30 seconds.

amster attribute: timeStepSize

ssoadm attribute: iplanet-am-auth-oath-size-of-time-step

One Time Password Max Retry

The number of times entry of the OTP may be attempted. Minimum is 1, maximum is 10.

Default: 3

amster attribute: oathOtpMaxRetry

ssoadm attribute: forgerock-oath-max-retry

TOTP Time Steps

The number of time step intervals that the system and the device can be off before password resynchronization is required. For example, if the number of TOTP time steps is 2 and the TOTP time step interval is 30 seconds, the server will allow an 89 second clock skew between the client and the server—two 30 second steps plus 29 seconds for the interval in which the OTP arrived. The default value is 2.

amster attribute: stepsInWindow

ssoadm attribute: iplanet-am-auth-oath-steps-in-window

Last Login Time Attribute

The name of the attribute where both HOTP and TOTP authentication will store information on when a person last logged in.

amster attribute: lastLoginTimeAttribute

ssoadm attribute: iplanet-am-auth-oath-last-login-time-attribute-name

The Shared Secret Provider Class

The class that processes the user profile attribute where the user's secret key is stored. The name of this attribute is specified in the Secret Key Attribute Name property.

Default: org.forgerock.openam.authentication.modules.oath.plugins.DefaultSharedSecretProvider

ssoadm attribute: forgerock-oath-sharedsecret-implementation-class

Clock Drift Attribute Name

The user profile attribute where the clock drift is stored. If this field is not specified, then AM does not check for clock drift.

ssoadm attribute: forgerock-oath-observed-clock-drift-attribute-name

Maximum Allowed Clock Drift

The maximum acceptable clock drift before authentication fails. If this value is exceeded, the user must register their device again.

The Maximum Allowed Clock Drift value should be greater than the TOTP Time Steps value.

ssoadm attribute: forgerock-oath-maximum-clock-drift

OpenID Connect id_token bearer Authentication Module Properties

The default settings are for Google's provider.

amster service name: SocialAuthOpenIDModule

ssoadm service name: amAuthOpenIdConnect

Account provider class

The account provider provides the means to search for and create OpenID Connect users given a set of attributes.

Default: org.forgerock.openam.authentication.modules.common.mapping.DefaultAccountProvider

amster attribute: accountProviderClass

ssoadm attribute: openam-auth-openidconnect-account-provider-class

OpenID Connect validation configuration type

In order to validate the ID token from the OpenID Connect provider, the module needs either a URL to get the public keys for the provider, or the symmetric key for an ID token signed with a HMAC-based algorithm.

By default, the configuration type is .well-known/openid-configuration_url. This means the module should retrieve the keys based on information in the OpenID Connect Provider Configuration Document.

You can instead configure the authentication module to validate the ID token signature with the client secret key you provide, or to validate the ID token with the keys retrieved from the URL to the OpenID Connect provider's JSON web key set.

.well-known/openid-configuration_url (Default)

Retrieve the provider keys based on the information provided in the OpenID Connect Provider Configuration Document.

Specify the URL to the document as the discovery URL.

client_secret

Use the client secret that you specify as the key to validate the ID token signature according to the HMAC, using the client secret to the decrypt the hash and then checking that the hash matches the hash of the ID token JWT.

jwk_url

Retrieve the provider's JSON web key set at the URL that you specify.

amster attribute: cryptoContextType

ssoadm attribute: openam-auth-openidconnect-crypto-context-type

OpenID Connect validation configuration value

Specifies the discovery URL, JWK or the client secret corresponding to the configuration type selected in the OpenID Connect validation configuration type property.

amster attribute: cryptoContextValue

ssoadm attribute: openam-auth-openidconnect-crypto-context-value

Name of header referencing the ID Token

Specifies the name of the HTTP request header to search for the ID token.

Default: oidc_id_token

amster attribute: idTokenHeaderName

ssoadm attribute: openam-auth-openidconnect-header-name

Name of OpenID Connect ID Token Issuer

Corresponds to the expected issue identifier value in the iss field of the ID token.

Default: accounts.google.com

amster attribute: idTokenIssuer

ssoadm attribute: openam-auth-openidconnect-issuer-name

Mapping of jwt attributes to local LDAP attributes

Maps OpenID Connect ID token claims to local user profile attributes, allowing the module to retrieve the user profile based on the ID token.

In OpenID Connect, an ID token is represented as a JSON Web Token (JWT). The ID Token section of the OpenID Connect Core 1.0 specification defines a number of claims included in the ID token for all flows. Additional claims depend on the scopes requested of the OpenID Connect provider.

For each item in the map, the key is the ID token field name and the value is the local user profile attribute name.

Default: mail=email, uid=sub

ssoadm attribute: openam-auth-openidconnect-local-to-jwt-attribute-mappings

Audience name

Specifies a case-sensitive audience name for this OpenID Connect authentication module. Used to check that the ID token received is intended for this module as an audience.

Default: example

amster attribute: audienceName

ssoadm attribute: openam-auth-openidconnect-audience-name

List of accepted authorized parties

Specifies a list of case-sensitive strings and/or URIs from which this authentication module accepts ID tokens. This list is checked against the authorized party claim of the ID token.

Default: AuthorizedPartyExample http://www.example.com/authorized/party

amster attribute: acceptedAuthorizedParties

ssoadm attribute: openam-auth-openidconnect-accepted-authorized-parties

Principal Mapper class

Specifies the class that implements the mapping of the OpenID Connect end user to an AM account. The default principal mapper uses the mapping of local attributes to ID token attributes to find a user profile.

Default: org.forgerock.openam.authentication.modules.oidc.JwtAttributeMapper

amster attribute: principalMapperClass

ssoadm attribute: openam-auth-openidconnect-principal-mapper-class

RADIUS Authentication Module Properties

amster service name: RadiusModule

ssoadm service name: iPlanetAMAuthRadiusService

Primary Radius Servers, Secondary Radius Servers

Specify one or more primary and secondary RADIUS servers.

When configuring RADIUS servers, specify their IP address or FQDN. Configuring multiple servers allows you to map a RADIUS server to a specific AM instance in the form of AM_instance | RADIUS_server, where the AM instance is also specified by its IP address or FQDN.

Tip

Ensure each RADIUS server listens to the port specified in the Port Number field.

When authenticating users from a directory server that is remote to AM, set the primary values and, optionally, the secondary server values. Assuming a multi-data center environment, AM determines priority within the primary and secondary remote servers, respectively, as follows:

  • Every RADIUS server that is mapped to the current AM instance has highest priority.

  • Every RADIUS server that was not specifically mapped to a given AM instance has the next highest priority.

  • RADIUS servers that are mapped to different AM instances have the lowest priority.

Note

AM does not use round-robin load balancing to set priority. AM uses an active-passive algorithm, determining the highest priority to the first available server within the primary server list. If no primary servers are available, AM uses the secondary remote server.

ssoadm attribute: primary is iplanet-am-auth-radius-server1; secondary is iplanet-am-auth-radius-server2

Shared Secret

Specify the shared secret for RADIUS authentication. The shared secret should be as secure as a well-chosen password.

amster attribute: sharedSecret

ssoadm attribute: iplanet-am-auth-radius-secret

Port Number

Specify the RADIUS server port.

Default is 1645.

amster attribute: serverPortNumber

ssoadm attribute: iplanet-am-auth-radius-server-port

Timeout

Specify how many seconds to wait for the RADIUS server to respond. The default value is 3 seconds.

amster attribute: serverTimeout

ssoadm attribute: iplanet-am-auth-radius-timeout

Health Check Interval

Used for failover. Specify how often AM performs a health check on a previously unavailable RADIUS server by sending an invalid authentication request.

Default: 5 minutes

amster attribute: healthCheckInterval

ssoadm attribute: openam-auth-radius-healthcheck-interval

Authentication Level

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.

amster attribute: authenticationLevel

ssoadm attribute: iplanet-am-auth-radius-auth-level

SAE Authentication Module Properties

amster service name: SaeModule

ssoadm service name: sunAMAuthSAEService

Authentication Level

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.

ssoadm service name: sunAMAuthSAEAuthLevel

SAML2 Authentication Module Properties

amster service name: Saml2Module

ssoadm service name: iPlanetAMAuthSAML2Service

Authentication Level

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.

ssoadm attribute: iplanet-am-auth-saml2-auth-level

IDP Entity ID

Specifies the identity provider (IDP) for authentication requests to this module. Specify the name of a SAML v2.0 entity provider that is defined in the SAML2 authentication module's realm.

You can find configured entity providers in the AM console under Federation. The Realm column identifies the realm in which an entity provider has been configured.

amster attribute: entityName

ssoadm attribute: forgerock-am-auth-saml2-entity-name

SP MetaAlias

Specifies the local alias for the service provider (SP).

For service providers configured in the Top Level Realm, use the format /SP Name.

For service providers configured in subrealms, use the format /Realm Name/SP Name.

To find the local aliases for entity providers in the AM console, navigate to Realms > Realm Name > Applications > Federation > Entity Providers > Entity Provider Name > Services.

amster attribute: metaAlias

ssoadm attribute: forgerock-am-auth-saml2-meta-alias

Allow IDP to Create NameID

Specifies whether the IDP should create a new identifier for the authenticating user if none exists.

A value of true permits the IDP to create an identifier for the authenticating user if none exists. A value of false indicates a request to constrain the IDP from creating an identifier.

For detailed information, see the section on the AllowCreate property in SAML Version 2.0 Errata 05.

Default: true

amster attribute: allowCreate

ssoadm attribute: forgerock-am-auth-saml2-allow-create

Linking Authentication Chain

Specifies an authentication chain that is invoked when a user requires authentication to the SP.

Authentication to the SP is required when the authentication module running on the SP is unable to determine the user's identity based on the assertion received from the IDP. In this case, the linking authentication chain is invoked to allow the end user to link their remote and local accounts.

amster attribute: loginChain

ssoadm attribute: forgerock-am-auth-saml2-login-chain

Comparison Type

Specifies a comparison method to evaluate authentication context classes or statements. The value specified in this property overrides the value set in the SP configuration under Realms > Realm Name > Applications > Federation > Entity Providers > Service Provider Name > Assertion Content > Authentication Context > Comparison Type.

Valid comparison methods are exact, minimum, maximum, or better.

For more information about the comparison methods, see the section on the <RequestedAuthnContext> element in Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0.

Default: exact

amster attribute: authComparison

ssoadm attribute: forgerock-am-auth-saml2-auth-comparison

Authentication Context Class Reference

Specifies one or more URIs for authentication context classes to be included in the SAML request. Authentication context classes are unique identifiers for an authentication mechanism. The SAML v2.0 protocol supports a standard set of authentication context classes, defined in Authentication Context for the OASIS Security Assertion Markup Language (SAML) V2.0. In addition to the standard authentication context classes, you can specify customized authentication context classes.

Any authentication context class that you specify in this field must be supported for the service provider. To determine which authentication context classes are supported, locate the list of authentication context classes that are available to the SP under Realms > Realm Name > Applications > Federation > Entity Providers > Service Provider Name > Assertion Content > Authentication Context, and then review the values in the Supported column.

When specifying multiple authentication context classes, use the | character to separate the classes.

Example value: urn:oasis:names:tc:SAML:2.0:ac:classes:Password|urn:oasis:names:tc:SAML:2.0:ac:classes:TimesyncToken

amster attribute: authnContextClassRef

ssoadm attribute: forgerock-am-auth-saml2-authn-context-class-ref

Authentication Context Declaration Reference

Specifies one or more URIs that identify authentication context declarations.

This field is optional.

When specifying multiple URIs, use the | character to separate the URIs.

For more information, see the section on the <RequestedAuthnContext> element in Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0.

amster attribute: authnContextDeclRef

ssoadm attribute: forgerock-am-auth-saml2-authn-context-decl-ref

Request Binding

Specifies the format used to send the authentication request from the SP to the IDP.

Valid values are HTTP-Redirect and HTTP-POST.

Default: HTTP-Redirect

ssoadm attribute: forgerock-am-auth-saml2-req-binding. When using the ssoadm command, set this attribute's value to urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect or urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST.

Response Binding

Specifies the format used to send the response from the IDP to the SP.

A value of HTTP-POST indicates that the HTTP POST binding with a self-submitting form should be used in assertion processing. A value of HTTP-Artifact indicates that the HTTP Artifact binding should be used.

Default: HTTP-Artifact

ssoadm attribute: forgerock-am-auth-saml2-binding. When using the ssoadm command, set this attribute's value to urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact or urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST.

Force IDP Authentication

Specifies whether the IDP should force authentication or can reuse existing security contexts.

A value of true indicates that the IDP should force authentication. A value of false indicates that the IDP can reuse existing security contexts.

amster attribute: forceAuthn

ssoadm attribute: forgerock-am-auth-saml2-force-authn

Passive Authentication

Specifies whether the IDP should use passive authentication or not. Passive authentication requires the IDP to only use authentication methods that do not require user interaction. For example, authenticating using an X.509 certificate.

A value of true indicates that the IDP should authenticate passively. A value of false indicates that the IDP should not authenticate passively.

amster attribute: isPassive

ssoadm attribute: forgerock-am-auth-saml2-is-passive

NameID Format

Specifies a SAML name ID format to be requested in the SAML authentication request.

Default: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

amster attribute: nameIdFormat

ssoadm attribute: forgerock-am-auth-saml2-name-id-format

Single Logout Enabled

Specifies whether AM should attempt to log out of the user's IDP session during session logout.

When enabling SAML v2.0 single logout, you must also configure the post-authentication processing class for the authentication chain containing the SAML2 authentication module to org.forgerock.openam.authentication.modules.saml2.SAML2PostAuthenticationPlugin.

For more information about configuring single logout when implementing SAML v2.0 federation using the SAML2 authentication module, see "Configuring SLO in Integrated Mode (Chains)".

Default: false

amster attribute: sloEnabled

ssoadm attribute: forgerock-am-auth-saml2-slo-enabled

Single Logout URL

Specifies the URL to which the user is forwarded after successful IDP logout. Configure this property only if you have enabled SAML v2.0 single logout by selecting the Single Logout Enabled check box.

amster attribute: sloRelay

ssoadm attribute: forgerock-am-auth-saml2-slo-relay

Scripted Authentication Module Properties

amster service name: scripted

ssoadm service name: iPlanetAMAuthScriptedService

Use the following settings at the realm level when configuring an individual scripted authentication module, in the AM console under Realms > Realm Name > Authentication > Modules.

Client-Side Script Enabled

When enabled, the module includes the specified client-side script in the login page to be executed on the user-agent prior to the server-side script.

amster attribute: clientScriptEnabled

ssoadm attribute: iplanet-am-auth-scripted-client-script-enabled

Client-Side Script

Specifies the ID of the script to include in the login page. This script is run on the user-agent prior to the server-side script. This script must be written in a language the user-agent can interpret, such as JavaScript, even if the server-side script is written in Groovy.

To create, view, or modify the content of the scripts, navigate to Realms > Realm Name > Scripts.

amster attribute: clientScript

ssoadm attribute: iplanet-am-auth-scripted-client-script

Server Side Script

Specifies the ID of the script to run in AM after the client-side script has completed.

To create, view, or modify the content of the scripts, navigate to Realms > Realm Name > Scripts.

amster attribute: serverScript

ssoadm attribute: iplanet-am-auth-scripted-server-script

Authentication Level

Sets the authentication level used to indicate the level of security associated with the scripted authentication module.

The value can range from 0 to any positive integer.

amster attribute: authenticationLevel

ssoadm attribute: iplanet-am-auth-scripted-auth-level

In the AM console, navigate to Configure > Global Services > Scripting > Secondary Configurations > Server-Side Script Type,> Secondary Configurations > EngineConfiguration.

On the EngineConfiguration page, configure the following settings for the scripting engine of the selected type:

Server-side Script Timeout

Specifies the maximum execution time any individual script should take on the server (in seconds). AM terminates scripts which take longer to run than this value.

ssoadm attribute: serverTimeout

Core thread pool size

Specifies the initial number of threads in the thread pool from which scripts operate. AM will ensure the pool contains at least this many threads.

ssoadm attribute: coreThreads

Maximum thread pool size

Specifies the maximum number of threads in the thread pool from which scripts operate. If no free thread is available in the pool, AM creates new threads in the pool for script execution up to the configured maximum. It is recommended to set the maximum number of threads to 300.

ssoadm attribute: maxThreads

Thread pool queue size

Specifies the number of threads to use for buffering script execution requests when the maximum thread pool size is reached. Disabling the maximum queue size is recommended, by setting the value to -1, which creates an unbounded queue.

For short, CPU-bound scripts, consider a small pool size and larger queue length. For I/O-bound scripts, for example, REST calls, consider a larger maximum pool size and a smaller queue.

Not hot-swappable: restart server for changes to take effect.

ssoadm attribute: queueSize

Thread idle timeout (seconds)

Specifies the length of time (in seconds) for a thread to be idle before AM terminates created threads. If the current pool size contains the number of threads set in Core thread pool size, then idle threads will not be terminated, maintaining the initial pool size.

ssoadm attribute: idleTimeout

Java class whitelist

Specifies the list of class name patterns allowed to be invoked by the script. Every class accessed by the script must match at least one of these patterns.

You can specify the class name as-is or use a regular expression.

ssoadm attribute: whiteList

Java class blacklist

Specifies the list of class name patterns that are NOT allowed to be invoked by the script. The blacklist is applied AFTER the whitelist to exclude those classes. Access to a class specified in both the whitelist and the blacklist will be denied.

You can specify the class name to exclude as-is or use a regular expression.

ssoadm attribute: blackList

Use system SecurityManager

When enabled, AM makes a call to the System.getSecurityManager().checkPackageAccess(...) method for each class that is accessed. The method throws SecurityException if the calling thread is not allowed to access the package.

Note

This feature only takes effect if the security manager is enabled for the JVM.

ssoadm attribute: useSecurityManager

SecurID Authentication Module Properties

Important

To use the SecurID authentication module, you must first build an AM .war file that includes the supporting library. For more information, see "Enabling RSA SecurID Support".

amster service name: securid

ssoadm service name: iPlanetAMAuthSecurIDService

ACE/Server Configuration Path

Specify the directory where the SecurID ACE/Server sdconf.rec file is located, which by default is expected under the AM configuration directory, such as /path/to/openam/config/auth/ace/data. The directory must exist before AM can use SecurID authentication.

amster attribute: serverConfigPath

ssoadm attribute: iplanet-am-auth-securid-server-config-path

Authentication Level

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.

amster attribute: authenticationLevel

ssoadm attribute: iplanet-am-auth-securid-auth-level

Social Authentication Module Properties - Instagram

amster service name: SocialAuthInstagramModule

ssoadm service name: iPlanetAMAuthSocialAuthInstagramService

Core

The following properties are available under the Core tab:

Authentication Level

Specifies the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

Default: 0

amster data attribute: authenticationLevel

Social Provider

Specifies the name of the social provider for which this module is being set up.

Default: Instagram

amster data attribute: provider

Client Id

Specifies the client_id parameter as described in section 2.2 of The OAuth 2.0 Authorization Framework (RFC 6749).

Tip

To register an application with Instagram and obtain an OAuth 2.0 client_id and client_secret, visit https://www.instagram.com/developer/.

amster attribute: clientId

Client Secret

Specifies the client_secret parameter as described in section 2.3 of The OAuth 2.0 Authorization Framework (RFC 6749).

amster attribute: clientSecret

Authentication Endpoint URL

Specifies the URL to the social provider's endpoint handling authentication as described in section 3.1 of The OAuth 2.0 Authorization Framework (RFC 6749).

Default: https://api.instagram.com/oauth/authorize

amster attribute: authorizeEndpoint

Access Token Endpoint URL

Specifies the URL to the endpoint handling access tokens as described in section 3.2 of The OAuth 2.0 Authorization Framework (RFC 6749).

Default: https://api.instagram.com/oauth/access_token

amster attribute: tokenEndpoint

User Profile Service URL

Specifies the user profile URL that returns profile information in JSON format.

Default:https://api.instagram.com/v1/users/self

amster attribute: userInfoEndpoint

Scope

Specifies a list of user profile attributes that the client application requires, according to The OAuth 2.0 Authorization Framework (RFC 6749). The list depends on the permissions that the resource owner, such as the end user, grants to the client application.

Default: basic

amster attribute: scope

Scope Delimiter

Specifies the delimiter used to separate scope values.

Some authorization servers use non-standard separators for scopes. Facebook, for example, uses commas.

Default: space character

amster attribute: scopeDelimiter

Subject Property

Specifies the attribute the social provider uses to identify a user.

Default: id

amster attribute: subjectProperty

Use Basic Auth

Specifies that the client uses HTTP Basic authentication when authenticating to the social provider.

Valid values are:

  • true

  • false

Default: false

amster attribute: usesBasicAuth

Proxy URL

Specifies the URL to the /oauth2c/OAuthProxy.jsp file, which provides AM with GET to POST proxying capabilities. Change this URL only if an external server performs the GET to POST proxying.

Default: @SERVER_PROTO@://@SERVER_HOST@:@SERVER_PORT@/@SERVER_URI@/oauth2c/OAuthProxy.jsp

Example: https://openam.example.com:8443/openam/oauth2c/OAuthProxy.jsp

amster attribute: ssoProxyUrl

OAuth 2.0 Provider Logout Service

Specifies the URL of the social provider's logout service.

To enable logout of the social authentication provider when logging out of AM, you must add org.forgerock.openam.authentication.modules.oauth2.OAuth2PostAuthnPlugin to the Authentication Post Processing Classes property. To add the class, navigate to Authentication > Settings > Post Authentication Processing.

Default: https://instagram.com/accounts/logout

amster attribute: logoutServiceUrl

Logout Options

Specifies the social provider logout actions to take when logging out of AM.

Valid options are:

prompt

Asks the user whether or not to log out from the social provider.

logout

Logs the user out of the social provider without prompting.

donotlogout

Keeps the user logged in to the social provider. There is no prompt to the user.

Default: prompt

amster attribute: logoutBehaviour

Account Provisioning

The following properties are available under the Account Provisioning tab:

Use IDM as Registration Service

Whether to use IDM as an external registration service to complete registration for new users. You must configure and enable the IDM Provisioning service to use this option. See "IDM Provisioning".

AM passes IDM these parameters:

  • clientToken: Signed, encrypted JWT of the OAuth 2.0 authentication state.

  • returnParams: Encoded URL parameters, required to be returned to AM to resume authentication after registration in IDM is complete.

Default: False

amster attribute: enableRegistrationService

Create account if it does not exist

When enabled, AM creates an account for the user if the user profile does not exist.

When disabled, a user without a profile may still log into AM if the Ignore Profile attribute is set in the authentication service of the realm, or if the account is mapped to an anonymous account.

Valid values are:

  • true

  • false

Default: true

amster attribute: createAccount

Account Provider

Specifies the name of the class that implements the account provider.

Default: org.forgerock.openam.authentication.modules.common.mapping.DefaultAccountProvider

amster attribute: accountProviderClass

Account Mapper

Specifies the name of the class that implements the attribute mapping for the account search.

Tip

You can provide string constructor parameters by appending pipe-separated (|) values.

Default: org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper|*|instagram-

amster attribute: accountMapperClass

Account Mapper Configuration

Specifies the attribute configuration used to map the account of the user authenticated in the social provider to the local data store in AM. Valid values take the form provider-attr=local-attr.

Default: id=uid

amster attribute: accountMapperConfiguration

Attribute Mapper

Specifies the list of fully qualified class names for implementations that map attributes from the social provider to AM profile attributes.

You can provide a custom attribute mapper. A custom attribute mapper must implement the org.forgerock.openam.authentication.modules.common.mapping.AttributeMapper interface.

Provided implementations are:

  • org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper

  • org.forgerock.openam.authentication.modules.oidc.JwtAttributeMapper - can only be used when using the openid scope

Tip

You can provide string constructor parameters by appending pipe-separated (|) values.

For example, the org.forgerock.openam.authentication.modules.oidc.JwtAttributeMapper class can take two constructor parameters: a comma-separated list of attributes, and a prefix to apply to their values. Specify these as follows:

org.forgerock.openam.authentication.modules.oidc.JsonAttributeMapper|uid|instagram-

Default: org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper|uid|instagram-

amster attribute: attributeMappingClasses

Attribute Mapper Configuration

Specifies a map of social provider user account attributes to local user profile attributes with values in the form provider-attr=local-attr.

Default:

id=uid
full_name=sn
username=cn
username=givenName

amster attribute: attributeMapperConfiguration

Map to anonymous user

When enabled, maps the social provider authenticated user to a specified anonymous user. If the Create account if it does not exist property is enabled, AM creates an account for the authenticated user instead of mapping the account to an anonymous user.

Valid values are:

  • true

  • false

Default: false

amster attribute: mapToAnonymousUser

Anonymous User

Specifies an anonymous user that exists in the current realm. The Map to anonymous user property maps authorized users without a profile to this anonyomus user, if enabled.

Default: anonymous

amster attribute: anonymousUserName

Save attributes in the session

When enabled, saves the values of attributes specified in the Attribute Mapper Configuration property in the AM session.

Valid values are:

  • true

  • false

Default: true

amster attribute: saveAttributesInSession

Social Authentication Module Properties - OAuth 2.0

amster service name: SocialAuthOAuth2Module

ssoadm service name: iPlanetAMAuthSocialAuthOAuth2Service

Core

The following properties are available under the Core tab:

Authentication Level

Specifies the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

Default: 0

amster data attribute: authenticationLevel

Social Provider

Specifies the name of the social provider for which this module is being set up.

Example: Google

amster data attribute: provider

Client Id

Specifies the client_id parameter as described in section 2.2 of The OAuth 2.0 Authorization Framework (RFC 6749).

amster attribute: clientId

Client Secret

Specifies the client_secret parameter as described in section 2.3 of The OAuth 2.0 Authorization Framework (RFC 6749).

amster attribute: clientSecret

Authentication Endpoint URL

Specifies the URL to the social provider's endpoint handling authentication as described in section 3.1 of The OAuth 2.0 Authorization Framework (RFC 6749).

Example: https://accounts.google.com/o/oauth2/v2/auth

amster attribute: authorizeEndpoint

Access Token Endpoint URL

Specifies the URL to the endpoint handling access tokens as described in section 3.2 of The OAuth 2.0 Authorization Framework (RFC 6749).

Example: https://www.googleapis.com/oauth2/v4/token

amster attribute: tokenEndpoint

User Profile Service URL

Specifies the user profile URL that returns profile information in JSON format.

Exaple: https://www.googleapis.com/oauth2/v3/userinfo

amster attribute: userInfoEndpoint

Scope

Specifies a list of user profile attributes that the client application requires, according to The OAuth 2.0 Authorization Framework (RFC 6749). The list depends on the permissions that the resource owner, such as the end user, grants to the client application.

amster attribute: scope

Scope Delimiter

Specifies the delimiter used to separate scope values.

Some authorization servers use non-standard separators for scopes. Facebook, for example, uses commas.

amster attribute: scopeDelimiter

Subject Property

Specifies the attribute the social provider uses to identify a user.

Example: sub

amster attribute: subjectProperty

Use Basic Auth

Specifies that the client uses HTTP Basic authentication when authenticating to the social provider.

Valid values are:

  • true

  • false

Default: true

amster attribute: usesBasicAuth

Proxy URL

Specifies the URL to the /oauth2c/OAuthProxy.jsp file, which provides AM with GET to POST proxying capabilities. Change this URL only if an external server performs the GET to POST proxying.

Default: @SERVER_PROTO@://@SERVER_HOST@:@SERVER_PORT@/@SERVER_URI@/oauth2c/OAuthProxy.jsp

Example: https://openam.example.com:8443/openam/oauth2c/OAuthProxy.jsp

amster attribute: ssoProxyUrl

OAuth 2.0 Provider Logout Service

Specifies the URL of the social provider's logout service.

To enable logout of the social authentication provider when logging out of AM, you must add org.forgerock.openam.authentication.modules.oauth2.OAuth2PostAuthnPlugin to the Authentication Post Processing Classes property. To add the class, navigate to Authentication > Settings > Post Authentication Processing.

amster attribute: logoutServiceUrl

Logout Options

Specifies the social provider logout actions to take when logging out of AM.

Valid options are:

prompt

Asks the user whether or not to log out from the social provider.

logout

Logs the user out of the social provider without prompting.

donotlogout

Keeps the user logged in to the social provider. There is no prompt to the user.

Default: prompt

amster attribute: logoutBehaviour

Token Issuer

Corresponds to the expected issue identifier value in the iss field of the ID token.

Example: https://accounts.google.com

amster attribute: issuerName

OAuth 2.0 Mix-Up Mitigation Enabled

Controls whether the OAuth 2.0 authentication module carries out additional verification steps when it receives the authorization code from the authorization server.

Specifies that the client must compare the issuer identifier of the authorization server upon registration with the issuer value returned in the iss response parameter. If they do not match, the client must abort the authorization process. The client must also confirm that the authorization server's response is intended for the client by comparing the client's client identifier to the value of the client_id response parameter.

The Token Issuer property must be entered when the OAuth 2.0 Mix-Up Mitigation feature is enabled, so that the validation can succeed. The authorization code response will contain an issuer value (iss) that will be validated by the client.

Note

Consult with the authorization server's documentation on what value it uses for the issuer field.

For more information, see section 4 of OAuth 2.0 Mix-Up Mitigration Draft.

amster attribute: mixUpMitigation

Account Provisioning

The following properties are available under the Account Provisioning tab:

Use IDM as Registration Service

Whether to use IDM as an external registration service to complete registration for new users. You must configure and enable the IDM Provisioning service to use this option. See "IDM Provisioning"

AM passes IDM these parameters:

  • clientToken: Signed, encrypted JWT of the OAuth 2.0 authentication state.

  • returnParams: Encoded URL parameters, required to be returned to AM to resume authentication after registration in IDM is complete.

Default: False

amster attribute: enableRegistrationService

Create account if it does not exist

When enabled, AM creates an account for the user if the user profile does not exist. If the Prompt for password setting and activation code attribute is enabled, AM prompts the user for a password and activation code before creating the account.

Important

When configured to create new accounts, the SMTP settings must also be valid. As part of account creation, the authentication module sends the resource owner an email with an account activation code. To send the mail, AM uses the SMTP settings you provide in the module configuration.

When disabled, a user without a profile may still log into AM if the Ignore Profile attribute is set in the authentication service of the realm, or if the account is mapped to an anonymous account.

Valid values are:

  • true

  • false

Default: true

amster attribute: createAccount

Account Provider

Specifies the name of the class that implements the account provider.

Default: org.forgerock.openam.authentication.modules.common.mapping.DefaultAccountProvider

amster attribute: accountProviderClass

Account Mapper

Specifies the name of the class that implements the attribute mapping for the account search.

Example: org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper|*|google-

amster attribute: accountMapperClass

Account Mapper Configuration

Specifies the attribute configuration used to map the account of the user authenticated in the social provider to the local data store in AM. Valid values take the form provider-attr=local-attr.

amster attribute: accountMapperConfiguration

Attribute Mapper

Specifies the list of fully qualified class names for implementations that map attributes from the social provider to AM profile attributes.

You can provide a custom attribute mapper. A custom attribute mapper must implement the org.forgerock.openam.authentication.modules.common.mapping.AttributeMapper interface.

Provided implementations are:

  • org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper

  • org.forgerock.openam.authentication.modules.oidc.JwtAttributeMapper - can only be used when using the openid scope

Tip

You can provide string constructor parameters by appending pipe-separated (|) values.

For example, the org.forgerock.openam.authentication.modules.oidc.JwtAttributeMapper class can take two constructor parameters: a comma-separated list of attributes, and a prefix to apply to their values. Specify these as follows:

org.forgerock.openam.authentication.modules.oidc.JwtAttributeMapper|*|google-

amster attribute: attributeMappingClasses

Attribute Mapper Configuration

Specifies a map of social provider user account attributes to local user profile attributes with values in the form provider-attr=local-attr.

amster attribute: attributeMapperConfiguration

Prompt for password setting and activation code

When enabled, the user must set a password before AM creates an account dynamically. An activation code is also sent to the user's email address. Both the password and the code are required before the account is created.

Valid values are:

  • true

  • false

Default: false

amster attribute: promptPasswordFlag

Map to anonymous user

When enabled, maps the social provider authenticated user to a specified anonymous user. If the Create account if it does not exist property is enabled, AM creates an account for the authenticated user instead of mapping the account to an anonymous user.

Valid values are:

  • true

  • false

Default: false

amster attribute: mapToAnonymousUser

Anonymous User

Specifies an anonymous user that exists in the current realm. The Map to anonymous user property maps authorized users without a profile to this anonyomus user, if enabled.

Default: anonymous

amster attribute: anonymousUserName

Save attributes in the session

When enabled, saves the values of attributes specified in the Attribute Mapper Configuration property in the AM session.

Valid values are:

  • true

  • false

Default: true

amster attribute: saveAttributesInSession

Email

The following properties are available under the Email tab:

Email attribute in the Response

Specifies the attribute identifying the authenticated user's email address in the response from the profile service in the social provider. This setting is used to send an email message with an activation code for accounts created dynamically.

amster attribute: emailAttribute

Mail Server Gateway implementation class

Specifies the class used by the module to send email. A custom subclass of org.forgerock.openam.authentication.modules.oauth2.EmailGateway class can be provided.

Default: org.forgerock.openam.authentication.modules.oauth2.DefaultEmailGatewayImpl

amster attribute: emailGateway

SMTP host

Specifies the host name of the mail server.

Default: localhost

amster attribute: smtpHost

SMTP port

Specifies the SMTP port number for the mail server.

Default: 25

amster attribute: smtpPort

SMTP User Name

Specifies the username AM uses to authenticate to the mail server.

amster attribute: smtpUsername

SMTP User Password

Specifies the password AM uses to authenticate to the mail server.

amster attribute: smtpPassword

SMTP SSL Enabled

When enabled, connects to the mail server over SSL. AM must be able to trust the SMTP server certificate.

Valid values are:

  • true

  • false

Default: false

amster attribute: smtpSslEnabled

SMTP From address

Specifies the address of the email sender, such as no-reply@example.com.

amster attribute: smtpFromAddress

Social Authentication Module Properties - OpenID Connect 1.0

The example settings are for Google.

amster service name: SocialAuthOpenIDModule

ssoadm service name: iPlanetAMAuthSocialAuthOpenIDService

Core

The following properties are available under the Core tab:

Social Provider

Specifies the name of the social provider for which this module is being set up.

Example: Google

amster data attribute: provider

Client Id

Specifies the client_id parameter as described in section 2.2 of The OAuth 2.0 Authorization Framework (RFC 6749).

amster attribute: clientId

Client Secret

Specifies the client_secret parameter as described in section 2.3 of The OAuth 2.0 Authorization Framework (RFC 6749).

amster attribute: clientSecret

Authentication Level

Specifies the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

Default: 0

amster data attribute: authenticationLevel

Authentication Endpoint URL

Specifies the URL to the social provider's endpoint handling authentication as described in section 3.1 of The OAuth 2.0 Authorization Framework (RFC 6749).

Example: https://accounts.google.com/o/oauth2/v2/auth

amster attribute: authorizeEndpoint

Access Token Endpoint URL

Specifies the URL to the endpoint handling access tokens as described in section 3.2 of The OAuth 2.0 Authorization Framework (RFC 6749).

Example: https://www.googleapis.com/oauth2/v4/token

amster attribute: tokenEndpoint

User Profile Service URL

Specifies the user profile URL that returns profile information in JSON format.

Exaple: https://www.googleapis.com/oauth2/v3/userinfo

amster attribute: userInfoEndpoint

Scope

Specifies a list of user profile attributes that the client application requires, according to The OAuth 2.0 Authorization Framework (RFC 6749). The list depends on the permissions that the resource owner, such as the end user, grants to the client application.

Default: openid

amster attribute: scope

Scope Delimiter

Specifies the delimiter used to separate scope values.

Some authorization servers use non-standard separators for scopes. Facebook, for example, uses commas.

amster attribute: scopeDelimiter

Subject Property

Specifies the attribute the social provider uses to identify a user.

Example: sub

amster attribute: subjectProperty

Use Basic Auth

Specifies that the client uses HTTP Basic authentication when authenticating to the social provider.

Valid values are:

  • true

  • false

Default: true

amster attribute: usesBasicAuth

Proxy URL

Specifies the URL to the /oauth2c/OAuthProxy.jsp file, which provides AM with GET to POST proxying capabilities. Change this URL only if an external server performs the GET to POST proxying.

Default: @SERVER_PROTO@://@SERVER_HOST@:@SERVER_PORT@/@SERVER_URI@/oauth2c/OAuthProxy.jsp

Example: https://openam.example.com:8443/openam/oauth2c/OAuthProxy.jsp

amster attribute: ssoProxyUrl

OAuth 2.0 Provider Logout Service

Specifies the URL of the social provider's logout service.

To enable logout of the social authentication provider when logging out of AM, you must add org.forgerock.openam.authentication.modules.oauth2.OAuth2PostAuthnPlugin to the Authentication Post Processing Classes property. To add the class, navigate to Authentication > Settings > Post Authentication Processing.

amster attribute: logoutServiceUrl

Logout Options

Specifies the social provider logout actions to take when logging out of AM.

Valid options are:

prompt

Asks the user whether or not to log out from the social provider.

logout

Logs the user out of the social provider without prompting.

donotlogout

Keeps the user logged in to the social provider. There is no prompt to the user.

Default: prompt

amster attribute: logoutBehaviour

Token Issuer

Corresponds to the expected issue identifier value in the iss field of the ID token.

Example: https://accounts.google.com

amster attribute: issuerName

OAuth 2.0 Mix-Up Mitigation Enabled

Controls whether the OAuth 2.0 authentication module carries out additional verification steps when it receives the authorization code from the authorization server.

Specifies that the client must compare the issuer identifier of the authorization server upon registration with the issuer value returned in the iss response parameter. If they do not match, the client must abort the authorization process. The client must also confirm that the authorization server's response is intended for the client by comparing the client's client identifier to the value of the client_id response parameter.

The Token Issuer property must be entered when the OAuth 2.0 Mix-Up Mitigation feature is enabled, so that the validation can succeed. The authorization code response will contain an issuer value (iss) that will be validated by the client.

Note

Consult with the authorization server's documentation on what value it uses for the issuer field.

For more information, see section 4 of OAuth 2.0 Mix-Up Mitigration Draft.

amster attribute: mixUpMitigation

OpenID Connect

The following properties are available under the OpenID Connect tab:

OpenID Connect validation configuration type

In order to validate the ID token from the OpenID Connect provider, the module needs either a URL to get the public keys for the provider, or the symmetric key for an ID token signed with a HMAC-based algorithm.

By default, the configuration type is .well-known/openid-configuration_url. This means the module should retrieve the keys based on information in the OpenID Connect Provider Configuration Document.

You can instead configure the authentication module to validate the ID token signature with the client secret key you provide, or to validate the ID token with the keys retrieved from the URL to the OpenID Connect provider's JSON web key set.

.well-known/openid-configuration_url (Default)

Retrieve the provider keys based on the information provided in the OpenID Connect Provider Configuration Document.

Specify the URL to the document in the OpenID Connect validation configuration value property

client_secret

Use the client secret that you specify in the Client Secret property (not the OpenID Connect validation configuration value property, which is ignored) as the key to validate the ID token signature according to the HMAC, using the client secret to the decrypt the hash and then checking that the hash matches the hash of the ID token JWT.

jwk_url

Retrieve the provider's JSON web key set at the URL that you specify in the OpenID Connect validation configuration value property.

amster attribute: cryptoContextType

OpenID Connect validation configuration value

Specifies the full URL to the discovery or JWK location, corresponding to the configuration type selected in the OpenID Connect validation configuration type property.

Example: https://accounts.google.com/.well-known/openid-configuration

amster attribute: cryptoContextValue

Account Provisioning

The following properties are available under the Account Provisioning tab:

Use IDM as Registration Service

Whether to use IDM as an external registration service to complete registration for new users. You must configure and enable the IDM Provisioning service to use this option. See "IDM Provisioning".

AM passes IDM these parameters:

  • clientToken: Signed, encrypted JWT of the OAuth 2.0 authentication state.

  • returnParams: Encoded URL parameters, required to be returned to AM to resume authentication after registration in IDM is complete.

Default: False

amster attribute: enableRegistrationService

Create account if it does not exist

When enabled, AM creates an account for the user if the user profile does not exist. If the Prompt for password setting and activation code attribute is enabled, AM prompts the user for a password and activation code before creating the account.

Important

When configured to create new accounts, the SMTP settings must also be valid. As part of account creation, the authentication module sends the resource owner an email with an account activation code. To send the mail, AM uses the SMTP settings you provide in the module configuration.

When disabled, a user without a profile may still log into AM if the Ignore Profile attribute is set in the authentication service of the realm, or if the account is mapped to an anonymous account.

Valid values are:

  • true

  • false

Default: true

amster attribute: createAccount

Account Provider

Specifies the name of the class that implements the account provider.

Default: org.forgerock.openam.authentication.modules.common.mapping.DefaultAccountProvider

amster attribute: accountProviderClass

Account Mapper

Specifies the name of the class that implements the attribute mapping for the account search.

Tip

You can provide string constructor parameters by appending pipe-separated (|) values.

Example: org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper|*|google-

amster attribute: accountMapperClass

Account Mapper Configuration

Specifies the attribute configuration used to map the account of the user authenticated in the social provider to the local data store in AM. Valid values take the form provider-attr=local-attr.

amster attribute: accountMapperConfiguration

Attribute Mapper

Specifies the list of fully qualified class names for implementations that map attributes from the social provider to AM profile attributes.

You can provide a custom attribute mapper. A custom attribute mapper must implement the org.forgerock.openam.authentication.modules.common.mapping.AttributeMapper interface.

Provided implementations are:

  • org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper

  • org.forgerock.openam.authentication.modules.oidc.JwtAttributeMapper - can only be used when using the openid scope

Tip

You can provide string constructor parameters by appending pipe-separated (|) values.

For example, the org.forgerock.openam.authentication.modules.oidc.JwtAttributeMapper class can take two constructor parameters: a comma-separated list of attributes, and a prefix to apply to their values. Specify these as follows:

org.forgerock.openam.authentication.modules.oidc.JwtAttributeMapper|*|google-

amster attribute: attributeMappingClasses

Attribute Mapper Configuration

Specifies a map of social provider user account attributes to local user profile attributes with values in the form provider-attr=local-attr.

amster attribute: attributeMapperConfiguration

Prompt for password setting and activation code

When enabled, the user must set a password before AM creates an account dynamically. An activation code is also sent to the user's email address. Both the password and the code are required before the account is created.

Valid values are:

  • true

  • false

Default: false

amster attribute: promptPasswordFlag

Map to anonymous user

When enabled, maps the social provider authenticated user to a specified anonymous user. If the Create account if it does not exist property is enabled, AM creates an account for the authenticated user instead of mapping the account to an anonymous user.

Valid values are:

  • true

  • false

Default: false

amster attribute: mapToAnonymousUser

Anonymous User

Specifies an anonymous user that exists in the current realm. The Map to anonymous user property maps authorized users without a profile to this anonyomus user, if enabled.

Default: anonymous

amster attribute: anonymousUserName

Save attributes in the session

When enabled, saves the values of attributes specified in the Attribute Mapper Configuration property in the AM session.

Valid values are:

  • true

  • false

Default: true

amster attribute: saveAttributesInSession

Email

The following properties are available under the Email tab:

Email attribute in the Response

Specifies the attribute identifying the authenticated user's email address in the response from the profile service in the social provider. This setting is used to send an email message with an activation code for accounts created dynamically.

amster attribute: emailAttribute

Mail Server Gateway implementation class

Specifies the class used by the module to send email. A custom subclass of org.forgerock.openam.authentication.modules.oauth2.EmailGateway class can be provided.

Default: org.forgerock.openam.authentication.modules.oauth2.DefaultEmailGatewayImpl

amster attribute: emailGateway

SMTP host

Specifies the host name of the mail server.

Default: localhost

amster attribute: smtpHost

SMTP port

Specifies the SMTP port number for the mail server.

Default: 25

amster attribute: smtpPort

SMTP User Name

Specifies the username AM uses to authenticate to the mail server.

amster attribute: smtpUsername

SMTP User Password

Specifies the password AM uses to authenticate to the mail server.

amster attribute: smtpPassword

SMTP SSL Enabled

When enabled, connects to the mail server over SSL. AM must be able to trust the SMTP server certificate.

Valid values are:

  • true

  • false

Default: false

amster attribute: smtpSslEnabled

SMTP From address

Specifies the address of the email sender, such as no-reply@example.com.

amster attribute: smtpFromAddress

Social Authentication Module Properties - VKontakte

amster service name: SocialAuthVKontakteModule

ssoadm service name: iPlanetAMAuthSocialAuthVKService

Core

The following properties are available under the Core tab:

Social Provider

Specifies the name of the social provider for which this module is being set up.

Default: VKontakte

amster data attribute: provider

Client Id

Specifies the client_id parameter as described in section 2.2 of The OAuth 2.0 Authorization Framework (RFC 6749).

Tip

To register an application with VKontakte and obtain an OAuth 2.0 client_id and client_secret, visit https://vk.com/apps?act=manage.

amster attribute: clientId

Client Secret

Specifies the client_secret parameter as described in section 2.3 of The OAuth 2.0 Authorization Framework (RFC 6749).

amster attribute: clientSecret

Authentication Level

Specifies the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

Default: 0

amster data attribute: authenticationLevel

Authentication Endpoint URL

Specifies the URL to the endpoint handling authentication as described in section 3.1 of The OAuth 2.0 Authorization Framework (RFC 6749).

Default: https://oauth.vk.com/authorize

amster attribute: authorizeEndpoint

Access Token Endpoint URL

Specifies the URL to the social provider's endpoint handling access tokens as described in section 3.2 of The OAuth 2.0 Authorization Framework (RFC 6749).

Default: https://oauth.vk.com/access_token

amster attribute: tokenEndpoint

User Profile Service URL

Specifies the user profile URL that returns profile information in JSON format.

Default:https://api.vk.com/method/users.get

amster attribute: userInfoEndpoint

Scope

Specifies a list of user profile attributes that the client application requires, according to The OAuth 2.0 Authorization Framework (RFC 6749). The list depends on the permissions that the resource owner, such as the end user, grants to the client application.

amster attribute: scope

Proxy URL

Specifies the URL to the /oauth2c/OAuthProxy.jsp file, which provides AM with GET to POST proxying capabilities. Change this URL only if an external server performs the GET to POST proxying.

Default: @SERVER_PROTO@://@SERVER_HOST@:@SERVER_PORT@/@SERVER_URI@/oauth2c/OAuthProxy.jsp

Example: https://openam.example.com:8443/openam/oauth2c/OAuthProxy.jsp

amster attribute: ssoProxyUrl

Subject Property

Specifies the attribute the social provider uses to identify a user.

Default: id

amster attribute: subjectProperty

Account Provisioning

The following properties are available under the Account Provisioning tab:

Account Provider

Specifies the name of the class that implements the account provider.

Default: org.forgerock.openam.authentication.modules.common.mapping.DefaultAccountProvider

amster attribute: accountProviderClass

Use IDM as Registration Service

Whether to use IDM as an external registration service to complete registration for new users. You must configure and enable the IDM Provisioning service to use this option. See "IDM Provisioning".

AM passes IDM these parameters:

  • clientToken: Signed, encrypted JWT of the OAuth 2.0 authentication state.

  • returnParams: Encoded URL parameters, required to be returned to AM to resume authentication after registration in IDM is complete.

Default: False

amster attribute: enableRegistrationService

Create account if it does not exist

When enabled, AM creates an account for the user if the user profile does not exist. If the Prompt for password setting and activation code attribute is enabled, AM prompts the user for a password and activation code before creating the account.

Important

When configured to create new accounts, the SMTP settings must also be valid. As part of account creation, the authentication module sends the resource owner an email with an account activation code. To send the mail, AM uses the SMTP settings you provide in the module configuration.

When disabled, a user without a profile may still log into AM if the Ignore Profile attribute is set in the authentication service of the realm, or if the account is mapped to an anonymous account.

Valid values are:

  • true

  • false

Default: true

amster attribute: createAccount

Account Mapper

Specifies the name of the class that implements the attribute mapping for the account search.

Default: org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper|uid|vkontakte-

amster attribute: accountMapperClass

Account Mapper Configuration

Specifies the attribute configuration used to map the account of the user authenticated in the social provider to the local data store in AM. Valid values take the form provider-attr=local-attr.

Default: uid=uid

amster attribute: accountMapperConfiguration

Attribute Mapper

Specifies the list of fully qualified class names for implementations that map attributes from the social provider to AM profile attributes.

You can provide a custom attribute mapper. A custom attribute mapper must implement the org.forgerock.openam.authentication.modules.common.mapping.AttributeMapper interface.

Provided implementations are:

  • org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper

  • org.forgerock.openam.authentication.modules.oidc.JwtAttributeMapper - can only be used when using the openid scope

Tip

You can provide string constructor parameters by appending pipe-separated (|) values.

For example, the org.forgerock.openam.authentication.modules.oidc.JwtAttributeMapper class can take two constructor parameters: a comma-separated list of attributes, and a prefix to apply to their values. Specify these as follows:

org.forgerock.openam.authentication.modules.oidc.JwtAttributeMapper|uid|vkontakte-

Default: org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper|uid|vkontakte-

amster attribute: attributeMappingClasses

Attribute Mapper Configuration

Specifies a map of social provider user account attributes to local user profile attributes with values in the form provider-attr=local-attr.

Default:

uid=uid
full_name=givenName
first_name=cn
last_name=sn
email=mail

amster attribute: attributeMapperConfiguration

Prompt for password setting and activation code

When enabled, the user must set a password before AM creates an account dynamically. An activation code is also sent to the user's email address. Both the password and the code are required before the account is created.

Valid values are:

  • true

  • false

Default: false

amster attribute: promptPasswordFlag

Map to anonymous user

When enabled, maps the social provider authenticated user to a specified anonymous user. If the Create account if it does not exist property is enabled, AM creates an account for the authenticated user instead of mapping the account to an anonymous user.

Valid values are:

  • true

  • false

Default: false

amster attribute: mapToAnonymousUser

Anonymous User

Specifies an anonymous user that exists in the current realm. The Map to anonymous user property maps authorized users without a profile to this anonyomus user, if enabled.

Default: anonymous

amster attribute: anonymousUserName

Save attributes in the session

When enabled, saves the values of attributes specified in the Attribute Mapper Configuration property in the AM session.

Valid values are:

  • true

  • false

Default: true

amster attribute: saveAttributesInSession

Email

The following properties are available under the Email tab:

Email attribute in the Response

Specifies the attribute identifying the authenticated user's email address in the response from the profile service in the social provider. This setting is used to send an email message with an activation code for accounts created dynamically.

amster attribute: emailAttribute

Mail Server Gateway implementation class

Specifies the class used by the module to send email. A custom subclass of org.forgerock.openam.authentication.modules.oauth2.EmailGateway class can be provided.

Default: org.forgerock.openam.authentication.modules.oauth2.DefaultEmailGatewayImpl

amster attribute: emailGateway

SMTP host

Specifies the host name of the mail server.

Default: localhost

amster attribute: smtpHost

SMTP port

Specifies the SMTP port number for the mail server.

Default: 25

amster attribute: smtpPort

SMTP User Name

Specifies the username AM uses to authenticate to the mail server.

amster attribute: smtpUsername

SMTP User Password

Specifies the password AM uses to authenticate to the mail server.

amster attribute: smtpPassword

SMTP SSL Enabled

When enabled, connects to the mail server over SSL. AM must be able to trust the SMTP server certificate.

Valid values are:

  • true

  • false

Default: false

amster attribute: smtpSslEnabled

SMTP From address

Specifies the address of the email sender, such as no-reply@example.com.

Default: info@forgerock.com

amster attribute: smtpFromAddress

Social Authentication Module Properties - WeChat

amster service name: SocialAuthWeChatModule

ssoadm service name: iPlanetAMAuthSocialAuthWeChatService

Core

The following properties are available under the Core tab:

Authentication Level

Specifies the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

Default: 0

amster data attribute: authenticationLevel

Social Provider

Specifies the name of the social provider for which this module is being set up.

Default: WeChat

amster data attribute: provider

Client Id

Specifies the client_id parameter as described in section 2.2 of The OAuth 2.0 Authorization Framework (RFC 6749).

Tip

To register an application with WeChat and obtain an OAuth 2.0 client_id and client_secret, visit https://open.weixin.qq.com/cgi-bin/frame?t=home/web_tmpl.

amster attribute: clientId

Client Secret

Specifies the client_secret parameter as described in section 2.3 of The OAuth 2.0 Authorization Framework (RFC 6749).

amster attribute: clientSecret

Authentication Endpoint URL

Specifies the URL to the social provider's endpoint handling authentication as described in section 3.1 of The OAuth 2.0 Authorization Framework (RFC 6749).

Default: https://open.weixin.qq.com/connect/qrconnect

amster attribute: authorizeEndpoint

Access Token Endpoint URL

Specifies the URL to the endpoint handling access tokens as described in section 3.2 of The OAuth 2.0 Authorization Framework (RFC 6749).

Default: https://api.wechat.com/sns/oauth2/access_token

amster attribute: tokenEndpoint

User Profile Service URL

Specifies the user profile URL that returns profile information in JSON format.

Default:https://api.wechat.com/sns/userinfo

amster attribute: userInfoEndpoint

Scope

Specifies a list of user profile attributes that the client application requires, according to The OAuth 2.0 Authorization Framework (RFC 6749). The list depends on the permissions that the resource owner, such as the end user, grants to the client application.

amster attribute: scope

Scope Delimiter

Specifies the delimiter used to separate scope values.

Some authorization servers use non-standard separators for scopes. Facebook, for example, uses commas.

Default: space character

amster attribute: scopeDelimiter

Subject Property

Specifies the attribute the social provider uses to identify a user.

Default: openid

amster attribute: subjectProperty

Use Basic Auth

Specifies that the client uses HTTP Basic authentication when authenticating to the social provider.

Valid values are:

  • true

  • false

Default: false

amster attribute: usesBasicAuth

Proxy URL

Specifies the URL to the /oauth2c/OAuthProxy.jsp file, which provides AM with GET to POST proxying capabilities. Change this URL only if an external server performs the GET to POST proxying.

Default: @SERVER_PROTO@://@SERVER_HOST@:@SERVER_PORT@/@SERVER_URI@/oauth2c/OAuthProxy.jsp

Example: https://openam.example.com:8443/openam/oauth2c/OAuthProxy.jsp

amster attribute: ssoProxyUrl

Account Provisioning

The following properties are available under the Account Provisioning tab:

Use IDM as Registration Service

Whether to use IDM as an external registration service to complete registration for new users. You must configure and enable the IDM Provisioning service to use this option. See "IDM Provisioning".

AM passes IDM these parameters:

  • clientToken: Signed, encrypted JWT of the OAuth 2.0 authentication state.

  • returnParams: Encoded URL parameters, required to be returned to AM to resume authentication after registration in IDM is complete.

Default: False

amster attribute: enableRegistrationService

Create account if it does not exist

When enabled, AM creates an account for the user if the user profile does not exist. If the Prompt for password setting and activation code attribute is enabled, AM prompts the user for a password and activation code before creating the account.

Important

When configured to create new accounts, the SMTP settings must also be valid. As part of account creation, the authentication module sends the resource owner an email with an account activation code. To send the mail, AM uses the SMTP settings you provide in the module configuration.

When disabled, a user without a profile may still log into AM if the Ignore Profile attribute is set in the authentication service of the realm, or if the account is mapped to an anonymous account.

Valid values are:

  • true

  • false

Default: true

amster attribute: createAccount

Account Provider

Specifies the name of the class that implements the account provider.

Default: org.forgerock.openam.authentication.modules.common.mapping.DefaultAccountProvider

amster attribute: accountProviderClass

Account Mapper

Specifies the name of the class that implements the attribute mapping for the account search.

Default: org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper|*|wechat-

amster attribute: accountMapperClass

Account Mapper Configuration

Specifies the attribute configuration used to map the account of the user authenticated in the social provider to the local data store in AM. Valid values take the form provider-attr=local-attr.

Default: openid=uid

amster attribute: accountMapperConfiguration

Attribute Mapper

Specifies the list of fully qualified class names for implementations that map attributes from the social provider to AM profile attributes.

You can provide a custom attribute mapper. A custom attribute mapper must implement the org.forgerock.openam.authentication.modules.common.mapping.AttributeMapper interface.

Provided implementations are:

  • org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper

  • org.forgerock.openam.authentication.modules.oidc.JwtAttributeMapper - can only be used when using the openid scope

Tip

You can provide string constructor parameters by appending pipe-separated (|) values.

For example, the org.forgerock.openam.authentication.modules.oidc.JwtAttributeMapper class can take two constructor parameters: a comma-separated list of attributes, and a prefix to apply to their values. Specify these as follows:

org.forgerock.openam.authentication.modules.oidc.JwtAttributeMapper|*|wechat-

Default: org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper|*|wechat-

amster attribute: attributeMappingClasses

Attribute Mapper Configuration

Specifies a map of social provider user account attributes to local user profile attributes with values in the form provider-attr=local-attr.

Default:

openid=uid
nickname=sn
nickname=cn
nickname=givenName

amster attribute: attributeMapperConfiguration

Prompt for password setting and activation code

When enabled, the user must set a password before AM creates an account dynamically. An activation code is also sent to the user's email address. Both the password and the code are required before the account is created.

Valid values are:

  • true

  • false

Default: false

amster attribute: promptPasswordFlag

Map to anonymous user

When enabled, maps the social provider authenticated user to a specified anonymous user. If the Create account if it does not exist property is enabled, AM creates an account for the authenticated user instead of mapping the account to an anonymous user.

Valid values are:

  • true

  • false

Default: false

amster attribute: mapToAnonymousUser

Anonymous User

Specifies an anonymous user that exists in the current realm. The Map to anonymous user property maps authorized users without a profile to this anonyomus user, if enabled.

Default: anonymous

amster attribute: anonymousUserName

Save attributes in the session

When enabled, saves the values of attributes specified in the Attribute Mapper Configuration property in the AM session.

Valid values are:

  • true

  • false

Default: true

amster attribute: saveAttributesInSession

Email

The following properties are available under the Email tab:

Email attribute in the Response

Specifies the attribute identifying the authenticated user's email address in the response from the profile service in the social provider. This setting is used to send an email message with an activation code for accounts created dynamically.

amster attribute: emailAttribute

Mail Server Gateway implementation class

Specifies the class used by the module to send email. A custom subclass of org.forgerock.openam.authentication.modules.oauth2.EmailGateway class can be provided.

Default: org.forgerock.openam.authentication.modules.oauth2.DefaultEmailGatewayImpl

amster attribute: emailGateway

SMTP host

Specifies the host name of the mail server.

Default: localhost

amster attribute: smtpHost

SMTP port

Specifies the SMTP port number for the mail server.

Default: 25

amster attribute: smtpPort

SMTP User Name

Specifies the username AM uses to authenticate to the mail server.

amster attribute: smtpUsername

SMTP User Password

Specifies the password AM uses to authenticate to the mail server.

amster attribute: smtpPassword

SMTP SSL Enabled

When enabled, connects to the mail server over SSL. AM must be able to trust the SMTP server certificate.

Valid values are:

  • true

  • false

Default: false

amster attribute: smtpSslEnabled

SMTP From address

Specifies the address of the email sender, such as no-reply@example.com.

Default: info@forgerock.com

amster attribute: smtpFromAddress

Social Authentication Module Properties - WeChat Mobile

amster service name: SocialAuthWeChatMobileModule

ssoadm service name: iPlanetAMAuthSocialAuthWeChatMobileService

Core

The following properties are available under the Core tab:

Authentication Level

Specifies the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

Default: 0

amster data attribute: authenticationLevel

Social Provider

Specifies the name of the social provider for which this module is being set up.

Default: WeChat

amster data attribute: provider

User Profile Service URL

Specifies the user profile URL that returns profile information in JSON format.

Default: https://api.wechat.com/sns/userinfo

amster attribute: userInfoEndpoint

Scope

Specifies a list of user profile attributes that the client application requires, according to The OAuth 2.0 Authorization Framework (RFC 6749). The list depends on the permissions that the resource owner, such as the end user, grants to the client application.

Default: snsapi_userinfo

amster attribute: scope

Subject Property

Specifies the attribute the social provider uses to identify a user.

Default: openid

amster attribute: subjectProperty

Proxy URL

Specifies the URL to the /oauth2c/OAuthProxy.jsp file, which provides AM with GET to POST proxying capabilities. Change this URL only if an external server performs the GET to POST proxying.

Default: @SERVER_PROTO@://@SERVER_HOST@:@SERVER_PORT@/@SERVER_URI@/oauth2c/OAuthProxy.jsp

Example: https://openam.example.com:8443/openam/oauth2c/OAuthProxy.jsp

amster attribute: ssoProxyUrl

Account Provisioning

The following properties are available under the Account Provisioning tab:

Use IDM as Registration Service

Whether to use IDM as an external registration service to complete registration for new users. You must configure and enable the IDM Provisioning service to use this option. See "IDM Provisioning".

AM passes IDM these parameters:

  • clientToken: Signed, encrypted JWT of the OAuth 2.0 authentication state.

  • returnParams: Encoded URL parameters, required to be returned to AM to resume authentication after registration in IDM is complete.

Default: False

amster attribute: enableRegistrationService

Create account if it does not exist

When enabled, AM creates an account for the user if the user profile does not exist. If the Prompt for password setting and activation code attribute is enabled, AM prompts the user for a password and activation code before creating the account.

Important

When configured to create new accounts, the SMTP settings must also be valid. As part of account creation, the authentication module sends the resource owner an email with an account activation code. To send the mail, AM uses the SMTP settings you provide in the module configuration.

When disabled, a user without a profile may still log into AM if the Ignore Profile attribute is set in the authentication service of the realm, or if the account is mapped to an anonymous account.

Valid values are:

  • true

  • false

Default: true

amster attribute: createAccount

Account Provider

Specifies the name of the class that implements the account provider.

Default: org.forgerock.openam.authentication.modules.common.mapping.DefaultAccountProvider

amster attribute: accountProviderClass

Account Mapper

Specifies the name of the class that implements the attribute mapping for the account search.

Default: org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper|*|wechat-

amster attribute: accountMapperClass

Account Mapper Configuration

Specifies the attribute configuration used to map the account of the user authenticated in the social provider to the local data store in AM. Valid values take the form provider-attr=local-attr.

Default: openid=uid

amster attribute: accountMapperConfiguration

Attribute Mapper

Specifies the list of fully qualified class names for implementations that map attributes from the social provider to AM profile attributes.

You can provide a custom attribute mapper. A custom attribute mapper must implement the org.forgerock.openam.authentication.modules.common.mapping.AttributeMapper interface.

Provided implementations are:

  • org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper

  • org.forgerock.openam.authentication.modules.oidc.JwtAttributeMapper - can only be used when using the openid scope

Tip

You can provide string constructor parameters by appending pipe-separated (|) values.

For example, the org.forgerock.openam.authentication.modules.oidc.JwtAttributeMapper class can take two constructor parameters: a comma-separated list of attributes, and a prefix to apply to their values. Specify these as follows:

org.forgerock.openam.authentication.modules.oidc.JwtAttributeMapper|*|wechat-

Default: org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper|*|wechat-

amster attribute: attributeMappingClasses

Attribute Mapper Configuration

Specifies a map of social provider user account attributes to local user profile attributes with values in the form provider-attr=local-attr.

Default:

openid=uid
nickname=sn
nickname=cn
nickname=givenName

amster attribute: attributeMapperConfiguration

Prompt for password setting and activation code

When enabled, the user must set a password before AM creates an account dynamically. An activation code is also sent to the user's email address. Both the password and the code are required before the account is created.

Valid values are:

  • true

  • false

Default: false

amster attribute: promptPasswordFlag

Map to anonymous user

When enabled, maps the social provider authenticated user to a specified anonymous user. If the Create account if it does not exist property is enabled, AM creates an account for the authenticated user instead of mapping the account to an anonymous user.

Valid values are:

  • true

  • false

Default: false

amster attribute: mapToAnonymousUser

Anonymous User

Specifies an anonymous user that exists in the current realm. The Map to anonymous user property maps authorized users without a profile to this anonyomus user, if enabled.

Default: anonymous

amster attribute: anonymousUserName

Save attributes in the session

When enabled, saves the values of attributes specified in the Attribute Mapper Configuration property in the AM session.

Valid values are:

  • true

  • false

Default: true

amster attribute: saveAttributesInSession

Email

The following properties are available under the Email tab:

Email attribute in the Response

Specifies the attribute identifying the authenticated user's email address in the response from the profile service in the social provider. This setting is used to send an email message with an activation code for accounts created dynamically.

amster attribute: emailAttribute

Mail Server Gateway implementation class

Specifies the class used by the module to send email. A custom subclass of org.forgerock.openam.authentication.modules.oauth2.EmailGateway class can be provided.

Default: org.forgerock.openam.authentication.modules.oauth2.DefaultEmailGatewayImpl

amster attribute: emailGateway

SMTP host

Specifies the host name of the mail server.

Default: localhost

amster attribute: smtpHost

SMTP port

Specifies the SMTP port number for the mail server.

Default: 25

amster attribute: smtpPort

SMTP User Name

Specifies the username AM uses to authenticate to the mail server.

amster attribute: smtpUsername

SMTP User Password

Specifies the password AM uses to authenticate to the mail server.

amster attribute: smtpPassword

SMTP SSL Enabled

When enabled, connects to the mail server over SSL. AM must be able to trust the SMTP server certificate.

Valid values are:

  • true

  • false

Default: false

amster attribute: smtpSslEnabled

SMTP From address

Specifies the address of the email sender, such as no-reply@example.com.

Default: info@forgerock.com

amster attribute: smtpFromAddress

Windows Desktop SSO Authentication Module Properties

amster service name: WindowsDesktopSsoModule

ssoadm service name: iPlanetAMAuthWindowsDesktopSSOService

Tip

Before configuring the authentication module, create an Active Directory account and a keytab file.

Service Principal

Specifies the Kerberos principal for authentication in the format HTTP/host.domain@DC-DOMAIN-NAME, where host.domain corresponds to the host and domain names of the AM instance and DC-DOMAIN-NAME is the domain name of the Kerberos realm (the FQDN of the Active Directory domain). DC-DOMAIN-NAME can differ from the domain name for AM.

In multi-server deployments, configure host.domain as the load balancer FQDN or IP address in front of the AM instances. For example, HTTP/openamLB.example.com@KERBEROSREALM.INTERNAL.COM.

For more information, see the KB article How do I set up the WDSSO authentication module in AM in a load-balanced environment?.

amster attribute: principalName

ssoadm attribute: iplanet-am-auth-windowsdesktopsso-principal-name

Keytab File Name

Specifies the full path of the keytab file for the Service Principal. You generate the keytab file using the Windows ktpass utility.

amster attribute: keytabFileName

ssoadm attribute: iplanet-am-auth-windowsdesktopsso-keytab-file

Kerberos Realm

Specifies the Kerberos Key Distribution Center realm. For the Windows Kerberos service, this is the domain controller server domain name.

amster attribute: kerberosRealm

ssoadm attribute: iplanet-am-auth-windowsdesktopsso-kerberos-realm

Kerberos Server Name

Specifies the fully qualified domain name of the Kerberos Key Distribution Center server, such as that of the domain controller server.

amster attribute: kerberosServerName

ssoadm attribute: iplanet-am-auth-windowsdesktopsso-kdc

Return Principal with Domain Name

When enabled, AM automatically returns the Kerberos principal with the domain controller's domain name during authentication.

amster attribute: returnPrincipalWithDomainName

ssoadm attribute: iplanet-am-auth-windowsdesktopsso-returnRealm

Authentication Level

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.

amster attribute: authenticationLevel

ssoadm attribute: iplanet-am-auth-windowsdesktopsso-auth-level

Trusted Kerberos realms

List of trusted Kerberos realms for user Kerberos tickets. If realms are configured, then Kerberos tickets are only accepted if the realm part of the user principal name of the user's Kerberos ticket matches a realm from the list.

amster attribute: trustedKerberosRealms

ssoadm attribute: iplanet-am-auth-windowsdesktopsso-kerberos-realms-trusted

isInitiator

Configuration used for the JDK Kerberos LoginModule (Krb5LoginModule), which authenticates users using Kerberos principals. Possible values are true for initiator credentials, and false for acceptor credentials.

Default value: true

amster attribute: kerberosServiceIsinitiator

ssoadm attribute: iplanet-am-auth-windowsdesktopsso-kerberos-isinitiator

Search for the user in the realm

Validates the user against the configured data stores. If the user from the Kerberos token is not found, authentication will fail. If an authentication chain is set, the user is able to authenticate through another module. This search uses the Alias Search Attribute Name from the core realm attributes. See User Profile for more information about this property.

amster attribute: lookupUserInRealm

ssoadm attribute: iplanet-am-auth-windowsdesktopsso-lookupUserInRealm

Authenticating to Windows Desktop SSO Using REST

When authenticating with Windows Desktop SSO, add an Authorization header containing the string Basic , followed by a base64-encoded string of the username, a colon character, and the password. For example, if the credentials demo:Ch4ng31t are base64-encoded, the resulting string is ZGVtbzpDaDRuZzMxdA==.

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=2.0, protocol=1.0" \
--header "X-OpenAM-Username: demo" \
--header "X-OpenAM-Password: Ch4ng31t" \
--header "Authorization: Basic ZGVtbzpDaDRuZzMxdA==" \
'https://openam.example.com:8443/openam/json/realms/root/authenticate'
{
    "tokenId":"AQIC5w...NTcy*",
    "successUrl":"/openam/console",
    "realm":"/"
}
Read a different version of :