Installer le serveur TOSIAM pas à pas

TOSIAM est une application web Java (WAR), sans état applicatif propre (voir Composants et couches), déployée sur Tomcat ou JBoss/Wildfly. Elle ne fait rien tant qu’elle n’a pas été configurée pour se connecter à un Config Store TosDJ.

Cet article suppose qu’un Config Store TosDJ est déjà installé et démarré (voir Installer un serveur TosDJ pas à pas) et détaille l’installation, sans conteneur, du nœud TOSIAM lui-même : déploiement du WAR, configuration silencieuse, puis mise en place des outils d’administration (ssoadm).

Prérequis

Un JDK compatible (Amazon Corretto) et un serveur d’application : Tomcat ou JBoss/Wildfly.
Un Config Store TosDJ déjà démarré et accessible en LDAPS, installé avec le profil config (voir l’article précédent). Ce profil crée systématiquement, via admin.ldif, un compte technique uid=tosiam,ou=system,<baseDN> doté de droits complets (lecture/écriture/recherche persistante/modification de schéma) sur tout l’arbre — c’est ce compte, et le mot de passe donné à tosiamPassword lors du setup de TosDJ, que TOSIAM utilisera pour s’y connecter.
La même autorité de certification interne que celle utilisée pour TosDJ (voir l’article précédent), pour que TOSIAM fasse confiance aux certificats des bases et présente lui-même un certificat cohérent aux clients.
L’archive de la distribution TOSIAM (TosiAM-<version>.war, plus les deux outils SSOConfiguratorTools-<version>.zip et SSOAdminTools-<version>.zip, livrés ensemble).

1. Déployer le serveur d’application et le WAR

Exemple avec Tomcat (le principe est identique avec Wildfly, en déposant le WAR dans standalone/deployments) :

JDK_VERSION=25
TOMCAT_VERSION=11.0.14
CONTEXT=tosiam

wget "https://archive.apache.org/dist/tomcat/tomcat-11/v${TOMCAT_VERSION}/bin/apache-tomcat-${TOMCAT_VERSION}.tar.gz"
tar xf apache-tomcat-*.tar.gz -C ~/opt
export CATALINA_HOME=~/opt/apache-tomcat-${TOMCAT_VERSION}
rm -rf "$CATALINA_HOME"/webapps/*

unzip -q TosiAM-3.35.0.war -d "$CATALINA_HOME"/webapps/tosiam

Le connecteur HTTPS de Tomcat (server.xml) référence un keystore PKCS12 partagé avec l’application :

<Connector protocol="org.apache.coyote.http11.Http11NioProtocol"
           port="8443" scheme="https" secure="true" SSLEnabled="true">
  <SSLHostConfig certificateVerification="optional" protocols="TLSv1.2,TLSv1.3">
    <Certificate certificateKeystoreFile="/chemin/vers/server.p12"
                 certificateKeystorePassword="*****"
                 certificateKeystoreType="PKCS12" type="RSA" />
  </SSLHostConfig>
</Connector>

2. Certificat serveur PKCS12

Réutiliser exactement la procédure openssl décrite dans Installer un serveur TosDJ pas à pas, avec la même autorité (tosiamCA.crt/tosiamCA.key) mais un nom d’hôte propre au nœud TOSIAM, pour obtenir le server.p12 référencé ci-dessus.

3. Le fichier de configuration silencieuse

Le configurator de TOSIAM (module tosiam-configurator-tool) accepte, comme le setup de TosDJ, un fichier de propriétés qui remplace toute interaction :

Paramètre	Rôle
`SERVER_URL`	URL (schéma + hôte + port) sous laquelle ce nœud sera joint
`DEPLOYMENT_URI`	Chemin de déploiement de l’application (`/tosiam`, doit correspondre au contexte du WAR)
`BASE_DIR`	Répertoire local où TOSIAM écrit sa configuration (bootstrap, connexion au Config Store) — c’est ce chemin qui sera redonné à `ssoadm setup -p`
`locale` / `PLATFORM_LOCALE`	Langue de l’installation
`AM_ENC_KEY`	Clé de chiffrement des secrets stockés en base (mots de passe de datastores, etc.) — doit être identique sur tous les nœuds d’une même ferme partageant le même Config Store, sous peine de ne plus pouvoir déchiffrer les secrets écrits par un autre nœud
`ADMIN_PWD`	Mot de passe du compte `amadmin` (administrateur TOSIAM)
`AMLDAPUSERPASSWD`	Mot de passe exigé par le configurateur pour un compte technique interne ; hérité du mode “Config Store embarqué” historique d’OpenAM — sans effet direct constaté ici en mode `dirServer` (Config Store externe), mais sa présence dans le fichier reste obligatoire
`ACCEPT_LICENSES`	Accepte la licence sans invite
`COOKIE_DOMAIN`	Domaine du cookie de session SSO ; à renseigner uniquement si plusieurs nœuds/applications sur des sous-domaines différents doivent partager la session (sans rapport avec l’URL de Site, voir Haute disponibilité)
`DATA_STORE`	`dirServer` pour un Config Store externe (celui qu’on vient d’installer), par opposition à un Config Store embarqué dans TOSIAM lui-même
`DIRECTORY_SSL`	`SSL` pour se connecter en LDAPS au Config Store
`DIRECTORY_SERVER` / `DIRECTORY_PORT`	Hôte et port LDAPS du Config Store TosDJ
`ROOT_SUFFIX`	Doit être identique au `baseDN` utilisé lors du `setup` du Config Store
`DS_DIRMGRDN`	`uid=tosiam,ou=system,<ROOT_SUFFIX>` — le compte technique créé par `admin.ldif`
`DS_DIRMGRPASSWD`	Le mot de passe donné à `tosiamPassword` lors du `setup` de ce Config Store
`LB_SITE_NAME` / `LB_PRIMARY_URL`	Facultatifs : rattachent ce nœud à un Site TOSIAM dès la configuration initiale (voir la notion de Site dans Haute disponibilité)

cat > ~/tosiam/config.properties <<'EOF'
SERVER_URL=https://@SERVER_HOST@:8443
DEPLOYMENT_URI=/@CONTEXT@
BASE_DIR=@BASE_DIR@
locale=en_US
PLATFORM_LOCALE=en_US
AM_ENC_KEY=@ENC_KEY@
ADMIN_PWD=@TOSIAM_ADMIN_PASSWORD@
AMLDAPUSERPASSWD=changeit
ACCEPT_LICENSES=true
#COOKIE_DOMAIN=tosit.org

DATA_STORE=dirServer
DIRECTORY_SSL=SSL
DIRECTORY_SERVER=@CONFIG_STORE_HOST@
DIRECTORY_PORT=@CONFIG_STORE_LDAPS_PORT@
ROOT_SUFFIX=@ROOT_SUFFIX@
DS_DIRMGRDN=uid=tosiam,ou=system,@ROOT_SUFFIX@
DS_DIRMGRPASSWD=@TOSIAM_DB_PASSWORD@
EOF

sed -i \
  -e "s/@SERVER_HOST@/$(hostname -f)/g" \
  -e "s/@CONTEXT@/tosiam/g" \
  -e "s#@BASE_DIR@#$HOME/tosiam/instance#g" \
  -e "s/@ENC_KEY@/$(openssl rand -base64 16)/g" \
  -e "s/@TOSIAM_ADMIN_PASSWORD@/password/g" \
  -e "s/@CONFIG_STORE_HOST@/cfg1.internal/g" \
  -e "s/@CONFIG_STORE_LDAPS_PORT@/1636/g" \
  -e "s#@ROOT_SUFFIX@#dc=tosit,dc=org#g" \
  -e "s/@TOSIAM_DB_PASSWORD@/password/g" \
  ~/tosiam/config.properties

chmod 600 ~/tosiam/config.properties

Remplacer les mots de passe et la clé de chiffrement d’exemple par de vraies valeurs, et retenir la valeur de AM_ENC_KEY en lieu sûr : elle sera nécessaire pour tout nouveau nœud rejoignant la même ferme.

4. Lancer la configuration silencieuse

java -jar SSOConfiguratorTools-3.35.0/tosiam-configurator-tool-3.35.0.jar -f ~/tosiam/config.properties

Cette étape écrit la configuration de service (SMS) dans le Config Store et crée le répertoire BASE_DIR local (bootstrap contenant la référence au Config Store, la clé de chiffrement, etc.) que l’application ira lire à chaque démarrage.

5. Installer les outils d’administration (ssoadm)

unzip -q SSOAdminTools-3.35.0.zip -d ~/tosiam/admin
echo password > ~/tosiam/.pwd.txt && chmod 400 ~/tosiam/.pwd.txt

cd ~/tosiam/admin/tosiam && ./setup --acceptLicense -p ~/tosiam/instance

-p/--path indique à ssoadm le BASE_DIR créé à l’étape précédente, pour qu’il sache à quelle instance TOSIAM il s’adresse.

6. Démarrer le serveur d’application

keytool -import -alias tosiam-ca-cert -file ~/tosdj/pki/tosiamCA.crt -storepass changeit -cacerts -noprompt

export CATALINA_OPTS="-Xmx2g -XX:MetaspaceSize=256m -XX:MaxMetaspaceSize=256m \
  -Dcom.sun.identity.configuration.directory=$HOME/tosiam/instance \
  --add-exports java.base/sun.misc=ALL-UNNAMED \
  --add-exports java.base/sun.security.provider=ALL-UNNAMED \
  --add-exports java.base/sun.security.x509=ALL-UNNAMED \
  --add-exports java.base/sun.security.util=ALL-UNNAMED \
  --add-exports java.base/sun.security.tools.keytool=ALL-UNNAMED \
  --add-exports java.xml/com.sun.org.apache.xerces.internal.dom=ALL-UNNAMED"

"$CATALINA_HOME"/bin/catalina.sh start

until [ "$(curl -sL -w '%{http_code}' -o /dev/null http://localhost:8080/tosiam/isAlive.jsp)" = "200" ]; do
  sleep 1
done

L’import de la CA dans les cacerts de la JVM est nécessaire pour que TOSIAM fasse confiance aux certificats du Config Store, du CTS et du User Store en LDAPS.
Les --add-exports ouvrent des API internes du JDK dont TOSIAM a besoin (accès réflexif à des classes de sécurité internes), sans quoi le démarrage échoue sur les JDK récents.
isAlive.jsp ne vérifie que la connectivité au Config Store (voir Haute disponibilité) — un 200 confirme le démarrage, pas la disponibilité complète des trois bases.

7. Vérifier l’installation avec ssoadm

~/tosiam/admin/tosiam/bin/ssoadm list-servers --adminid amadmin --password-file ~/tosiam/.pwd.txt

8. Déclarer un Config Store secondaire (haute disponibilité)

Une fois deux instances TosDJ du Config Store répliquées (voir Haute disponibilité), TOSIAM doit connaître la seconde comme repli. Cela ne se fait pas en ré-éditant config.properties, mais en modifiant le ServerGroup nommé sms du fichier de configuration serveur exposé par ssoadm :

ssoadm get-svrcfg-xml -s https://tosiam1.internal:8443/tosiam -o /tmp/svrcfg.xml \
  --adminid amadmin --password-file ~/tosiam/.pwd.txt
# éditer /tmp/svrcfg.xml : ajouter un <Server> dans le <ServerGroup name="sms">,
# avec le host du second Config Store et le même port/type que le serveur existant
ssoadm set-svrcfg-xml -s https://tosiam1.internal:8443/tosiam -X /tmp/svrcfg.xml \
  --adminid amadmin --password-file ~/tosiam/.pwd.txt

Pour aller plus loin

Installer un serveur TosDJ pas à pas pour préparer le Config Store, le CTS et le User Store.
Scalabilité & haute disponibilité pour la notion de Site, la réplication des bases et le sharding du CTS.