How To

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

Last updated Jan 16, 2019

The purpose of this article is to provide information on importing Service configurations in AM using Amster when you have custom authentication modules. You must install and register the custom module before you can import a service configuration.

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:

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
```
Restart the web application container in which AM runs to complete the registration of the custom module.
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:

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
```
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)
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.
Restart the web application container in which AM runs to complete the registration of the custom module.
You can now import your service configurations using the Amster import-config command, for example:
```
am> import-config --path /path/to/config
```

Related Training

N/A

Related Issue Tracker IDs

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