Setting up Single Sign-On to the Request Workflow Server

Web Center usually forwards the current user’s login credentials to the request workflow server (a component of the Java-based Server) in order to authenticate the user to the server. If you operate Web Center in single sign-on mode, however, the user’s password is unknown to Web Center, and hence cannot be used to authenticate the user against the request workflow server. In this case, Web Center authenticates itself to the server with its private key, and forwards only the name of the current user. The request workflow server verifies that it has a valid certificate of the presented private key, and if so, accepts the user name without further validation.

Thus, in case of single sign-on, you need a private key for Web Center, which may be

  • A key generated solely for this purpose; see section “Creating a Keystore and a Truststore” below.

  • The private key used by Tomcat for HTTPS.

The keystore location and the alias of the private key must be configured in Web Center’s deployment descriptor /WEB-INF/web.xml in context parameters

  • com.siemens.webMgr.requestworkflow.keystoreName

  • com.siemens.webMgr.requestworkflow.keyAlias.

The keystore password and, if different, the key password must be added to Web Center’s password file /WEB-INF/password.properties with keys

  • webcenterKeystore

  • webcenterKey

A certificate of the private key must be imported into the Java-based Server’s truststore

  • install_path/ids-j-domain-Sn/private/webcenter-truststore.

The truststore password must match the one with key truststore in file

  • install_path/ssl/password.properties.

The webcenter-truststore shares its password with the server-truststore of the Java-based Server. When creating a webcenter-truststore you must secure it with the server-truststore password if you’ve created the server-truststore beforehand. Otherwise, you can choose any password for the webcenter-truststore and then assign it manually to key truststore in the password file.

If Web Center and the Java-based Server run on different hosts, the keystore must reside on the machine hosting Web Center, the truststore on the one hosting the Java-based Server.

In a domain with multiple Web Center instances you can use the same key for each instance, or one key per instance, or anything in between. When using different keys, choose a unique alias for each key, and add a certificate for each key to the Java-based Server’s webcenter-truststore.

In a domain with multiple Java-based Servers, the request workflow server is part of the Java-based Server with request workflow type “default”. Since the request workflow engine can be shifted dynamically from one Java-based Server to another, make sure to add the Web Center certificate to the truststores of all affected Java-based Servers.

Note: This chapter applies to single sign-on and to external authentication against an ADS or an LDAP directory. External authentication was first introduced for Web Center for Password Management but works with any Web Center application.

Creating a Keystore and a Truststore

The batch file

  • install_path/ids-j-domain-Sn/utils/ssl/genWebCenter.bat (or .sh)

provides a convenient way to:

  • Create a keystore with a private key for Web Center

install_path/ids-j-domain-Sn/private/webcenter-keystore-alias

  • Export a self-signed certificate of that key to file

install_path/ids-j-domain-Sn/private/webcenter-alias.crt

  • Add the certificate to the truststore

install_path/ids-j-domain-Sn/private/webcenter-truststore

If the truststore doesn’t yet exist, it is created. Keystore and certificate file are overwritten if they already exist.

Before running the file, open it and set

  • dname – A distinguished name intended to identify the Web Center instance(s) the key is generated for.

  • alias - A unique name for the key.Since the alias gets part of the keystore file name don’t use any special characters in the alias.

  • keystorePassword – The keystore password; any password you like.

  • truststorePassword – The truststore password.Note that the password is shared with the server-truststore (see previous section).

Afterwards, move the created keystore to the machine hosting Web Center, and adapt the Web Center configuration as described in the previous section.

If you’ve assigned an initial truststore password change the Java-based Server’s password.properties file accordingly.

When using the batch file again to generate a key for another Web Center instance, choose a different dname and alias.

Samples

Web Center and Java-based Server on the Same Host

In the simplest case, you have a single Web Center instance which runs on the same machine as the Java-based Server.

Let’s assume

  • The folder for the Java-based Server is install_path/ids-j-My-Company-S1.

  • There’s isn’t yet a server-truststore or a webcenter-truststore for the Java-based Server, so that we can choose the truststore password.

To set up single sign-on, proceed as follows.

Generating a Private Key and a Certificate

  • Change to folder install_path/ids-j-My-Company-S1/utils/ssl.

  • Open file genWebCenter.bat.

  • Set dname, alias, keystorePassword and truststorePassword as appropriate, e.g.:

    set dname="CN=Pine, OU=Beta, O=Gamma, L=Atlanta, C=US"
set alias=pine
set keystorePassword=abc-X-123
set truststorePassword=XYZ-1234

  • Save the changes.

  • Run the batch file genWebCenter.bat.

  • Change to folder install_path/ids-j-My-Company-S1/private.

  • Check if the files webcenter-keystore-pine, webcenter-truststore and webcenter-pine.crt have been created.

  • If you open the truststore webcenter-truststore with the DirX Identity Manager, you should see the certificate with alias “pine”.

  • Make sure the keystore’s access rights grant Web Center (that is the Tomcat service) read access to the keystore.

  • Change to folder install_path/ssl.

  • Open file password.properties.

  • Assign the new password to key truststore:

    truststore=XYZ-1234

  • Save the changes.

Configuring Web Center

  • Change to Web Center’s WEB-INF folder.

  • Open file web.xml.

  • Set the value of configuration parameter com.siemens.webMgr.requestworkflow.keystoreName to the full path name of the keystore:

    @DIRXIDENTITY_INST_PATH@/ids-j-My-Company-S1/
    private/webcenter-keystore-pine

    The expression @DIRXIDENTITY_INST_PATH@ is dynamically replaced at runtime with the DirX Identity installation folder name.

  • Set the value of configuration parameter com.siemens.webMgr.requestworkflow.keyAlias to “pine“.

  • Save the changes.

  • Open file password.properties.

  • Assign the keystore password to webcenterKeystore:

    webcenterKeystore=abc-X-123

  • Save the changes.

Another Web Center on a Different Host

Now let’s configure single sign-on for a second Web Center instance on another host.

Generating a Private Key and a Certificate

On the machine with the Java-based Server:

  • Change to folder install_path/ids-j-My-Company-S1/utils/ssl.

  • Open file genWebCenter.bat.

  • Set dname, alias and keystorePassword as appropriate (note that you cannot change the truststorePassword), e.g.:

    set dname="CN=Beech, OU=Beta, O=Gamma, L=Atlanta, C=US"
set alias=beech
set keystorePassword=Y+9876-c
set truststorePassword=XYZ-1234

  • Save the changes.

  • Run the batch file genWebCenter.bat.

  • Change to folder install_path/ids-j-My-Company-S1/private.

  • Check if the files webcenter-keystore-beech and webcenter-beech.crt have been created.

  • Make sure the keystore’s access rights grant Web Center (that is the Tomcat service) read access to the keystore.

  • If you open the truststore webcenter-truststore with the DirX Identity Manager, you should see now two certificates with aliases “beech” and “pine” (from the first sample).

Moving the Keystore

Now move (or copy) the keystore webcenter-keystore-beech to any folder on the machine hosting the second Web Center instance. Make sure the keystore’s access rights grant Web Center (that is the Tomcat service) read access to the keystore.

Configuring Web Center

On the machine hosting the second Web Center instance:

  • Change to Web Center’s WEB-INF folder.

  • Open file web.xml.

  • Set the value of configuration parameter com.siemens.webMgr.requestworkflow.keystoreName to the full path name of the keystore:

    ...folder.../webcenter-keystore-pine

    Replace “…​folder…​” with the actual folder path name.

  • Set the value of configuration parameter com.siemens.webMgr.requestworkflow.keyAlias to “beech“.

  • Save the changes.

  • Open file password.properties.

  • Assign the keystore password to webcenterKeystore:

    webcenterKeystore=Y+9876-c

  • Save the changes.

Logging

When testing the single sign-on access from Web Center to a Java Server, set the log level for package "com.siemens.idm.server.authenticator" in the Java Server’s Web Admin to "FINEST".