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

Overview

This article assumes you have working AM and Amster installations, and you have already created a custom authentication module. See Authentication and Single Sign-On Guide › Creating a Custom Authentication Module for further information on creating custom modules.

Prior to importing service configurations that contain custom authentication modules, you must install and register the custom module. The way in which this is done varies between AM versions as detailed in this article:

• AM 5.5 and later.
• AM 5 and 5.1.x.

This change is detailed in the AM 5.5 Release Notes: Release Notes › Important Changes to Existing Functionality.

Import Error

Failing to install and register the custom module first will cause the import to fail with the following error (where custom-authentication-module is the example custom module name):

Failed to import /path/to/config/global/custom-authentication-module.json : Unrecognised entity type: custom-authentication-module
Failed to import /path/to/config/realms/realmName/custom-authentication-module/custom-authentication-module.json : Unrecognised entity type: custom-authentication-module

AM 5.5 and later

You can import service configurations that contain custom authentication modules in AM 5.5 and later 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-authentication-module-5.5.0.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.
3. You can now import your service configurations using the Amster import-config command, for example:

   am> import-config --path /path/to/config

AM 5 and 5.1.x

You can import service configurations that contain custom authentication modules in AM 5 and 5.1.x 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-authentication-module-14.0.0.jar /path/to/tomcat/webapps/openam/WEB-INF/lib
   

2. Install the custom authentication module using ssoadm:

   $ ./ssoadm create-svc -u [adminID] -f [passwordfile] -X [xmlfile]

   replacing [adminID], [passwordfile] and [xmlfile] with appropriate values, where [xmlfile] is the service configuration file for the auth module (e.g., amAuthSampleAuth.xml)  
3. Register the custom authentication module using ssoadm:

   $ ./ssoadm register-auth-module -u [adminID] -f [passwordfile] -a [javaClass]

   replacing [adminID], [passwordfile] and [javaClass] with appropriate values, where [javaClass] is the Java class name of the custom authentication module.
4. Restart the web application container in which AM runs to complete the registration of the custom module.
5. You can now import your service configurations using the Amster import-config command, for example:

   am> import-config --path /path/to/config

See Also

How do I export and import Service configurations for AM/OpenAM (All versions)?

How do I customize authentication modules using source code in AM/OpenAM (All versions)?

How do I access and build the sample code provided for AM/OpenAM (All versions)?

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

Amster User Guide > Importing Configuration Data

Related Training

N/A

Related Issue Tracker IDs

OPENAM-11947 (Not able to import AM configs with custom authentication module)