Authentication modules in AM/OpenAM

This book provides information on authentication modules in AM/OpenAM, including how to configure and troubleshoot.


How do I understand what the user data store is used for in AM/OpenAM (All versions)?

The purpose of this article is to provide information to help you understand what the user store is used for in AM/OpenAM. The term user store can be used to refer to different data stores in AM/OpenAM. This article also discusses how the identity data store interacts with identities and authentication modules.

Understanding the user store

The term user store can be used to refer to one of the following data stores in AM/OpenAM:

  • Authentication - this data store contains the credentials used for authenticating a user. The location of this data store is determined by the type of Authentication module you are using and how it has been configured. For example, if you are using the LDAP authentication module, the user's credentials will be stored on your LDAP server. This data store is also referred to as the Credential Store. 
  • User profiles - this data store contains user profiles or identity data (attributes) for users who have authenticated to AM/OpenAM. The location of this data store is determined by the data store you have configured for the applicable realm. This data store is also referred to as the Identity Data Store or Identity Repository. You can check what data store has been configured in a realm as follows:
    • AM / OpenAM 13.x console: navigate to: Realms > [Realm Name] > Data Stores.
    • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Data Stores.

When a user wants to access an application protected by AM/OpenAM, they supply credentials (such as user name and password) to log in. These credentials are then validated against the ones held in the Credential store (authentication); if they match, the user successfully authenticates to AM/OpenAM and the user profile is retrieved if an Identity data store is configured.

Note

Although these two user stores are conceptually different, they may in fact refer to the same data store. For example, if you are using the LDAP authentication module and have also configured your LDAP server to be used as the data store, then these user stores will be the same.

How does the identity data store, identities and authentication modules interact?

Component 1 - the identity data store 

The purpose of the identity data store is to provide information about the authenticated user, which allows you to identify users. This identity data store can be any directory server or an LDAP, and can be new or existing. The identity data store is configured on the Data Store page for each realm; this means you can have completely distinct identity data stores for each realm or inherit the top level realm configuration. It is not always necessary to have an identity data store though as the authentication module can authenticate users without one; this is discussed in Component 4 where other credentials are used for authenticating users and the identity data store is used purely to retrieve the user profile. 

In summary, the identity data store allows you to identify your users.

Component 2 - the Identities page (previously the Subjects tab)

The Identities page provides a view of some of your users (first 100 by default). It is a useful way of checking that your connection to the identity data store is working (if you can see your users, you know that you are connected). The Identities page provides basic information about users only. You should use a dedicated tool for managing users such as IDM/OpenIDM or DS/OpenDJ, depending on your use case.

In summary, the Identities page allows you check your connection to the identity data store.

Component 3 - authentication modules and how they relate to the identity data store

When configuring user authentication, you create authentication modules and add these modules to chains. A simple way to identify and authenticate a realm user is to use the default DataStore module in a chain. The DataStore module is whatever identity data store you have configured for that particular realm. The resulting flow when using the DataStore module is:

  1. When the user authenticates, AM/OpenAM validates the credentials entered by the user using the connection details you configured when you created your identity data store.
  2. Once validated, AM/OpenAM obtains the user details from the directory you use as your identity data store to begin building the user's profile. 

This flow explains why the DataStore module configuration is very simple; you configured everything the module needs when you configured the identity data store and added your identities initially. 

In summary, the DataStore authentication module uses the identity data store configured for a particular realm.

Component 4 - using something other than the realm identity data store for authentication

To attain flexibility and increase security, we need to provide the capability of authenticating users with a variety of credentials. These credentials may or may not reside in your directory of choice. Further, how users are authenticated depends on a number of things, including the resource you are protecting, its criticality and security requirements, the device they authenticate with, etc. The authentication method / credentials could be Active Directory® (AD) / DS/OpenDJ or other LDAP, SAML, OIDC, RSA token, etc. Therefore, we have decoupled the identity data store (where we identify users, provide the user profile) from the authentication method(s) themselves. This allows us to create and use a variety of other authentication modules, which offers greater flexibility when creating authentication chains, offering different authentication methods, 2FA, etc. 

However (and very importantly), any additional authentication methods need to be associated with the identity created in the identity data store via a common attribute so we know who we are dealing with, that is, if a user authenticates against DS/OpenDJ, but your identity data store is AD, we need to be able to identify the authenticated user within the identity data store. To achieve this, we map the identifier of the module to the cn/uid/sAMAccountName/[whatever you use to identify your user in AD] of the identity data store. Without this mapping, we can authenticate users but cannot identity them in the identity data store and therefore cannot retrieve their user profile.

Confusion arises when creating authentication modules. It is possible (and often correct) to re-create a connection to the directory used to populate the identity data store. A common scenario, for example, is you are using a lower level realm to limit the users who can access a resource to a particular geographical location. Provided you use exactly the same unique identifier in your newly created authentication module as you used in your identity data store, it will still work. Therefore, when the user authenticates, AM/OpenAM takes the unique identifier used to authenticate, searches the identity data store with it, finds the appropriate user and is happy. This is a supported approach and entirely appropriate, particularly if you are using numerous modules. However, keep in mind for troubleshooting, if AM/OpenAM cannot find the user using the unique identifier, the authentication will fail. 

In summary, you map your authentication module back to a user with a common attribute to allow AM/OpenAM to identify the identity and retrieve the user profile. 

See Also

FAQ: Users in AM/OpenAM

How do I configure AM/OpenAM (All versions) to use the sAMAccountName for authentication?

User has no profile in this organization message received when user authenticates in AM/OpenAM (All versions)

AM/OpenAM (All versions) fails to connect to the user data store when anonymous access is disabled in DS/OpenDJ

How do I make a whole user data store read-only to users in AM/OpenAM (All versions)?

Data stores in AM/OpenAM

Release Notes › Before You Install › Data Store Requirements

Authentication and Single Sign-On Guide › Implementing Authentication › Configuring Authentication Modules

Setup and Maintenance Guide › Setting Up Identity Data Stores

Setup and Maintenance Guide › Setting Up Identity Data Stores › About the Identity Repository Plugin

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

N/A


How do I authenticate to another chain but keep the same session token in AM (All versions)?

The purpose of this article is to provide information on authenticating to another chain (using ForceAuth) while keeping the same session tokenId in AM. Keeping the same session tokenId is often a requirement for audit purposes. Session upgrade using the ForceAuth parameter is only supported for CTS-based sessions (called Stateful in AM 5.x).

Overview

The following example demonstrates a user authenticating to one chain and then doing a session upgrade to a second chain with the same session token. When the session is upgraded, the existing session token is checked to ensure it is valid and any existing session properties are copied across to the second chain. The authentication parameters required to achieve this are: sessionUpgradeSSOTokenId and ForceAuth.

Note

You must ensure you use the correct case for the ForceAuth parameter; forceAuth=true will be ignored and the session token will change after you authenticate to the second chain.

This example uses a very simple authentication setup purely for demonstration purposes. You can adapt this to your environment as needed ensuring you use the same authentication parameters to retain the session token.

Example setup

  • Create two authentication modules: DataStore and LDAP.
  • Set different Authentication Levels for each module, for example:
    • DataStore: 10
    • LDAP: 20
  • Create authChain1 and add the DataStore module as required.
  • Create authChain2 and add the LDAP module as required.

Authenticating to another chain with same session token

Note

Please observe the following when constructing REST calls:

  • Make the REST call to the actual AM server URL (not lb).
  • Change the name of the iPlanetDirectoryPro header to the name of your actual session cookie.
  • Set this session cookie header to the token returned when you authenticated.
  • Ensure the Accept-API-Version header contains valid resource versions (AM 5 and later).

See How do I avoid common issues with REST calls in AM/OpenAM (All versions)? for further information.

You can authenticate as follows:

  1. Authenticate to the first chain, for example:
    $ curl -X POST -H "X-OpenAM-Username: demo" -H "X-OpenAM-Password: changeit" -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.1" http://host1.example.com:8080/openam/json/realms/root/authenticate?authIndexType=service&authIndexValue=authChain1
    Example response:
    {
        "tokenId": "35huKgysok9Sg2Uk-MqX6agOArM.*AAJTSQACMDEAAlNLABxJb29DZnN1R1VZU0xNRWd6NDdrTndHVzZzQ1U9AAR0eXBlAANDVFMAAlMxAAA.*",
        "successUrl": "/openam/console",
        "realm": "/"
    }
    
  2. Perform a session upgrade (ForceAuth) to the second chain:
    $ curl -X POST  -H "X-OpenAM-Username: demo" -H "X-OpenAM-Password: changeit" -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.1" http://host1.example.com:8080/openam/json/realms/root/authenticate?authIndexType=service&authIndexValue=authChain2&sessionUpgradeSSOTokenId=35huK...AAA.*&ForceAuth=true
    Example response:
    {
        "tokenId": "35huKgysok9Sg2Uk-MqX6agOArM.*AAJTSQACMDEAAlNLABxJb29DZnN1R1VZU0xNRWd6NDdrTndHVzZzQ1U9AAR0eXBlAANDVFMAAlMxAAA.*",
        "successUrl": "/openam/console",
        "realm": "/"
    }
    
  3. Observe that the session token has stayed the same in both responses.

See Also

How do I validate session tokens and obtain session details using the REST API in AM (All versions)?

FAQ: Core Token Service (CTS) and session high availability in AM/OpenAM

Best practices for configuring sessions in AM (All versions) to reduce the impact on the CTS store

Authentication and Single Sign-On Guide › Session Upgrade

Authentication and Single Sign-On Guide › Performing Session Upgrade

Authentication and Single Sign-On Guide › Using Authentication

Related Training

N/A

Related Issue Tracker IDs

OPENAM-11015 (ForceAuth session upgrade does not work)


How do I update Authentication modules in an authentication chain in AM/OpenAM (All versions) using ssoadm?

The purpose of this article is to provide information on updating Authentication modules in an authentication chain in AM/OpenAM using ssoadm. This also includes removing existing Authentication modules. This article assumes the authentication chain already exists.

Updating the authentication chain

You can update the Authentication modules in an existing authentication chain using the following ssoadm command:

$ ./ssoadm update-auth-cfg-entr -u [adminID] -f [passwordfile] -e [realmname] -m [authchain] -a "[module1|criteria|options]" "[module2|criteria|options]"

replacing [adminID], [passwordfile], [realmname], [authchain] and "[module|criteria|options]" with appropriate values. You should include "[module|criteria|options]" for each module you want included in the chain (in the required order) where:

  • module is the module name, for example, LDAP.
  • criteria is REQUIRED, OPTIONAL, SUFFICIENT or REQUISITE.
  • options are any additional options and values you want to specify. This is optional and each option=value should be separated with a space.

Alternatively, you can use a data file to specify these values using the ssoadm -D option instead of -a. 

Note

The update-auth-cfg-entr command overwrites the Authentication modules included in the chain with the ones specified. Therefore you must always specify all the modules you want included. For example, if you already have two modules in a chain and want to add a new one, you must specify all three. Similarly, if you already have three modules in a chain and want to remove one, you must specify the two remaining ones.

Example - add a module

To add a second module (LDAP) to the testChain that already includes the DataStore module (no options):

$ ./ssoadm update-auth-cfg-entr -u amadmin -f pwd.txt -e / -m testChain -a "DataStore|REQUIRED" "LDAP|SUFFICIENT"

Example - update modules

To update these modules in the testChain to share credentials by adding options and to make the LDAP module REQUIRED:

$ ./ssoadm update-auth-cfg-entr -u amadmin -f pwd.txt -e / -m testChain -a "DataStore|REQUIRED|iplanet-am-auth-store-shared-state-enabled=true" "LDAP|REQUIRED| iplanet-am-auth-shared-state-enabled=true iplanet-am-auth-shared-state-behavior-pattern=useFirstPass"

Example - remove a module

To remove the LDAP module (and the shared credential options) from the testChain:

$ ./ssoadm update-auth-cfg-entr -u amadmin -f pwd.txt -e / -m testChain -a "DataStore|REQUIRED"

Example - using a data file

To add two new modules (LDAP and HOTP) to the testChain that replace the DataStore module (no options):

  1. Create a data file (called DATA_FILE to match the next command) with the following contents:
    LDAP|REQUIRED
    HOTP|REQUIRED
    
  2. Run the following command:
    $ ./ssoadm update-auth-cfg-entr -u amadmin -f pwd.txt -e / -m testChain -D DATA_FILE
Note

There is a known issue in OpenAM 13.0, which prevents added options being seen in the console and further options being added: OPENAM-8727 (Module options in authentication chain are not displayed or editable). This is a UI issue only; the options are stored correctly in the configuration store and can be viewed using the ssoadm get-auth-cfg-entr command. This is fixed in OpenAM 13.5.

See Also

FAQ: Installing and using ssoadm in AM/OpenAM

Reference › Command Line Tools › ssoadm

Authentication and Single Sign-On Guide › Implementing Authentication › Configuring Authentication Chains

Related Training

N/A

Related Issue Tracker IDs

OPENAM-8727 (Module options in authentication chain are not displayed or editable)


How do I configure the Post Authentication plugin in AM/OpenAM (All versions)?

The purpose of this article is to provide information on configuring the post authentication plugin in AM/OpenAM. You can configure the post authentication plugin for a realm or a service (authentication chain) depending on who the plugin should apply to.

Configuring the post authentication plugin (realm)

You can configure the post authentication plugin for all users in a specific realm using either the console or ssoadm:

  • AM / OpenAM 13.x console: navigate to: Realms > [Realm Name] > Authentication > Settings > Post Authentication Processing > Authentication Post Processing Classes and add the required post authentication class.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Authentication > All Core Settings > Post Authentication Processing > Authentication Post Processing Classes and add the required post authentication class.
  • ssoadm: enter the following command:
    $ ./ssoadm set-svc-attrs -s iPlanetAMAuthService -e [realmname] -u [adminID] -f [passwordfile] -a iplanet-am-auth-post-login-process-class=[postAuthClass]
    
    replacing [realmname], [adminID], [passwordfile] and [postAuthClass] with appropriate values.

See How do I add multiple attributes with a single ssoadm command in AM/OpenAM (All versions)? for further information on adding multiple classes. 

Configuring the post authentication plugin (authentication chain)

You can configure the post authentication plugin for a specific authentication chain using either the console or ssoadm:

  • AM / OpenAM 13.x console: navigate to: Realms > [Realm Name] > Authentication > Chains > [Chain Name] > Settings > Post Authentication Processing Class and add the required post authentication class.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Authentication > Authentication Chaining > [Authentication Chain] > Post Authentication Processing Class and add the required post authentication class.
  • ssoadm: enter the following command:
    $ ./ssoadm update-auth-cfg-props -e [realmname] -m [authchain] -u [adminID] -f [passwordfile] -a iplanet-am-auth-post-login-process-class=[postAuthClass]
    
    replacing [realmname], [authchain], [adminID], [passwordfile] and [postAuthClass] with appropriate values.

See How do I add multiple attributes with a single ssoadm command in AM/OpenAM (All versions)? for further information on adding multiple classes.  

See Also

How do I add multiple attributes with a single ssoadm command in AM/OpenAM (All versions)?

Authentication and Single Sign-On Guide › Implementing Authentication › Configuring Authentication Chains

Authentication and Single Sign-On Guide › Implementing Authentication › Implementing Post-Authentication Plugins

Authentication and Single Sign-On Guide › Customizing Authentication › Creating a Post Authentication Plugin

Reference › Command Line Tools › ssoadm

Related Training

ForgeRock Access Management Customization and APIs (AM-421)

Related Issue Tracker IDs

N/A


How do I register or re-register a custom authentication module in AM 5.5.x and 6.x?

The purpose of this article is to provide assistance on registering a custom authentication module in AM. If you make changes to the custom module code, you will need to re-register it to apply the changes.

Overview

As of AM 5.5, modules are loaded using a service loader. As a result, the process to register custom authentication modules has been simplified and involves deploying a JAR file instead of using ssoadm. See Release Notes › Important Changes to Existing Functionality for further information. If you make changes to your custom module once it has been registered, you must re-register it to apply your changes.

See the following sections for further details:

Preparing the JAR file

You must ensure you have a valid JAR file before registering or re-registering your module.

The JAR file must contain the following files, which are needed to register the module with AM:

META-INF/services/org.forgerock.openam.plugins.AmPlugin
org/forgerock/openam/examples/SampleAuthPlugin.java

Where:

  • The org.forgerock.openam.plugins.AmPlugin file holds the fully qualified class name of the AmPlugin that registers the custom implementations. The org.forgerock.openam.plugins.AmPlugin file must not be renamed or placed in a different directoryFor example:
    $ cat META-INF/services/org.forgerock.openam.plugins.AmPlugin
    ..........
    
    # This file is used by the service loader to find implementations of org.forgerock.openam.plugins.AmPlugin
    # In this case, we are providing our new plugin, which will then be picked up and executed by OpenAM.
    # For more information on service loading, see the javadoc for the ServiceLoader class.
    
    org.forgerock.openam.examples.SampleAuthPlugin
    
    
    The above file would find the org.forgerock.openam.examples.SampleAuthPlugin file and execute the file.
  • The SampleAuthPlugin Java class implements the org.forgerock.openam.plugins.AmPlugin interface. This class registers the SampleAuth implementation and the amAuthSampleAuth.xml service schema. See Authentication and Single Sign-On Guide › About the Sample Authentication Module for further information on the usage of the sample files.  

You can build the JAR file using Apache Maven™ as detailed in How do I customize authentication modules using source code in AM/OpenAM (All versions)? and Authentication and Single Sign-On Guide › Creating a Custom Authentication Module.

Registering a custom module

You can register a custom module as follows:

  1. Copy the custom authentication module JAR file to the /path/to/tomcat/webapps/openam/WEB-INF/lib directory, for example:
    $ cp custom-module-X.X.X.jar /path/to/tomcat/webapps/openam/WEB-INF/lib
    
  2. Restart the web application container in which AM runs to complete the registration of the custom module.  

See Authentication and Single Sign-On Guide › Installing the Module for further information.

Re-registering a custom module

If you make any changes to your custom module, you must re-register the module with AM as follows:

  1. Take a backup of your configuration prior to making any changes in case you need to revert: How do I make a backup of configuration data in AM/OpenAM (All versions)? 
  2. Delete the module sub-entry in the configuration store using ldapdelete, for example: 
    $ ./ldapdelete --hostname host1.example.com --port 50389 --bindDN "cn=Directory Manager" --bindPassword password "ou=[plugin_name],ou=plugins,ou=default,ou=GlobalConfig,ou=1.0,ou=amPluginService,ou=services,[configuration_suffix]"
    
    # DELETE operation successful for DN ou=[plugin_name],ou=plugins,ou=default,ou=GlobalConfig,ou=1.0,ou=amPluginService,ou=services,[configuration_suffix]
    
    Replacing [plugin_name] and [configuration_suffix] as follows:
    • [plugin_name] - for example, org.forgerock.openam.examples.SampleAuthPlugin. You can find this in your META-INF/services/org.forgerock.openam.plugins.AmPlugin file, for example: 
      $ cat META-INF/services/org.forgerock.openam.plugins.AmPlugin
      ..........
      
      # This file is used by the service loader to find implementations of org.forgerock.openam.plugins.AmPlugin
      # In this case, we are providing our new plugin, which will then be picked up and executed by OpenAM.
      # For more information on service loading, see the javadoc for the ServiceLoader class.
      
      org.forgerock.openam.examples.SampleAuthPlugin
    • [configuration_suffix] - for example, dc=openam,dc=forgerock,dc=org
  3. Delete the old JAR file in the /path/to/tomcat/webapps/openam/WEB-INF/lib directory and replace with the updated JAR file.
  4. Restart the web application container in which AM runs to apply the changes.

See Also

How do I import Service configurations in AM (All versions) using Amster when there are custom modules?

API Javadoc › Interface AmPlugin

ServiceLoader API specification

Related Training

N/A

Related Issue Tracker IDs

OPENAM-12347 (AmPlugin Custom Authentication Module cannot be uninstalled or reregistered)


Account lockout fails when an authentication chain contains a custom module in AM/OpenAM (All versions)

The purpose of this article is to provide assistance if user accounts are not locked in accordance with the account lockout settings in AM/OpenAM when you have an authentication chain that contains one or more custom modules.

Symptoms

User account is not locked after a repeated number of failed login attempts.

The following message is shown when the user subsequently attempts to log in with invalid credentials. 

{ "code": 401, "reason": "Unauthorized", "message": "Authentication Failed" }

Expected messages

When account lockout is working in an authentication chain, you would expect to see the following message after x number of failed logins: 

{ "code": 401, "reason": "Unauthorized", "message": "Authentication Failed Warning: You will be locked out after 1 more failure(s)." }

And then the following message after another attempt:

{ "code": 401, "reason": "Unauthorized", "message": "Your account has been locked." }

Recent Changes

Added a custom authentication module to the chain.

Causes

The account lockout functionality works based on invalid password exceptions rather than invalid login exceptions. This means all login modules must throw an InvalidPasswordException instead of an AuthLoginException to trigger account lockout.

Solution

This issue can be resolved by updating your custom authentication modules to throw an InvalidPasswordException. For example, by changing:

throw new AuthLoginException(<parameters>);

To:

throw new InvalidPasswordException(<parameters>);

See Also

How do I enable account lockout in AM/OpenAM (All versions)?

How do I unlock a user's account using the REST API in AM/OpenAM (All versions)?

How do I lock a user's account if they do not authenticate to AM/OpenAM (All versions) within a specific period of time?

Authentication and Single Sign-On Guide › The Sample Authentication Logic

Authentication and Single Sign-On Guide › Implementing Account Lockout

Authentication and Single Sign-On Guide › Account Lockout

Related Training

N/A

Related Issue Tracker IDs

OPENAM-14192 (Addition needed for sample custom auth code to mention account lockout)

OPENAM-6362 (HOTP and OATH auth-modules do not set 'failureUserID' when throwing InvalidPasswordException, this breaks OpenAM account lockout)


Some ssoadm commands fail with Service URL not found:session error when module based authentication is disabled in AM/OpenAM (All versions)

The purpose of this article is to provide assistance if you encounter a "Service URL not found:session" error or a "java.lang.NullPointerException" error when running some ssoadm commands in AM/OpenAM. You may also encounter a 401 Unauthorized: Access denied response when running the ssoadm start-recording command. These issues occur when module based authentication is disabled.

Symptoms

When module based authentication is disabled in the top level realm, many ssoadm functions will fail with one of the following errors in response to the ssoadm command:

Service URL not found:session
java.lang.NullPointerException
com.sun.identity.cli.CLIException: Message:New Generic Exception

The following response is shown when you run the ssoadm start-recording command:

{"code":401,"reason":"Unauthorized","message":"Access Denied"}

An error similar to the following is shown in the CoreSystem debug log when the ssoadm command fails:

amXMLHandler:12/07/2015 02:52:34:165 PM EST: Thread[WebContainer : 7,5,main]
ERROR: Exception during LoginIndex
com.sun.identity.authentication.spi.AuthLoginException: Module Based Authentication is not allowed.
   at com.sun.identity.authentication.service.AMLoginContext.executeLogin(AMLoginContext.java:297)
   at com.sun.identity.authentication.server.AuthContextLocal.login(AuthContextLocal.java:544)
   at com.sun.identity.authentication.server.AuthContextLocal.login(AuthContextLocal.java:419)
...

ssoadm commands that do not include the realm parameter are successful, whereas ones that include the realm parameter, such as agent related ones (show-agent, list-agents, create-agent and update-agent) fail.

Recent Changes

Disabled module based authentication (sunEnableModuleBasedAuth=false) in the top level realm. Module based authentication can be checked via the console or ssoadm:

  • AM / OpenAM 13.x console: navigate to: Realms > Top Level Realm / > Authentication > Settings > Security and check if Module Based Authentication is enabled.
  • Pre-OpenAM 13 console: navigate to: Access Control > (Top Level Realm) > Authentication > All Core Settings > Security and check if the Module Based Authentication option is enabled.
  • ssoadm: enter the following command and check the value of the sunEnableModuleBasedAuth property:
    $ ./ssoadm get-attr-defs -s iPlanetAMAuthService -t organization -u [adminID] -f [passwordfile]
    replacing [adminID] and [passwordfile] with appropriate values.

Causes

The ssoadm command fails during the authentication process, as successful admin authentication relies on module based authentication being enabled (sunEnableModuleBasedAuth=true) in AM/OpenAM. Admin privileges are needed for some ssoadm commands.

Solution

You can re-enable module based authentication if this is viable. If you do re-enable module based authentication, you can secure your environment by defining policies to have a condition that enforces authentication against a given authentication module/chain. In this scenario, the agent will ensure that the user is authenticated by the configured authentication module/chain; this means it would not be possible to access the application using different authentication mechanisms.

Alternatively, this issue can be resolved as follows depending on your version of AM/OpenAM:

AM 5 and later; OpenAM 12.0.1 and later

This issue is fixed in OpenAM 12.0.1 onwards and two additional JVM options have been introduced to identify which authentication service/module should be used for authenticating as an administrator.

Add the following JVM options to the ssoadm or ssoadm.bat script and set appropriately:

  • org.forgerock.openam.ssoadm.auth.indexType - specify the type of authentication mechanism that should be used for authenticating the administrator in the top level realm; this can be one of the following values:
    • module_instance (this value can only be used if module based authentication is enabled)
    • service
    • user
    • role
    • level
    • composite_advice
    • resource
  • org.forgerock.openam.ssoadm.auth.indexName - enter the name of the actual authentication mechanism that should be used. This must be consistent with the indexType specified. For example, if you set indexType to module_instance, indexName would be the name of the actual authentication module to use, such as LDAP. 

If these JVM options are missing, authentication will continue to rely on module based authentication being enabled.

Caution

Do not use module_instance as your IndexType if module based authentication is disabled as ssoadm will still fail. For a default configuration, you can set the following JVM options to provide an alternative authentication mechanism: org.forgerock.openam.ssoadm.auth.indexType=service | org.forgerock.openam.ssoadm.auth.indexName=ldapService 

OpenAM 12.0.0

This issue can be resolved by upgrading to OpenAM 12.0.1 and later, and setting the JVM options as described above; you can download this from BackStage.

Alternatively, you can use the console to make changes as a workaround.

See Also

Authentication and Single Sign-On Guide › Reference › Security

Related Training

N/A

Related Issue Tracker IDs

OPENAM-816 (ssoadm authentication depends on the sunEnableModuleBasedAuth=true)

OPENAM-5898 (ssoadm get-realm-svc-attrs fails with Nullpointer when module based authentication is disabled)

OPENAM-6211 (Document new JVM properties for ssoadm)


Creating authentication module via ssoadm causes Not found error in AM 5, 5.1.x and OpenAM 13.0, 13.5

The purpose of this article is to provide assistance if you create an authentication module via ssoadm and get a "Not found error" when trying to open the new module in the AM/OpenAM console.

Symptoms

When you create an authentication module via ssoadm with a command such as the following, where the module name and type match:

$ ./ssoadm create-auth-instance -u amadmin -f pwd.txt -e / -m HOTP -t HOTP 

the module appears to be created but when you try to open it in the console, you will see the following message:

Not found error.

Please note: 

  • You can create authentication modules with the same module name and type via the console. 
  • This issue affects all authentication modules, including custom ones.
  • This issue also affects authentication modules that were created in earlier versions of AM/OpenAM, where the module name and type match. If you upgrade to an affected version and then try to open an authentication module that was created in an earlier version of OpenAM with the same module name and type, you will see the "Not found error."

Recent Changes

Upgraded to, or installed AM 5 or 5.1.x.

Upgraded to, or installed OpenAM 13.0 or 13.5.

Causes

The sub-configuration is not created if the name of the authentication module is the same as the auth type when the module is created using ssoadm.

Solution

This issue can be resolved by upgrading to AM 5.5 and later, or OpenAM 13.5.1; you can download this from BackStage.

Workaround

You can workaround this issue by using a different module name and type when creating the authentication module via ssoadm. For example:

$ ./ssoadm create-auth-instance -u amadmin -f pwd.txt -e / -m HOTPmodule -t HOTP

Alternatively, you can create the authentication module via the console, which allows you to use the same module name and type if required.

See Also

N/A

Related Training

N/A

Related Issue Tracker IDs

OPENAM-9156 ('Not Found' error in UI when opening a custom auth module created with ssoadm with the name the same as type)

OPENAM-8574 (The OpenAM CREST processing chain doesn't contain a RuntimeException handler)


Active Directory


How do I configure AM/OpenAM (All versions) to use the sAMAccountName for authentication?

The purpose of this article is to provide information on configuring AM/OpenAM to use the sAMAccountName attribute for authentication when you have an Active Directory® user data store. This change allows your users to log in using sAMAccountName as their user ID.

Using sAMAccountName as the user ID

Active Directory does not have a uid attribute, but instead uses sAMAccountName as the equivalent of the uid attribute. This means you need to configure AM/OpenAM to use sAMAccountName as the user ID. This article assumes you are already using the Active Directory authentication module; if not, you should configure it and set the attributes as described below. See Authentication and Single Sign-On Guide › Active Directory Module Properties for further information.

Note

The Search and Naming Attributes specified in your Active Directory authentication module configuration must match your user store configuration, otherwise you will encounter an error. See User has no profile in this organization message received when user authenticates in AM/OpenAM (All versions) for further information. Additionally the Search and Naming Attributes set in the data store must match, otherwise you will see "User Requires Profile to Login" errors.

You can configure AM/OpenAM as follows:

  1. Change the attributes used in the Active Directory data store using either the console, Amster (AM 5 and later) or ssoadm:
    • AM 6 and later console: navigate to: Realms > [Realm Name] > Data Stores > [AD Data Store] and set the following attributes to sAMAccountName:
      User Configuration tab > LDAP Users Search Attribute
      Authentication Configuration tab > Authentication Naming Attribute
    • AM 5.x / OpenAM 13.x console: navigate to: Realms > [Realm Name] > Data Stores > [AD Data Store] and set the following attributes to sAMAccountName:
      LDAP Users Search Attribute
      Authentication Naming Attribute
    • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Data Stores > [AD Data Store] and set the above attributes to sAMAccountName.
    • Amster: follow the steps in How do I update property values in AM (All versions) using Amster? with these values:
      • Entity: ActiveDirectory
      • Properties: sun-idrepo-ldapv3-config-users-search-attribute, sun-idrepo-ldapv3-config-auth-naming-attr
    • ssoadm: enter the following command:
      $ ./ssoadm update-datastore -e [realmname] -m [datastorename] -u [adminID] -f [passwordfile] -a sun-idrepo-ldapv3-config-users-search-attribute=sAMAccountName sun-idrepo-ldapv3-config-auth-naming-attr=sAMAccountName
      replacing [realmname], [datastorename], [adminID] and [passwordfile] with appropriate values.
  2. Change the attributes used in the Active Directory authentication module using either the console, Amster (AM 5 and later) or ssoadm:
    • AM / OpenAM 13.x console: navigate to: Configure > Authentication > Active Directory and set the following attributes to sAMAccountName:
      Attribute Used to Retrieve User Profile
      Attributes Used to Search for a User to be Authenticated
      
    • Pre-OpenAM 13 console: navigate to: Configuration > Authentication > Active Directory and set the above attributes to sAMAccountName:
    • Amster: follow the steps in How do I update property values in AM (All versions) using Amster? with these values:
      • Entity: ActiveDirectoryModule
      • Properties: userProfileRetrievalAttribute, userSearchAttributes
    • ssoadm: enter the following command:
      $ ./ssoadm update-auth-instance -e [realmname] -u [adminID] -f [passwordfile] -a iplanet-am-auth-ldap-user-naming-attribute=sAMAccountName iplanet-am-auth-ldap-user-search-attributes=sAMAccountName
      replacing [realmname], [adminID] and [passwordfile] with appropriate values.

See Also

Setup and Maintenance Guide › Active Directory Configuration Properties

How do I understand what the user data store is used for in AM/OpenAM (All versions)?

How do I create a user data store in AM/OpenAM (All versions) using ssoadm?

Data stores in AM/OpenAM

Authentication modules in AM/OpenAM

Configuring and troubleshooting WDSSO in AM/OpenAM

Related Training

N/A

Related Issue Tracker IDs

N/A


Adaptive Risk


How do I set up Adaptive Authentication (Risk Based Authentication) in AM/OpenAM (All versions)?

The purpose of this article is to provide a video demonstration that will help guide you through understanding and configuring the Adaptive Risk authentication module in AM/OpenAM.

Background information

The Adaptive Risk module is designed to assess risk during authentication so that AM/OpenAM can determine whether the user needs to complete further authentication steps.

Some key things to be aware of when configuring the Adaptive Risk module are:

  • The Adaptive Risk module must be included in an authentication chain that includes additional modules before and after it. The module after it is required for when it assesses the risk and returns failure, as the authentication processing is then passed to the next module in the chain.
  • The criteria for the Adaptive Risk module in the chain must always be set to sufficient.
  • If you want to save cookies and profile attributes after successful authentication, you must set up AM/OpenAM to save the data as part of post-authentication processing by editing the authentication chain and adding one of the following classes to the list of post authentication plugins:
    AM 5:         org.forgerock.openam.authentication.modules.adaptive.AdaptivePostAuthenticationPlugin
    Pre-AM 5:     org.forgerock.openam.authentication.modules.adaptive.Adaptive
  • You can use a Known Cookie instead of a Device Cookie. This cookie can either be set outside of AM/OpenAM (from another app or gateway for example) or it can be added by AM/OpenAM after successful authentication. To have AM/OpenAM add it, you must select the Save Cookie Value on Successful Login option and ensure you have added the appropriate class to the list of post authentication plugins as detailed above.
  • If you have set up the Adaptive Risk module to use client IP address and AM/OpenAM is behind a load balancer or proxy, you must configure the load balancer or proxy to send the address by using the X-Forwarded-For header and configure AM/OpenAM to consume and forward the header as necessary. See Installation Guide › Installing and Starting Servers › Handling HTTP Request Headers for further information.
  • If you use the LDAP module with the AM/OpenAM user data store, you cannot use the admin user (called amadmin by default) to test this set up as the admin user will not be found. You should instead use the demo user or another user that you have created.
  • If you use the LDAP module and have changed the attribute used for authentication (Attributes Used to Search for a User to be Authenticated), you should set the Alias Search Attribute Name to the same value. This is a Core authentication module setting; see Authentication and Single Sign-On Guide › Reference › User Profile for further information. You can also set this in the Realm authentication settings. 

Setting up Adaptive Risk Based Authentication

Note

This video demonstration uses OpenAM 10.0.0; although the appearance has changed between OpenAM 10.x and later versions, the principles and processes are still applicable. In AM / OpenAM 13.x, the authentication options under Access Control are now under Realms.

See Also

Authentication and Single Sign-On Guide › Implementing Authentication › Configuring Authentication Chains

Authentication and Single Sign-On Guide › Implementing Authentication › Adaptive Risk Authentication Module

Authentication and Single Sign-On Guide › Implementing Authentication › Implementing Post-Authentication Plugins

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

OPENAM-5598 (Adaptive Risk auth module can not be used in auth chain if the username in sharedstate map does not 'match' the search attribute of the data store)

OPENAM-3607 (Adaptive IP check fails when message level debug enabled)

OPENAM-2097 (Adaptive risk module does not describe which GeoIP client is used and where to obtain the GeoIP database file)


Anonymous Authentication


How do I deactivate the default anonymous user in AM/OpenAM (All versions)?

The purpose of this article is to provide information on deactivating the anonymous user in AM/OpenAM. This user exists by default and is used in conjunction with the Anonymous Authentication module. It is safe to deactivate this user if you do not use this module and this will prevent them logging in to the top level realm.

Deactivating the anonymous user

Note

Please observe the following when constructing REST calls:

  • Make the REST call to the actual AM/OpenAM server URL (not lb).
  • Change the name of the iPlanetDirectoryPro header to the name of your actual session cookie.
  • Set this session cookie header to the token returned when you authenticated.
  • Ensure the Accept-API-Version header contains valid resource versions (AM 5 and later).

See How do I avoid common issues with REST calls in AM/OpenAM (All versions)? for further information.

You can deactivate the anonymous user as follows: 

  1. Deactivate the anonymous user using either the console, REST or ssoadm:
    • AM 6.x console: you cannot use the console to deactivate the anonymous user in AM 6.x due to a known issue: OPENAM-14199 (anonymous user is missing from console as well as amadmin).
    • AM 5.x / OpenAM 13.x console: navigate to: Realms > Top Level Realm / > Subjects > anonymous > User Status and select the Inactive option.
    • Pre-OpenAM 13 console: navigate to: Access Control > (Top Level Realm) > Subjects > anonymous > User Status and select the Inactive option.
    • REST:
      1. Authenticate as an admin user. For example:
        • AM 5 and later:
          $ curl -X POST -H "X-OpenAM-Username: amadmin" -H "X-OpenAM-Password: cangetinam" -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.1" http://host1.example.com:8080/openam/json/realms/root/authenticate
          
        • Pre-AM 5:
          $ curl -X POST -H "X-OpenAM-Username: amadmin" -H "X-OpenAM-Password: cangetinam" -H "Content-Type: application/json" http://host1.example.com:8080/openam/json/authenticate
        Example response:
        { "tokenId": "AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*", "successUrl": "/openam/console", "realm": "/" } 
        
      2. Deactivate the anonymous user using the following curl command:
        $ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-Type: application/json" -H "Accept-API-Version: resource=3.0" -d '{"inetUserStatus":"Inactive"}' http://host1.example.com:8080/openam/json/users/anonymous
    • ssoadm: enter the following command:
      $ ./ssoadm set-identity-attrs -e / -i anonymous -t User -u [adminID] -f [passwordfile] -a inetUserStatus=Inactive
      replacing [adminID] and [passwordfile] with appropriate values; the following message is returned if the command is successful:
      Attribute values of identity, anonymous of type, User in realm, / was modified.
  2. Restart the web application container in which AM/OpenAM runs. 

Checking the anonymous user was successfully deactivated

You can verify that the anonymous user was successfully deactivated using either REST or ssoadm.

REST

Enter the following curl command:

$ curl -X GET -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-Type: application/json" http://host1.example.com:8080/openam/json/users/anonymous

Example response showing the Inactive status:

{"_id":"anonymous","_rev":"-1300605335","username":"anonymous","realm":"/","sunIdentityMSISDNNumber":[],"telephoneNumber":[],"iplanet-am-user-alias-list":[],"mail":[],"roles":[],"givenName":["anonymous"],"dn":["uid=anonymous,ou=people,dc=openam,dc=forgerock,dc=org"],"cn":["anonymous"],"employeeNumber":[],"postalAddress":[],"iplanet-am-user-success-url":[],"universalid":["id=anonymous,ou=user,dc=openam,dc=forgerock,dc=org"],"inetUserStatus":["Inactive"],"sn":["anonymous"],"iplanet-am-user-auth-config":["[Empty]"],"iplanet-am-user-failure-url":[]}

ssoadm

Enter the following ssoadm command: 

$ ./ssoadm get-identity -e / -i anonymous -t User -u [adminID] -f [passwordfile]

replacing [adminID] and [passwordfile] with appropriate values; observe the result, which should be similar to the following:

sunidentitymsisdnnumber=
mail=
sn=anonymous
givenname=anonymous
telephonenumber=
employeenumber=
postaladdress=
cn=anonymous
iplanet-am-user-success-url=
roles=
iplanet-am-user-failure-url=
inetuserstatus=Inactive
dn=uid=anonymous,ou=people,dc=openam,dc=forgerock,dc=org
iplanet-am-user-alias-list=

See Also

FAQ: Users in AM/OpenAM

How does AM/OpenAM (All versions) use anonymous access calls to DS/OpenDJ?

Authentication and Single Sign-On Guide › Anonymous Authentication Module

Related Training

N/A

Related Issue Tracker IDs

OPENAM-14199 (anonymous user is missing from console as well as amadmin)


Certificate Authentication


How do I configure AM/OpenAM (All versions) to check the HTTP header for the user certificate?

The purpose of this article is to provide information on configuring AM/OpenAM to check the HTTP header for the user (X.509) certificate. This setup can be used if you are SSL offloading at a load balancer or reverse proxy in front of AM/OpenAM, the user certificate is passed to AM/OpenAM in the HTTP header (in PEM format) and the Certificate Authentication module is used to authenticate users.

Configuring AM/OpenAM

Note

If you use IG/OpenIG as your reverse proxy, IG/OpenIG will just pass the HTTP header containing the user certificate (providing you have not configured IG/OpenIG to explicitly remove headers as part of a Filter configuration). If however you want IG/OpenIG to retrieve the user certificate and pass it to AM/OpenAM, you will need to configure IG/OpenIG as detailed in How do I configure IG/OpenIG (All versions) to retrieve the user certificate and pass it to AM/OpenAM in the HTTP header?

You can configure the Certificate Authentication module to check the HTTP header for user certificates using either the console or ssoadm:

  • AM / OpenAM 13.x console: navigate to: Realms > [Realm Name] > Authentication > Modules > [Certificate Module] and update the following fields:
    • Trusted Remote Hosts - Add the IP of the host supplying the HTTP header that contains the user certificate. You can add "any" instead of a specific IP to allow any host; however, this option is not as secure. Remove the "none" value.
    • HTTP Header Name for Client Certificate - Enter the HTTP header name for the client certificate that is inserted by the load balancer or reverse proxy. This should be the full PEM encoded certificate, including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- boundary lines. In between these boundary lines, there should be the Base64 encoding output of the DER encoded certificate.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Authentication > Module Instances > [Certificate Module] and update the Trusted Remote Hosts and HTTP Header Name for Client Certificate fields as detailed above.
  • ssoadm: enter the following command:
    $ ./ssoadm set-realm-svc-attrs -s iPlanetAMAuthCertService -e [realmname] -u [adminID] -f [passwordfile] -a iplanet-am-auth-cert-gw-cert-auth-enabled=[hostIP] sunAMHttpParamName=[header]
    
    replacing [realmname], [adminID], [passwordfile], [hostIP] and [header] with appropriate values.
Note

You must restart the web application container in which AM/OpenAM runs to apply these configuration changes. 

See Also

How do I configure IG/OpenIG (All versions) to retrieve the user certificate and pass it to AM/OpenAM in the HTTP header?

Authentication and Single Sign-On Guide › Implementing Authentication › Certificate Authentication Module

Gateway Guide › Understanding OpenIG › Handlers, Filters, and Chains

Related Training

N/A

Related Issue Tracker IDs

OPENAM-5938 (Cert Auth module should not read cert from HTTP request when 'iplanet-am-auth-cert-gw-cert-auth-enabled' is set)


How do I configure IG/OpenIG (All versions) to retrieve the user certificate and pass it to AM/OpenAM in the HTTP header?

The purpose of this article is to provide information on configuring IG/OpenIG to retrieve the user (X.509) certificate from the web container and pass it to AM/OpenAM in the HTTP header. This setup can be used if you are using IG/OpenIG as a reverse proxy for AM/OpenAM and are using the Certificate Authentication module in AM/OpenAM to authenticate users.

Overview

Note

If SSL is terminated by a reverse-proxy or load balancer in front of IG/OpenIG that has been configured to pass on user certificates, IG/OpenIG will pass the HTTP header containing the user certificate (providing IG/OpenIG has not been configured to explicitly remove headers as part of a Filter configuration). Therefore, you will not need to configure IG/OpenIG in this scenario.

You should ensure AM/OpenAM has been configured to check the HTTP header for the user certificate. See How do I configure AM/OpenAM (All versions) to check the HTTP header for the user certificate? for further information.

If you are using IG/OpenIG as the reverse proxy, you can configure IG/OpenIG to retrieve the user certificate from the web container and pass it to AM/OpenAM via the HTTP header. The approach you take depends on version:

  • IG / OpenIG 4.x - as of OpenIG 4.x, there are no additional coding steps required as the certificate(s) contained in client.certificates (certificates is a list that is never null but can be empty) are already in the form required by AM/OpenAM and can just be passed on in a header as is. See Configuration Reference › Client for further information.
  • OpenIG 3.1.x - you can use ClientInfo to retrieve the certificate and then include it in a Filter. See Configuring OpenIG 3.1.x for further information.
  • OpenIG 3.0 - you need to create a custom Filter to achieve this as you cannot access the attributes of the request in this version of OpenIG. See Configuring OpenIG 3.0 for further information.

Web container

You should ensure the web container in which AM/OpenAM and IG/OpenIG are deployed handles user certificates correctly. For example, for Apache Tomcat™, you should set clientAuth to "want" in the server.xml file.

See Gateway Guide › Configuring Deployment Containers for further information on configuring the web container. In particular, Gateway Guide › Configuring Tomcat For HTTPS (Server-Side) for information on getting Tomcat up quickly on an SSL port.

Configuring OpenIG 3.1.x

In OpenIG 3.1.x, you can access the client certificates through exchange.clientInfo.certificates (certificates is a list, never null but can be empty) so the example code is a little simpler than in OpenIG 3.0:

import java.io.IOException;
import java.security.cert.CertificateEncodingException;
import java.security.cert.X509Certificate;
import javax.xml.bind.DatatypeConverter;
import org.forgerock.openig.filter.GenericFilter;
import org.forgerock.openig.handler.Handler;
import org.forgerock.openig.handler.HandlerException;
import org.forgerock.openig.http.Exchange;
import org.forgerock.openig.log.LogTimer;

public class CertFilter3x extends GenericFilter {

    @Override
    public void filter(Exchange exchange, Handler next) throws HandlerException, IOException {

        LogTimer timer = logger.getTimer().start();
        for (X509Certificate cert : exchange.clientInfo.getCertificates()) {
            // Add certificate to headers here
            exchange.request.getHeaders().add("CertHeaderName", getPemCert(cert));
        }
        next.handle(exchange);
        timer.stop();
    }

    private String getPemCert(X509Certificate x509cert) {

        StringBuilder pemCert = new StringBuilder();
        try {
            pemCert.append("-----BEGIN CERTIFICATE-----");
            pemCert.append(DatatypeConverter.printBase64Binary(x509cert.getEncoded()));
            pemCert.append("-----END CERTIFICATE-----");
        } catch (CertificateEncodingException e) {
            // Handle exception
        }

        return pemCert.toString();
    }
}

Configuring OpenIG 3.0

In OpenIG 3.0, you need to create a custom Filter to access the user certificate. An example to get you started is:

import java.io.IOException;
import java.security.cert.CertificateEncodingException;
import java.security.cert.X509Certificate;
import javax.servlet.http.HttpServletRequest;
import javax.xml.bind.DatatypeConverter;
import org.forgerock.openig.filter.GenericFilter;
import org.forgerock.openig.handler.Handler;
import org.forgerock.openig.handler.HandlerException;
import org.forgerock.openig.http.Exchange;
import org.forgerock.openig.log.LogTimer;

public class CertFilter21 extends GenericFilter {

    @Override
    public void filter(Exchange exchange, Handler next) throws HandlerException, IOException {

        LogTimer timer = logger.getTimer().start();
        HttpServletRequest request = (HttpServletRequest)exchange.get("javax.servlet.http.HttpServletRequest");
        if (request != null) {
            X509Certificate[] certs = (X509Certificate[])request.getAttribute("javax.servlet.request.X509Certificate");
            if (certs != null) {
                for (X509Certificate cert : certs) {
                    exchange.request.getHeaders().add("CertHeaderName", getPemCert(cert));
                }
            }
        }
        next.handle(exchange);
        timer.stop();
    }
    
    private String getPemCert(X509Certificate x509cert) {

        StringBuilder pemCert = new StringBuilder();
        try {
            pemCert.append("-----BEGIN CERTIFICATE-----");
            pemCert.append(DatatypeConverter.printBase64Binary(x509cert.getEncoded()));
            pemCert.append("-----END CERTIFICATE-----");
        } catch (CertificateEncodingException e) {
            // Handle exception
        }

        return pemCert.toString();
    }
}

See Also

How do I configure AM/OpenAM (All versions) to check the HTTP header for the user certificate?

Authentication and Single Sign-On Guide › Implementing Authentication › Certificate Authentication Module

Gateway Guide › Extending the ForgeRock Identity Gateway › Key Extension Points

Related Training

N/A

Related Issue Tracker IDs

N/A


Data Store and LDAP


How do I configure AM/OpenAM (All versions) to ensure user profile lookups work after changing the LDAP authentication attribute?

The purpose of this article is to provide a guide to configuring AM/OpenAM to allow seamless changes of the LDAP authentication attribute whilst protecting the LDAP search attribute. By default, user profile lookup will fail if the LDAP authentication attribute is changed without reauthenticating.

Configuring AM/OpenAM

In summary, you can achieve this configuration by separating out Authentication from the User Profile with separate LDAP and DataStore authentication modules.

The following process assumes:

  • you have created a separate DS/OpenDJ User Data Store on localhost:1389, cn=Directory Manager. In this example, the sample data was populated with 200 users with domain suffix dc=example,dc=com
  • you are using uid as the Universal Id.
  • mail is the element you wish to log in with and change.

To configure AM/OpenAM:

  1. Navigate to the authentication module options in your realm:
    • AM / OpenAM 13.x console: Realms > [Realm Name] > Authentication > Modules and click Add Module.
    • Pre-OpenAM 13 console: Access Control > [Realm Name] > Authentication > Module Instances and click New.
  2. Enter a name for the new module and select type LDAP.
  3. Re-select the new LDAP module if you are using a pre-OpenAM 13.
  4. Configure the new LDAP module with the LDAP connection details and the following options:
    • Set the Attribute Used to Retrieve User Profile field to the Universal Id field (in this example uid).
    • Add the username/email attribute you wish to be changeable to the Attributes Used to Search for a User to be Authenticated field (in this example mail).
    • Deselect the Enabled option against the Return UserDN to DataStore field (this is enabled by default). This means that the text of the username is returned as the authentication principal rather than the whole dn (user.0 rather than cn=user.0,ou=people,dc=example,dc=com) 

  1. Optionally, add the new LDAP module to the default authentication chain as the only or the first module:
    • AM / OpenAM 13.x console: navigate to: Realms > [Realm Name] > Authentication > Chains > ldapService and replace the required DataStore module with your new LDAP module.
    • Pre-OpenAM 13 console: Access Control > [Realm Name] > Authentication > Authentication Chaining > ldapService and replace the required DataStore module with your new LDAP module.
  2. Delete the embedded data store:
    • AM / OpenAM 13.x console: navigate to: Realms > [Realm Name] > Data Stores, select embedded and click Delete.
    • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Data Stores, select embedded and click Delete.
  3. Add a new data store with a type that matches the LDAP Server you are configuring against (for example, DS/OpenDJ):
    • AM 6 and later console: navigate to: Realms > [Realm Name] > Data Stores, click Add Data Store, enter a name and select the type.
    • AM 5.x / OpenAM 13.x console: navigate to: Realms > [Realm Name] > Data Stores, click New, enter a name and select the type.
    • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Data Stores, click New, enter a name and select the type.
  4. ​Complete the following details for the new Data Store:
    • Configure the LDAP connection details and dn suffixes (Server Settings tab in AM 6 and later).
    • Set the LDAP Users Search Attribute field (User Configuration tab in AM 6 and later) to the Universal Id field (in this example uid).
    • Enable Load Schema or select the Load schema when saved option before saving your changes.

  1. Check the new data store is recognized by navigating to the Identities page (Subjects tab) and checking it contains the expected users from the new data store.
  2. Log into the realm as a user (in this example, user.199@maildomain.net).
  3. Change the email address for this user (in this example, changed to user.199.new@maildomain.net) and click Save.
  4. Log into the console on your realm as user.199@maildomain.net, for example:
    • AM 5 and later:
      http://host1.example.com:8080/openam/XUI/?realm=/test#login
      
    • Pre-AM 5:
      http://host1.example.com:8080/openam/XUI/#login/&realm=test
    You will see the user's old email address still.
  5. Call the the /users endpoint for this user, for example:
    • AM 5 and later:
      http://host1.example.com:8080/openam/json/realms/root/realms/test/users/user.199
      
    • Pre-AM 5:
      http://host1.example.com:8080/openam/json/test/users/user.199
    You will see the user attributes returned, including the new email address:
    {"username":"user.199","realm":"/test","uid":["user.199"],"mail":["user.199.new@maildomain.net"], ...

See Also

User has no profile in this organization message received when user authenticates in AM/OpenAM (All versions)

How do I understand what the user data store is used for in AM/OpenAM (All versions)?

How do I create a user data store in AM/OpenAM (All versions) using ssoadm?

Authentication and Single Sign-On Guide › Implementing Authentication › LDAP Authentication Module

Setup and Maintenance Guide › Setting Up Identity Data Stores

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I tune LDAP connection pool settings in AM/OpenAM (All versions) using ssoadm?

The purpose of this article is to provide assistance with tuning LDAP connection pool settings in AM/OpenAM using ssoadm. These connection pool settings apply to your LDAP data stores and LDAP authentication modules.

Tuning LDAP connection pool settings

LDAP data store settings

You can configure the LDAP data store connection pool sizes as follows using ssoadm:

  • LDAP Connection Pool Minimum Size: enter the following command:
    $ ./ssoadm update-datastore -e [realmname] -m [datastorename] -u [adminID] -f [passwordfile] -a sun-idrepo-ldapv3-config-connection_pool_min_size=[size]
    replacing [realmname], [datastorename], [adminID], [passwordfile] and [size] with appropriate values.
  • LDAP Connection Pool Maximum Size: enter the following command:
    $ ./ssoadm update-datastore -e [realmname] -m [datastorename] -u [adminID] -f [passwordfile] -a sun-idrepo-ldapv3-config-connection_pool_max_size=[size]
    replacing [realmname], [datastorename], [adminID], [passwordfile] and [size] with appropriate values.

LDAP authentication modules 

You can configure the LDAP authentication module connection pool sizes (Default LDAP Connection Pool Size) as follows using ssoadm:

$ ./ssoadm set-attr-defs -s iPlanetAMAuthService -t global -u [adminID] -f [passwordfile] -a iplanet-am-auth-ldap-connection-pool-default-size=[minSize:maxSize]

replacing [adminID], [passwordfile] and [minSize:maxSize] with appropriate values.

For example, if you wanted to tune this to the recommended production settings: 10 (minimum connection pool size) and 65 (maximum connection pool size), you would use an ssoadm command such as:

$ ./ssoadm set-attr-defs -s iPlanetAMAuthService -t global -u amadmin -f pwd.txt -a iplanet-am-auth-ldap-connection-pool-default-size=10:65

See Also

How do I understand what the user data store is used for in AM/OpenAM (All versions)?

FAQ: Installing and using ssoadm in AM/OpenAM

Setup and Maintenance Guide › Maintaining an Instance › Tuning LDAP Data Store Settings

Setup and Maintenance Guide › Maintaining an Instance › Tuning LDAP Authentication Module Settings

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I change what characters are permitted in user names in AM/OpenAM (All versions) for authentication purposes?

The purpose of this article is to provide information on changing the characters that are permitted in user names in AM/OpenAM for authentication purposes. AM/OpenAM checks that the user name does not contain special characters when authenticating.

Overview

The list of special characters are defined using different properties depending on your version as follows:

  • AM / OpenAM 13.5.x - the list of special characters is defined in the usernameInvalidChars property, which has a default value of *|(|)|&|!
  • OpenAM 13.0 and earlier - the list of special characters is defined in the iplanet-am-admin-console-invalid-chars property, which has a default value of *|(|)|&|! 
Warning

Special characters (& and * in particular) are also used in different contexts, such as building filters to look up values in LDAP or for privilege evaluation. Removing the default characters from these properties may lead to unexpected behavior (in particular, it is likely to break any modules related to LDAP) and is therefore not recommended. If you choose to remove these default characters, you should test your changes in a pre-production environment first.

Changing invalid characters (AM / OpenAM 13.5.x)

The list of special characters is defined in the usernameInvalidChars property, which has a default value of *|(|)|&|!, where the invalid characters are separated by |.

You can change this list of characters using either ssoadm or Amster (AM 5 and later); you can do this globally or in a specific realm, where realm level takes precedence over the global level:

  • ssoadm - Global: 
    1. Run the following command to create a data file (called DATA_FILE to match the next command), which is populated with the current sunIdRepoAttributeValidator property values to ensure you don't lose any existing changes:
      $ ./ssoadm get-attr-defs -s sunIdentityRepositoryService -t Organization -u [adminID] -f [passwordfile] | grep sunIdRepoAttributeValidator > DATA_FILE
      
      replacing [adminID] and [passwordfile] with appropriate values.
    2. Update the data file you just created by amending the sunIdRepoAttributeValidator=usernameInvalidChars property value. For example, if you want to allow ! in user names, you would change it to:
      sunIdRepoAttributeValidator=usernameInvalidChars=*|(|)|&
    3. Run the following command to update the sunIdRepoAttributeValidator property values:
      $ ./ssoadm set-attr-defs -s sunIdentityRepositoryService -t Organization -u [adminID] -f [passwordfile] -D DATA_FILE
      replacing [adminID] and [passwordfile] with appropriate values.
    4. Restart the web application container in which AM/OpenAM runs to apply these configuration changes.
  • ssoadm - Realm:
    1. Run the following command to create a data file (called DATA_FILE to match the next command), which is populated with the current sunIdRepoAttributeValidator property values to ensure you don't lose any existing changes:
      $ ./ssoadm get-realm-svc-attrs -s sunIdentityRepositoryService -e [realmname] -u [adminID] -f [passwordfile] | grep sunIdRepoAttributeValidator > DATA_FILE
      
      replacing [realmname], [adminID] and [passwordfile] with appropriate values.
    2. Update the data file you just created by amending the sunIdRepoAttributeValidator=usernameInvalidChars property value. For example, if you want to allow ! in user names, you would change it to:
      sunIdRepoAttributeValidator=usernameInvalidChars=*|(|)|&
    3. Run the following command to update the sunIdRepoAttributeValidator property values:
      $ ./ssoadm set-realm-svc-attrs -s sunIdentityRepositoryService -e [realmname] -u [adminID] -f [passwordfile] -D DATA_FILE
      replacing [realmname], [adminID] and [passwordfile] with appropriate values.
Note

When changing this list of characters using ssoadm in OpenAM 13.5.x, AM 5 or AM 5.1, you may encounter an "Exception in thread "SystemTimer" java.lang.Error: java.lang.ExceptionInInitializerError" response. This error can be safely ignored since the operation performed by ssoadm still completes successfully. See java.lang.ExceptionInInitializerError when using ssoadm commands in AM 5, 5.1 and OpenAM 13, 13.5, 13.5.1 for further information.

Changing invalid characters (OpenAM 13.0 and earlier)

The list of special characters is defined in the iplanet-am-admin-console-invalid-chars property, which has a default value of *|(|)|&|! 

For the LDAP and DataStore authentication modules, the list of special characters is also defined in the iplanet-am-auth-ldap-invalid-chars property, which has the same default value. 

Note

You cannot leave either of these properties blank to remove all invalid characters; however, you can disable user name validation as detailed in the Disabling user name validation section below.

iplanet-am-admin-console-invalid-chars property

You can change what characters are invalid in user names using ssoadm (they cannot be changed in the console):

  • Global - enter the following command to change this property globally:
    $ ./ssoadm set-attr-defs -s iPlanetAMAdminConsoleService -t Organization -u [adminID] -f [passwordfile] -a 'iplanet-am-admin-console-invalid-chars=[chars]'
    replacing [adminID], [passwordfile] and [chars] with appropriate values, where [chars] equals the characters that are invalid, separated by |. For example, *|(|)|&|!|$ if you want to add $ to the default list of invalid characters. 
  • Relam - enter the following command to change this property in a specific realm:
    $ ./ssoadm set-realm-svc-attrs -s iPlanetAMAdminConsoleService -e [realmname] -u [adminID] -f [passwordfile] -a 'iplanet-am-admin-console-invalid-chars=[chars]'
    replacing [realmname], [adminID], [passwordfile] and [chars] with appropriate values, where [chars] equals the characters that are invalid, separated by |.
Note

You may need to add the iPlanetAMAdminConsoleService service if it is not assigned to the realm. You can do this by replacing set-realm-svc-attrs in the above ssoadm command with add-svc-realm.

iplanet-am-auth-ldap-invalid-chars property

You should also change this property for the LDAP and DataStore authentication modules to match the value you specified for the iplanet-am-admin-console-invalid-chars property.

You can change this using ssoadm (it cannot be changed in the console):

  • Global - enter the following command to change this property for all LDAP and DataStore authentication modules:
    $ ./ssoadm set-attr-defs -s iPlanetAMAuthLDAPService -t Organization -u [adminID] -f [passwordfile] -a 'iplanet-am-auth-ldap-invalid-chars=[chars]'
    replacing [adminID], [passwordfile] and [chars] with appropriate values, where [chars] equals the characters that are invalid, separated by |.
  • Module - enter the following command to change this property in a specific authentication module:
    $ ./ssoadm update-auth-instance -m [modulename] -e [realmname] -u [adminID] -f [passwordfile] -a 'iplanet-am-auth-ldap-invalid-chars=[chars]'
    replacing [modulename], [realmname], [adminID], [passwordfile] and [chars] with appropriate values, where [chars] equals the characters that are invalid, separated by |.​

Disabling and re-enabling user name validation (OpenAM 13.0 and earlier)

Caution

Although you can disable user name validation completely, it is not recommended and you should test your changes in a pre-production environment first.

You can disable user name validation completely, if required, using ssoadm (it cannot be changed in the console).

Enter the following command:

$ ./ssoadm set-attr-defs -s iPlanetAMAdminConsoleService -t Organization -u [adminID] -f [passwordfile] -a iplanet-am-admin-console-user-password-validation-class=

replacing [adminID] and [passwordfile] with appropriate values. 

Re-enable user name validation

You can re-enable user name validation using ssoadm (it cannot be changed in the console). This will restore user name validation to its default value.

Enter the following command:

$ ./ssoadm set-attr-defs -s iPlanetAMAdminConsoleService -t Organization -u [adminID] -f [passwordfile] -a iplanet-am-admin-console-user-password-validation-class=com.sun.identity.common.AMUserPasswordValidationPlugin

replacing [adminID] and [passwordfile] with appropriate values. 

See Also

Authentication fails in AM/OpenAM (All versions) when the user name contains special characters

How do I change the data store minimum password length in AM/OpenAM (All versions)?

Related Training

N/A

Related Issue Tracker IDs

OPENAM-5034 (Legacy password pages unable to handle special characters in username)

OPENAM-3561 (Special characters are incorrectly handled when using LDAP auth module)

OPENAM-3522 (Special LDAP characters in the data store's naming attribute are not escaped)

OPENAM-776 (Character "\" in UID not processed correctly, two differend UIDs stored in DS entery.)


Known Issues


Authentication fails in AM/OpenAM (All versions) when the user name contains special characters

The purpose of this article is to provide assistance when authentication fails in AM/OpenAM because the user name contains special characters. You will see errors such as: "Detected invalid chars" or "User Name validation Failed".

Symptoms

A user can be created in DS/OpenDJ with & in their user name, but when they try to authenticate to an application protected by AM/OpenAM, authentication fails with the following error in the IdRepo debug log:

amProfile_ldap:10/01/2014 11:51:36:600 AM BST: Thread[http--182.127.17.56-8080-113,5,main]
ERROR: AMUserPasswordValidationPlugin.validateUserID() : Detected invalid chars ...

amProfile_ldap:10/01/2014 11:51:36:600 AM BST: Thread[http--182.127.17.56-8080-113,5,main]
ERROR: AMUserPasswordValidationPlugin.validateUserID() : User Name validation Failed:&

An exception similar to the following is shown in the Authentication debug log (when debug level is set to Message):

Exception : 
com.sun.identity.authentication.spi.AuthLoginException: a1234567! contains invalid characters : & 
at com.sun.identity.authentication.spi.AMLoginModule.wrapProcess(AMLoginModule.java:1008) 
at com.sun.identity.authentication.spi.AMLoginModule.login(AMLoginModule.java:1105) 
at sun.reflect.GeneratedMethodAccessor19.invoke(Unknown Source) 
at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)

amLoginModule:15/01/2015 10:57:05:526 AM BST: Thread[ajp-/205.132.14.197:11009-4,5,main] 
User Name validation Faileda1234567! contains invalid characters : ! 
amAuthLDAP:15/01/2015 10:57:05:526 AM BST: Thread[ajp-/205.132.14.197:11009-4,5,main] 
Invalid Characters detected 
amLoginModule:15/01/2015 10:57:05:526 AM BST: Thread[ajp-/205.132.14.197:11009-4,5,main] 
SETTING Failure Module name.... :LDAP 
amAuth:15/01/2015 10:57:05:526 AM BST: Thread[ajp-/205.132.14.197:11009-4,5,main] 
Module name is .. LDAP 
amAuth:15/01/2015 10:57:05:526 AM BST: Thread[ajp-/205.132.14.197:11009-4,5,main] 
failureModuleSet is : [LDAP] 
amJAAS:15/01/2015 10:57:05:526 AM BST: Thread[ajp-/205.132.14.197:11009-4,5,main] 
Method login LoginModuleControlFlag: requisite failure. 
amLoginModule:15/01/2015 10:57:05:526 AM BST: Thread[ajp-/205.132.14.197:11009-4,5,main] 
ABORT return.... false 
amJAAS:15/01/2015 10:57:05:526 AM BST: Thread[ajp-/205.132.14.197:11009-4,5,main] 
abort success 
amLoginModule:15/01/2015 10:57:05:526 AM BST: Thread[ajp-/205.132.14.197:11009-4,5,main] 
ABORT return.... false 
amJAAS:15/01/2015 10:57:05:526 AM BST: Thread[ajp-/205.132.14.197:11009-4,5,main] 
abort success 
amLoginModule:15/01/2015 10:57:05:526 AM BST: Thread[ajp-/205.132.14.197:11009-4,5,main] 
ABORT return.... false 
amJAAS:15/01/2015 10:57:05:526 AM BST: Thread[ajp-/205.132.14.197:11009-4,5,main] 
abort ignored 
amAuth:15/01/2015 10:57:05:526 AM BST: Thread[ajp-/205.132.14.197:11009-4,5,main] 
LOGINFAILED Error.... 
amAuth:15/01/2015 10:57:05:526 AM BST: Thread[ajp-/205.132.14.197:11009-4,5,main]

Recent Changes

Created a user with a user name that contains special characters. By default, these special characters are one of the following: * ( ) & ! 

Causes

This is expected behavior. AM/OpenAM checks that the user name does not contain special characters when authenticating; the list of special characters is defined in the usernameInvalidChars property (AM and OpenAM 13.5.x) or the iplanet-am-admin-console-invalid-chars property (pre-OpenAM 13.5), which has a default value of *|(|)|&|!

For the LDAP and DataStore authentication modules, the list of special characters can also be defined in the iplanet-am-auth-ldap-invalid-chars property, which has the same default value.

Solution

This issue can be resolved by replacing the special characters in user names with alternative characters that are permitted.

Alternatively, you can change the usernameInvalidChars property (AM and OpenAM 13.5.x) or the iplanet-am-admin-console-invalid-chars property (pre-OpenAM 13.5) to remove the character that you specifically want to include in user names. You may also want to update the iplanet-am-auth-ldap-invalid-chars property for the LDAP and DataStore authentication modules.

See How do I change what characters are permitted in user names in AM/OpenAM (All versions) for authentication purposes? for further information on changing these properties.

Warning

Special characters (& in particular) are also used in different contexts, such as building filters to look up values or for delegation evaluation. Modifying these properties may lead to unexpected behavior and is therefore not recommended. If you choose to change these properties, you should test your changes in a pre-production environment first.

See Also

How do I change what characters are permitted in user names in AM/OpenAM (All versions) for authentication purposes?

Related Training

N/A

Related Issue Tracker IDs

OPENAM-10421 (Unable to authenticate to XUI when username contains special characters)

OPENAM-10135 (Classic UI customizations not found due to incorrect defaultOrg format)

OPENAM-5034 (Legacy password pages unable to handle special characters in username)

OPENAM-3561 (Special characters are incorrectly handled when using LDAP auth module)

OPENAM-3522 (Special LDAP characters in the data store's naming attribute are not escaped)


AM/OpenAM (All versions) fails to connect to the user data store when anonymous access is disabled in DS/OpenDJ

The purpose of this article is to provide assistance if you experience connectivity failures between AM/OpenAM and the user data store (Identity Repository). Common errors logged include "Connection factory became offline" error and data store module fails with "ldap errorcode=91". This issue will only affect you if you are using DS/OpenDJ for your user data store and anonymous access is disabled for that DS/OpenDJ instance.

Symptoms

Users cannot authenticate to AM/OpenAM protected applications and you cannot see your users on the Identities page (previously the Subjects tab) in the console.

An error similar to the following is shown in the IdRepo log when this happens:

LDAPUtils:12/06/2015:03:46:31:049 PM CST: Thread[SystemTimerPool,5,main]
**********************************************
LDAPUtils:12/06/2015:03:46:11:048 PM CST: Thread[SystemTimerPool,5,main]
ERROR: Connection factory became offline: AuthenticatedConnectionFactory(HeartBeatConnectionFactory(LDAPConnectionFactory(host1.example.com/192.168.1.8:1636)), SimpleBindRequest(name=uid=openam-admin,ou=sysaccounts,dc=example,dc=com, authentication=simple, controls=[]))
org.forgerock.opendj.ldap.ConnectionException: Connect Error: Connection refused
     at org.forgerock.opendj.ldap.ErrorResultException.newErrorResult(ErrorResultException.java:163)
     at org.forgerock.opendj.ldap.ErrorResultException.newErrorResult(ErrorResultException.java:125)
     at com.forgerock.opendj.ldap.LDAPConnectionFactoryImpl$CompletionHandlerAdapter.adaptConnectionException(LDAPConnectionFactoryImpl.java:183)
     at com.forgerock.opendj.ldap.LDAPConnectionFactoryImpl$CompletionHandlerAdapter.failed(LDAPConn
...
Caused by: java.net.ConnectException: Connection refused
     at sun.nio.ch.SocketChannelImpl.checkConnect(Native Method)
     at sun.nio.ch.SocketChannelImpl.finishConnect(SocketChannelImpl.java:735)
     at org.glassfish.grizzly.nio.transport.TCPNIOConnectorHandler.onConnectedAsync(TCPNIOConnectorHandler.java:206)

One of the following errors is shown in the Authentication log, depending on which authentication module you are using:

  • LDAP authentication module:
    amAuthLDAP:12/06/2015 03:46:26:919 PM CST: Thread[http-bio-8080-exec-57,5,main]
    WARNING: Search for User error: 
    org.forgerock.opendj.ldap.ConnectionException: Connect Error: No operational connection factories available
        at org.forgerock.opendj.ldap.ErrorResultException.newErrorResult(ErrorResultException.java:210)
    ...
    Caused by: org.forgerock.opendj.ldap.ConnectionException: Server Connection Closed: Heartbeat failed
        at org.forgerock.opendj.ldap.ErrorResultException.newErrorResult(ErrorResultException.java:210)
    ...
    Caused by: org.forgerock.opendj.ldap.ErrorResultException: Unwilling to Perform: Rejecting the requested operation  because the connection has not been authenticated
        at org.forgerock.opendj.ldap.ErrorResultException.newErrorResult(ErrorResultException.java:232)
    
  • Data Store authentication module:
    amAuth:12/06/2015 03:28:39:704 PM BST: Thread[http-bio-18080-exec-2,5,main]
    Exception : 
    com.sun.identity.authentication.spi.AuthLoginException: Authentication Failed
    Plug-in org.forgerock.openam.idrepo.ldap.DJLDAPv3Repo encountered a ldap exception.  ldap errorcode=91
            at com.sun.identity.authentication.modules.datastore.DataStore.process(DataStore.java:165)
            at com.sun.identity.authentication.spi.AMLoginModule.wrapProcess(AMLoginModule.java:1023)
            at com.sun.identity.authentication.spi.AMLoginModule.login(AMLoginModule.java:1197)
    ...
    Caused by: Message:Plug-in org.forgerock.openam.idrepo.ldap.DJLDAPv3Repo encountered a ldap exception.  ldap errorcode=91
    
            at org.forgerock.openam.idrepo.ldap.DJLDAPv3Repo.newIdRepoException(DJLDAPv3Repo.java:2478)
            at org.forgerock.openam.idrepo.ldap.DJLDAPv3Repo.handleErrorResult(DJLDAPv3Repo.java:2451)
            at org.forgerock.openam.idrepo.ldap.DJLDAPv3Repo.getDN(DJLDAPv3Repo.java:2316)
            at org.forgerock.openam.idrepo.ldap.DJLDAPv3Repo.findDNForAuth(DJLDAPv3Repo.java:2266)
    

Correspondingly, the DS/OpenDJ access log shows a CONNECT and DISCONNECT without a SEARCH occurring:

[12/Jun/2015:15:46:31 +0100] CONNECT conn=907 from=127.0.0.1:35590 to=127.0.0.1:20389 protocol=LDAP 
[12/Jun/2015:15:46:31 +0100] UNBIND REQ conn=907 op=2 msgID=3 
[12/Jun/2015:15:46:31 +0100] DISCONNECT conn=907 reason="Client Unbind"  

Recent Changes

Disabled anonymous access in DS/OpenDJ using the following command:

$ ./dsconfig --hostname server.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password set-global-configuration-prop --set reject-unauthenticated-requests:true --trustAll --no-prompt

Causes

Completely disabling anonymous access in DS/OpenDJ prevents the SEARCH request from succeeding if AM/OpenAM uses the heartbeat mechanism (which it does by default) and causes connections from AM/OpenAM to fail. 

See How does AM/OpenAM (All versions) use anonymous access calls to DS/OpenDJ? for further information.

Solution

This issue can be resolved by allowing anonymous access in DS/OpenDJ and then using Access Control Instruction (ACI) to ALLOW anonymous binds for the heartbeat search but disallow other anonymous searches. See How do I prevent anonymous access in DS/OpenDJ (All versions)? for further information.

  • You can use the following command to allow anonymous access:
    $ ./dsconfig --hostname ds1.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password set-global-configuration-prop --set reject-unauthenticated-requests:false --trustAll --no-prompt
    
  • You should construct an ACI that allows anonymous binds for the heartbeat search, but only allows access to the root DSE; the following is an example SEARCH request AM/OpenAM normally sends for the heartbeat:
    SEARCH REQ conn=6 op=2468 msgID=2469 base="" scope=baseObject filter="(objectClass=*)" attrs="1.1"
    
  • You can reproduce the heartbeat request using an ldapsearch such as the following:
    $ ./ldapsearch --port 50389 --bindDN "cn=Directory Manager" --bindPassword password --baseDN "" --searchScope base "objectClass=*" "1.1"
    

Alternatively, you can disable heartbeats in AM/OpenAM, although this approach is not recommended as it degrades failover handling. You can disable heartbeats in the data store as follows; you must disable heartbeats for data stores in all affected realms:

  • AM / OpenAM 13.x console: navigate to: Realms > [Realm Name] > Data Stores > [Data Store Name] > LDAP Connection Heartbeat Interval and enter 0.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Data Stores > [Data Store Name] > LDAP Connection Heartbeat Interval and enter 0.
  • ssoadm: enter the following command:
    $ ./ssoadm update-datastore -e [realmname] -m [datastorename] -u [adminID] -f [passwordfile] -a openam-idrepo-ldapv3-heartbeat-interval=0
    replacing [realmname], [datastorename], [adminID] and [passwordfile] with appropriate values.
  • Amster: follow the steps in How do I update property values in AM (All versions) using Amster?with these values:
    • Entity: OpenDJ
    • Property: openam-idrepo-ldapv3-heartbeat-interval
Caution

If you choose to disable heartbeats rather than using access controls, you should test this in your pre-production environment first to ensure there are no unwanted side effects.

See Also

How do I prevent anonymous access in DS/OpenDJ (All versions)?

How does AM/OpenAM (All versions) use anonymous access calls to DS/OpenDJ?

Data stores in AM/OpenAM

Setup and Maintenance Guide › Setting Up Identity Data Stores

Related Training

N/A

Related Issue Tracker IDs

OPENAM-3498 (IdRepo connection pool fails if anonymous access is disabled)


User has no profile in this organization message received when user authenticates in AM/OpenAM (All versions)

The purpose of this article is to provide assistance if you receive a "User has no profile in this organization" or "Profile not found" error when a user authenticates in AM/OpenAM. This issue may affect you if you use either an LDAP or Active Directory® authentication module.

Symptoms

The following message is shown when the user successfully authenticates to AM/OpenAM:

User has no profile in this organization

An error similar to the following is shown in the Authentication log:

amAuth:04/08/2015 14:17:45:076 PM UTC: Thread[http-apr-7077-exec-53,5,main]
ERROR: Profile not found

Recent Changes

Implemented an LDAP or Active Directory authentication module.

Made configuration changes to your Authentication modules or user store.

Moved a user to a different Organizational Unit (OU) in Active Directory.

Deleted and then re-added a user in Active Directory. 

Causes

AM/OpenAM cannot find the user and associated user profile in the user store once the user has authenticated. This can be caused by one of the following:

  • Misconfiguration of the authentication module and/or user store - this is likely to be the cause if the error appeared after implementing an authentication module or making configuration changes to an existing authentication module or user store.
  • Authentication module and user store have conflicting attributes - this is likely to be the cause if the error appeared after setting iplanet-am-auth-ldap-return-user-dn=true in your authentication module. Example conflicting attributes are: 
    iplanet-am-auth-ldap-return-user-dn=true
    sun-idrepo-ldapv3-config-users-search-attribute=uid
    iplanet-am-auth-alias-attr-name=uid
  • Caching - this is likely to be the cause if the error appeared after moving or deleting/re-adding a user in Active Directory.
Note

This error only occurs if the profile is set to required in the core authentication service. You can change this if you do not rely on user profile information for authentication by navigating to: Realms > [Realm Name] > Authentication > Settings > User Profile > User Profile and selecting Ignore in AM / OpenAM 13.x. In pre-OpenAM 13, you should navigate to: Access Control > [Realm Name] > Authentication > All Core Settings > User Profile and select Ignore.

Solution

The solution depends on the cause.

Misconfiguration of the authentication module and/or user store

You should check your Authentication module and user store configuration is correct. In particular, you should check the following specific properties:

  • Search and Naming Attributes - The Search and Naming Attributes specified in your LDAP or Active Directory authentication module configuration must match your user store configuration, otherwise you will see this error. A common cause is changing AM/OpenAM to use a different search attribute without updating your authentication module to use the alternate search attribute.
  • Search Scope - The Search Scope determines what level to search at for a matching user profile in the user store. This should be set to SUBTREE, which searches the base DN and all levels below as this ensures it will find the user profile assuming it exists. Other settings are OBJECT (only searches the Base DN) and ONELEVEL (only searches the single level below, but not the Base DN). 
Note

AM/OpenAM will search all user stores for a matching user profile. If you have multiple user stores, it is recommended that you use different naming attributes for each user store as AM/OpenAM merges user attributes if multiple user stores contain the same naming attribute=value combination. If you update naming attributes in a user store, you will need to make corresponding changes to the relevant authentication module.

You can check the Search and Naming attributes in the user store using the console or ssoadm:

  • AM / OpenAM 13.x console: navigate to: Realms > [Realm Name] > Data Stores > [Data Store].
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Data Stores > [Data Store].
  • ssoadm: enter the following command:
    $ ./ssoadm show-datastore -e [realmname] -m [datastorename] -u [adminID] -f [passwordfile]
    replacing [realmname], [datastorename], [adminID] and [passwordfile] with appropriate values.

The values you are looking for are: LDAP Users Search Attribute (sun-idrepo-ldapv3-config-users-search-attribute) and Authentication Naming Attribute (sun-idrepo-ldapv3-config-auth-naming-attr). You can use the update-datastore ssoadm command to change these properties if needed.

You can check the Search and Naming attributes, and the Search Scope in the LDAP or Active Directory authentication module using the console or ssoadm:

  • AM / OpenAM 13.5 console: navigate to: Configure > Authentication > LDAP or Active Directory.
  • Pre-OpenAM 13.5 console: navigate to: Configuration > Authentication > LDAP or Active Directory.
  • ssoadm: enter the following command:
    $ ./ssoadm get-attr-defs -s [servicename] -t Organization -u [adminID] -f [passwordfile]
    replacing [servicename], [adminID] and [passwordfile] with appropriate values, where [servicename] is iPlanetAMAuthLDAPService (LDAP) or sunAMAuthADService (Active Directory).

The values you are looking for are: Attributes Used to Retrieve User Profile (iplanet-am-auth-ldap-user-naming-attribute), Attributes Used to Search for a User to be Authenticated (iplanet-am-auth-ldap-user-search-attributes) and Search Scope (iplanet-am-auth-ldap-search-scope). You can use the set-attr-defs ssoadm command to change these properties if needed.

Note

You can also check your LDAP server access logs to see exactly how AM/OpenAM searches the entries in the user store upon successful authentication. You can then enable How do I enable Message level debugging in AM/OpenAM (All versions) debug files? in AM/OpenAM and check the IdRepo debug log to see what AM/OpenAM is searching for and compare these searches. 

Authentication module and user store have conflicting attributes

The DN is returned when the iplanet-am-auth-ldap-return-user-dn property is set to true in your authentication module, which means the value of the RDN is used to search the user profile.

You can resolve this behavior using the console or ssoadm:

  • AM / OpenAM 13.x console: navigate to: Realms > [Realm Name] > Authentication > Modules > LDAP or Active Directory and disable Return User DN to DataStore.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Authentication > Module Instances > LDAP or Active Directory > Return User DN to DataStore and deselect the Enabled option.
  • ssoadm: enter the following command:
    $ ./ssoadm update-auth-instance -e [realmname] -m [modulename] -u [adminID] -f [passwordfile] -a iplanet-am-auth-ldap-return-user-dn=false
    replacing [realmname], [modulename], [adminID] and [passwordfile] with appropriate values.

Caching

You should check your caching settings to make sure caching is correctly enabled. In particular, this error can occur if persistent search is incorrectly configured, which means your changes are not being picked up.

Within the Active Directory authentication module configuration, you should check the following specific settings:

  • DN Cache Enabled (sun-idrepo-ldapv3-dncache-enabled) - this should be enabled if Active Directory allows move/rename operations (Mod DN) and AM/OpenAM uses persistent searches to obtain notification of such updates. This is disabled by default.
  • Persistent Search Scope (sun-idrepo-ldapv3-config-psearch-scope) - this must be changed as SCOPE_SUB is the default, but you should not use SCOPE_SUB for Active Directory as this causes performance issues.

You can use the console navigation instruction and/or ssoadm commands detailed above for Active Directory to check these settings.

See Setup and Maintenance Guide › Tuning CachingFAQ: Caching in AM/OpenAM and Authentication and Single Sign-On Guide › Active Directory Authentication Module for further information.

See Also

How do I understand what the user data store is used for in AM/OpenAM (All versions)?

Setup and Maintenance Guide › Setting Up Identity Data Stores

Authentication and Single Sign-On Guide › Implementing Authentication › LDAP Authentication Module

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

OPENAM-844 (If Directory Server is started after OpenAM, LDAPv3Repo will never recover)


HOTP and OATH


How do I set up the HOTP Authentication module for SMS in AM/OpenAM (All versions)?

The purpose of this article is to provide assistance with setting up the HOTP Authentication module for SMS in AM/OpenAM. The HOTP Authentication module provides a multi-factor authentication method that uses the SMS feature to send a dynamically generated one-time password to the user.

Background information

Custom Attributes

Custom attributes are required in your LDAP directory server for the following purposes:

  • Mobile Phone Number - this attribute will store the user's mobile phone number. The default attribute is telephoneNumber, which already exists in the embedded DS/OpenDJ.
  • Mobile Carrier - this attribute will store the carrier domain associated with the user's mobile phone number. For example, carrierName.

The HOTP service picks up the mobile phone number and carrier from these custom attributes, it then concatenates them into an email address, passes this to the SMS gateway, which sends the email. For example, if you have:

Attribute Name            Attribute values for User1
telephoneNumber           14151234567
carrierName               @vtext.com

The resulting email address used by the SMS gateway for User1 is: 14151234567@vtext.com

If a Mobile Carrier attribute name is not specified, the default @txt.att.net carrier domain is used when forming the email address. Alternatively, you may specify the carrier domain as part of the user's mobile phone number, for example: 14151234567@vtext.com; in which case this will be used as the email address. However, this means the user's mobile phone number may not be useful for other purposes. 

AM/OpenAM doesn't perform any processing on the phone number itself as part of the default SMS gateway implementation (com.sun.identity.authentication.modules.hotp.DefaultSMSGatewayImpl). Therefore, you should ensure you use the correct format for your mobile phone numbers as determined by your carrier/SMS gateway service. Typically this will mean removing any spaces or dashes from mobile phone numbers as these will result in an invalid email address.

Note

If the default SMS gateway implementation is not sufficient for your needs, you can use a different SMS service by writing a custom SMS Gateway implementation to replace the default. This type of customization is outside the scope of ForgeRock support; if you want more tailored advice, consider engaging Professional Services.

Load balancer

If you have set up a site with a load balancer in front of it, you must ensure that the load balancer uses the amlbcookie for stickiness to correctly route user sessions. The AM/OpenAM server sending the HOTP response code must be the same one that the request came from since the HOTP Authentication module stores its current response codes in the server's cache. Failing to route correctly will result in the following error in the browser when the HOTP response code is submitted:

"responseStatus":400,"responseStatusText":"Bad Request"

Authentication chain

The HOTP Auth module must be added as the second required module in the authentication chain. The first required authentication module in the authentication chain must be a module that stores the user's username attribute, such as the Data Store module. For example, your resulting authentication chain would look like this:

DataStore    -> Required
HOTP         -> Required

In AM / OpenAM 13.x, you can utilize session upgrades (the sessionUpgradeSSOTokenId parameter) to allow the HOTP authentication module to work on its own in a separate authentication chain.

When the following flow is used with XUI, the sessionUpgradeSSOTokenId parameter is automatically added to the request:

  1. Configure an authentication chain with one DataStore module (called DS in this example).
  2. Configure an authentication chain with one HOTP module (called OTP in this example).
  3. Authenticate to AM/OpenAM with ?service=DS.
  4. Enter the correct credentials and receive a token.
  5. Authenticate to AM/OpenAM with ?service=OTP.

See Authentication and Single Sign-On Guide › Session Upgrade for further information on session upgrades. 

Configuring the HOTP module for SMS

You can configure the HOTP Authentication module as follows for SMS:

  1. Create the two custom attributes (Mobile Phone Number and Mobile Carrier) in your directory server. If you use the embedded DS/OpenDJ, see Setup and Maintenance Guide › Customizing Profile Attributes for further information; if you use an external DS/OpenDJ, see Administration Guide › Updating Directory Schema for further information.
  2. Update your user profiles to add and populate these custom attributes, for example, using the ldapmodify command. Only users who have a valid mobile phone number will receive a text message containing the one-time passcode.
  3. Update the data store configuration in AM/OpenAM to add the new custom class and custom attributes:
    • AM 6 and later console: navigate to: Realms > [Realm Name] > Data Stores > [Data Store Name] > User Configuration and update the LDAP User Object Class and LDAP User Attributes fields.
    • AM 5.x / OpenAM 13.x console: navigate to: Realms > [Realm Name] > Data Stores > [Data Store Name] and update the LDAP User Object Class and LDAP User Attributes fields.
    • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Data Stores > [Data Store Name] and update the LDAP User Object Class and LDAP User Attributes fields.
  4. Update the HOTP authentication module in your realm for SMS:
    • AM / OpenAM 13.x console: navigate to: Realms > [Realm Name] > Authentication > Modules > HOTP.
    • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Authentication > HOTP.
    In particular, you should ensure the following fields are completed correctly:
    • Mobile Phone Number Attribute Name - enter the name of the custom attribute that contains the user's phone number.
    • Mobile Carrier Attribute Name - enter the name of the custom attribute that contains the mobile carrier associated with the user's phone number. This must not be the carrier domain itself. 
    • All Mail Server fields - you need to configure the SMTP details correctly since the SMS goes through a SMTP service.
    See Authentication and Single Sign-On Guide › HOTP Authentication Module for further information on the fields you can configure for the HOTP module.
  5. Add the HOTP module to an authentication chain; it should be the second required module:
    • AM / OpenAM 13.x console: navigate to: Realms > [Realm Name]  > Authentication > Chains > [Chain Name] and add the HOTP module as a required module.
    • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Authentication > Authentication Chaining > [Chain Name] and add the HOTP module as a required module.

Testing your configuration

You can test this with a free trial from a service such as: TextMagic and AM/OpenAM will send an email to [user's phone number]@textmagic.com, which is then converted to SMS. You will need to create an account with TextMagic before you start.

For testing purposes, you should:

  • Ensure the Mobile Carrier attribute is set to @textmagic.com for the user you want to test with.
  • Specify the user name you have in the Mail Server Authentication Username field as an Allowed Email in TextMagic (Services > Email to SMS).

See How to set up Email to SMS for further information on setting up email for SMS in TextMagic. 

Note

This is a third-party tool that we suggest can be used for testing your configuration but is not supported by ForgeRock.

See Also

FAQ: Upgrading AM/OpenAM

Best practice for migrating Authentication Chains to Trees in AM 6.x

Authentication and Single Sign-On Guide › Introducing Authentication and Single Sign-On › About Multi-Factor Authentication

Authentication and Single Sign-On Guide › Implementing Authentication › Configuring Authentication Chains

Upgrade Guide › About Upgrading › Apply Customization Before Upgrading

Related Training

N/A

Related Issue Tracker IDs

OPENAM-1739 (HOTP module may ignore SMTP settings in the configuration)

OPENAM-1743 (AMSendMail should offer a way to set content type for e-mails)

OPENAM-3872 (HOTP Configuration: openamSMSCarrierAttribute not attached to phone number)

OPENAM-5105 (When Auto Send OTP Code is enabled and HOTP error occures user ends up on an empty page)


Known Issues


OTP based authentication modules prompt user twice when using RADIUS server with AM (All versions) and OpenAM 13.x

The purpose of this article is to provide assistance if end users are prompted twice to enter their OTP when logging in using certain authentication modules (OATH, Authenticator (OATH) and HOTP) in AM/OpenAM. This occurs when you are using the Remote Authentication Dial-In User Service (RADIUS) server service.

Symptoms

The end user is prompted twice to enter their OTP after entering their user name and password credentials.

Entering 0 to the final OTP request allows authentication to continue.

Recent Changes

Implemented the RADIUS server.

Implemented an OTP based module.

Causes

This is a known limitation of the RADIUS server service, which is detailed in RADIUS Server Guide › Troubleshooting the RADIUS Server Service › RADIUS Server Limitations, specifically:

Because RADIUS authentication attempts always start with a user name and password transmitted in an Access-Request packet, the first module in an authentication chain used for RADIUS clients must accept a user name and a password.

Some OpenAM callback types are not applicable to RADIUS clients. For example, a RedirectCallback directs HTTP clients, such as browsers, to HTTP resources to be used for some aspect of authentication. Redirects make no sense to RADIUS clients and cannot be consumed in any meaningful way.

A ConfirmationCallback also presents challenges for RADIUS clients.

As a result, some OpenAM authentication modules cannot be used with RADIUS clients. Before attempting to use an authentication module with RADIUS clients, review the module's callbacks to determine whether the module will support RADIUS clients. You can use the REST API to determine the callbacks for an authentication module as described in Development Guide › Developing with the REST API › Authentication and Logout.

Modules such as OATH, Authenticator (OATH) and HOTP include the ConfirmationCallback for the OTP. For example, in OATH.xml:

<ConfirmationCallback>
    <OptionValues>
        <OptionValue>
            <Value>Submit OTP Code</Value>
         </OptionValue>
    </OptionValues>
</ConfirmationCallback>

The default RADIUS handler class (OpenAMAuthHandler.java) translates this request as Submit=0.

Solution

This issue can be resolved using one of the following options, although such customizations are outside the scope of ForgeRock support:

  • Create a custom authentication module that removes the ConfirmationCallback or merges them, for example, you could merge the password and OTP into a single request.
  • Create a custom RADIUS handler class to translate this request differently to avoid the second prompt.

This change is outside the scope of ForgeRock support; if you want more tailored advice, consider engaging Professional Services

Note

You can customize the module's callbacks file (RADIUS.xml) if you want to change the text shown for the prompts to make them more user friendly. This file is located in the /path/to/tomcat/webapps/openam/config/auth/default directory (or the appropriate default_xx directory if you have localized AM/OpenAM). See Authentication and Single Sign-On Guide › Customizing Authentication › Sample Auth Callbacks for further information.

See Also

RADIUS Server Guide

Authentication and Single Sign-On Guide › Customizing Authentication › Creating a Custom Authentication Module

Related Training

N/A

Related Issue Tracker IDs

OPENAM-8863 (Radius Server response shows "Sign in to OpenAM null" with OATH module)

OPENAM-8704 (Have option to avoid extra "0" radius challenge in Radius Server)

OPENAM-8602 (Configurable Failure Retry attempts for OTP Authentication modules)


Push


How do I set up AM/OpenAM Push Notification Service credentials?

This article explains how to use BackStage to provision credentials for the AM/OpenAM Push Notification Service.

About Push Notifications in AM/OpenAM

OpenAM 13.5 introduced a new passwordless authentication module that uses push notifications. This module relies on a cloud based notification service provided by ForgeRock to AM/OpenAM customers.

The ForgeRock Authenticator (Push) authentication module introduced in OpenAM 13.5 provides authentication using an additional factor, for example a phone running Android™ or iOS® and the ForgeRock Authenticator app.

The ForgeRock Authenticator (Push) authentication module sends messages through an online push notification service called SNS (provided by Amazon AWS™), which delegates push messages to APNS (Apple Push Notification Service) for iOS devices and GCM (Google Cloud Messaging) for Android devices.

ForgeRock customers who have subscribed for the Push Authentication module for AM/OpenAM can provision Push Authentication credentials in BackStage. Only credentials created via BackStage can be used with the official ForgeRock Authenticator App available in the Apple® App Store and the Google® Play Store.

Note

If you are a ForgeRock customer and AM/OpenAM is part of your subscription, but you do not have access to Push Authentication credentials in BackStage, it means that your contract currently does not include the Push Authentication (AM-PUSH-AUTH) module. To add this module to your subscription, please contact your account manager or our sales team at sales@forgerock.com.

Push Notification Service Credentials

The credentials required for the Push Notification Service are the following:

  • Amazon IAM User (“sub-account”)
    • AWS Key ID
    • AWS Key Secret
  • Amazon SNS Endpoints
    • GCM Endpoint (identified by an ARN)
    • APNS Endpoint (identified by an ARN)​
  • Amazon AWS Region

A set of credentials (and endpoints) can be created for an environment. Each subscription can have multiple projects and each project can have multiple environments, but each environment can only have a single set of credentials, see Working with Projects in BackStage and Working with Environments in BackStage.

Push Notification Service credentials cannot be provisioned for your private projects (that is, projects that are not owned by a subscription).

If your subscriptions do not have any projects, a project must be created first. If the selected project does not have any environments, an environment must also be created before credentials can be provisioned.

To create a project, go to https://backstage.forgerock.com/support/projects/. To create an environment, navigate to an existing project’s details page and click “new environment”.

Note

While you can only provision a single set of credentials per environment, there is no limit to the number of environments a project can have.

Warning

BackStage stores each set of credentials created (along with some audit data such as user ID and a timestamp), but it does NOT store the secret key. The secret key must therefore be copied and saved by the user who requested the credentials before they leave or refresh the page.

Provisioning Credentials

To provision Push Notification Service credentials for an environment, go to https://backstage.forgerock.com/support/projects/, select (or create) a project, then scroll down to the Environments section and select (or create) an environment.

On the environment details page, scroll down to the Cloud Services section. Under Cloud Services, you should see a panel entitled OpenAM Push Authentication.

Note

If you selected an environment that belongs to a private project or the subscription doesn't have a valid AM/OpenAM subscription, the OpenAM Push Authentication section will not be available.

If there are not credentials for this environment yet, there will be a button labeled Set up Push Auth Credentials.

Clicking the Set up Push Auth Credentials button opens a modal dialog where you can fill in a description, and then submit your provisioning request by clicking Submit.

Once created, the credentials will appear in a modal dialog.

Warning

You must save the secret key as it will not be stored by BackStage. There is no way to recover a lost or forgotten secret key.

Caution

You must select the correct SNS Client Region (us-east-1).

After the credentials have been provisioned, the controls on environment details page change to allow showing or deleting the credentials.

Credentials can be viewed after they have been created, but the access key secret is no longer there.

Deprovisioning Credentials

Credentials for each environment can be deprovisioned by the user who created the credentials or by any admin member of the subscription that owns the credentials. However, customers can have an unlimited number of projects and environments in BackStage.

Deprovisioning a set of credentials will remove the Amazon IAM user, the policies and SNS endpoints from Amazon, but will keep a record of the credentials in the BackStage database for audit purposes.

BackStage runs an automated task every day to check if there are any Push Auth credentials for customers without a valid subscription. If BackStage finds that a subscription has expired one month ago, it will automatically deprovision any Push Auth credentials that are owned by that subscription.

If the credentials were deprovisioned manually, members of the subscription have the option to provision a new set of credentials for the same environment.

See Also

How do I use my own AWS SNS Push Service with AM (All versions) and OpenAM 13.5?

How do I use Push notifications in AM (All versions) and OpenAM 13.5 with a non-AWS SNS Push Service?

How do I update and recompile the iOS authenticator app with custom branding in AM (All versions)?


How do I use my own AWS SNS Push Service with AM (All versions) and OpenAM 13.5?

The purpose of this article is to provide information on using your own Amazon Web Services™ (AWS™) SNS Push Service with AM/OpenAM.

Introduction

Push Messages are a (relatively) easy way to communicate with a mobile phone. While similar to SMS messages, they are considered to be more secure and NIST (National Institute of Standards and Technology), for example, recommends favoring push messages over traditional SMS messages.

AM/OpenAM provides push authentication as a secure authentication mechanism, which can utilize the TouchID of modern phones (iOS® and Android™). ForgeRock also provides a mobile app, which can:

  • Register a smartphone for use with push authentication.
  • Receive Push messages and authenticate the user using the TouchID fingerprint mechanism.

This app (ForgeRock Authenticator) is available on both the Apple® App Store and Google® Play Store. ForgeRock provides a push notification service via AWS SNS. ForgeRock customers can easily subscribe to this service, which sends out push messages from both cloud-based and on-premise based AM/OpenAM installations. See How do I set up AM/OpenAM Push Notification Service credentials? for further details.

The need for customization

The push messages technology needs the messaging service to know exactly which mobile app the message should be sent to. For iOS, the mobile app is identified by a so-called bundle identifier. This bundle ID cannot be changed once the developer has signed the app and submitted it to the App Store. As a result, the configuration of the message service must be changed whenever the app is modified and vice versa. This requirement prevents people who do not own or develop the app from sending push messages to other apps (for example, this prevents a potentially hostile entity sending messages to apps such as LinkedIn or WhatsApp).

In summary:

  • If you want to modify the app, you have to use your own AWS SNS service.
  • If you want to use your own AWS SNS service, you have to modify/recompile the app with a new bundle ID.

See How do I update and recompile the iOS authenticator app with custom branding in AM (All versions)? for further information on branding the iOS app. 

How to create your own SNS service

The following sections explain how to create your own SNS service and how to connect to the Apple Push Notification Service (APNS) as well as Google Cloud Messaging (GCM):

  1. Create a keypair
  2. Create a GCM service
  3. Create a SNS service

If you experience issues registering the new app with the new SNS service, see the Debugging section for further help.

Prerequisites

To set up AWS SNS you need:

  • A valid AWS account
  • An Apple Developer account
  • A Google Firebase account

Creating a keypair

First you need to create a public/private keypair that will be uploaded as a .p12 file to AWS. AWS uses this keypair to authenticate against APNS. You can, for example, use the Keychain app on Mac OS X to generate the keypair as demonstrated here:

  1. Navigate to the Apple Developer page (developer.apple.com) and log in with your iOS developer account; select Certificates, IDs & Profiles.
  2. Create an XCode project, enable Push Notifications and choose a new bundle ID. Alternatively, you can check out the ForgeRock Authenticator app (iOS or Android) and amend the bundle ID. 

The bundle ID should now show up in Apple developer console “iOS App IDs”. 

  1. Create the keypair that AWS uses to access APNS. Add a development or production certificate for Push Notifications. Then add a certificate for APNS:

  1. Select which application should receive the push notifications. Since an app is identified by the App ID (which matches the Bundle ID) we need to select the Bundle ID we entered in step 2 (io.push.demo in this example):

  1. The Apple wizard will now guide you through the steps using the Keychain app to generate a CSR (Certificate Signing Request), submit it to Apple CA via the developer console, download it and then import it into the Keychain. The new certificate will appear with type “Apple Push Services” in the Apple developer certificates section:

  1. Create a PKCS12 version from the Keychain app, which has the public and private parts in one file. This file will be uploaded to your AWS SNS later:

This completes the preparation for iOS.

Creating a GCM service

Recently Google moved the creation of a GCM service to the Firebase console. You need a Google cloud account to access this console.

You can create a GCM service as follows:

  1. Navigate to the Firebase console (console.firebase.google.com) and log in with your Google cloud account.
  2. Create a new project:

  1. Open settings:

The project ID and an API key are on the page that follows. You’ll need the API key in the next step to access GCM from the AWS SNS service.

Creating a SNS service

You can create a SNS service as follows:

  1. Navigate to the AWS console (aws.amazon.com/console) and then go to AWS service and select Simple Notification Service (SNS):

  1. Select Create platform application. You’ll now have to provide the data to access APNS and GCM services. For APNS, do:

  1. Select “Choose P12 file”, provide the password that protects the file (remember that this file contains both your private and public key) and click “Load credentials from file”. The field containing certificates and private key should now be auto-populated.
  2. Configure access to GCM accordingly. GCM uses an API key rather than a P12 but this is basically the same approach:

If all goes well, your AWS SNS application will show up under applications together with their endpoint. These endpoints look like the following and need to be entered in the AM/OpenAM Push Service configuration:

arn:aws:sns:us-east-1:0123456787:app/APNS_SANDBOX/FRDemo

To prevent people accessing the endpoints in AWS for APNS or GCM, these endpoint are protected with a clientID/clientSecret pair. To generate such a pair, you need to create a user via the AWS console using the IAM service. Make sure you tick the box for programmatic access.

  1. Click on “Attach existing policies directly” area and select the “AmazonSNSFullAccess” policy:

  1. Select the user and retrieve the Access Key ID and Secret Access Key from the IAM console. You can download these values as a CSV file:

That’s it. You can now configure the AM/OpenAM’s push service to use these values and test it. See the following links for further information:

Debugging

If something goes wrong with registering the new app with the new SNS service, you can test if the app can receive push messages that are not issued by AM/OpenAM.

Note

You should also try updating the AWS SDK jar files to the latest version to ensure there are no jar incompatibilities. You should obtain the latest aws-java-sdk-core-<version>.jaraws-java-sdk-sns-<version>.jar and aws-java-sdk-sqs-<version>.jar files, copy them to the /path/to/tomcat/webapps/openam/WEB-INF/lib directory and delete the old jar files.

To do this, you can test push messages using Amazon’s AWS SDK: 

  1. Download the ForgeRock authenticator’s source code: iOS or Android.
  2. Replace the bundle ID as described earlier. Attach your iOS device to your Mac and run the app while the mobile phone is connected to XCode. Once you have allowed Push Notifications to be received, you’ll see something similar to the following in the XCode console’s output:
    2017–07–20 08:46:29.111970+0200 ForgeRock[7354:2548462] Registered for remote notifications. deviceToken=<8e0729bb 565fbddc bde0bd42 e06ecf2 4464f063 7932a580 73add12c ee6e3af7>’
    
    The deviceToken is a sort of phone number that SNS must know in order to send a message to this specific device. This is exactly what happens during the the QR registration step. After a successful registration, the AM/OpenAM’s profile for the push user will have a pushDeviceProfiles attribute that contains the deviceToken (among other data).
  3. Try to send push message to your device using the AWS console or a NodeJS program (for example, tmarshall - aws-sns-example.js).

AWS console 

  1. Navigate to the AWS console (aws.amazon.com/console) and then go to SNS service:

  1. Select your application. Click on the correct ARN (for example, iOS for Apple devices). Now click on Create Endpoint (this will add a device specific endpoint).

  1. Enter the deviceToken without spaces (you can leave the User Data field empty) and publish a message to this endpoint (for example, “Long live Rock’n’Roll”). You should now receive this message on your phone.

NodeJS

To use NodeJS code, simply set the following parameters to match your environment:

  • SNS Endpoints of the application
  • ID/Secret to access AWS
  • deviceToken
  • region (for example, us-east-1) where you created your service 

See Also

How do I set up AM/OpenAM Push Notification Service credentials?

Using Push Notifications for Passwordless Authentication and Easy MFA

Using your own SNS messaging with ForgeRock Authenticator

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

N/A


Known Issues


User cannot log in using Push authentication in AM (All versions) and OpenAM 13.5

The purpose of this article is to provide assistance if a user cannot log in using Push authentication in AM/OpenAM.

Symptoms

The user cannot log in using Push authentication.

You see the following error when a user attempts to log in using Push authentication:

{"code":500,"reason":"Internal Server Error","message":"Authentication Error!!"}

An error similar to the following is shown in the CoreSystem debug log when this happens:

Formatted event: "de6427e2-4671-9359-aff9-bac00cd4c431-311","2018-03-04T12:21:28.554Z","AM-LOGIN-COMPLETED","de6427e2-4671-9359-aff9-bac00cd4c431-305",,"[""c3f6d35deec82a4031""]","FAILED",,,"[{""moduleId"":""pushAuth"",""info"":{""authIndex"":""service"",""failureReason"":""LOGIN_FAILED"",""ipAddress"":""203.0.113.0"",""authLevel"":""2""}}]","Authentication","/"

You may also see the following error in the Push debug logs:

Received error response: com.amazonaws.services.sns.model.EndpointDisabledException: Endpoint is disabled (Service: AmazonSNS; Status Code: 400; Error Code: EndpointDisabled; Request ID: 1431e de2-94b3-2d50-6e21-bc9c8f3931f7)

The endpoint referred to in this error is the end user's device (for example, mobile) endpoint.

Recent Changes

N/A

Causes

The majority of issues with Push authentication are caused by changes to the end user's device. Common reasons include (although not limited to):

  • The device has been restored from a backup.
  • The relevant app has been reinstalled on the device.
  • The user has disabled push notifications.

These changes result in the end user's device (endpoint) being disabled in AWS.

See Stack Overflow - Getting “EndpointDisabled” from Amazon SNS for information on other causes for the "Endpoint is disabled" error.

Solution

This issue, regardless of the exact cause, can typically be resolved by re-registering the device. This process initiates a search for the endpoint and results in it being re-enabled in AWS. 

Note

Please observe the following when constructing REST calls:

  • Make the REST call to the actual AM/OpenAM server URL (not lb).
  • Change the name of the iPlanetDirectoryPro header to the name of your actual session cookie.
  • Set this session cookie header to the token returned when you authenticated.
  • Ensure the Accept-API-Version header contains a valid resource version (AM 5 and later).

See How do I avoid common issues with REST calls in AM/OpenAM (All versions)? for further information.

You can re-register the device as follows:

  1. Authenticate as an admin user. For example:
    • AM 5 and later:
      $ curl -X POST -H "X-OpenAM-Username: amadmin" -H "X-OpenAM-Password: cangetinam" -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.1" http://host1.example.com:8080/openam/json/realms/root/authenticate
      
    • Pre-AM 5:
      $ curl -X POST -H "X-OpenAM-Username: amadmin" -H "X-OpenAM-Password: cangetinam" -H "Content-Type: application/json" http://host1.example.com:8080/openam/json/authenticate
    Example response:
    { "tokenId": "AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*", "successUrl": "/openam/console", "realm": "/" } 
    
  2. Remove the device from the user's profile using one of the following curl commands where myUser in the URL is replaced with the name of the user:
    • AM 5 and later:
      $ curl -X POST -H "Content-Type: application/json" -H "Accept-API-Version: resource=3.0" -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" http://host1.example.com:8080/openam/json/realms/root/users/myUser/devices/push?_action=reset
      
    • Pre-AM 5:
      $ curl -X POST -H "Content-Type: application/json" -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" http://host1.example.com:8080/openam/json/users/myUser/devices/push?_action=reset
      
  3. Ask the user to re-register their device.

See Also

How do I set up AM/OpenAM Push Notification Service credentials?

How do I use my own AWS SNS Push Service with AM (All versions) and OpenAM 13.5?

Authentication and Single Sign-On Guide › About Push Authentication

Authentication and Single Sign-On Guide › Creating Authentication Chains for Push Authentication

Authentication and Single Sign-On Guide › ForgeRock Authenticator (Push) Registration Authentication Module

Authentication and Single Sign-On Guide › Resetting Registered Devices by using REST

How do I troubleshoot failed Amazon SNS push notification deliveries?

Related Training

N/A

Related Issue Tracker IDs

OPENAM-12043 (Trigger SNS endpoint enablement when a recovery code is used)


MSISDN


How do I configure authentication using the MSISDN Authentication module in AM/OpenAM (All versions)?

The purpose of this article is to provide information on configuring authentication using the MSISDN Authentication module in AM/OpenAM. The MSISDN module authenticates a user via the ISDN number assigned to the user in the LDAP directory server, meaning it is a non-interactive authentication method.

Prerequisites

The Mobile Station Integrated Services Digital Network (MSISDN) number must be included in the request sent to AM/OpenAM for this authentication method to work. If the MSISDN number cannot be retrieved from the request, then callbacks to get the MSISDN number and WAP gateway are sent back to the client.

Firstly, the user's mobile network must support passing the MSISDN number in the HTTP header and then it is up to them to include it (this is outside the scope of AM/OpenAM). 

You can check whether it is included by examing the HTTP header and looking for any headers that reference MSISDN or possibly X-UP-CALLING-LINE-ID (the actual header varies depending on the mobile network). See FAQ: Configuring Policy Agents in AM/OpenAM (Q. Why can't I see the http_header attributes in the browser?) for further information on checking the HTTP header if you have policy agents protecting your application.

Configuring the MSISDN Authentication module

Note

There is a known issue in OpenAM 13.0, which causes authentication to fail using the MSISDN Authentication module: OPENAM-6406 (Cannot authenticate using MSISDN module in nightly build). This is fixed in OpenAM 13.5.

This process demonstrates configuring the MSISDN Authentication module for a single user and uses the following example values:

  • Realm: mobile
  • Authentication module: MSISDN
  • HTTP header attribute: msisdn
  • User: employee1
  • MSISDN number: 987654321

You should replace these values and amend other configuration details as appropriate to your environment.

You can configure the MSISDN Authentication module as follows:

  1. Navigate to the authentication module options in your realm:
    • AM / OpenAM 13.x console: navigate to: Realms > /mobile > Authentication > Modules and click Add Modules.
    • Pre-OpenAM 13 console: navigate to: Access Control > mobile > Authentication > Module Instances and click New.
  2. Enter a name for the new module (MSISDN) and select type MSISDN.
  3. Re-select the new MSISDN module if you are using a pre-13.0 version of OpenAM.
  4. Complete the following fields:
    • MSISDN Number Search Parameter Name - specify 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 (msisdn in this example).
    • Attribute To Use To Search LDAP - leave the default value of sunIdentityMSISDNNumber.
    • LDAP Server Authentication User - check this is set to the correct DN of the user used by the module to authenticate to the LDAP server.
    • LDAP Server Authentication Password - check the password is correct for the above user.
    • MSISDN Header Search Attribute - ensure all three options are selected if you are using a pre-13.0 version of OpenAM or ensure the following values are present in AM / OpenAM 13.x:
    • searchRequest searchParam searchCookie
      This ensures AM/OpenAM searches the cookie, request header and request parameters for the MSISDN number.
  5. Assign the MSISDN number to your user (MSISDN number = 987654321 and user = employee1 in this example):
    • AM / OpenAM 13.x console: navigate to: Realms > /mobile > Subjects > employee1 > MSISDN Number and enter 987654321.
    • Pre-OpenAM 13 console: navigate to: Access Control > mobile > Subjects > employee1 > MSISDN Number and enter 987654321.
  6. Add the new module to the default authentication chain:
    • AM / OpenAM 13.x console: navigate to: Realms > /mobile > Authentication > Chains > ldapService and replace the required DataStore module with your new MSISDN module.
    • Pre-OpenAM 13 console: navigate to: Access Control > mobile > Authentication > Authentication Chaining > ldapService and replace the required DataStore module with your new MSISDN module.
  7. Log out of AM/OpenAM.
  8. Navigate to one of the following URLs to test your new configuration:
    • AM 5 and later:
      http://host1.example.com:8080/openam/XUI/?realm=/mobile#login&module=MSISDN&msisdn=987654321
      
    • Pre-AM 5:
      http://host1.example.com:8080/openam/XUI/#login/&module=MSISDN&msisdn=987654321&realm=mobile
    This should take you directly to the profile of the employee1 user without requiring a password.

See Also

Authentication and Single Sign-On Guide › Implementing Authentication › MSISDN Authentication Module

Related Training

N/A

Related Issue Tracker IDs

OPENAM-4128 (MSISDN auth module - insufficient logging )

OPENAM-6406 (Cannot authenticate using MSISDN module in nightly build)


Persistent Cookie


How do I change the persistent cookie name (session-jwt) in AM/OpenAM (All versions)?

The purpose of this article is to provide information on changing the persistent cookie name in AM/OpenAM. The persistent cookie is called session-jwt by default and is created via the Persistent Cookie module.

Overview

The property that relates to the persistent cookie name (openam-auth-persistent-cookie-name) is not exposed via the console or ssoadm by default in earlier releases. However, in those releases you can still change it via the console.

The following sections detail how to change the persistent cookie name depending on which version you are using:

Changing the persistent cookie name (AM 5.5 and later; OpenAM 13.5.2)

You can change the name of the persistent cookie as follows using either the console, Amster (AM 5.5 and later) or ssoadm:

  • Console: navigate to: Realms > [Realm Name] > Authentication > Modules > Persistent Cookie Module > Persistent Cookie Name and enter the new cookie name.
  • Amster: follow the steps in How do I update property values in AM (All versions) using Amster?with these values:
    • Entity: PersistentCookieModule
    • Property: cookieName
  • ssoadm: enter the following command:
    $ ./ssoadm update-auth-instance -e [realmname] -m [modulename] -u [adminID] -f [passwordfile] -a openam-auth-persistent-cookie-name=[name]
    replacing [realmname], [modulename], [adminID], [passwordfile] and [name] with appropriate values.

Changing the persistent cookie name (AM 5, 5.1.x; pre-OpenAM 13.5.2)

You can change the name of the persistent cookie as follows in the console:

  • AM / OpenAM 13.x console: navigate to: Realms > [Realm Name] > Authentication > Chains > [Chain Name] and click the pencil icon against the Persistent Cookie module to edit the module properties. Enter the following Key and Value under Options:
    KEY                                  VALUE
    openam-auth-persistent-cookie-name   newName
    where newName is the new name for the persistent cookie.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Authentication > Authentication Chaining > [Chain Name] and enter the following in the Options field against the Persistent Cookie module:
    openam-auth-persistent-cookie-name=newName
    where newName is the new name for the persistent cookie.

See Also

How do I change the session cookie name for AM/OpenAM and Policy Agents (All versions)?

FAQ: Cookies in AM/OpenAM

Persistent cookie is not created in AM/OpenAM (All versions) after changing default keystore

Persistent cookie is no longer created in AM/OpenAM (All versions)

Session quotas not limiting active user sessions in AM/OpenAM (All versions) when persistent cookies are used

Authentication modules in AM/OpenAM

Authentication and Single Sign-On Guide › Persistent Cookie Module

Related Training

N/A

Related Issue Tracker IDs

OPENAM-7781 (persistent cookie auth module does not allow to change cookie name by default)


Known Issues


Persistent cookie is not created in AM/OpenAM (All versions) after changing default keystore

The purpose of this article is to provide assistance if the persistent cookie (called session-jwt by default) is not created in AM/OpenAM after you have changed the default keystore and a NullPointerException is shown in the logs. This applies to the persistent cookie created via the Persistent Cookie module.

Symptoms

The persistent cookie is not created.

An error similar to the following is shown in the log (when debug level is set to Message):

postLoginProcess Class Name is : org.forgerock.openam.authentication.modules.persistentcookie.PersistentCookieAuthModule
amAuth:02/25/2014 04:21:39:487 PM GMT: Thread[http-bio-8443-exec-5,5,main]
Error 
java.lang.NullPointerException
    at org.forgerock.common.util.KeystoreManager.getPublicKey(KeystoreManager.java:128)
    at org.forgerock.jaspi.modules.session.jwt.JwtSessionModule.createSessionJwtCookie(JwtSessionModule.java:428)
    at org.forgerock.jaspi.modules.session.jwt.JwtSessionModule.secureResponse(JwtSessionModule.java:407) 

Recent Changes

Changed the AM/OpenAM keystore.

Causes

The JSON Web Token (JWT) cookie is encrypted using the default test key in the default AM/OpenAM keystore. The default test key cannot be found if the keystore changes, which causes the Persistent Cookie module to fail.

Solution

This issue can be resolved by updating the key from its default value of test to the value associated with the new keystore. You can do this globally or in a specific realm, where realm level take precedence over the global level.

Global

You can update this value globally using either the console or ssoadm:

  • AM / OpenAM 13.5 console: navigate to: Configure > Authentication > Core Attributes > Security > Persistent Cookie Encryption Certificate Alias and change test to the name of your actual key.
  • Pre-OpenAM 13.5 console: navigate to: Configuration > Authentication > Core > Security > Organization Authentication Certificate Alias and change test to the name of your actual key. This option is called Persistent Cookie Encryption Certificate Alias in OpenAM 13.0
  • ssoadm: enter the following command:
    $ ./ssoadm set-attr-defs -s iPlanetAMAuthService -t organization -u [adminID] -f [passwordfile] -a iplanet-am-auth-key-alias=[keyname]
    replacing [adminID], [passwordfile] and [keyname] with appropriate values.

Realm level

You can update this value in a specific realm using either the console or ssoadm:

  • AM / OpenAM 13.x console: navigate to: Realms > [Realm Name] > Authentication > Settings > Security > Persistent Cookie Encryption Certificate Alias and change test to the name of your actual key.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Authentication > All Core Settings > Security > Organization Authentication Certificate Alias and change test to the name of your actual key.
  • ssoadm: enter the following command:
    $ ./ssoadm set-realm-svc-attrs -s iPlanetAMAuthService -e [realmname] -u [adminID] -f [passwordfile] -a iplanet-am-auth-key-alias=[keyname]
    replacing [realmname], [adminID], [passwordfile] and [keyname] with appropriate values.
Note

You must restart the web application container in which AM/OpenAM runs to apply these configuration changes.

See Also

Persistent cookie is no longer created in AM/OpenAM (All versions)

How do I change the persistent cookie name (session-jwt) in AM/OpenAM (All versions)?

Setup and Maintenance Guide › Changing Default Key Aliases

Authentication and Single Sign-On Guide › Implementing Authentication › Persistent Cookie Module

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

OPENAM-4370 (NPE when trying to authenticate via the REST authentication service)


Persistent cookie is no longer created in AM/OpenAM (All versions)

The purpose of this article is to provide assistance if the persistent cookie is not created after installing AM, OpenAM 12.0.4, 13.5, or installing the patch for OpenAM Security Advisory #201605 and you see the following error: "Signing key must be at least 256-bits base64 encoded". The persistent cookie is called session-jwt by default and is created via the Persistent Cookie module.

Symptoms

The persistent cookie is not created; users who were logged in using a persistent cookie generated in an earlier version of AM/OpenAM or before the security patch was installed must log in again. 

The following error is shown in the Authentication log when the persistent cookie is not created:

amAuthO2PersistentCookie:08/10/2016 11:47:19:546 AM EST: Thread[ajp-bio-8010-exec-10,5,main]: TransactionId[ddda86b2-56b2-4fe7-8fb1-d8fb94c0455b-475] 
ERROR: Failed to initialise the underlying JASPI Server Auth Module. 
org.forgerock.caf.authentication.api.AuthenticationException: Signing key must be at least 256-bits base64 encoded 
   at org.forgerock.jaspi.modules.session.jwt.AbstractJwtSessionModule.initialize(AbstractJwtSessionModule.java:196)
   at org.forgerock.jaspi.modules.session.jwt.ServletJwtSessionModule.initialize(ServletJwtSessionModule.java:47) 
   at org.forgerock.jaspi.modules.session.jwt.ServletJwtSessionModule.initialize(ServletJwtSessionModule.java:68) 
   at org.forgerock.openam.authentication.modules.common.JaspiAuthModuleWrapper.init(JaspiAuthModuleWrapper.java:78) 
   at org.forgerock.openam.authentication.modules.common.AbstractLoginModuleBinder.init(AbstractLoginModuleBinder.java:66) 

Recent Changes

Upgraded to, or installed AM 5 or later.

Upgraded to, or installed OpenAM 12.0.4 or 13.5.

Installed the patch for OpenAM Security Advisory #201605.

Implemented the Persistent Cookie module. 

Causes

Changes were introduced in OpenAM 12.0.4 and 13.5, and the security patch to sign the persistent cookie using a user-specified HMAC signing key in addition to it being encrypted; this improves the security of persistent cookies.

Persistent cookies must now be signed by this HMAC signing key to be considered valid; additionally the HMAC signing key must be a random string that is at least 256 bits and base64 encoded. If the HMAC signing key is either missing or invalid, the persistent cookie will not be created and you will see this error.

Solution

This issue can be resolved by setting or correcting the value of the HMAC signing key.

  1. Generate a random string that is at least 256 bits and base64 encoded for your signing key. For example, you could a use a random number generator and then encode it using the OpenDJ base64 tool or you could use openssl:
    $ openssl rand -base64 32
  2. Update the value of the HMAC signing key for the Persistent Cookie module using either the console or ssoadm:
    • AM / OpenAM 13.x console: navigate to: Realms > [Realm Name] > Authentication > Modules > [Module Name] > HMAC Signing Key and enter the string you generated in step 1.
    • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Authentication > Modules > [Module Name] > HMAC Signing Key and enter the string you generated in step 1.
    • ssoadm: enter the following command:
      $ ./ssoadm update-auth-instance -e [realmname] -m [modulename] -u [adminID] -f [passwordfile] -a openam-auth-persistent-cookie-hmac-key=[string]
      replacing [realmname], [modulename], [adminID], [passwordfile] and [string] with appropriate values, where [string] is the string you generated in step 1.
Note

The Persistent Cookie Encryption Certificate Alias is used to encrypt the persistent cookie, the new HMAC key is for signing. Both are necessary for the persistent cookie to be created,  but the value of one does not depend on the other. See Persistent cookie is not created in AM/OpenAM (All versions) after changing default keystore for further information on changing this value.

See Also

OpenAM Security Advisory #201605

Persistent cookie is not created in AM/OpenAM (All versions) after changing default keystore

How do I change the persistent cookie name (session-jwt) in AM/OpenAM (All versions)?

OpenAM 13 Release Notes › Changes and Deprecated Functionality › Important Changes to Existing Functionality

Authentication and Single Sign-On Guide › Implementing Authentication › Persistent Cookie Module

Related Training

N/A

Related Issue Tracker IDs

OPENAM-9558 (Organization Authentication Certificate Alias property has been renamed in 13)

OPENAM-9492 (XUI should validate the value of a Persistent Cookie HMAC Signing Key)

OPENAM-8264 (insufficient validator for service property 'iplanet-am-auth-hmac-signing-shared-secret')


SAML2


How do I set up the SAML2 Authentication module using Integrated Mode in AM (All versions) and OpenAM 13.x?

The purpose of this article is to provide information on setting up federation with the SAML2 Authentication module in AM/OpenAM, where AM/OpenAM is the hosted SP. This information applies when you want to configure SAML2 SSO in integrated mode.

Setting up federation in integrated mode

Note

The process to set up federation with the SAML2 authentication module is fully documented in SAML v2.0 Guide › Implementing SAML v2.0 Single Sign-On in Integrated Mode.

However, if you are confident about setting up federation in integrated mode without referring to the documentation, here are the high-level steps (including the key changes you must make that are not so obvious without referring to the documentation):

  1. Set up federation as usual with AM/OpenAM as the hosted SP.
  2. Create the SAML2 authentication module and include it in an authentication chain.
  3. Select the SP entity provider:
    • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers and click the name of the entity provider that is of type Hosted SP.
    • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers and click the name of the entity provider that is of type Hosted SP.
    • OpenAM 13.x console: navigate to: Federation > Circle of Trust Configuration > Entity Providers and click the name of the entity provider that is of type Hosted SP.
  4. Navigate to Services > Assertion Consumer Service and change the following consumer service locations in the SP configuration:
    • Change the location of the HTTP-Artifact consumer service to use AuthConsumer rather than Consumer. For example, if the location is http://sp.example.com:8080/openam/Consumer/metaAlias/sp, change it to http://sp.example.com:8080/openam/AuthConsumer/metaAlias/sp.
    • Change the location of the HTTP-POST consumer service to use AuthConsumer rather than Consumer as per the HTTP-Artifact consumer service.
    These changes are necessary and imply that you cannot have both the SAML2 authentication module and non-integrated federation on the same SP.
  5. Notify the IdP of these new endpoints if relevant. 
Note

You do not need to change the location of the PAOS service because integrated mode does not support the PAOS binding.

  1. Test your configuration. First, clear your browser's cache and cookies. Then, attempt to log in to AM/OpenAM using a login URL that references the authentication chain that includes the SAML2 module. For example: 
    http://sp.example.com:8080/openam/XUI/#login/&service=mySAMLChain

See Also

How do I configure the SAML2 Authentication module for Local Account Linking in AM (All versions) and OpenAM 13.x?

FAQ: SAML federation in AM/OpenAM

SAML Federation in AM/OpenAM

Authentication and Single Sign-On Guide › Implementing Authentication › SAML2 Authentication Module

Related Training

N/A

Related Issue Tracker IDs

OPENAM-8071 (Documentation on SAML2 Authn module: add a reference for the need to modify the SP Assertion Consumer Service endpoints)


How do I configure the SAML2 Authentication module for Auto Federation in AM (All versions) and OpenAM 13.x?

The purpose of this article is to provide a quick video tutorial on how to configure the SAML2 Authentication module for auto-federation in AM/OpenAM. This demonstration walks through configuring the module from first principles, showing how to configure a service provider (SP), an identity provider (IdP) and then the Authentication module as part of a login chain.

Configuring the SAML2 Authentication module for auto-federation

Note

This video demonstration uses OpenAM 13.0; although the appearance has changed between AM and OpenAM 13.x, the principles and processes are still applicable. In AM, the options under Federation are now under Realms > [Realm Name] > Applications > SAML.

This video demonstration was recorded in HD and is best viewed in Full Screen mode:

Contributed by David Luna

Video Transcript

Click here to download a transcript of this video tutorial. 

See Also

ohnomorejuzzoblogs - Example Configuration - Dynamic Account Federation

How do I configure the SAML2 Authentication module for Local Account Linking in AM (All versions) and OpenAM 13.x?

How do I set up the SAML2 Authentication module using Integrated Mode in AM (All versions) and OpenAM 13.x?

How do I export and import SAML2 metadata in AM/OpenAM (All versions)?

FAQ: SAML federation in AM/OpenAM

SAML Federation in AM/OpenAM

Authentication and Single Sign-On Guide › Implementing Authentication › Federation Authentication Module

Reference › Service Endpoints › SAML2 JSP Endpoints

SAML v2.0 Guide › Implementing SAML v2.0 Using the AM Console › To Share Identity and Service Provider Metadata

Related Training

N/A

Related Issue Tracker IDs

OPENAM-8071 (Documentation on SAML2 Authn module: add a reference for the need to modify the SP Assertion Consumer Service endpoints)


How do I configure the SAML2 Authentication module for Local Account Linking in AM (All versions) and OpenAM 13.x?

The purpose of this article is to provide a video demonstration that walks you through configuring both the identity provider (IdP) and service provider (SP) for federation using the SAML2 Authentication module as part of a complex login chain in AM/OpenAM.

Configuring federation using the SAML2 Authentication module for Local Account Linking

Note

This video demonstration uses OpenAM 13.0; although the appearance has changed between AM aand OpenAM 13.x, the principles and processes are still applicable. In AM, the options under Federation are now under Realms > [Realm Name] > Applications > SAML.

This video demonstration was recorded in HD and is best viewed in Full Screen mode:

Contributed by David Luna

Video Transcript

Click here to download a transcript of this video tutorial. 

See Also

ohnomorejuzzoblogs - Example Configuration - Local Account Linking

How do I configure the SAML2 Authentication module for Auto Federation in AM (All versions) and OpenAM 13.x?

How do I set up the SAML2 Authentication module using Integrated Mode in AM (All versions) and OpenAM 13.x?

How does AM/OpenAM (All versions) use account mapping to identify the end user from a SAML Assertion?

FAQ: SAML federation in AM/OpenAM

SAML Federation in AM/OpenAM

Authentication and Single Sign-On Guide › Implementing Authentication › SAML2 Authentication Module

SAML v2.0 Guide › Implementing SAML v2.0 Using the AM Console › Implementing SAML v2.0 Single Sign-On and Single Logout

Authentication and Single Sign-On Guide › Implementing Authentication › Device ID (Match) Authentication Module

Authentication and Single Sign-On Guide › Implementing Authentication › OATH Authentication Module

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I know which binding to use for SAML2 federation in AM/OpenAM (All versions)?

The purpose of this article is to provide information on using bindings for SAML2 federation in AM/OpenAM. There are two different concepts to bindings in SAML2; the binding used for the communication, including sending the request, and the protocol binding, which is used when returning the response message. This article focuses on standalone mode, in which you invoke JSPs to initiate SSO and SLO, but the principles apply if you use integrated mode, in which you configure a SAML2 authentication module.

Communication bindings

Communication bindings correspond to the method used for communications between the SP and the IdP.

For the authentication request, the communication can be sent through HTTP-POST or HTTP-REDIRECT (GET).

HTTP-REDIRECT is used by default when you use spSSOInit.jsp. If you want to use HTTP-POST, you need to add the reqBinding parameter to the URL, for example:

http://sp.example.com:8080/openam/saml2/jsp/spSSOInit.jsp?idpEntityID=http%3A%2F%2Fidp.acme.com%3A8080%2Fopenam&metaAlias=/sp&reqBinding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST

If you are the IdP and do not want to, or cannot accept HTTP-REDIRECT, you can inform the SP by not providing the corresponding endpoint. For example, if AM/OpenAM is the IdP and you want to prevent access to http://idp.acme.com:8080/openam/SSORedirect/metaAlias/idp, you should configure the IdP as follows:

  1. Select the IdP entity provider:
    • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers and click the name of the entity provider that is of type Hosted IdP.
    • AM 5.x console: navigate to Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers and click the name of the entity provider that is of type Hosted IdP.
    • Pre-AM 5 console: navigate to: Federation > Circle of Trust Configuration > Entity Providers and click the name of the entity provider that is of type Hosted IdP.
  2. Navigate to Services > Single SignOn Service and remove the entry in the HTTP-REDIRECT Location field.
  3. Inform the SP that the metadata has changed and they need to update their configuration accordingly. This ensures the SP knows it cannot send a GET request to that endpoint.

For the following JSP pages, you can also specify the communication binding to use for the entire communication by adding the binding parameter to the URL:

  • spSSOInit.jsp
  • idpSSOInit.jsp
  • idpSingleLogoutInit.jsp
  • spSingleLogoutInit.jsp
  • idpMNIRequestInit.jsp
  • spMNIRequestInit.jsp

For example, if you want to use SOAP (machine to machine communication) for SLO via idpSingleLogoutInit.jsp, you would need to specify the binding parameter in the URL as follows:

http://idp.acme.com:8080/openam/saml2/jsp/idpSingleLogoutInit.jsp?metaAlias=/sp&idpEntityID=http%3A%2F%2Fidp.example.com%3A8080%2Fopenam&binding=urn:oasis:names:tc:SAML:2.0:bindings:SOAP

See SAML v2.0 Guide › Implementing SAML v2.0 Single Sign-On and Single Logout for further information on which bindings are available for which JSP pages.

Protocol bindings

Protocol bindings correspond to the protocol to use when returning the Response message:

  • With HTTP-Artifact, the IdP sends a nonce (a unique number working as a reference) back to the SP and the SP does a server-to-server communication using that nonce to retrieve the assertion. 
  • With HTTP-POST, the IdP sends the assertion back through the user-agent directly. 

The flow used is defined on the SP side. If AM/OpenAM is the SP,  you can change this as follows:

  1. Select the SP entity provider:
    • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers and click the name of the entity provider that is of type Hosted SP.
    • AM 5.x console: navigate to Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers and click the name of the entity provider that is of type Hosted SP.
    • Pre-AM 5 console: navigate to: Federation > Circle of Trust Configuration > Entity Providers and click the name of the entity provider that is of type Hosted SP.
  2. Navigate to Services > Assertion Consumer Service and select the required binding. This defaults to HTTP-Artifact.
  3. Inform the IdP that the metadata has changed and they need to update their configuration accordingly.
Note

The protocol binding is optional in a <AuthnRequest> message as per the SAML spec: Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0 (3.4.1 Element <AuthnRequest>).

See Also

How do I update metadata for an IdP or SP in AM/OpenAM (All versions) using ssoadm?

FAQ: SAML federation in AM/OpenAM

SAML Federation in AM/OpenAM

SAML v2.0 Guide

Authentication and Single Sign-On Guide › Implementing Authentication › SAML2 Authentication Module​​​​​​​

Related Training

N/A

Related Issue Tracker IDs

N/A


SecurID


FAQ: SecurID authentication module in AM/OpenAM

The purpose of this FAQ is to provide answers to commonly asked questions regarding the SecurID® authentication module in AM/OpenAM. The SecurID module allows AM/OpenAM to authenticate users with RSA® Authentication Manager software and RSA SecurID authenticators. This article also includes information for troubleshooting failed authentication attempts to the SecurID authentication module.

Frequently asked questions

Q. Does AM/OpenAM support RSA SecurID?

A. Yes, SecurID is fully supported in AM/OpenAM.

OpenAM 13

In OpenAM 13.0, the SecurID authentication module is missing as noted in: OPENAM-8456 (SecurID authentication module is missing from 13.0.0). A patch is provided in SecurID authentication module is missing from OpenAM 13.0 to restore this missing module. This is the simplest way to get the SecurID authentication module in OpenAM 13.

Alternatively, you can build your own version of OpenAM with the SecurID authentication module as described in How do I build OpenAM 12.x and 13.x from source? if you are upgrading to OpenAM 13.0. Or, if you have already upgraded to OpenAM 13.0 and wish to use the SecurID authentication module, you can obtain the amAuthSecurID.xml file from the source code and run the following ssoadm command to update the service schema with the SecurID authentication module:

$ ./ssoadm update-svc [adminID] -f [passwordfile] -X amAuthSecurID.xml

replacing [adminID] and [passwordfile] with appropriate values. 

See FAQ: Source code in AM/OpenAM (Q. How do I get the source code for AM/OpenAM and policy Agents?) for further information on getting this file from source.

Q. Why is the log4j-over-slf4j jar missing from AM 5 and later?

A. The log4j-over-slf4j jar file is no longer distributed with AM. You must obtain a version of the log4j library from RSA that is compatible with your version of the authapi jar file.

See OPENAM-9745 (SecurID Authentication not working, error displayed "Unknown error. Please contact your Administrator") for further information.

Q. Why is the authapi-2005-08-12.jar missing?

A. ForgeRock is not licensed to redistribute the RSA SecurID library (authapi jar). You must obtain the latest authapi jar file from RSA. They should provide this to you along with a dependency crypto.jar / cryptoj.jar file. You should then include these files in the path/to/tomcat/webapps/openam/WEB-INF/lib directory where AM/OpenAM is deployed.

If you do not obtain the latest authapi jar, you will not be able to log into the SecurID module and will see an error as detailed in SecurID authentication module login fails in AM/OpenAM (All versions) with java.lang.NoClassDefFoundError.

Q. Can I use RSA SDK 8.6?

A. No, RSA SDK 8.6 will not work with the SecurID module. The SecurID module requires UDP, which is not supported as of SDK 8.6.

Q. What are common issues with authentication failing in the SecurID authentication module?

A. Authentication in the SecurID module can fail for a number of reasons; here are some common issues you may encounter:

Pertinent Error Snippet Issue Resolution
Error in web application container log:
Caused by: java.lang.NoClassDefFoundError: com/rsa/authagent/authapi/AuthAgentException
Missing authapi jar and dependency crypto.jarcryptoj.jar files The authapi jar and dependency crypto.jar / cryptoj.jar files are needed and must be obtained from RSA. See SecurID authentication module login fails in AM/OpenAM (All versions) with java.lang.NoClassDefFoundError for further information.
Error in Authentication debug log:
Exception : 
com.sun.identity.authentication.spi.AuthLoginException: SecurID system profile login error occurred. 
RSA API Initialization Error: com.rsa.authagent.authapi.datarepository.AUTHf: sdconf.rec not found 
Missing sdconf.rec file Check the rsa_api.properties file is in the same directory as the sdconf.rec file (which is typically located in $HOME/openam/openam/auth/ace/data, but this location is user-defined when you configure the SecurID authentication module so can vary). If it is not there:
  1. Copy the the rsa_api.properties file to the same directory as the sdconf.rec file. You can find the rsa_api.properties file in the path/to/tomcat/webapps/openam/WEB-INF/lib directory where AM/OpenAM is deployed.
  2. Update the file path properties that reference @BASE_DIR@/@SERVER_URI@ to point to the correct location (which is the directory where the rsa _api.properties and sdconf.rec files reside).
  3. Restart the web application container in which AM/OpenAM runs.

Error shown in browser when accessing SecurID module:

Unknown error. Please contact your Administrator
Incorrect use of the Log4J bridge libraries This is a known issue: OPENAM-9745 (SecurID Authentication not working, error displayed "Unknown error. Please contact your Administrator"). You should replace the existing log4j-over-slf4j library with the log4j library. You should obtain a compatible version of the log4j library from RSA.
Errors on RSA side (in rsa_api_debug.log file or RSA log monitor console):
Can't get node
Secret

Node secret mismatch: cleared on server but not on agent
Node secret mismatch: agent and server using different node secrets
Node secret mismatch The resolution is detailed in: RSA Authentication Manager Issue – Node secret mismatch. In summary, you should delete the node secret on the client (AM/OpenAM side) and the RSA Server. The node secret will then be re-negotiated when the client contacts the server again.
Error in rsa_api_debug.log file:
CheckServer failedcom.rsa.ace.techservice.udpserver.AUTHa1: Error receiving packet Timeout: java.net.SocketTimeoutException: Receive timed out

Error in rsa_api.log file:

[2018-10-22 09:36:44,873] ERROR http-bio-443-exec-3 - Error sending request: com.rsa.ace.techservice.udpserver.a: Error sending packet: java.io.IOException: Invalid argument (sendto failed)
[2018-10-22 09:36:44,873] WARN http-bio-443-exec-3 - User TIME's access is denied.

Error in Authentication debug log:

Exception : 
com.sun.identity.authentication.spi.AuthLoginException: SecurID initialization login exception: No Server available
Network issue The resolution is to find and resolve the Network issue. The following information may help you track it down:
  • Is there a firewall between AM/OpenAM and the RSA server?
  • Are you using an IP address instead of FQDN? All servers listed in the generated sdconf.rec file must have a fully qualified domain name (FQDN). Also, check that the servers listed in your /etc/hosts file or DNS server if using DNS, are using FQDNs and are not defined upon IP address or hostname only.
  • Are you using Linux® running on Hardware? This error has been seen on Linux running on Hardware where 5 UDP packets were dropped for every authentication attempt. Moving to VMWare (with the same network configuration) resolved this issue.
  • Use a tool such as truss (Solaris®) or strace (Linux) to perform system level tracing to help you identify the issue.
  • Use a tool such as dropwatch to monitor packet drops in the TCP/IP stack of the operating system.

Q. How do I enable debug logging for the RSA server?

A. You can enable debug logging in the rsa_api.properties file if you want to see what is happening on the RSA server. This file must reside in the same directory as the sdconf.rec file (which is typically located in $HOME/openam/openam/auth/ace/data, but this location is user-defined when you configure the SecurID authentication module so can vary).

To enable debug logging:

  1. Copy the rsa_api.properties file to the same directory as the sdconf.rec file if it does not already exist. You can find the rsa_api.properties file in the path/to/tomcat/webapps/openam/WEB-INF/lib directory where AM/OpenAM is deployed.
  2. Update the required debug options in the event logger and debugger sections in the rsa_api.properties file to YES.
  3. Update the file path properties that reference @BASE_DIR@/@SERVER_URI@ to point to the correct location (which is the directory where the rsa_api.properties and sdconf.rec files reside).
  4. Restart the web application container in which AM/OpenAM runs.
  5. Reproduce the issue you were encountering.
  6. Retrieve the log files (rsa_api.log and rsa_api_debug.log) from the location you specified.

Example

An example snippet of the rsa_api.properties file with the event logger and debugger sections configured to output debug information to file:

# [This section is for event logger.] 
# Logs event messages to the console. 
RSA_LOG_TO_CONSOLE=NO 
# Logs event messages to a file. 
RSA_LOG_TO_FILE=YES 
# Name of the log file. 
RSA_LOG_FILE=$HOME/openam/openam/debug/rsa_api.log 
# Minimum severity level allowed to log. 
RSA_LOG_LEVEL=DEBUG

# [This section is for debugger.] 
# Enables debug tracing. 
RSA_ENABLE_DEBUG=YES 
# Sends tracing to the console. 
RSA_DEBUG_TO_CONSOLE=NO 
# Sends tracing to a file. 
RSA_DEBUG_TO_FILE=YES 
# Name of the trace file. 
RSA_DEBUG_FILE=$HOME/openam/openam/debug/rsa_api_debug.log 
# Allows function entry tracing. 
RSA_DEBUG_ENTRY=YES 
# Allows function exit tracing. 
RSA_DEBUG_EXIT=YES 
# Allows control flow tracing. 
RSA_DEBUG_FLOW=YES 
# Allows regular tracing. 
RSA_DEBUG_NORMAL=YES 
# Traces the location. 
RSA_DEBUG_LOCATION=YES

See Also

Authentication modules in AM/OpenAM

Source code in ForgeRock products


Known Issues


SecurID authentication module login fails in AM/OpenAM (All versions) with java.lang.NoClassDefFoundError

The purpose of this article is to provide assistance if you receive a "java.lang.NoClassDefFoundError: com/rsa/authagent/authapi/AuthAgentException" when attempting to log into the SecurID® authentication module in AM/OpenAM.

Symptoms

The following error is shown in the web application container log (for example, catalina.out for Apache Tomcat™) when the login to the SecurID authentication module fails:

Caused by: java.lang.NoClassDefFoundError: com/rsa/authagent/authapi/AuthAgentException 
  at java.lang.Class.forName0(Native Method) 
  at java.lang.Class.forName(Class.java:274) 
  at com.sun.identity.authentication.service.AuthUtils.isPureJAASModulePresent(AuthUtils.java:1515) 
  at com.sun.identity.authentication.service.AMLoginContext.executeLogin(AMLoginContext.java:390) 
  at com.sun.identity.authentication.server.AuthContextLocal.login(AuthContextLocal.java:544) 
  at com.sun.identity.authentication.server.AuthContextLocal.login(AuthContextLocal.java:436) 
  at com.sun.identity.authentication.server.AuthContextLocal.login(AuthContextLocal.java:287) 
  at com.sun.identity.authentication.server.AuthContextLocal.login(AuthContextLocal.java:219) 
  at com.sun.identity.authentication.UI.LoginViewBean.getLoginDisplay(LoginViewBean.java:916) 
  at com.sun.identity.authentication.UI.LoginViewBean.processLogin(LoginViewBean.java:862) 
  at com.sun.identity.authentication.UI.LoginViewBean.forwardTo(LoginViewBean.java:519) 
  at com.iplanet.jato.ApplicationServletBase.dispatchRequest(ApplicationServletBase.java:981) 
  at com.iplanet.jato.ApplicationServletBase.processRequest(ApplicationServletBase.java:615) 
  at com.iplanet.jato.ApplicationServletBase.doGet(ApplicationServletBase.java:459) 
  at javax.servlet.http.HttpServlet.service(HttpServlet.java:620) 
  at javax.servlet.http.HttpServlet.service(HttpServlet.java:727) 
  at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:303) 
... 28 more 

Recent Changes

Configured the SecurID authentication module.

Causes

ForgeRock is not licensed to redistribute the RSA® SecurID library (authapi jar). This error means the authapi jar (for example, authapi-2005-08-12.jar) is missing.

Solution

You must obtain the latest authapi jar file from RSA. They should provide this to you along with a dependency crypto.jarcryptoj.jar file. You should then include these files in the path/to/tomcat/webapps/openam/WEB-INF/lib directory where AM/OpenAM is deployed.

Note

As of AM 5, you should also obtain a version of the log4j library from RSA that is compatible with your version of the authapi jar file. See  OPENAM-9745 (SecurID Authentication not working, error displayed "Unknown error. Please contact your Administrator") for further information.

See Also

FAQ: SecurID authentication module in AM/OpenAM

Related Training

N/A

Related Issue Tracker IDs

N/A


SecurID authentication module is missing from OpenAM 13.0

The purpose of this article is to provide the missing SecurID® authentication module in OpenAM 13.0.

Symptoms

Following an upgrade (from an OpenAM instance with a working SecurID authentication module) to OpenAM 13.0, you see any of the following issues:

  • You get a "not found error" when trying to view or edit the module in a realm (Realm > Authentication > Modules).
  • You see that the SecurID module type is missing when you try to add a SecurID authentication module. Instead an iPlanetAMAuthSecurIDService type is visible; when you try to create a module of this type, it fails with a "Resource 'iPlanetAMAuthSecurIDService' not found" error.
  • You get an "Invalid parameters" message when trying to create a module of type SecurID via ssoadm.

Following the fresh installation of an OpenAM 13.0 instance, you see any of the following issues:

  • You see that the SecurID module type is missing when you try to add a SecurID authentication module.
  • You get an "Invalid parameters" message when trying to create a module of type SecurID via ssoadm.

Recent Changes

Installed, or upgraded to OpenAM 13.0.

Causes

Due to a bug in the build scripts of OpenAM 13.0, the SecurID authentication module was not correctly built and consequently not included in the final release of OpenAM 13.0.

Solution

This issue can be resolved by upgrading to OpenAM 13.5 or later; you can download this version from BackStage.

Alternatively, you apply a patch to OpenAM; this can either be applied to an existing deployment or to the OpenAM 13.0 WAR file prior to installation or upgrade.

Applying patch to existing OpenAM 13.0 deployment

  1. Download this patch file: SecurID-auth-13.0.0-tpatch.zip
  2. Follow the standard patch installation instructions to install the patch: How do I install an AM/OpenAM patch (All versions) supplied by ForgeRock support?
  3. Register the SecurID authentication service:
    $ ./ssoadm create-svc -u [adminID] -f [passwordfile] -X amAuthSecurID.xml
    replacing [adminID] and [passwordfile] with appropriate values.
  4. Register the SecurID authentication module:
    $ ./ssoadm register-auth-module -u [adminID] -f [passwordfile] -a com.sun.identity.authentication.modules.securid.SecurID
    replacing [adminID] and [passwordfile] with appropriate values.
  5. Restart the web application container in which OpenAM runs to have the patch take effect. 

Applying the patch to the OpenAM 13.0 WAR before an installation or upgrade 

  1. Download this patch file: SecurID-auth-13.0.0-tpatch.zip
  2. Unzip the patch file into a temporary directory where you also have a copy of the OpenAM 13.0 WAR file.
  3. Run the following jar command to update the WAR file with the key components from the patch:
    $ jar uf OpenAM-13.0.0.war README-securid-auth.tpatch WEB-INF/classes/serviceNames.properties WEB-INF/lib/openam-auth-securid-13.0.0.jar
    The resulting OpenAM-13.0.0.war file can now be used for a fresh installation and/or upgrade of an earlier version of OpenAM.
Note

You may also want to add the RSA® SecurID client libraries (the latest authapi jar file and a dependency crypto.jar / cryptoj.jar file) at the same time. To use the SecurID authentication module the supporting libraries need to be copied to the WEB-INF/lib directory of the OpenAM WAR file. These client libraries must be obtained from RSA.

See Also

FAQ: SecurID authentication module in AM/OpenAM

How do I build OpenAM 12.x and 13.x from source?

SecurID authentication module login fails in AM/OpenAM (All versions) with java.lang.NoClassDefFoundError

OpenAM Administration Guide › Defining Authentication Services › Hints For the SecurID Authentication Module

Related Issue Tracker IDs

OPENAM-8456 (SecurID authentication module is missing from 13.0.0)


WDSSO


How do I set up Windows Desktop SSO in AM/OpenAM (All versions)?

The purpose of this article is to provide information that will help guide you through understanding and configuring the Windows Desktop SSO (WDSSO) authentication module in AM/OpenAM. This functionality uses the Kerberos™ capabilities of Active Directory®.

Background information

The WDSSO authentication module allows users logged in to Microsoft® Windows® to access a resource protected by AM/OpenAM without further authentication. Prior to setting up the WDSSO module, you should ensure Kerberos is configured correctly; in particular, you should ensure the krb5.conf file has been set up (see krb5.conf for details) and that your firewall allows necessary communications (see Kerberos and Firewalls for the required ports). 

Some key things to be aware of when configuring the WDSSO module are:

  • If you are using Oracle® JDK 7, you must ensure both TCP port 88 and UDP port 88 are open in your firewall to allow communication between AM/OpenAM and Kerberos.
  • If you are using the WDSSO authentication module as part of an authentication chain and Windows Desktop SSO fails, you may no longer be able to POST data to non-NTLM-authenticated web sites. For information on a possible workaround, see KB251404: You cannot post data to a non-NTLM-authenticated Web site.
  • The userPrincipalName must be unique for all users.
  • The key version number (kvno) in the keytab file must equal the value of the msDS-KeyVersionNumber attribute for the AM/OpenAM principal in Active Directory +1. This is because Active Directory increases the value of kvno by 1 when you use the keypass command to create the keytab file and these values must match.
  • You must restart the web application container in which AM/OpenAM runs after making configuration changes to the WDSSO authentication module per known issue: OPENAM-5107 (Configuration changes of WindowsDesktopSSO auth module require restart)
Note

You can query the value of msDS-KeyVersionNumber in Active Directory using the ldapsearch command.

Setting up WDSSO

The following steps are required to set up WDSSO; below these steps is a video demonstration that covers the same process:

  1. Configure your browser for Windows authentication. The settings needed are specific to the browser you are using as detailed in the Browser Settings section below.
  2. Configure the WDSSO authentication module in the console:
    • AM / OpenAM 13.x console: navigate to: Realms > [Realm Name] > Authentication > Modules > [Module Name].
    • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Authentication > Module Instances > [Module Name].
    See Authentication and Single Sign-On Guide › Implementing Authentication › Windows Desktop SSO Authentication Module for further information on these options.
  3. Restart the web application container in which AM/OpenAM runs to apply these configuration changes.
  4. Set the login URL for the resource you are protecting so that it includes your WDSSO module. For example:
    • AM 5 and later:
      http://host1.example.com:8080/openam/XUI/?realm=/myrealm#login&module=WDSSO
    • Pre-AM 5:
      http://host1.example.com:8080/openam/XUI/#login&realm=/myrealm&module=WDSSO
    This means a user won't need to authenticate again when accessing this URL providing they are already logged in to Microsoft Windows.

Video demonstration 

Note

This video demonstration uses OpenAM 10.0.0; although the appearance has changed between OpenAM 10.x and later versions, the principles and processes are still applicable. In AM / OpenAM 13.x, the options under Access Control are now under Realms.

Browser Settings

The configuration required varies according to the browser you are using, as summarized below:

Internet Explorer® or Microsoft Edge

If you use Internet Explorer or Microsoft Edge, there are three settings you need to check and configure in Internet Options:

  • Ensure the Enable Integrated Windows Authentication option is selected. This option is found on the Advanced tab under Security.
  • Ensure the Automatic logon only in Intranet zone option is selected. This option can be accessed from the Security tab. Select Local Intranet and then click the Custom Level button. This option can then be found under User Authentication > Logon.
  • Add the AM/OpenAM FQDN to the trusted Intranet site list. This list can be accessed from the Security tab. Select Local Intranet and then click the Sites button, followed by the Advanced button.

You must restart Internet Explorer or Microsoft Edge for these settings to take effect.

Note

WDSSO only works with Internet Explorer and Microsoft Edge when the server uses HTTP persistent connection.

Chrome™

Chrome inherits its settings from Internet Explorer or Microsoft Edge when you are using Microsoft Windows so will work providing you have configured Internet Explorer or Microsoft Edgeas detailed above.

Firefox®

If you use Firefox, you can use a plugin called Integrated Authentication. You should ensure the AM/OpenAM FQDN is added to the Integrated Authentication Sites list (Tools > Integrated Authentication Sites) if you're using the Integrated Authentication plugin.

Alternatively, you can change the equivalent Firefox setting (network.negotiate-auth.trusted-uris) via about:config.

Safari®

Safari has built-in support for Kerberos SSO and no additional configuration is required.

See Also

OpenAM Windows Desktop SSO deep dive – part 1

How do I set up the WDSSO authentication module in AM/OpenAM (All versions) in a load balanced environment?

How do I troubleshoot WDSSO and Kerberos issues in AM/OpenAM (All versions)?

How do I enable debug logging for troubleshooting WDSSO and Kerberos issues in AM/OpenAM (All versions)?

Configuring and troubleshooting WDSSO in AM/OpenAM

Kerberos token is not valid error when authenticating with Windows Desktop SSO in AM/OpenAM (All versions) using Internet Explorer

Authenticating with Windows Desktop SSO in AM/OpenAM (All versions) does not proceed when using non-Internet Explorer browser

Authentication and Single Sign-On Guide › Implementing Authentication › Windows Desktop SSO Authentication Module

Related Training

N/A

Related Issue Tracker IDs

OPENAM-3400 (Chain authentication not working when using Internet Explorer 9, 10, 11)

OPENAM-3826 (WindowsDesktopSSO auth-module does not log details about GSSException)

OPENAM-5107 (Configuration changes of WindowsDesktopSSO auth module require restart)

OPENAM-6180 (Uncheck “Enable Integrated Windows Authentication” statement in docs)


How do I set up the WDSSO authentication module in AM/OpenAM (All versions) in a load balanced environment?

The purpose of this article is to provide information on setting up the Windows Desktop SSO (WDSSO) authentication module in AM/OpenAM in a load balanced environment, where multiple AM/OpenAM instances are running in a site. This article assumes you already have a working WDSSO authentication module and want to scale your WDSSO solution.

Overview

Typically, AM/OpenAM is deployed in a site environment with multiple AM/OpenAM instances running behind a load balancer, where:

  • Authentication modules share the same configuration across all AM/OpenAM instances behind the load balancer; the configuration is not server specific. In terms of the WDSSO authentication module, this means the keytab file is also shared.
  • Multiple AM/OpenAM instances in a site act as one under the configured load balancer's hostname.

When you configure the WDSSO authentication module in this environment, you need to ensure the service provider name is set to the load balancer host/domain rather than to a single AM/OpenAM instance and that this service provider name is used to create the keytab file. The steps you should follow to complete this setup are detailed in the following section.

Setting up the WDSSO authentication module in a load balanced environment

The following example details are used in this process:

  • Load balancer / site FQDN - http://lb.openam.com:8080/openam
  • Service principal name: HTTP/lb.openam.com@FORGEROCK.COM

You can configure the WDSSO authentication module in a load balanced environment as follows:

  1. Set up your separate AM/OpenAM instances in a site with a load balancer:
  2. Create an Active Directory® account to use as your Kerberos™ principal (user), for example: openamKerberos. See OpenAM Windows Desktop SSO deep dive – part 1 (Create an account in active directory for your Kerberos principal section) for further information on this step if required.
  3. Formulate a Service Principal in Active Directory that uses the load balancer URL, this is being formulated to use in the next step when creating the keytab file. You should specify the Kerberos™ principal for authentication in the following format, where DC-DOMAIN-NAME is in upper case and is typically the Kerberos realm name (the FQDN of the Active Directory domain):
    HTTP/lbhost.domain@DC-DOMAIN-NAME
    For example:
    HTTP/lb.openam.com@FORGEROCK.COM
  4. Create the keytab file for the WDSSO authentication module using a ktpass command such as:
    $ ktpass -out lb.HTTP.keytab -princ HTTP/lb.example.com@FORGEROCK.COM -pass +rndPass -maxPass 256 -mapuser openamKerberos -crypto All -ptype KRB5_NT_PRINCIPAL -kvno n
    
    Where:
    • -princ is the name of the service principal you formulated in step 3.
    • -pass is set to use a very robust password with the +rndpass and -maxpass options setting a random 256 character password on the account, which is then used to derive the key in the Kerberos service principal.
    • -mapuser is the name of the user you created in step 2. 
    • -crypto is set to All to allow all supported crypto types to be used. If you do specify a specific encryption type and use AES256-SHA1, you must have the Oracle® Java JCE unlimited strength jars installed in the $JAVA_HOME/jre/lib/security/ directory and your Microsoft® Windows® machine must also support this encryption.
    • -kvno - the key version number (kvno) in the keytab file must equal the value of the msDS-KeyVersionNumber attribute for the AM/OpenAM principal in Active Directory +1. This is because Active Directory increases the value of kvno by 1 when you use the keypass command to create the keytab file and these values must match.
    This ktpass command gives the following output:
    Targeting domain controller: WIN2012LAB.forgerock.com
    Successfully mapped HTTP/lb.example.com to openamKerberos.
    Password successfully set!
    Key created.
    Output keytab to lb.HTTP.keytab:
    Keytab version: 0x502
    keysize 84 HTTP/lb.example.com@FORGEROCK.com ptype 1 (KRB5_NT_PRINCIPAL) vno 0 e
    type 0x12 (AES256-SHA1) keylength 32 (0xc2072ad3157629437adbc7c2fa637fa4f8b6569e
    12c446d5970cd52cf35f6b71)
    
    See OpenAM Windows Desktop SSO deep dive – part 1 (Creating a KeyTab file) for further information on this step if required.
  5. Copy the generated keytab file to all AM/OpenAM instances in your site. You must place this keytab file in the exact same location on all servers as the keytab location can only be set in one place and this location is then shared across all instances (for example: /tmp/openam.HTTP.keytab).
  6. Update the WDSSO authentication module on one AM/OpenAM instance to use the service principal name you formulated in step 3 (for example: HTTP/lb.openam.com@FORGEROCK.COM). You can do this in the console as follows:
    • AM / OpenAM 13.x console: navigate to Realms > [Realm Name] > Authentication > Modules > [Module Name] > Service Principal and enter the new value.
    • Pre-OpenAM 13 console: navigate to Access Control > [Realm Name] > Authentication >  Module Instances > [Module Name] > Service Principal and enter the new value.
  7. Update the WDSSO authentication module on one AM/OpenAM instance to set the location of the keytab file to match where you placed it in step 5 (for example: /tmp/openam.HTTP.keytab). You can do this in the console as follows:
    • AM / OpenAM 13.x console: navigate to Realms > [Realm Name] > Authentication > Modules > [Module Name] > Keytab File Name and enter the new value.
    • Pre-OpenAM 13 console: navigate to Access Control > [Realm Name] > Authentication >  Module Instances > [Module Name] > Keytab File Name and enter the new value.
  8. Restart the web application container in which AM/OpenAM runs to apply these changes.
  9. Test the WDSSO authentication module going through the load balancer; that is, check that the protected sites and policy agents are configured to use the load balancer FQDN instead of an individual OpenAM server. For example, you can authenticate with the WDSSO authentication module via:
    http://lb.openam.com:8080/openam

See Also

How do I set up Windows Desktop SSO in AM/OpenAM (All versions)?

OpenAM Windows Desktop SSO deep dive – part 1

How do I specify multiple Kerberos servers in AM/OpenAM (All versions) for failover purposes?

How do I redirect users to a different login module if Kerberos/WDSSO authentication fails with a 401 error in OpenAM 11.x and 12.x using the Classic UI?

Configuring and troubleshooting WDSSO in AM/OpenAM

Installation Guide › Installing and Starting Servers › Installing Multiple Servers

Authentication and Single Sign-On Guide › Implementing Authentication › Windows Desktop SSO Authentication Module

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I specify multiple Kerberos servers in AM/OpenAM (All versions) for failover purposes?

The purpose of this article is to provide information on specifying multiple Kerberos™ Domain Controllers (DCs) in AM/OpenAM for failover purposes when configuring the Windows Desktop SSO (WDSSO) authentication module.

Specifying multiple Kerberos DCs

If you have multiple Kerberos DCs configured for failover purposes, you can specify them when configuring the WDSSO authentication module at the global or realm level.

Note

If you have set up the WDSSO module with multiple Kerberos DCs and have used a keytab file from one of the trusted DCs, you should be aware that all users from the trusted domains can authenticate through the WDSSO module. Configuring and managing Active Directory Domain Trusts is outside the scope of this article and ForgeRock Support.

Global level

You can configure multiple Kerberos DCs at the global level using either the console or ssoadm:

  • AM / OpenAM 13.5 console: navigate to: Configure > Authentication > Windows Desktop SSO > Kerberos Server Name and specify the server names using a colon as a separator, for example:
    primary_server:secondary_server:tertiary_server
  • Pre-OpenAM 13.5 console: navigate to: Configuration > Authentication > Windows Desktop SSO > Kerberos Server Name and specify the server names using a colon as a separator, for example:
    primary_server:secondary_server:tertiary_server
  • ssoadm: enter the following command:
    $ ./ssoadm set-attr-defs -s iPlanetAMAuthWindowsDesktopSSOService -t organization -u [adminID] -f [passwordfile] -a iplanet-am-auth-windowsdesktopsso-kdc="[servers]"
    
    replacing [adminID], [passwordfile] and [servers] with appropriate values, where [servers] must be contained within " " and each server name is separated with a colon.

An example ssoadm command to add two Kerberos DCs at the global level looks like this:

$ ./ssoadm set-attr-defs -s iPlanetAMAuthWindowsDesktopSSOService -t organization -u amadmin -f pwd.txt -a iplanet-am-auth-windowsdesktopsso-kdc="kdc.example.com:kdc2.example.com"

Realm level

You can configure multiple Kerberos DCs at the realm level using either the console or ssoadm:

  • AM / OpenAM 13.x console: navigate to: Realms > [Realm Name] > Authentication > Modules > [WDSSO Module] > Kerberos Server Name and specify the server names using a colon as a separator, for example:
    primary_server:secondary_server:tertiary_server
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Authentication > Module Instances > [WDSSO Module] > Kerberos Server Name and specify the server names using a colon as a separator.
  • ssoadm: enter the following command:
    $ ./ssoadm set-realm-svc-attrs -s iPlanetAMAuthWindowsDesktopSSOService -e [realmname] -u [adminID] -f [passwordfile] -a iplanet-am-auth-windowsdesktopsso-kdc="[servers]"
    
    replacing [realmname], [adminID], [passwordfile] and [servers] with appropriate values, where [servers] must be contained within " " and each server name is separated with a colon.

An example ssoadm command to add two Kerberos DCs at the realm level looks like this:

$ ./ssoadm set-realm-svc-attrs -s iPlanetAMAuthWindowsDesktopSSOService -e employees -u amadmin -f pwd.txt -a iplanet-am-auth-windowsdesktopsso-kdc="kdc.example.com:kdc2.example.com"

See Also

How do I set up Windows Desktop SSO in AM/OpenAM (All versions)?

OpenAM Windows Desktop SSO deep dive – part 1

Configuring and troubleshooting WDSSO in AM/OpenAM

Authentication and Single Sign-On Guide › Implementing Authentication › Windows Desktop SSO Authentication Module

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I get the WDSSO authentication module to work in AM/OpenAM (All versions) with the IBM Kerberos implementation?

The purpose of this article is to provide information on getting the Windows Desktop SSO (WDSSO) authentication module to work in AM/OpenAM using the IBM® Kerberos™ implementation. This applies when you have deployed AM/OpenAM on IBM WebSphere® and are using the IBM JVM.

Enabling the IBM Kerberos implementation

The WDSSO authentication module uses the Oracle® Kerberos implementation by default. If you are using the IBM JVM, you must enable the IBM Kerberos implementation to allow the WDSSO authentication module to function correctly.

Note

When enabling the IBM Kerberos implementation via the console or ssoadm, you will get a warning about unidentified property or invalid property; you can ignore this warning as the property is still added successfully.

You can enable the IBM Kerberos implementation using either the console or ssoadm:

  • AM / OpenAM 13.5 console: navigate to: Configure > Server Defaults > Advanced and add the following property and value:
    com.sun.identity.authentication.module.WindowsDesktopSSO.Krb5LoginModule = com.ibm.security.auth.module.Krb5LoginModule
    Once you have entered the property and value, click + to add followed by Save Changes.
  • Pre-OpenAM 13.5 console: navigate to: Configuration > Servers and Sites > Default Server Settings > Advanced and add the following property and value:
    com.sun.identity.authentication.module.WindowsDesktopSSO.Krb5LoginModule = com.ibm.security.auth.module.Krb5LoginModule
  • ssoadm: enter the following command:
    $ ./ssoadm update-server-cfg -s default -u [adminID] -f [passwordfile] -a com.sun.identity.authentication.module.WindowsDesktopSSO.Krb5LoginModule=com.ibm.security.auth.module.Krb5LoginModule
    replacing [adminID] and [passwordfile] with appropriate values. 

Adding this property to the Server Defaults ensures it will be inherited by any AM/OpenAM server sharing the same configuration store.

Note

You must restart the web application container in which AM/OpenAM runs to apply these configuration changes. 

See Also

How do I set up Windows Desktop SSO in AM/OpenAM (All versions)?

OpenAM Windows Desktop SSO deep dive – part 1

How do I set up the WDSSO authentication module in AM/OpenAM (All versions) in a load balanced environment?

How do I specify multiple Kerberos servers in AM/OpenAM (All versions) for failover purposes?

How do I redirect users to a different login module if Kerberos/WDSSO authentication fails with a 401 error in OpenAM 11.x and 12.x using the Classic UI?

Configuring and troubleshooting WDSSO in AM/OpenAM

Authentication and Single Sign-On Guide › Implementing Authentication › Windows Desktop SSO Authentication Module

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I use the WDSSO module to authenticate via REST in AM/OpenAM (All versions)?

The purpose of this article is to provide information on using the Windows Desktop Single-Sign On (WDSSO) module to authenticate via the REST API in AM/OpenAM.

Background information

The WDSSO authentication module uses Kerberos authentication. The user presents a Kerberos token to AM/OpenAM through the Simple and Protected GSS-API Negotiation Mechanism (SPNEGO) protocol. 

In order to authenticate via the REST API, the REST client needs to have access to the Kerberos side of things. For example, you can use curl because it has support for SPNEGO and Kerberos (as of version 7.10.6), but Postman currently does not. 

You can check that your version of curl does support SPNEGO and Kerberos using the -V option as follows:

$ curl -V

curl 7.54.0 (x86_64-apple-darwin16.0) libcurl/7.54.0 SecureTransport zlib/1.2.8
Protocols: dict file ftp ftps gopher http https imap imaps ldap ldaps pop3 pop3s rtsp smb smbs smtp smtps telnet tftp
Features: AsynchDNS IPv6 Largefile GSS-API Kerberos SPNEGO NTLM NTLM_WB SSL libz UnixSockets

Using the WDSSO module to authenticate via REST

To authenticate using the WDSSO module, you need to include the following options:

  • -u  - this is a fake user option needed to activate the authentication code.
  • --negotiate - this enables the Negotiate (SPNEGO) authentication.

For example, you can authenticate with a command such as the following:

$ curl "http://host1.example.com:8080/openam/json/authenticate?service=winsso&authIndexType=service&authIndexValue=winsso" -X POST -u : --negotiate 

Example response:

{ "tokenId": "AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*", "successUrl": "/openam/console"}

See Also

How do I troubleshoot WDSSO and Kerberos issues in AM/OpenAM (All versions)?

FAQ: REST API in AM/OpenAM

Using the REST API in AM/OpenAM

Configuring and troubleshooting WDSSO in AM/OpenAM

Postman: New feature: Support API endpoints protected by kerberos

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I troubleshoot WDSSO and Kerberos issues in AM/OpenAM (All versions)?

The purpose of this article is to provide information on troubleshooting Windows Desktop SSO (WDSSO) and Kerberos™ issues in AM/OpenAM. You can use the collected data to troubleshoot issues yourself or include it when you raise a ticket to enable us to help you more effectively.

Troubleshooting WDSSO and Kerberos issues

If you are experiencing issues with your WDSSO module and/or Kerberos setup in AM/OpenAM, you can use the following troubleshooting steps to debug your issue:

  1. Generate a full set of message level debug logs and capture the HTTP trace while reproducing the issue. Required debug logs include the AM/OpenAM ones and the debug logs for the How do I enable debug logging for troubleshooting WDSSO and Kerberos issues in AM/OpenAM (All versions)? of the JVM (this module is called by AM/OpenAM for WDSSO purposes).
  2. Verify a Kerberos token has been sent (rather than a NTLM token).
  3. Enable Kerberos event logging on the Microsoft® Windows® / Active Directory® server as detailed in: Microsoft - How to enable Kerberos event logging.
  4. Export the configuration for your WDSSO module - it is essential to check if a configuration issue is contributing to your issues.
  5. Check your keytab file details are correct.
  6. Check your browser settings are correct.
  7. Check other configuration details.
  8. Check connection to Kerberos Key Distribution Center (KDC).

Additionally, information is included about the expected access flows for WDSSO authentication (with a policy agent protected resource) and a federated environment. These flows can help you track down where the breakdown in WDSSO is occurring, which can help focus your troubleshooting efforts. 

If you need to raise a ticket to troubleshoot an issue, you should include relevant information to help us investigate your issues more effectively. Refer to Best practice for raising a ticket with ForgeRock Support for further information on creating a ticket.

Note

If none of these resolve the issue, another problem must exist with the Kerberos protocol between the browser and Active Directory; you can attempt to track this down using utilities such as the Microsoft Network Monitor or the Microsoft Message Analyzer.

Understanding access flows for WDSSO

Windows Desktop SSO Authentication​

The expected access flow for WDSSO single sign-on (SSO) with a policy agent protected resource is as follows: 

  1. The user attempts to access the protected resource with a SPNEGO-enabled browser.
  2. The policy agent intercepts the request and redirects to the AM/OpenAM server.
  3. The AM/OpenAM server returns a HTTP 401 Authenticate/Negotiate response.
  4. The browser sends the following to the Active Directory server:
    • a request for the Ticket Granting Ticket (TGT) if a TGT does not already exist. 
    • a request (accompanied by the TGT) for a Kerberos Service Ticket.
  5. The Kerberos Domain Controller sends a Service Ticket to the browser.
  6. The browser sends HTTP, POST, GET, Web-Service and SPNEGO tokens to the AM/OpenAM server.
  7. The WDSSO module validates the SPNEGO token and retrieves the user profile from the user data store.
  8. The AM/OpenAM server creates an SSO Token.
  9. The AM/OpenAM server returns a HTTP 200 OK response and the SSO Token to the browser.
  10. The browser sends the SSO token to the policy agent and the policy agent grants access to the protected resource.

Federated environment

The expected access flow for WDSSO in a federated environment is as follows: 

  1. The user attempts to access the protected resource at the service provider (SP).
  2. The SP sends the authorization request to the AM/OpenAM identity provider (IdP).
  3. The AM/OpenAM IdP returns a HTTP 401 Authenticate/Negotiate response.
  4. The browser sends the following to the Active Directory server:
    • a request for the Ticket Granting Ticket (TGT) if a TGT does not already exist. 
    • a request (accompanied by the TGT) for a Kerberos Service Ticket.
  5. The Kerberos Domain Controller sends a Service Ticket to the browser.
  6. The browser sends HTTP, POST, GET, Web-Service and SPNEGO tokens to the AM/OpenAM IdP.
  7. The WDSSO module validates the SPNEGO token and retrieves the user profile from the user data store.
  8. The AM/OpenAM IdP creates an SSO Token.
  9. The AM/OpenAM IdP returns a HTTP 200 OK response and the SSO Token to the browser.
  10. The AM/OpenAM IdP sends the authorization response of Success to the SP and the SP grants access.

Generating debug logs and capturing the HTTP trace

It is important to ensure your debug logs and HTTP trace have corresponding date and timestamps. You should follow this process:

  1. Enable message level debugging as described in How do I enable Message level debugging in AM/OpenAM (All versions) debug files? 
  2. Clear the AM/OpenAM debug logs as described in How do I clear debug logs in AM/OpenAM (All versions)?
  3. Enable debug logging for the Krb5LoginModule of the JVM; this adds additional logging to the container's standard logs, which allows you to trace the program's execution of the Kerberos V5 protocol. You can enable debug logging as detailed in How do I enable debug logging for troubleshooting WDSSO and Kerberos issues in AM/OpenAM (All versions)?
  4. Start a HTTP trace in your browser. You can do this by capturing a HAR file as described in How do I create a HAR file for troubleshooting AM/OpenAM (All versions)?
  5. Reproduce the issue using your browser.
  6. Stop the HTTP trace.

Verifying a Kerberos token has been sent

Microsoft Windows will first try Kerberos; unless all the requirements are met, it will fallback to NTLM authentication. 

You can use the output from the HTTP trace captured in the above section to check that a Kerberos token has been sent as follows:

  1. Examine the output from the HTTP trace tool. You are looking for the Authorization: Negotiate section:
    • If this begins YII, then Kerberos is being used, for example:
      Authorization: Negotiate YIIVDAYGKwYBE...
    • If this begins TlR, then Kerberos is not being used,  for example:
      Authorization: Negotiate TlRMTVNTUA...

You can also check the Authentication log to see if it has fallen back to NTLM authentication. If it has, you will see the following error:

ERROR: kerberos token is not valid 

See Kerberos token is not valid error when authenticating with Windows Desktop SSO in AM/OpenAM (All versions) using Internet Explorer for further information on this error.

Exporting the WDSSO module configuration

You can export this configuration using the following ssoadm command:

$ ./ssoadm get-auth-instance -e [realmname] -m [modulename] -u [adminID] -f [passwordfile]

Replacing [realmname], [modulename], [adminID] and [passwordfile] with appropriate values.

For example:

$ ./ssoadm get-auth-instance -e / -m wdsso -u amadmin -f pwd.txt

Example response:

Authentication Instance profile:
iplanet-am-auth-windowsdesktopsso-returnRealm=false
iplanet-am-auth-windowsdesktopsso-auth-level=0
iplanet-am-auth-windowsdesktopsso-kerberos-realm=FORGEROCK.COM
iplanet-am-auth-windowsdesktopsso-lookupUserInRealm=false
iplanet-am-auth-windowsdesktopsso-kdc=host1.example.com
iplanet-am-auth-windowsdesktopsso-principal-name=HTTP/host1.example.com@FORGEROCK.COM
iplanet-am-auth-windowsdesktopsso-keytab-file=/tmp/keytab

Checking keytab file details

First you should check the keytab file exists in the location detailed in the WDSSO module export; if it does not, you should update the WDSSO module details. You should also ensure that the user that AM/OpenAM is running as has read access permissions to the keytab file.

You can then output details for your keytab file using either the Kerbtray or Klist utilities from Microsoft (depending on Microsoft Windows version). For example:

$ klist

An example output from the Klist utility is:

Server: HTTP/host1.example.com @ FORGEROCK.COM
KerbTicket Encryption Type: RSADSI RC4-HMAC(NT)
Ticket Flags 0x40a10000 -> forwardable renewable pre_authent name_canonicalize
Start Time: 3/17/2016 11:33:06 (local)
End Time: 3/17/2016 21:31:54 (local)
Renew Time: 3/24/2016 11:31:54 (local)
Session Key Type: RSADSI RC4-HMAC(NT)
Cache Flags: 0
Kdc Called: SVR1

You can then check the following and resolve as applicable:

  • Check the Kerberos service ticket was retrieved for AM/OpenAM:
    • If the Kerberos service ticket does exist for the AM/OpenAM FQDN - check your browser settings to ensure the browser is correctly set up for Windows authentication and update where necessary. See the Checking your browser settings are correct section below for further information.
    • If the Kerberos service ticket does not exist for the AM/OpenAM FQDN - continue troubleshooting.
  • Check you have used an appropriate encryption type (KerbTicket Encryption Type in example Klist output) when generating the keytab file and that you have updated the user account properties in Active Directory to match. The corresponding encryption type should be selected in the user account properties. If you want to use a 256-bit AES encryption type, you must have the Oracle® Java JCE unlimited strength jars installed in the $JAVA_HOME/jre/lib/security/ directory and your Microsoft Windows machine must also support this encryption. 
  • Check the service principal defined in AM/OpenAM (iplanet-am-auth-windowsdesktopsso-principal-name in WDSSO module export) matches the one in the keytab file (Server in Klist output). This can be determined by looking at the Kerberos ticket with klist to see what Principal was actually authenticated in Kerberos.
  • The key version number (kvno) in the keytab file must equal the value of the msDS-KeyVersionNumber attribute for the AM/OpenAM principal in Active Directory +1. This is because Active Directory increases the value of kvno by 1 when you use the keypass command to create the keytab file and these values must match.
Note

You can query the value of msDS-KeyVersionNumber in Active Directory using the ldapsearch command.

Checking your browser settings are correct

You should check the following specific browser settings: 

  • Check the AM/OpenAM FQDN is listed as a trusted host in the browser and add it if it's not listed. You can check as follows according to which browser you are using:
    • Internet Explorer® and Microsoft Edge - the AM/OpenAM FQDN should be added to the trusted Intranet site list (Security tab > Local Intranet > Sites > Advanced).
    • Chrome™ - since Chrome uses the Internet Explorer or Microsoft Edgesettings, you should check the AM/OpenAM FQDN is added to the trusted Intranet site list per the previous bullet.
    • Firefox - the AM/OpenAM FQDN should be added to the Integrated Authentication Sites list (Tools > Integrated Authentication Sites) if you're using the Integrated Authentication plugin. The equivalent Firefox setting is network.negotiate-auth.trusted-uris (accessed via about:config).
  • If you use Internet Explorer or Microsoft Edge, there are two more settings you need to check and configure in Internet Options:
    • Ensure the Enable Integrated Windows Authentication option is selected. This option is found on the Advanced tab under Security.
    • Ensure the Automatic logon only in Intranet zone option is selected. This option can be accessed from the Security tab. Select Local Intranet and then click the Custom Level button. This option can then be found under User Authentication > Logon.
    You must restart Internet Explorer or Microsoft Edge for these settings to take effect.
Note

WDSSO only works with Internet Explorer and Microsoft Edge when the server uses HTTP persistent connection.

  • If you use Chrome, Chrome inherits its settings from Internet Explorer or Microsoft Edge when you are using Microsoft Windows so will work providing you have configured Internet Explorer or Microsoft Edge as detailed above.
  • If you use Firefox, you can use a plugin called Integrated Authentication. You should ensure the AM/OpenAM FQDN is added to the Integrated Authentication Sites list (Tools > Integrated Authentication Sites) if you're using the Integrated Authentication plugin. Alternatively, you can change the equivalent Firefox setting (network.negotiate-auth.trusted-uris) via about:config.
  • If you use Safari®, Safari has built-in support for Kerberos SSO and no additional configuration is required.

Checking other configuration details

You should also check the following configuration details: 

  • The krb5.conf file has been set up; this file contains the Kerberos configuration information (see krb5.conf for details).
  • An Active Directory datastore is configured for the realm you are using and you can see the Active Directory users on the Identities page (previously the Subjects tab) in that realm. 
  • Your credentials are correct. You can check them by logging into the realm for the authentication chain that includes the WDSSO module using your Active Directory user credentials. For example, the URL would be similar to this, where the authentication chain is ldapService and the realm is top level:
    http://host1.example.com:8080/openam/XUI/#login/&service=ldapService
  • The Service Principal Name (SPN) for the AM/OpenAM service is correct in Active Directory; ensure the FQDN, which matches the SPN in Active Directory is used and the specified authcontext matches the authentication module/chain for WDSSO. You can use the following command to check the SPN:
    $ setspn -l [account]
    replacing [account] with the name of the account created for AM/OpenAM. An example command looks like this:
    $ setspn -l openam
    and gives an output as follows:
    Registered ServicePrincipalNames for CN=OpenAM,OU=employees,DC=example,DC=com:
    
    HTTP/host1.example.com
  • The Kerberos realm name (FQDN of the Active Directory domain) is all in upper case letters everywhere (keytab, WDSSO module configuration, etc). For example, FORGEROCK.COM.
  • The userPrincipalName must be unique for all users.
  • If you are using Oracle® JDK 7, you must ensure both TCP port 88 and UDP port 88 are open in your firewall to allow communication between AM/OpenAM and Kerberos.
  • The Kerberos Server Name is an A record and not a CNAME, and that the reverse (PTR) record for that IP also resolves back to that Server Name.
  • If you are using the Windows Desktop SSO module as part of an authentication chain and Windows Desktop SSO fails, you may no longer be able to POST data to non-NTLM-authenticated web sites. For information on a possible workaround, see KB251404: You cannot post data to a non-NTLM-authenticated Web site.

Checking connection to Kerberos Key Distribution Center (KDC)

Your firewall must be configured to allow necessary communications with Kerberos; see Kerberos and Firewalls for the required ports. 

You can test the connection to the Kerberos KDC using a third-party tool called HelloKDC.java. This tool will determine if there is a connection issue and give you guidance on what the issue might be. If it shows there is a connection issue, it means the issue is outside of AM/OpenAM and will need resolving before you attempt any further configuration / testing within AM/OpenAM.

Note

This is a third-party tool that we suggest can be used for troubleshooting but is not supported by ForgeRock.

The following links provide information about the HelloKDC.java tool:

Example

The following example shows a connection issue returned from HelloKDC.java, which correlates to an exception in the Authentication logs:

  • HelloKDC.java output:
    >>>KRBError:
         sTime is Thu Jul 20 14:21:25 GMT 2017 1498776265000
         suSec is 154839
         error code is 25
         error Message is Additional pre-authentication required
    ...
    KRBError received: Need to use PA-ENC-TIMESTAMP/PA-PK-AS-REQ
    
  • Authentication logs:
    amAuth:20/07/2017 20 14:21:25 GMT: Thread[http-nio-8443-exec-1,5,main]: TransactionId[daffa5fe-cca9-4a16-8cc3-dec02f21a81f-57]
    Exception : 
    com.sun.identity.authentication.spi.AuthLoginException: Service authentication failed.
    Additional pre-authentication required (25) - Need to use PA-ENC-TIMESTAMP/PA-PK-AS-REQ
    

As you can see, both are showing an error code 25: Additional pre-authentication required (Need to use PA-ENC-TIMESTAMP/PA-PK-AS-REQ). Seeing the same error returned from HelloKDC.java confirms this issue is independent of AM/OpenAM and will need to be resolved outside of ForgeRock support. 

See Also

How do I set up Windows Desktop SSO in AM/OpenAM (All versions)?

OpenAM Windows Desktop SSO deep dive – part 1

Configuring and troubleshooting WDSSO in AM/OpenAM

WDSSO authentication fails with GSSException: Failure unspecified at GSS-API level error in AM/OpenAM (All versions)

How do I collect all the data required for troubleshooting AM/OpenAM and Policy Agents (All versions)?

Java 8 - Troubleshooting Kerberos Login

Related Training

N/A

Related Issue Tracker IDs

OPENAM-3826 (WindowsDesktopSSO auth-module does not log details about GSSException)

OPENAM-5894 (Can't update WindowsDesktopSSO module with ssoadm)


How do I enable debug logging for troubleshooting WDSSO and Kerberos issues in AM/OpenAM (All versions)?

The purpose of this article is to provide information on enabling debug logging for troubleshooting Windows Desktop SSO (WDSSO) and Kerberos™ issues in AM/OpenAM. Debug logging applies to the Krb5LoginModule of the JVM used by the web application container; this module is called by AM/OpenAM for WDSSO purposes.

Enabling debug logging

You can enable debug logging for the Krb5LoginModule of the JVM by setting the following JVM options in the application web container in which AM/OpenAM runs:

-Dsun.security.krb5.debug=true
-Dsun.security.jgss.debug=true

This setting adds additional debug output from the Krb5LoginModule to the stdout, which allows you to trace the program's execution of the Kerberos V5 protocol.

Additionally, you can set the following JVM option to enable debug logging for the SPNEGO token:

-Dsun.security.spnego.debug=true
Note

You should also ensure you have enabled Message level debugging in the AM/OpenAM debug logs as this provides much more information in the Authentication log. See How do I enable Message level debugging in AM/OpenAM (All versions) debug files? for further information.

Example using Apache Tomcat™ web container

With AM/OpenAM running in the Tomcat web container, you would enable debug logging by specifying CATALINA_OPTS settings in the setenv.sh file (typically located in the /tomcat/bin/ directory). If this file doesn't exist, you should create it in the same directory as the catalina.sh file (located in the /tomcat/bin/ directory).

To enable debug logging:

  1. Add the following line to the setenv.sh file:
    export CATALINA_OPTS="-Dsun.security.krb5.debug=true -Dsun.security.jgss.debug=true -Dsun.security.spnego.debug=true"
  2. Restart the web container.

The additional debug output will be sent to the Tomcat catalina.out log file by default.

Note

If you can't find an issue on the AM/OpenAM side or instead believe it to be an issue on the Microsoft® Windows® side, you can enable Kerberos event logging on the Windows / Active Directory® server as detailed in: Microsoft - How to enable Kerberos event logging.

See Also

How do I troubleshoot WDSSO and Kerberos issues in AM/OpenAM (All versions)?

How do I set up Windows Desktop SSO in AM/OpenAM (All versions)?

How do I collect all the data required for troubleshooting AM/OpenAM and Policy Agents (All versions)?

How do I record troubleshooting information in AM/OpenAM (All versions)?

Configuring and troubleshooting WDSSO in AM/OpenAM

OpenAM Windows Desktop SSO deep dive – part 1

Java 11 - Troubleshooting Kerberos Login

Java 8 - Troubleshooting Kerberos Login

Related Training

N/A

Related Issue Tracker IDs

OPENAM-3826 (WindowsDesktopSSO auth-module does not log details about GSSException)

OPENAM-5894 (Can't update WindowsDesktopSSO module with ssoadm)


Known Issues


WDSSO authentication fails with GSSException: Failure unspecified at GSS-API level error in AM/OpenAM (All versions)

The purpose of this article is to provide assistance if Windows Desktop SSO (WDSSO) authentication fails with a "GSSException: Failure unspecified at GSS-API level (Mechanism level: Encryption type AES256 CTS mode with HMAC SHA1-96 is not supported/enabled)" error in AM/OpenAM.

Symptoms

The following error is shown in the Authentication debug log when authentication fails:

amAuthWindowsDesktopSSO:12/10/2016 10:02:47:186 AM GMT: Thread[http-nio-8082-exec-8,5,main]: TransactionId[5abc2e7a-5281-477d-8f2e-afd6b4a51cf9-132]
ERROR: Authentication failed with PrivilegedActionException wrapped GSSException. Stack Trace
GSSException: Failure unspecified at GSS-API level (Mechanism level: Encryption type AES256 CTS mode with HMAC SHA1-96 is not supported/enabled)
   at sun.security.jgss.krb5.Krb5Context.acceptSecContext(Unknown Source)
   at sun.security.jgss.GSSContextImpl.acceptSecContext(Unknown Source)
   at sun.security.jgss.GSSContextImpl.acceptSecContext(Unknown Source)
   at com.sun.identity.authentication.modules.windowsdesktopsso.WindowsDesktopSSO$1.run(WindowsDesktopSSO.java:265)
...
Caused by: KrbException: Encryption type AES256 CTS mode with HMAC SHA1-96 is not supported/enabled
   at sun.security.krb5.EncryptionKey.findKey(Unknown Source)
   at sun.security.krb5.KrbApReq.authenticate(Unknown Source)
   at sun.security.krb5.KrbApReq.<init>(Unknown Source)
   at sun.security.jgss.krb5.InitSecContextToken.<init>(Unknown Source)
   ... 58 more

Recent Changes

The keytab file was created using a key with 256-bit AES encryption, for example with the following crypto option:

-crypto AES256-SHA1

Causes

256-bit AES encryption was not enabled on the machine where the keytab file was created. Java® 8 and earlier does not support 256-bit AES encryption by default; only 128-bit AES encryption is supported.

Solution

This issue can be resolved by installing the Oracle® Java JCE unlimited strength jars in the $JAVA_HOME/jre/lib/security/ directory and your Microsoft® Windows® machine must also support this encryption. These jars can be downloaded from the following link for Java 8 and earlier: Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files Download. Java 9 and later uses the unlimited policy files by default.

You should then re-create the keytab file.

Note

You can check that the keytab file has AES256 enabled as detailed in How do I troubleshoot WDSSO and Kerberos issues in AM/OpenAM (All versions)? (Checking keytab file details).

See Also

WDSSO/Kerberos authentication fails in AM/OpenAM (All versions) with an HTTP 400 Bad Request response

Unable to obtain password from user error when WDSSO authentication fails in AM/OpenAM (All versions)

Clock skew too great (37) error when WDSSO authentication fails in AM/OpenAM (All versions)

SAML redirect is ignored when doing an IdP or SP initiated SSO with WDSSO/Kerberos authentication in OpenAM 13.0 and 13.5

How do I troubleshoot WDSSO and Kerberos issues in AM/OpenAM (All versions)?

Configuring and troubleshooting WDSSO in AM/OpenAM

Authentication and Single Sign-On Guide › Implementing Authentication › Windows Desktop SSO Authentication Module

Related Training

N/A

Related Issue Tracker IDs

N/A


WDSSO/Kerberos authentication fails in AM/OpenAM (All versions) with an HTTP 400 Bad Request response

The purpose of this article is to provide assistance if Windows Desktop SSO/Kerberos™ authentication fails in AM/OpenAM with an HTTP 400 Bad Request response.

Symptoms

The browser hangs when attempting WDSSO/Kerberos authentication and you see the following response:

HTTP 400 - Bad Request

This may only affect some users, especially those who are members of a large number of Active Directory® groups.

Recent Changes

N/A

Causes

AM/OpenAM does not put a limit on the token size. This issue occurs when the Kerberos token being sent by the browser (in the Authorization: Negotiate section of the HTTP request header) is bigger than the max header size specified in the web application container's configuration file (server.xml if you are using Apache Tomcat™). This can happen when a user is a member of a large number of Active Directory groups, which results in a much larger token.

The default max header size in Tomcat is 8KB:

<Connector port="443" maxHttpHeaderSize="8192" protocol="HTTP/1.1" SSLEnabled="true"

The maxHttpHeaderSize attribute may not be present in the server.xml file, but still defaults to 8KB.

See Problems with Kerberos authentication when a user belongs to many groups for further information.

Solution

You can resolve this issue by excluding the PAC when issuing service tokens, since AM/OpenAMM does not need the PAC in order for WDSSO auto-login to be successful. You can achieve this by adding the following bit flag to the existing User Account Control settings in Active Directory for the account associated with the Service Principal Name (SPN) of AM/OpenAM:

0x2000000:  When KDC emits ticket for this service accounts, do NOT include the Privilege Attribute Certificate (PAC)

You should consult your Active Directory administrator on how to make this change or use a script such as: UserAccountControl - Add/Remove Bits. This change is outside the scope of ForgeRock support; if you want more tailored advice, consider engaging Professional Services.

Optional workaround

Alternatively, you can increase the max header size in the web application container. You should increase it to a size that will accommodate your expected token sizes; capturing a HTTP trace when authentication fails can help you determine the size of the token being passed in the header. Otherwise, increasing it to 16KB is a good starting point.

Note

This option may consume more memory; you should test this to determine the optimal size in your environment.

For example, for Tomcat:

  1. Edit the server.xml file and amend the maxHttpHeaderSize value, for example, to increase it to 16KB:
    <Connector port="443" maxHttpHeaderSize="16384" protocol="HTTP/1.1" SSLEnabled="true"
    
    
    If this attribute is not present, you should add it with the new value.

See Apache Tomcat 8 Configuration Reference for further information.

See Also

How do I troubleshoot WDSSO and Kerberos issues in AM/OpenAM (All versions)?

How do I enable debug logging for troubleshooting WDSSO and Kerberos issues in AM/OpenAM (All versions)?

Configuring and troubleshooting WDSSO in AM/OpenAM

Problems with Kerberos authentication when a user belongs to many groups

Related Training

N/A

Related Issue Tracker IDs

N/A


Kerberos token is not valid error when authenticating with Windows Desktop SSO in AM/OpenAM (All versions) using Internet Explorer

The purpose of this article is to provide assistance if you receive an "Error: kerberos token is not valid" when authenticating with the Windows Desktop SSO (WDSSO) authentication module in AM/OpenAM and using the Internet Explorer® or Microsoft® Edge browser. WDSSO only works with Internet Explorer or Microsoft Edge when the server uses HTTP persistent connection. The user sees a "401 Unauthorized / Access denied" error.

Symptoms

The user sees a 401 Unauthorized / Access denied error when they attempt to access a resource protected by AM/OpenAM, even though they are logged in to Microsoft Windows and another authentication module exists in the authentication chain. An authentication dialog may also display prior to the 401 error. 

An error similar to the following is shown in the Authentication log:

amAuthWindowsDesktopSSO:06/06/2014 08:39:06:540 AM CEST: Thread[http-bio-8080-exec-3,5,main] 
Init WindowsDesktopSSO. This should not happen often. 
amAuth:06/06/2014 08:39:06:540 AM CEST: Thread[http-bio-8080-exec-3,5,main] 
spi authLevel :0 
amAuth:06/06/2014 08:39:06:540 AM CEST: Thread[http-bio-8080-exec-3,5,main] 
module configuration authLevel :0 
amAuth:06/06/2014 08:39:06:540 AM CEST: Thread[http-bio-8080-exec-3,5,main] 
levelSet :false 
amAuthWindowsDesktopSSO:06/06/2014 08:39:06:540 AM CEST: Thread[http-bio-8080-exec-3,5,main] 
New Service Login ... 
amAuthWindowsDesktopSSO:06/06/2014 08:39:06:669 AM CEST: Thread[http-bio-8080-exec-3,5,main] 
Service login succeeded. 
amAuthWindowsDesktopSSO:06/06/2014 08:39:06:671 AM CEST: Thread[http-bio-8080-exec-3,5,main] 
SPNEGO token: 
4e 54 4c 4d 53 53 50 00 01 00 00 00 97 82 08 e2 
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 
06 02 f0 23 00 00 00 0f 
amAuthWindowsDesktopSSO:06/06/2014 08:39:06:671 AM CEST: Thread[http-bio-8080-exec-3,5,main] 
token tag:4e 
amAuthWindowsDesktopSSO:06/06/2014 08:39:06:671 AM CEST: Thread[http-bio-8080-exec-3,5,main] 
ERROR: kerberos token is not valid.

Recent Changes

Implemented the Windows Desktop SSO authentication module.

Causes

Internet Explorer or Microsoft Edge returns a NTLM token instead of a Kerberos™ token during the SPNEGO handshake because it cannot retrieve a Kerberos service ticket for AM/OpenAM from Active Directory®. This is indicated by the token tag in the Authentication log, where 4e is a NTLM token; if it was a Kerberos token, the token tag would be 60.

Two common reasons for the browser failing to send a Kerberos token are:

  • The AM/OpenAM FQDN is not listed as a trusted host in the browser.
  • The Service Principal Name (SPN) is not set up correctly in Active Directory.

Solution

This issue can be resolved by checking the following:

  1. Check if the Kerberos service ticket was retrieved for AM/OpenAM using either the Kerbtray or Klist utilities from Microsoft (depending on Microsoft Windows version). For example:
    • If the Kerberos service ticket does exist for the AM/OpenAM FQDN - check your browser settings to ensure the browser is correctly set up for Windows authentication and update where necessary. See How do I set up Windows Desktop SSO in AM/OpenAM (All versions)? for further information.
    • If the Kerberos service ticket does not exist for the AM/OpenAM FQDN - proceed to the next step.
    Running the klist command:
    $ klist
    Produces an output such as the following:
    Server: HTTP/host1.example.com @ FORGEROCK.COM
    KerbTicket Encryption Type: RSADSI RC4-HMAC(NT)
    Ticket Flags 0x40a10000 -> forwardable renewable pre_authent name_canonicalize
    Start Time: 3/17/2016 11:33:06 (local)
    End Time: 3/17/2016 21:31:54 (local)
    Renew Time: 3/24/2016 11:31:54 (local)
    Session Key Type: RSADSI RC4-HMAC(NT)
    Cache Flags: 0
    Kdc Called: SVR1
  2. Check the AM/OpenAM FQDN is listed as a trusted host (trusted Intranet site list) in the browser and add it if it's not listed (Security tab > Local Intranet > Sites > Advanced).
  3. Check the SPN for the AM/OpenAM service in Active Directory and correct if necessary. Ensure FQDN which matches the SPN in AD is used and the specified authcontext matches the auth module/chain for WDSSO. You can use the following command to check the SPN:
    $ setspn -l [account]
    replacing [account] with the name of the account created for AM/OpenAM. An example command looks like this:
    $ setspn -l openam
    and gives an output as follows:
    Registered ServicePrincipalNames for CN=OpenAM,OU=employees,DC=example,DC=com:
    
    HTTP/host1.example.com
    
Note

If none of these resolve the issue, another problem must exist with the Kerberos protocol between the browser and Active Directory; you can attempt to track this down using utilities such as the Microsoft Network Monitor or the Microsoft Message Analyzer.

See Also

How do I troubleshoot WDSSO and Kerberos issues in AM/OpenAM (All versions)?

Authenticating with Windows Desktop SSO in AM/OpenAM (All versions) does not proceed when using non-Internet Explorer browser

How do I set up Windows Desktop SSO in AM/OpenAM (All versions)?

Configuring and troubleshooting WDSSO in AM/OpenAM

Setspn Utility

Related Training

N/A

Related Issue Tracker IDs

N/A


Authenticating with Windows Desktop SSO in AM/OpenAM (All versions) does not proceed when using non-Internet Explorer browser

The purpose of this article is to provide assistance if authenticating with Windows Desktop SSO (WDSSO) in AM/OpenAM does not proceed when using a non-Internet Explorer® browser, such as Chrome™ or Firefox®. The user sees a "401 Unauthorized / Access denied" error.

Symptoms

The user sees a 401 Unauthorized / Access denied error when they attempt to access a resource protected by AM/OpenAM, even though they are logged in to Microsoft® Windows® and another authentication module exists in the authentication chain.

An error similar to the following is shown in the Authentication log:

amLoginModule:03/11/2014 11:52:22:563 PM CET: Thread[http-bio-8080-exec-8,5,main]
Login, class = com.sun.identity.authentication.modules.windowsdesktopsso.WindowsDesktopSSO, module=WDSSO, file=/config/auth/default/WindowsDesktopSSO.xml
amLoginModule:03/11/2014 11:52:22:563 PM CET: Thread[http-bio-8080-exec-8,5,main]
AMLoginModuleiplanet-am-auth-shared-state-behavior-pattern is set to tryFirstPass
amLoginModule:03/11/2014 11:52:22:563 PM CET: Thread[http-bio-8080-exec-8,5,main]
This module is not done yet. CurrentState: 1
amLoginModule:03/11/2014 11:52:22:563 PM CET: Thread[http-bio-8080-exec-8,5,main]
callback stateLength in file = 1
amLoginModule:03/11/2014 11:52:22:563 PM CET: Thread[http-bio-8080-exec-8,5,main]
callback size for state 1=1
amLoginModule:03/11/2014 11:52:22:563 PM CET: Thread[http-bio-8080-exec-8,5,main]
clone #0 is PagePropertiesCallback
amLoginModule:03/11/2014 11:52:22:563 PM CET: Thread[http-bio-8080-exec-8,5,main]
Login, state = 1
amCallback:03/11/2014 11:52:22:563 PM CET: Thread[http-bio-8080-exec-8,5,main]
callback handler method
amAuth:03/11/2014 11:52:22:563 PM CET: Thread[http-bio-8080-exec-8,5,main]
Setting page timeout :120
amAuth:03/11/2014 11:52:22:563 PM CET: Thread[http-bio-8080-exec-8,5,main]
setting Last Callback Sent :1394578342563
amCallback:03/11/2014 11:52:22:563 PM CET: Thread[http-bio-8080-exec-8,5,main]
Set callbacks, throwing java.lang.Error.
amJAAS:03/11/2014 11:52:22:563 PM CET: Thread[http-bio-8080-exec-8,5,main]
LoginContext.invoke():Handling expected java.lang.Error
amAuth:03/11/2014 11:52:22:563 PM CET: Thread[http-bio-8080-exec-8,5,main]
Caught java.lang.Error returned from DSAMEHandler
java.lang.Error: return from DSAMECallback
   at com.sun.identity.authentication.service.DSAMECallbackHandler.handle(DSAMECallbackHandler.java:141)
   at com.sun.identity.authentication.spi.AMLoginModule.login(AMLoginModule.java:1134)
   at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
   at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
   at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
   at java.lang.reflect.Method.invoke(Method.java:597)
...
amAuth:03/11/2014 11:52:22:563 PM CET: Thread[http-bio-8080-exec-8,5,main]
AMLoginContext:Thread started... returning.
amAuthContextLocal:03/11/2014 11:52:22:563 PM CET: Thread[http-bio-8080-exec-8,5,main]
after AMLoginContext::exceuteLogin : 
amAuth:03/11/2014 11:52:22:563 PM CET: Thread[http-bio-8080-exec-8,5,main]
getStatus : status is... : 2
amAuth:03/11/2014 11:52:22:563 PM CET: Thread[http-bio-8080-exec-8,5,main]
getStatus : status is... : 2
amAuthContextLocal:03/11/2014 11:52:22:563 PM CET: Thread[http-bio-8080-exec-8,5,main]
Status at the end of login() : in_progress
amAuthContextLocal:03/11/2014 11:52:22:563 PM CET: Thread[http-bio-8080-exec-8,5,main]
AuthContextLocal::hasMoreRequirements()
amAuth:03/11/2014 11:52:22:563 PM CET: Thread[http-bio-8080-exec-8,5,main]
getStatus : status is... : 2
amAuth:03/11/2014 11:52:22:563 PM CET: Thread[http-bio-8080-exec-8,5,main]
getStatus : status is... : 2
amAuth:03/11/2014 11:52:22:563 PM CET: Thread[http-bio-8080-exec-8,5,main]
Recd Callback in amlc.getRequiredInfo : com.sun.identity.authentication.spi.PagePropertiesCallback@2f466880
amAuth:03/11/2014 11:52:22:563 PM CET: Thread[http-bio-8080-exec-8,5,main]
Recd Callback in amlc.getRequiredInfo : com.sun.identity.authentication.spi.HttpCallback@3776c3bf
amLoginViewBean:03/11/2014 11:52:22:563 PM CET: Thread[http-bio-8080-exec-8,5,main]
In getLoginDisplay, has More Requirements
amAuthContextLocal:03/11/2014 11:52:22:563 PM CET: Thread[http-bio-8080-exec-8,5,main]
AuthContextLocal::getRequirements()
amAuth:03/11/2014 11:52:22:563 PM CET: Thread[http-bio-8080-exec-8,5,main]
getStatus : status is... : 2
amAuth:03/11/2014 11:52:22:563 PM CET: Thread[http-bio-8080-exec-8,5,main]
getStatus : status is... : 2
amLoginViewBean:03/11/2014 11:52:22:563 PM CET: Thread[http-bio-8080-exec-8,5,main]
Start authorization negotiation...
amLoginViewBean:03/11/2014 11:52:22:563 PM CET: Thread[http-bio-8080-exec-8,5,main]
header: WWW-Authenticate, value: Negotiate, code: 401

Recent Changes

Implemented the Windows Desktop SSO authentication module.

Causes

The browser cannot return a Kerberos™ token during the SPNEGO handshake because it cannot retrieve a Kerberos service ticket for AM/OpenAM from Active Directory®.

Two common reasons for the browser failing to send a Kerberos token are:

  • The AM/OpenAM FQDN is not listed as a trusted host in the browser.
  • The Service Principal Name (SPN) is not set up correctly in Active Directory.

Solution

This issue can be resolved by checking the following:

  1. Check if the Kerberos service ticket was retrieved for AM/OpenAM using either the Kerbtray or Klist utilities from Microsoft (depending on Microsoft Windows version). For example:
    • If the Kerberos service ticket does exist for the AM/OpenAM FQDN - check your browser settings to ensure the browser is correctly set up for SPNEGO (Integrated Windows Authentication) and update where necessary. See How do I set up Windows Desktop SSO in AM/OpenAM (All versions)? for further information.
    • If the Kerberos service ticket does not exist for the AM/OpenAM FQDN - proceed to the next step.
    Running the klist command:
    $ klist
    Produces an output such as the following:
    Server: HTTP/host1.example.com @ FORGEROCK.COM
    KerbTicket Encryption Type: RSADSI RC4-HMAC(NT)
    Ticket Flags 0x40a10000 -> forwardable renewable pre_authent name_canonicalize
    Start Time: 3/17/2016 11:33:06 (local)
    End Time: 3/17/2016 21:31:54 (local)
    Renew Time: 3/24/2016 11:31:54 (local)
    Session Key Type: RSADSI RC4-HMAC(NT)
    Cache Flags: 0
    Kdc Called: SVR1
  2. Check the AM/OpenAM FQDN is listed as a trusted host in the browser and add it if it's not listed. You can check as follows according to which browser you are using:
    • Chrome - since Chrome uses the Internet Explorer settings, you should check the AM/OpenAM FQDN is added to the trusted Intranet site list in Internet Explorer (Security tab > Local Intranet > Sites > Advanced).
    • Firefox - the AM/OpenAM FQDN should be added to the Integrated Authentication Sites list (Tools > Integrated Authentication Sites) if you're using the Integrated Authentication plugin. The equivalent Firefox setting is network.negotiate-auth.trusted-uris (accessed via about:config).
  3. Check the SPN for the AM/OpenAM service in Active Directory and correct if necessary. Ensure the FQDN which matches the SPN in AD is used and the specified authcontext matches the auth module/chain for WDSSO. You can use the following command to check the SPN:
    $ setspn -l [account]
    replacing [account] with the name of the account created for AM/OpenAM. An example command looks like this:
    $ setspn -l openam
    and gives an output as follows:
    Registered ServicePrincipalNames for CN=OpenAM,OU=employees,DC=example,DC=com:
    
    HTTP/host1.example.com
    
Note

If none of these resolve the issue, another problem must exist with the Kerberos protocol between the browser and Active Directory; you can attempt to track this down using utilities such as the Microsoft Network Monitor or the Microsoft Message Analyzer.

Custom 401 Page (Classic UI in OpenAM 12.x)

You can additionally implement a custom application or container level 401 error page if you are using the Classic UI. This page redirects the user (using the refresh meta tag within the html head tag) to the OpenAM login page to allow authentication to continue using the next authentication module in the authentication chain. This provides a better user experience, as users can either authenticate with the WDSSO module or be redirected to a different login module for authentication depending on whether their browser is configured to retrieve a Kerberos token or not.

See How do I redirect users to a different login module if Kerberos/WDSSO authentication fails with a 401 error in OpenAM 11.x and 12.x using the Classic UI? for further information on creating this page.

See Also

How do I troubleshoot WDSSO and Kerberos issues in AM/OpenAM (All versions)?

Kerberos token is not valid error when authenticating with Windows Desktop SSO in AM/OpenAM (All versions) using Internet Explorer

How do I set up Windows Desktop SSO in AM/OpenAM (All versions)?

Configuring and troubleshooting WDSSO in AM/OpenAM

Setspn Utility

Related Training

N/A

Related Issue Tracker IDs

N/A


SAML redirect is ignored when doing an IdP or SP initiated SSO with WDSSO/Kerberos authentication in OpenAM 13.0 and 13.5

The purpose of this article is to provide assistance if SAML redirection is ignored when doing an IdP or SP initiated SSO in OpenAM 13.0 and 13.5. This issue occurs when you are using a realm DNS alias for federation and that Realm is setup for Windows Desktop SSO/Kerberos authentication.

Symptoms

XUI

If you are using the XUI, you will observe the following behavior after successfully authenticating with the WDSSO authentication module:

  • You are redirected to the default SuccessURL if one has been set up for the WDSSO authentication module, OR
  • You are redirected to OpenAM and see the following message in the browser:
    You have already logged in. Do you want to log out and then login to a different organization?

Expected behavior: you are redirected to the IdP or SP depending on your setup.

Classic UI

If you are using the Classic UI, you will see the following message in the browser:

An internal authentication error has occurred. Contact your system administrator.

The following error is shown in the Authentication debug log when this happens:

ERROR: LoginViewBean.forwardTo(): There was an Exception doing the forward/redirect 
org.apache.jasper.JasperException: java.lang.ClassCastException: [Ljava.lang.String; cannot be cast to java.lang.String 
   at org.apache.jasper.servlet.JspServletWrapper.handleJspException(JspServletWrapper.java:555) 
   at org.apache.jasper.servlet.JspServletWrapper.service(JspServletWrapper.java:476) 
   at org.apache.jasper.servlet.JspServlet.serviceJspFile(JspServlet.java:396) 
   at org.apache.jasper.servlet.JspServlet.service(JspServlet.java:340) 
   at javax.servlet.http.HttpServlet.service(HttpServlet.java:729) 
   at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:291) 
   at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:206) 
   at org.apache.tomcat.websocket.server.WsFilter.doFilter(WsFilter.java:52) 
...
Caused by: java.lang.ClassCastException: [Ljava.lang.String; cannot be cast to java.lang.String 
   at com.sun.identity.saml2.common.SAML2Utils.getParameter(SAML2Utils.java:1370) 
   at com.sun.identity.saml2.common.SAML2Utils.getRealm(SAML2Utils.java:1356) 
   at org.apache.jsp.saml2.jsp.idpSSOFederate_jsp._jspService(idpSSOFederate_jsp.java:131) 
   at org.apache.jasper.runtime.HttpJspBase.service(HttpJspBase.java:70) 
   at javax.servlet.http.HttpServlet.service(HttpServlet.java:729) 
   at org.apache.jasper.servlet.JspServletWrapper.service(JspServletWrapper.java:438) 
... 72 more

Recent Changes

Upgraded to, or installed OpenAM 13.0 or 13.5.

Made changes to your configuration so that you now have the combination of using a realm DNS alias for federation purposes and have the WDSSO authentication module configured in that realm for authentication.

Causes

The realm context is lost in the process when the realm DNS alias is used, which prevents you being correctly redirected to the IdP or SP as expected. 

Solution

This issue can be resolved by upgrading to OpenAM 13.5.1 or later; you can download this from BackStage.

Workaround

Alternatively, the following options are available to resolve this issue:

  • You can update your configuration so that you use the OpenAM DNS URL for federation rather than the realm DNS alias.
  • You can use an alternative authentication module.

See Also

N/A

Related Training

N/A

Related Issue Tracker IDs

OPENAM-8351 (SAML2 JSP pages making use of the SAML2Auditor are calling the SAML2Utils.getRealm with an incorrect Map structure)

OPENAM-8971 (currentGoto : null is received in XUI when a realm dns is being used for Federation and authentication is done via wdsso/kerberos auth module)


Unable to obtain password from user error when WDSSO authentication fails in AM/OpenAM (All versions)

The purpose of this article is to provide assistance if you receive a "javax.security.auth.login.LoginException: Unable to obtain password from user" error when attempting to log into AM/OpenAM using the Windows Desktop SSO (WDSSO) authentication module.

Symptoms

The following error is shown in the Authentication log when WDSSO authentication fails:

amAuthWindowsDesktopSSO:04/10/2016 16:43:11:135 PM PDT: Thread[http-bio-12023-exec-4,5,main]
WindowsDesktopSSO params:
principal: HTTP/host1.forgerock.com@WINDOWS.EXAMPLE.COM
keytab file: /etc/openam.HTTP.keytab
realm : WINDOWS.EXAMPLE.COM
kdc server: windows.example.com
domain principal: false
Lookup user in realm:false
Accepted Kerberos realms: []
auth level: 0
amAuthWindowsDesktopSSO:04/10/2016 16:43:11:135 PM PDT: Thread[http-bio-12023-exec-4,5,main]
Init WindowsDesktopSSO. This should not happen often.
amAuth:04/10/2016 16:43:11:135 PM PDT: Thread[http-bio-12023-exec-4,5,main]
spi authLevel :0
amAuth:04/10/2016 16:43:11:135 PM PDT: Thread[http-bio-12023-exec-4,5,main]
module configuration authLevel :0
amAuth:04/10/2016 16:43:11:135 PM PDT: Thread[http-bio-12023-exec-4,5,main]
levelSet :false
amAuthWindowsDesktopSSO:04/10/2016 16:43:11:135 PM PDT: Thread[http-bio-12023-exec-4,5,main]
New Service Login ...
amAuthWindowsDesktopSSO:04/10/2016 16:43:11:136 PM PDT: Thread[http-bio-12023-exec-4,5,main]
ERROR: Service Login Error:
amAuthWindowsDesktopSSO:04/10/2016 16:43:11:136 PM PDT: Thread[http-bio-12023-exec-4,5,main]
Stack trace:
javax.security.auth.login.LoginException: Unable to obtain password from user
     at com.sun.security.auth.module.Krb5LoginModule.promptForPass(Krb5LoginModule.java:856)
     at com.sun.security.auth.module.Krb5LoginModule.attemptAuthentication(Krb5LoginModule.java:719)
     at com.sun.security.auth.module.Krb5LoginModule.login(Krb5LoginModule.java:584)
...

You will also see a similar error in the amAuthWindowsDesktopSSO debug log:

04/10/2016 16:43:11:135 PM PDT: Thread[service-j2ee,5,main] 
ERROR: Service Login 
Error: 04/10/2016 16:43:11:135 PM PDT: Thread[service-j2ee,5,main] 
Stack trace: javax.security.auth.login.LoginException: 
Unable to obtain password from user at com.sun.security.auth.module.
Krb5LoginModule.promptForPass(Krb5LoginModule.java:745) 
     at com.sun.security.auth.module.Krb5LoginModule.attemptAuthentication
(Kr b5LoginModule.java:624) at com.sun.security.auth.module.
Krb5LoginModule.login(Krb5LoginModule.java:512) 
     at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
... 

Recent Changes

Configured the WDSSO module.

Updated your keytab file.

Causes

There is an issue with your keytab file and/or the configured service principal. Alternatively, this can be caused by an incorrect version of Java® being used for your AM/OpenAM version.

Solution

You should use either the Kerbtray or Klist utilities from Microsoft® (depending on Microsoft Windows version) to display details about your keytab file.

This is an example output from the Klist utility:

Server: HTTP/host1.example.com @ WINDOWS.EXAMPLE.COM
KerbTicket Encryption Type: RSADSI RC4-HMAC(NT)
Ticket Flags 0x40a10000 -> forwardable renewable pre_authent name_canonicalize
Start Time: 3/17/2016 11:33:06 (local)
End Time: 3/17/2016 21:31:54 (local)
Renew Time: 3/24/2016 11:31:54 (local)
Session Key Type: RSADSI RC4-HMAC(NT)
Cache Flags: 0
Kdc Called: SVR1

You can then check the following and resolve as applicable:

  • Check you have used an appropriate encryption type (KerbTicket Encryption Type in example Klist output) when generating the keytab file and that you have updated the user account properties in Active Directory® to match. The corresponding encryption type should be selected in the user account properties.
  • Check the configured service principal in AM/OpenAM matches the one in the keytab file (Server in example Klist output). You can check the configured service principal in the console as follows:
    • AM / OpenAM 13.x console: navigate to Realms > [Realm Name] > Authentication > Modules > [Module Name] > Service Principal and update if it does not match the value in the keytab file.
    • Pre-OpenAM 13 console: navigate to Access Control > [Realm Name] > Authentication >  Module Instances > [Module Name] > Service Principal and update if it does not match the value in the keytab file.

If this fails to resolve your issue, you should check you are using an appropriate Java® version for your AM/OpenAM version. Supported Java versions can be found in the release notes applicable to your AM/OpenAM version, for example, the latest supported Java versions can be found here: Release Notes › Before You Install › Java Requirements

See Also

WDSSO/Kerberos authentication fails in AM/OpenAM (All versions) with an HTTP 400 Bad Request response

WDSSO authentication fails with GSSException: Failure unspecified at GSS-API level error in AM/OpenAM (All versions)

Clock skew too great (37) error when WDSSO authentication fails in AM/OpenAM (All versions)

How do I troubleshoot WDSSO and Kerberos issues in AM/OpenAM (All versions)?

How do I enable debug logging for troubleshooting WDSSO and Kerberos issues in AM/OpenAM (All versions)?

Related Training

N/A

Related Issue Tracker IDs

N/A


Clock skew too great (37) error when WDSSO authentication fails in AM/OpenAM (All versions)

The purpose of this article is to provide assistance if you receive a "javax.security.auth.login.LoginException: Clock skew too great (37)" error when attempting to log into the Windows Desktop SSO (WDSSO) authentication module in AM/OpenAM.

Symptoms

The following error is shown in the Authentication log when WDSSO authentication fails:

amAuthWindowsDesktopSSO:04/10/2016 16:43:11:135 PM PDT: Thread[http-bio-12023-exec-8,5,main]
WindowsDesktopSSO params:
principal: HTTP/host1.example.com@WINDOWS.EXAMPLE.COM
keytab file: /etc/openam.HTTP.keytab
realm : WINDOWS.EXAMPLE.COM
kdc server: windows.example.com
domain principal: false
Lookup user in realm:false
Accepted Kerberos realms: []
auth level: 0
amAuthWindowsDesktopSSO:04/10/2016 16:43:11:135 PM PDT: Thread[http-bio-12023-exec-8,5,main]
Init WindowsDesktopSSO. This should not happen often.
amAuth:04/10/2016 16:43:11:135 PM PDT: Thread[http-bio-12023-exec-8,5,main]
spi authLevel :0
amAuth:04/10/2016 16:43:11:135 PM PDT: Thread[http-bio-12023-exec-8,5,main]
module configuration authLevel :0
amAuth:04/10/2016 16:43:11:135 PM PDT: Thread[http-bio-12023-exec-8,5,main]
levelSet :false
amAuthWindowsDesktopSSO:04/10/2016 16:43:11:135 PM PDT: Thread[http-bio-12023-exec-8,5,main]
New Service Login ...
amAuthWindowsDesktopSSO:04/10/2016 16:43:11:135 PM PDT: Thread[http-bio-12023-exec-8,5,main]
ERROR: Service Login Error:
amAuthWindowsDesktopSSO:04/10/2016 16:43:11:135 PM PDT: Thread[http-bio-12023-exec-8,5,main]
Stack trace:
javax.security.auth.login.LoginException: Clock skew too great (37)
    at com.sun.security.auth.module.Krb5LoginModule.attemptAuthentication(Krb5LoginModule.java:763)
    at com.sun.security.auth.module.Krb5LoginModule.login(Krb5LoginModule.java:584)
    at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
    at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:57)
    at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
...
Caused by: KrbException: Identifier doesn't match expected value (906)
    at sun.security.krb5.internal.KDCRep.init(KDCRep.java:143)
    at sun.security.krb5.internal.ASRep.init(ASRep.java:65)
    at sun.security.krb5.internal.ASRep.<init>(ASRep.java:60)
    at sun.security.krb5.KrbAsRep.<init>(KrbAsRep.java:60)
... 113 more

amLoginModule:04/10/2016 16:43:11:135 PM PDT: Thread[http-bio-12023-exec-8,5,main]
SETTING Failure Module name.... :wdsso

Recent Changes

N/A

Causes

The difference between the time on the Kerberos™ or Active Directory® Domain Controller and the AM/OpenAM server is too great.

Solution

This issue can be resolved by correcting the time on the Kerberos or Active Directory Domain Controller so it matches the time on the AM/OpenAM server.

See Also

WDSSO authentication fails with GSSException: Failure unspecified at GSS-API level error in AM/OpenAM (All versions)

WDSSO/Kerberos authentication fails in AM/OpenAM (All versions) with an HTTP 400 Bad Request response

Unable to obtain password from user error when WDSSO authentication fails in AM/OpenAM (All versions)

How do I troubleshoot WDSSO and Kerberos issues in AM/OpenAM (All versions)?

How do I enable debug logging for troubleshooting WDSSO and Kerberos issues in AM/OpenAM (All versions)?

Related Training

N/A

Related Issue Tracker IDs

N/A


Copyright and TrademarksCopyright © 2018 - 2019 ForgeRock, all rights reserved.

This content has been optimized for printing.

Loading...