Skip to main content
Version: 2.82.x.x LTS

Migration to Standalone

This chapter provides a guideline for migrating a nevisIDM instance with container type adnjboss (v5.1.x) or adnwildfly (v10.1.x) to a nevisIDM instance of deployment type "standalone".

There is no automated instance migration. Gather the information from the current source instance and use it to create a new target standalone instance. This document covers the most common configuration use cases and makes recommendations for their migration.

Instance parameters gathering

Server parameters

In a first step, gather all the required parameters of the current instance. See also the following table. Some parameters are only required if TLS is used.

If all the required parameters are known, you can skip the step Parameter retrieval.

ParameterDefaultDescription
SERVER_URL_PROTOCOLhttp or httpsThe server protocol. In case of TLS the protocol is https.
SERVER_URL_SERVERlocalhostThe server host name.
SERVER_URL_PORT8989The server port.
SERVER_TLS_KEYSTORE/var/opt/neviskeybox/
default/default/node_keystore.jks
Keystore used to identify the server (sent to the client on a SSL/TLS client hello).(info) Only required for TLS.
SERVER_TLS_KEYSTORE_PASSWORDPassphrase to access the server keystore.(info) Only required for TLS.
SERVER_TLS_TRUSTSTORE/var/opt/neviskeybox/
default/default/truststore.jks
Truststore used to validate client certificates.(info) Only required for TLS.
SERVER_TLS_TRUSTSTORE_PASSWORDPassphrase to access the server truststore (usually not required, because the truststore contains public certificates, which do not require protection).(info) Only required for TLS.
NINJA_CERT/var/opt/neviskeybox/
default/nevis/truststore.jks
This parameter is used to configure the trust anchor for Nevis SecToken validation. It is used by the Nevis JAAS login module.

Parameter retrieval

adnjboss

The required parameters can be retrieved as described in chapter Parameter retrieval of the Migration Guide from adnjboss to adnwildfly.

adnwildfly

The server parameters can be retrieved from security realms, security domains, interfaces and socket bindings configured in the file standalone.xml. You can access this file either with the command nevisidm <instance_name> config server, or by opening the file /var/opt/adnwildfly/instances/<new_instance_name>/standalone/configuration/standalone.xml.

The following two examples show the standalone.xml file for the protocol types HTTPS and HTTP, respectively.

HTTPS standalone.xml

<security-realms>
<security-realm name="SslRealm">
<server-identities>
<ssl>
<keystore path="${SERVER_TLS_KEYSTORE}" keystore-password="${SERVER_TLS_KEYSTORE_PASSWORD}"/>
</ssl>
</server-identities>
<authentication>
<truststore path="${SERVER_TLS_TRUSTSTORE}" keystore-password="${SERVER_TLS_TRUSTSTORE_PASSWORD}"/>
</authentication>
</security-realm>
</security-realms>

<profile>
<subsystem xmlns="urn:jboss:domain:undertow:1.2">
<buffer-cache name="default" />
<server name="default-server">
`<http-listener name="default-ssl" socket-binding="https" security-realm="SslRealm"/>
<host name="default-host" alias="${SERVER_URL_SERVER}"/>
</server>
<servlet-container name="default">
<jsp-config />
</servlet-container>
</subsystem>
<subsystem xmlns="urn:jboss:domain:security:1.2">
<security-domains>
<security-domain name="NevisSecTokenDomain" cache-type="default">
<authentication>
<login-module code="ch.nevis.ninja.jboss.auth.NinjaJbossLoginModuleImpl" flag="required" module="ch.nevis.ninja">
<module-option name="NevisSignerCertificate" value="${NINJA_CERT}"/>
<module-option name="UserGetter" value="AttributeUserGetter(source=loginId)"/>
<module-option name="AdjustIdentity" value="true"/>
<module-option name="LogDebug" value="false"/>
<module-option name="RoleGetters" value="ch.nevis.ninja.commons.mapping.StaticRoleGetter, ch.nevis.ninja.commons.mapping.TokenRoleGetter"/>
</login-module>
</authentication>
</security-domain>
</security-domains>
</subsystem>
</profile>

<interfaces>
<interface name="public">
<inet-address value="${SERVER_URL_SERVER}"/>
</interface>
</interfaces>
<socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}">
<socket-binding name="https" port="${SERVER_PORT}" fixed-port="true" />
</socket-binding-group>

HTTP standalone.xml

<profile>
<subsystem xmlns="urn:jboss:domain:undertow:1.2">
<buffer-cache name="default"/>
<server name="default-server">
<http-listener name="default" socket-binding="http" redirect-socket="http"/>
<host name="default-host" alias="${SERVER_URL_SERVER}"/>
</server>
<servlet-container name="default">
<jsp-config/>
</servlet-container>
</subsystem>
<subsystem xmlns="urn:jboss:domain:security:1.2">
<security-domains>
<security-domain name="NevisSecTokenDomain" cache-type="default">
<authentication>
<login-module code="ch.nevis.ninja.jboss.auth.NinjaJbossLoginModuleImpl" flag="required" module="ch.nevis.ninja">
<module-option name="NevisSignerCertificate" value="${NINJA_CERT}"/>
<module-option name="UserGetter" value="AttributeUserGetter(source=loginId)"/>
<module-option name="AdjustIdentity" value="true"/>
<module-option name="LogDebug" value="false"/>
<module-option name="RoleGetters" value="ch.nevis.ninja.commons.mapping.StaticRoleGetter, ch.nevis.ninja.commons.mapping.TokenRoleGetter"/>
</login-module>
</authentication>
</security-domain>
</security-domains>
</subsystem>
</profile>

<interfaces>
<interface name="public">
<inet-address value="${SERVER_URL_SERVER}"/>
</interface>
</interfaces>

<socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}">
<socket-binding name="http" port="${SERVER_PORT}" fixed-port="true"/>
</socket-binding-group>

Old instance stopping

Once you have gathered the required parameters, you can stop the old instance.

Use the following command:

nevisidm <instance_name> stop

Upgrade nevisIDM

The latest version of nevisIDM has deprecated the support of adnjboss. Therefore, if your old nevisIDM instance is of deployment type adnjboss, make sure to stop itbefore you upgrade nevisIDM to the latest version.

The next step is to install the latest version of nevisIDM (at least 2.72.0.x) on the server.

Standalone instance creation

The deployment type standalone is the default. To create a new standalone instance, use the following command:

Standalone instance creation

nevisidm inst create <new_instance_name>

Instance configuration migration

Copy configurations

The following configuration files can be copied from the adnjboss/adnwildfly instance directly to the standalone instance:

cp -f /var/opt/nevisidm/<instance_name>/conf/attrAccess.properties /var/opt/nevisidm/<new_instance_name>/conf/attrAccess.properties
cp -f /var/opt/nevisidm/<instance_name>/conf/authorizationConfig.properties /var/opt/nevisidm/<new_instance_name>/conf/authorizationConfig.properties
cp -f /var/opt/nevisidm/<instance_name>/conf/batchjobContext.xml /var/opt/nevisidm/<new_instance_name>/conf/batchjobContext.xml
cp -f /var/opt/nevisidm/<instance_name>/conf/batchjob-config-reloader.properties /var/opt/nevisidm/<new_instance_name>/conf/batchjob-config-reloader.properties
cp -f /var/opt/nevisidm/<instance_name>/conf/rolesAssignment.properties /var/opt/nevisidm/<new_instance_name>/conf/rolesAssignment.properties
cp -f /var/opt/nevisidm/<instance_name>/conf/rolesMapping.properties /var/opt/nevisidm/<new_instance_name>/conf/rolesMapping.properties
cp -f /var/opt/nevisidm/<instance_name>/conf/tlds-alpha-by-domain.txt /var/opt/nevisidm/<new_instance_name>/conf/tlds-alpha-by-domain.txt

Migrate configurations

Manually migrate the following files of the adnjboss/adnwildfly instance (see below). Each custom configuration that differs from the default value will be adjusted or set in the corresponding newly generated files of the standalone instance. It is recommended that you use a diff tool like Meld to compare the two versions.

nevisidm-prod.properties

Besides migrating each custom configuration, also add the server parameters retrieved in the step Parameter retrieval to the newly generated nevisidm-prod.properties file:

server.tls.enabled=<false for HTTP, true for HTTPS>
server.tls.require-client-auth=<false for one-way TLS, true for two-way TLS>
server.host=<SERVER_URL_SERVER>
server.port=<SERVER_URL_PORT>
server.tls.keystore=<SERVER_TLS_KEYSTORE>
server.tls.keystore-passphrase=<SERVER_TLS_KEYSTORE_PASSWORD>
server.tls.truststore=<SERVER_TLS_TRUSTSTORE>
server.tls.truststore-passphrase=<SERVER_TLS_TRUSTSTORE_PASSWORD>
server.auth.ninja.truststore=<NINJA_CERT>

log4j.xml

Do not simply overwrite the new log4j.xml file by the old configuration file, because new categories for the standalone logging have been added. Migrate every custom configuration, i.e., categories, to the newly generatedlog4j.xml file.

Custom facing

See the following page for more information about custom facing migration.

vmargs.conf

There is no vmargs.conf file for the standalone deployment type. JVM arguments can be configured by setting the JAVA_OPTS environment variable in the file env.conf.

Migrate and append each custom configuration in the vmargs.conf file to the JAVA_OPTS environment variable in the env.conf file.

Special configurations

Login modules

No additional login module configuration is required for client certificate or secToken authentication in the standalone deployment.

In standalone deployment, the login modules for both client certificate and SecToken authentication are enabled per default. The two login modules are chained, that is, at least a valid client certificate or a valid SecToken as authentication information is required for a successful login. In case a request contains both a client certificate and a SecToken, the SecToken will be used for the login.

Client certificate authentication

In the standalone deployment, you can use the same server port as before for client certificate authentication. In addition, the ForwardSerlvet does not have to be configured as JVM argument anymore.

JMS

The standalone deployment has a built-in JMS queue. The port, storage location, username and password can be configured via the nevisidm-prod properties. For further information, see JMS parameters.

OpenJDK migration

The standalone deployment requires Java OpenJDK. For migration information, see Migrating to OpenJDK 1.8.0.

Standalone instance start

When the migration is completed, you can start the new standalone instance. Use the following command:

nevisidm <new_instance_name> start

Old instance removal

When you have successfully completed the migration and started the new instance, you can remove the old instance. Use the following command:

nevisidm inst remove <instance_name>
Deprecated

The latest version of nevisIDM has deprecated the support of adnjboss. Therefore, if your old nevisIDM instance was of deployment type adnjboss, remove it manually.