Configuring the SSO Authentication

The SSO ("preauth" in Spring framework terminology) configurations are located in the WEB-INF\config\context\security\preauth folder.

SmartClient will attempt to retrieve configuration settings from WebCentral using the WSDL SmartClientSsoConfigService. The SmartClientSsoConfigService returns the SSO properties usernameKey and projectIdKey. To configure these keys in WebCentral: modify the *.properties files in the /WEB-INF/config/context/security/preauth folder.

If the SmartClientSsoConfigService call fails, indicating a Web Central version prior to V20.1, the values for usernameKey and projectIdKey are taken from hard-coded constants.

Note: For an overview of the SSO authentication, see Authentication: Single Sign-On (SSO).

Note: If you are setting a value of string_format for afm_users.user_name to any other value than UPPER*, you also must change the value of the convertToUpperCase property to false in /WEB-INF/config/context/security/preauth/account-mapper.xml.

Link to Web Central

To load Web Central in SSO mode, each user should use URL that ends with "login.axvw", for example: localhost:8080/archibus/login.axvw

The Logout Page

This step applies to all SSO configurations.

Modify the WEB-INF/config/security.properties file: replace values of the logoutView and timeoutView properties:

security.logoutView=schema/ab-core/views/process-navigator/logout-preauth.htm

security.timeoutView=schema/ab-core/views/process-navigator/logout-preauth.htm

This view appears if SSO users time out of their ARCHIBUS session or log out explicitly.

This setting places users on a page that notifies them that they have logged out.

The SSO configuration does not use the login page that prompts for a user ID and a password.

Note: Users who use the Page Navigation features (home pages) must have their roles published after SSO is configured so that the logout page is correctly written to the published HTML pages.

The Error Page

This step applies to all SSO configurations.

Modify the WEB-INF/config/context/compatibility/afm-config.xml file: replace value of the loginView attribute:

loginView="preauth-error.axvw"

This view appears if the username of SSO user does not match any record.

The SSO configuration does not use the login page that prompts for a user ID and a password.

Request Header Configuration

This configuration supports both Web Central and the Smart Client.

In this SSO configuration, sites use an authentication server, such as SiteMinder, to protect access to the Web Central server. The authentication server forwards requests from the Smart Client and the Web browser, and inserts the proper username into the request before passing it to Web Central.

Procedure:

Configure Web Central according to the instructions in WEB-INF/config/context/security/preauth/username-source/request-header/readme.txt.

Remote User Configuration

In this scenario, you configure the application server to use container-based authentication. In this configuration, Web Central gets its username from the HttpServletRequest.getRemoteUser() method.

The procedure below illustrate how to establish this type of authentication using a typical reference configuration involving IIS and Tomcat.

1. Configure Tomcat and IIS according to the instructions in Configuring Tomcat and IIS for the Remote User Configuration.

2. Configure Web Central according to instructions in WEB-INF/config/context/security/preauth/username-source/remote-user/readme.txt.

The remote user configuration does not itself support the Smart Client. Sites that use the remote user configuration for Web Central can use the following complementary options for authenticating Smart Client users:

authenticate Smart Client users against a reverse-proxy server using either client-certificates or form-based authentication
use request header authentication for the Smart Client (by using the instructions below).
use ARCHIBUS authentication for the Smart Client workstations

If you use ARCHIBUS authentication, you would set up a separate Web Central instance to support those users that require Smart Client access. If you want to use the same directory service (e.g. Active Directory) to authenticate these users, you can have Web Central authenticate these users via LDAP.

Remote User + Request Header for Smart Client Configuration

This configuration supports both Web Central and the Smart Client.

In this SSO configuration:

Web Central gets its username from the from HttpServletRequest.getRemoteUser() method (as is usually the case if you are using IIS).
The Smart Client uses request header authentication; that is, it automatically inserts the username into the header of the HTTP request, when sending request to Web Central.

Procedure:

Configure Tomcat and IIS according to instructions in Configuring Tomcat and IIS for the Remote User Configuration.
Configure Web Central according to instructions in WEB-INF/config/context/security/preauth/username-source/remote-user-request-header/readme.txt.

Some sites prefer to use the certificate security option for the Smart Client workstations instead. Doing so removes potential concerns about users falsifying their authentication information using sophisticated techniques.

Sites that do use the SSO request header configuration for the Smart Client may wish to use TLS to protect the traffic to the server and alter their usernameKey per the instructions above.