Activating Single Sign-On

Once the credential sets have been created for your end users, you now have to activate the Single Sign-On component. Activating single sign-on involves editing properties files, setting variables, etc.

Depending on the type of application you are deploying, the steps to be performed are different.

There are two groups of applications:

  • Webtop application: ENOVIA VPM Lifecycle Navigator
  • Wintop applications: the ENOVIA VPM Product Editor (the ENOVIA VPC product), 3d com Classic and the VPM Navigator client.

The following table sums up the relevant SSO activation tasks, depending on whether you are deploying SSO for Webtop or Wintop applications:

Task Wintop Webtop
Activate SSO in the install path deployed in the Web Application Server Yes Yes
Activate SSO on the ENOVIA server side Yes Yes
Activate SSO on the ENOVIA client side Yes No

Warning: Wintop and Webtop applications (for example, ENOVIA VPM Lifecycle Navigator and the ENOVIA VPM Product Editor, the VPC product) cannot by default share access to the same ENOVIA server in SSO mode. For a detailed explanation of how to enable this function, refer to Enabling Wintop and Webtop Applications to Share the Same ENOVIA V5 Server.
 

Deployment Possibilities

The deployment diagrams in Deploying Wintop and Webtop Applications identify the software components involved but do not specify on which machine they are located.

Important: we recommend that the V5 code installation path deployed in the WAS resides on the same machine as the WAS.

Test Configuration: All Code on the Same Machine

It is quite possible, for example in the case of Webtop applications, to install all the ENOVIA server code (including for example Webtop applications) on the same machine as the WAS, in which case there is only one V5 installation path, like this:

The only use for this type of deployment is, for example, to test the software before deciding to deploy it on different machines.

Please note, however, that this is not a recommended deployment scenario.

Recommended Industrial Production Scenario: Server Code On One Machine, and WAS and V5 Code on Another Machine

We recommend that you deploy ENOVIA V5 VPM server code on one machine, and deploy the V5 code in the WAS together on a different machine. In this illustration, we illustrate how to deploy Webtop applications in the WAS on the same machine:

Keep in mind that with this kind of setup, you have two different installation paths. You need to understand fully in which install path you need to perform the different activation steps.
 

Activating SSO in the Installation Path Deployed in the Web Application Server (Wintop or Webtop)

To activate SSO for either Webtop or Wintop applications, the following steps are required to activate the SSO component in the Web Application Server, and must be performed in the installation path for the V5 application deployed in the Web Application Server.

When you have the WAS and V5 code on one machine, and the ENOVIA V5 VPM server on another, you must edit two files in the installation path of the V5 code deployed on the same machine as the WAS.

Activating SSO in the Install Path Deployed in the WAS

  1. Go to the directory:

    install_path/$os/resources/sso (UNIX)
    install_path\$os\resources\sso (Windows)

    then edit the file:

    SSOServer.properties

    and check that the SSO Administrator username has been correctly defined. It contains the following lines:

    SSORepositoryClassname=com.dassault_systemes.plmsecssoserver.plmsecssosrvimpl.SSORepository

    #You should change wpsadmin to the right Single Sign On administrator name
    SSOAdministrator=wpsadmin

    The SSO Administrator username is set by default to: wpsadmin. As mentioned in Configuring and Customizing the LDAP Repository, this is a recommended user, but you can replace it with another user. If so, set it to the correct name.
    Note: the SSORepositoryClassname referenced in R16 is the same as in R20.

  2. Edit the file:

    install_path/$os/resources/sso/SSOClient.properties  (UNIX)
    install_path\$os\resources\sso\SSOClient.properties (Windows)

    and set the following properties to "yes" (the default is "no"):

    SSOActivated=yes
    SSOSecuredEnvironment=yes

    The role of the property SSOActivated is to activate the SSO mode.

    The role of the property SSOSecuredEnvironment is to specify that you have secured the application server hosting the SSO Server.

The result is now this:

Activating SSO on the ENOVIA Server (Wintop or Webtop) and ENOVIA Client Side (Wintop only)

You also have to:

  • activate SSO on the ENOVIA server side (both Wintop and Webtop)
  • activate SSO on the Wintop client (whenever a Wintop client is necessary).

in addition to the steps you already performed in Activating SSO in the Web Application Server for Webtop and Wintop Applications.

Activating SSO on the ENOVIA Server

The following operations are required to activate the SSO component for the ENOVIA server and must be performed in the V5 installation path of the ENOVIA server:

  1. Copy the CATSSO.dic dictionary file from:

    install_path/$os/startup/sso (UNIX)
    install_path\$os\startup\sso (Windows)

    to:

    install_path/$os/code/dictionary (UNIX)
    install_path\$os\code\dictionary (Windows)

  2. Define the following variables in the shell launching the server manager, after the comments and before the line defining the operating system, #OS, and make sure they are included before the command starting the server manager.

    The variables are:

    • CATJWSServiceDirectory
    • CATLoginServletHost
    • CATSMWebMode.

    UNIX

    On UNIX, edit the file:

    install_path/$os/code/command/runServerManager

    and export them like this:

    export CATJWSServiceDirectory=http://host.domain:port/RootURI
    export CATLoginServletHost=<wasservername>
    export CATSMWebMode=true (only when deploying Webtop applications)

    Example for deploying Wintop applications:

    export CATJWSServiceDirectory=http://loug3dsy.dsy.ds:9080/B20
    export CATLoginServletHost=loug3dsy.dsy.ds

    Example for deploying Webtop applications:

    export CATJWSServiceDirectory=http://loug3dsy.dsy.ds:9080/B20
    export CATLoginServletHost=loug3dsy.dsy.ds
    export CATSMWebMode=true

    Windows

    On Windows, edit the file:

    install_path\$os\code\command\runOrbix.bat

    and set them like this:

    set CATJWSServiceDirectory=http://host.domain:port/RootURI
    set CATLoginServletHost=<wasservername>
    set CATSMWebMode=true (only when deploying Webtop applications)

    Example for deploying Wintop applications:

    set CATJWSServiceDirectory=http://loug3dsy.dsy.ds:9080/B20
    set CATLoginServletHost=loug3dsy.dsy.ds

    Example for deploying Webtop applications:

    set CATJWSServiceDirectory=http://loug3dsy.dsy.ds:9080/B20
    set CATLoginServletHost=loug3dsy.dsy.ds
    set CATSMWebMode=true

    Then, on Windows, restart Orbix using the following command:

    install_path\$os\code\bin\catstart -direnv envdirectory -env environment_file -run runOrbix.bat

    where envdirectory is the name of the directory containing the environment and environment_file is the name of your runtime environment file.

    Warning: After applying or rolling back a service pack, the running processes will be stopped at the beginning of the procedure, but re-started at the end, at least for the orbix daemon. After deploying SSO, the runorbix.exe will be-relaunched while runorbix.bat was expected. So you should manually kill and restart your orbix daemon.

    For a detailed explanation of why exporting these three variables is necessary, refer to Importance of Exporting the CATJWSServiceDirectory, CATLoginServletHost and CATSMWebMode Variables for Webtop Applications.

  3. If you do NOT want to add a specific user ServerManager in your corporate LDAP repository (and you did not import this user earlier via an LDIF file), you have to specify an existing user by creating a file named:

    ServerManagerUser

    in:

    install_path/$os/startup/sso (UNIX)
    install_path\$os\startup\sso (Windows)

    and storing the LDAP username to be used instead of the user ServerManager.

    And in the file:

    ServerManagerPwd

    store the password for the same LDAP username.

  4. If you DID import the specific user ServerManager, you must store in the file named:

    ServerManagerPwd

    in:

    install_path/$os/startup/sso (UNIX)
    install_path\$os\startup\sso (Windows)

    the password of the user ServerManager (that you created earlier in the LDAP directory), then save and exit the file.

    Due to security concerns, when filling in the file:

    install_path/$os/startup/sso/ServerManagerPwd (UNIX)
    install_path\$os\startup\sso\    ServerManagerPwd (Windows)

    you should give read access rights only for the user who starts the Orbix process.

The result is now this:

Activating SSO on the Wintop Client

If you installed a Wintop client (for example, the ENOVIA VPM Product Editor), you must activate the SSO component by editing the following files in the V5 installation path of each client.

  1. Edit the file:

    install_path/$os/docs/java/startup.properties (UNIX)
    install_path\$os\docs\java\startup.properties (Windows)

    and add at the end of the line of the applet.0.dsar property (do not insert a carriage return):

    PLBssoClientSide.jar

  2. Edit the file:

    install_path/$os/docs/java/logon.properties (UNIX)
    install_path\$os\docs\java\logon.properties (Windows)

    then uncomment and customize the file as follows:

    ###
    # Custom properties for single sign-on solution
    ###
    #AuthenticationImpl=<full class name of the AuthenticationInterface implementation>
    #CryptImpl=<full class name of the CryptInterface implementation>
    #CATLoginServletHost=<host name the web server is running on>
    #CATLoginServletPort=<port number the web server is listening to>
    #CATLoginServletURI=<path to the login servlet the web server will follow>
    ###

    Example:
    ###
    # Custom properties for single sign-on solution
    ###
    AuthenticationImpl=com.dassault_systemes.catweb.base.security.AuthenticationImpl
    CryptImpl=com.dassault_systemes.catweb.base.security.CryptBase64Impl
    CATLoginServletHost=loug3dsy.dsy.ds
    CATLoginServletPort=9080
    CATLoginServletURI=/B20/sso
    ###

    Warning: the path for the CATLoginServletURI property must comprise the Application Root URI value you entered when generating the enterprise archive file (.ear), and the suffix /sso. For example:

    /B20/sso

  3. Edit the file:

    install_path/$os/docs/java/VPMlogon.properties (UNIX)
    install_path\$os\docs\java\VPMlogon.properties (Windows)

    which looks like this:

    Nb_Languages=6
    Language.0=en
    Language.1=fr
    Language.2=de
    Language.3=ja
    Language.4=zh
    Language.5=ko

    roleModelClassname=com.dassault_systemes.vpm.security.catlet.model.CATVpmRoleModel

    then add and customize the following declaration (as in the logon.properties file) as follows:

    ###
    # Custom properties for single sign-on solution
    ###
    AuthenticationImpl=com.dassault_systemes.catweb.base.security.AuthenticationImpl
    CryptImpl=com.dassault_systemes.catweb.base.security.CryptBase64Impl
    CATLoginServletHost=loug3dsy.dsy.ds
    CATLoginServletPort=9080
    CATLoginServletURI=/    B20/sso/
    ###

    Warning: the path for the CATLoginServletURI property must comprise the Application Root URI value you entered when generating the enterprise archive file (.ear), and the suffix /sso/. For example:

    /B20/sso/

  4. For VPM Navigator, edit the file:

    install_path/$os/resources/sso/SSOClient.properties  (UNIX)
    install_path\$os\resources\sso\SSOClient.properties (Windows)

    and set the following properties to "yes" (the default is "no"):

    SSOActivated=yes
    SSOSecuredEnvironment=yes

  5. For VPM Navigator, export the CATJWSServiceDirectory variable, for example:

    export CATJWSServiceDirectory=http://loug3dsy.dsy.ds:9080/B20

The result is now this:

Importance of Exporting the CATJWSServiceDirectory, CATLoginServletHost and CATSMWebMode Variables for Webtop Applications

If you are deploying SSO mode for Webtop applications, you can only truly consider that the SSO mode has been successfully activated once you have exported the CATJWSServiceDirectory, CATLoginServletHost and CATSMWebMode variables on the ENOVIA server side, that is, if you have performed the steps explained in Activating SSO on the ENOVIA Server.

The temptation is to take shortcuts. It is actually possible to deploy the ENOVIA VPM Lifecycle Navigator, for example, in the WAS, activate SSO partially in the installation path deployed in the WAS (that is, by editing only the SSOServer.properties and SSOClient.properties files, but without exporting the three above-mentioned variables on the ENOVIA server side), and log onto an ENOVIA VPM Lifecycle Navigator session using an LDAP identity. This gives the impression that the SSO mode is fully activated. The fact that you can then create and save ENOVIA V5 lifecycle objects reinforces this impression that you are working in SSO mode, whereas in reality this is not the case.

THIS IS A PITFALL.

This pitfall occurs irrespective of whether the WAS, the Webtop code and the ENOVIA server are on the same machine, or the WAS and Webtop code are on one machine, and the ENOVIA server on another.

To illustrate this pitfall, and for the sake of simplicity, in the following scenarios the different software components are installed on the same machine.

Scenario 1

In this scenario:

  1. Server side activation has not been performed: SSO has been activated by editing ONLY the SSOServer.properties and SSOClient.properties files.
  2. The LDAP user is SMQ.
  3. The P&O user is also SMQ.
  4. The generic OS user who starts the ENOVIA V5 VPM server manager is SES.

Here is the credential set:

You will be able to log on without realizing that the SSO mode has not been fully activated: the SSO token has not been propagated:

What does that mean? The SSO token is an internal mechanism which transfers the correct credentials to the application process. If the variables are not exported, the application process started by the server manager will be owned by the OS user who started the server manager process, and not the P&O user.

This is the process ownership hierarchy (using the process explorer tool on Windows):

demonstrating that the owner of the server manager process is SES.

This is the properties tab of an action created with the same credentials:

demonstrating that the owner/creator of the action is SES.

In concrete terms, this means that when creating objects using lifecycle functions, for example, the creator of ENOVIA V5 objects will be the OS user who started the server manager process, and not the P&O user. Consequently, the owner of all the objects you create will be identical: the OS user. This is not desired.

Scenario 2

In this scenario:

  1. Server side activation has been fully performed with all the variables exported.
  2. The LDAP user is SMQ.
  3. The P&O user is also SMQ.
  4. The generic OS user who starts the ENOVIA V5 VPM server manager is SES.

So the credential set is identical:

This is the process ownership hierarchy:

demonstrating that the owner of the server manager process is still SES.

This is the properties tab of an action created with the same credentials:

demonstrating that the owner/creator of the action is this time the P&O user: SMQ.

Note: the OS userid does NOT have to be declared in the P&O database.

Enabling Wintop and Webtop Applications to Share the Same ENOVIA V5 Server

There are two groups of applications:

  • Wintop applications: the ENOVIA V5 VPM client (the ENOVIA VPC product), 3d com Classic  and the VPM Navigator client
  • Webtop application: ENOVIA VPM Lifecycle Navigator.

By default, Webtop applications and Wintop applications cannot share access to the same ENOVIA V5 server in SSO mode.

Warning: the same installation path must NOT contain both the code for the Wintop client (with SSO enabled) and the code for the Webtop application (with SSO enabled) required by the WebSphere Application Server. You can have the following configurations:

Configuration 1

In one installation path:

  • the ENOVIA V5 VPM server code (with SSO enabled)
  • the Webtop code (with SSO enabled) required by the WAS

and in another installation path:

  • the Wintop client code (with SSO enabled)
Configuration 2

In one installation path:

  • the ENOVIA V5 VPM server code (with SSO enabled)
  • the Wintop client code (with SSO enabled)

and in another installation path:

  • the Webtop code (with SSO enabled) required by the WAS.

However, you can enable Webtop applications and Wintop applications to effectively share access to the same server by following this scenario which involves duplicating the Orbix entry point, with one Orbix environment for Webtop applications and one for Wintop applications, then exporting a variable in the resulting Webtop environment:

  1. Create a new Orbix directory, orbix2 (for the Webtop environment), for example by copying the Orbix directory in the ENOVIA V5 VPM server installation path from:

    $install_path/startup/orbix

    to:

    $install_path/startup/orbix2
  2. Modify the file:

    $install_path/startup/orbix2/iona.cfg

    by replacing:

    cfg_dir = "$install_path/startup/orbix/config/";

    with:

    cfg_dir = "$install_path/startup/orbix2/config/";
  3. Set the orbix2 ports. In:

    $install_path/startup/orbix2/config/common.cfg

    set:

    IT_DAEMON_PORT = "xxxx", where xxxx is the number of an available listen port
    IT_DAEMON_SERVER_BASE = "yyyy", where yyyy is a number of an available port
    IT_DAEMON_SERVER_RANGE="zzz", where zzz is a range interval
  4. Copy the file:

    $install_path/code/command/runServerManager

    to:

    $install_path/code/command/runServerManager2
  5. Modify the file CATIAServerManager.IMP file found in:

    $install_path/startup/orbix2/config/Repositories/ImpRep

    by replacing:

    runServerManager

    with:

    runServerManager2
  6. Activate the SSO mode in the file runServerManager2.
  7. Edit the file runServerManager2 and set the following variable:

    export CATSMWebMode=true
  8. Create a shell starter for orbix2 by copying the shell:

    $install_path/code/command/runOrbix

    to:

    $install_path/code/command/runOrbix2
  9. Modify IT_CONFIG_PATH in the runOrbix2 shell as follows:

    IT_CONFIG_PATH=$install_path/startup/orbix2
    IT_DAEMON_PORT=xxxx (as defined in step 2 above)
  10. Start the orbix2 daemon as follows:

    $install_path/code/command/runOrbix2

This means that:

  • in the runServerManager file for the Wintop applications, the CATSMWebMode variable is not set
  • but the runServerManager2 file for the Webtop applications contains the line:

    export CATSMWebMode=true

Note: This methodology can be easily implemented on the Windows OS. The purpose of the CATSMWebMode environment parameter is to differentiate two behaviors of the Server Manager, which are not compatible.

Note that the CATSMWebMode variable can only be exported for the Webtop applications.

Note about Orbix On AIX

The Orbix connection from an ENOVIA App Server launched by an Orbix Daemon A to a Vault Server fails if the Vault Server is running on the same machine and has not been launched by the same Orbix Daemon A.

The recommended by-pass is to deploy the Vault Server on a dedicated machine which is not shared with the ENOVIA App Servers. If it is not possible to have a dedicated machine, then the same Orbix daemon has to be used for ENOVIA App Server and the Vault Server.
 

Deactivating Single Sign-On and Deleting Credential Sets

To deactivate the Single Sign-On capability, you must undo the steps that were performed on the ENOVIA server and the client.

Note: If you are using the default SSO Repository, to delete all credential sets that you created on the machine on which the server was installed, delete the file:

$install_path/$os/resources/credentials/SSOServer.credentials

WARNING: We do not recommend that you use the default SSO Repository. To create your own SSO Repository, see the task Implementing Your Own SSO Repository. However, if you do use your own SSO Repository, you must manage the deactivation yourself.
 

V5 SSO Authentication User Exit

In V5 PLM solutions, the Single Sign-On Infrastructure relies on IBM WebSphere for authentication, and only supports basic authentication mode.

This limitation prevents the use of the V5 SSO solution with an IBM WebSphere secured with other schemes, such as Kerberos or Digest authentication. This feature aims at providing a simple way to enable support by the V5 SSO infrastructure of authentication schemes other than basic authentication.

A Few Definitions

LTPA: Acronym for Lightweight Third-Party Authentication. LTPA is an authentication technology used in IBM WebSphere and Lotus Domino products. When accessing web servers that use the LTPA technology it is possible for a web user to re-use his login across physical servers.

SSO: Acronym for Single Sign-On: SSO is a method of access control that enables a user to log in once and gain access to the resources of multiple software systems without being prompted to log in again.

Previous SSO Behavior

Prior to the V5 SSO authentication user exit, SSO behavior can be summed up by the following illustration:

New SSO Behavior

The V5 SSO authentication user exit enables customers to use an alternative authentication scheme, in particular Kerberos, as shown in the following illustration:

This authentication user exit provides a way for V5 applications using the SSO infrastructure to authenticate to the SSO Server using any authentication method, provided that the following conditions are met:

  • The IBM WebSphere server must be secured in such way that LTPA mode is active
  • The application must be provided a valid LTPA token corresponding to the SSO user for whom credentials need to be retrieved from the SSO server.

Authentication for V5 applications Based on the C++ SSO Client

To enable integration of authentication schemes from V5 applications to SSO Server other than basic authentication, this feature provides a way for a customer-provided application to start V5 applications in SSO mode so as to skip the basic authentication step performed by the SSO client to the SSO server, and use instead an SSO Token value (consisting in an LTPA token string) for this authentication.

To be more precise, the feature will be activated only if the following environment variable is set:

CATSSOTokenExitValue

There are two ways to take advantage of this feature:

  • either the CATSSOTokenExitValue variable directly contains the SSO Token value
  • or it contains the absolute path of an executable command which outputs the SSO Token value.

SSO Token Set via an Environment Variable

One simple way to take advantage of direct LTPA-based authentication consists in setting the CATSSOTokenExitValue variable with a value based on the following template:

LtpaToken2=<value>;Path=/

For example:

LtpaToken2=QAWeWznUcsj9AUfHYFwmMkG/uNfdGq1p/vUObxNsHYH0J8R0aZO7E+
scMun+DvKQzF6f8iJZTj8hTxgouZqkxuEupGdUsM5mb/teH4KXREw0a94X+TC+WOP
/6XNpdDDKhabNsnG4mhznp/dNSLYlee1529p05nGNZUYZCWGFB4h/Vt1ooreZUHllM
qFPDFGVRP9SECpwmNRVAwkzETCdRh4Tp61XAljQae0AjGeBNr2d1hNrd3Iti+Xm06L
NbLU33Wetjz3DffSL9JO8xCMHJqTER6WyfyFRvplSCWqczCxzp5x8CP53VHeqSdbKQ74c7Qntauax50w=;Path=/

To enable a specific authentication scheme for CATIA V5 with VPM Navigator, you will have to create an executable which will deal with the authentication authority (which can be a Kerberos server with WebSphere SPNEGO integration), and make sure this executable can output the value need for the CATSSOTokenExitValue variable.

Then, for example on UNIX, CATIA could be launched using a wrapper shell containing:

export CATSSOTokenExitValue=`customercode.exe` catstart

If it needs the URL of the SSO Server, your executable can be started using catstart –run and get the value of the CATJWSServiceDirectory variable.

SSO Token Set via a Customer-Defined Executable

The other way to to take advantage of direct LTPA-based authentication consists in setting the CATSSOTokenExitValue variable with the absolute path of an executable program which prints to its standard output a value based on the following template:

LtpaToken2=<value>;Path=/

Given that this executable is called by the V5 application relying on the SSO infrastructure, it inherits the V5 environment variables, so it can use the CATJWSServiceDirectory variable to get the URL of the SSO Server if needed.

Authentication for V5 applications not based on the C++ SSO Client

The authentication solution provides the PLMSecSSOPing command, which can be used to benefit from the CATSSOTokenExitValue solution for a non-basic authentication based SSO Server.

The PLMSecSSOPing command is used as follows:

PLMSecSSOPing.EXE [-user <username> -password <pwd>] | [-ssocred <value>] [-app <name>] [-instance <name>] -action <type> | -h

where:

  • -user <username>: SSO user name
  • -password <pwd>: SSO password
  • -ssocred <value>: SSO credential, can be used instead of SSO user name & password
  • -app <name>: application name
  • -instance <name>: instance name, use ‘.’ as the instance name if the instance is an empty string
  • -action <type>: Type of action, must be one of:
    •  listapps : list all applications having al least one SSO credential
    •  listinst : list all instances of a given application
    •  listcreds : list all credentials for a given application & instance
    •  showssocred : show the value of the SSO credential
    •  showuser : show the SSO user name
    •  isauth : check whether or not SSO authentication is valid (TRUE or FALSE)
  • -h: shows this help message

Limitations

This featrue provides a direct solution for V5 applications based on the C++ SSO Infrastructure, such as VPM Navigator. On the other hand, it only indirectly provides a solution for an application like ENOVIA VPM Product Editor which is based on a deprecated SSO Java API. For VPM Product Editor, to support an authentication scheme other than basic for SSO server connection, keep in mind the following facts related to the PLMSecSSOPing command:

  • the PLMSecSSOPing command relies on the C++ SSO Infrastructure, which means that it can use the SSO Token provided by your code in order to authenticate to the SSO Server.
  • Using  the -action listcreds option allows you to get the credentials for ENOVIA V5 server login. Then, VPM Product Editor can be started using these credentials retrieved later. Note: to benefit from this solution, VPM Product Editor must be set up in non-SSO mode.

This feature will only work for authentication schemes compatible with the IBM WebSphere LTPA token mechanism. To be more precise, if an authentication scheme does not allow for a client application to login to IBM WebSphere using a valid LTPA token set in request cookie headers, then the V5 SSO solution will not work.
 

Customizing User Exits for VPM V4

The repository database of VPM V4 must be configured to support server authentication for SSO to be enabled in VPM V4 (and therefore ENOVIA V5 VPM).

In addition to the ENOVIA V5 VPM setup itself, other tasks must be performed in the environment of VPM V4 in order to complete the SSO setup when using ENOVIA V5 VPM. To do so:

  • run the following command to activate the single sign-on plug-in in VPM V4:

    VPMSettings -a -n VPM_EXTERNAL_LOGIN -v YES
  • set the following environment variables:

    CATLoginServletHost
    CATLoginServletPort
    CATLoginServletURI

They reference the server host name, the port to be used for HTTP connections, and the servlet to be run on it, respectively.

If data encryption is enabled on the server, the following variables must also be set in order to reference the correct library and encryption/decryption methods:

CATLoginCryptLibrary
CATLoginCryptFunction
CATLoginUncryptFunction

The default values should be:

CATLoginCryptLibrary=VX0SCEXT
CATLoginCryptFunction=encodeBase64Password
CATLoginUncryptFunction=decodeBase64Password

which make VPM V4 use its built-in 64-bit encoding.

All these variables should be set in the run-time environment of VPM V4. This could be done automatically by adding the adequate variable export commands to an initialization file, such as VPMWsUser.env.

Note: the previous six environment variables are the same as those set in initialization file ssoinit.sh of ServerManager. The values always be the same for the first three servlet variables. The values of the other three may differ depending on the legacy encryption implementation.
 

Servers Checkpoint

Troubleshooting Session Management

Some database or WAS configuration mistakes can break Single Sign-On in a way which leads to an exception page whenever users try to open the Single Sign-On administration page. The following lines appear in the exception page:

Original Exception: Error Message: Server caught unhandled exception from servlet [CATServletManager]: null Error Code: 500 Target Servlet: CATServletManager Error Stack: java.lang.NullPointerException at com.dassault_systemes.catjsystem.catjsyj2ee.CATJ2EEServlet Manager.getSession(CATJ2EEServletManager.java:111) at com.dassault_systemes.catjsystem.catjsyj2ee.CATJ2EEServlet Manager.service(CATJ2EEServletManager.java:168) at javax.servlet.http.HttpServlet.service (HttpServlet.java:853)

Possible causes leading to this error are:

  • Single Sign-On not being able to connect to the Settings database.
  • Wrong session parameters at server or web application scope.

The following subsections will cover determining the problem's cause and fixing it.

Fixing Single Sign-On not being able to connect to the Settings database

The error page quoted above shows up when Single Sign-On application is not able to connect to the Settings databases. The usual causes of this failure are:

  • Database not started: check this by issuing a start database command.
  • Database alias not properly defined (DB2) or wrong TNSNAME (ORACLE): check this using command-line SQL client (sqllib for DB2, sqlplus for ORACLE) in order to check database connection.
  • Mistake in the Data Source definition: use the 'Test Connection' button in WAS admin console to check the Data Source ; and make sure that its JNDI name is 'jdbc/JSystem'.
  • Database server being corrupted for other reasons: restart the database server, or even the database server machine.

If any changes to database or data source definition where made during these verification steps, stop and restart WAS to make sure all changes were taken into account. In case of a WAS ND-based deployment, also restart the node agents.

Fixing Wrong session parameters at server or web application scope

Another cause leading to the exception page can be a mistake in WAS session configuration. You can check session parameters with the following steps:

  1. Launch the Administrative Console and select Servers  >  Application Servers.
  2. Click the name of the server on which the Single Sign-On EAR file was deployed. In this example, this is server1.
  3. Scroll down and click Web Container.
  4. On the Web Container page, click Session Management.
  5. On the Session Management page, check that Enable Cookies property is checked in the 'Session tracking mechanism' line, and click on the Enable Cookies link.
  6. On the Cookies page, make sure that in the Cookie maximum age line, the 'No timeout' radio button is checked. If Set timeout radio button is checked, change this so that No timeout is checked.
  7. Save all changes and restart all servers before re-testing.