CentraSite SSO with Trusted Reverse Proxy Introduction Single-sign-on (SSO) via reverse proxy is the preferred SSO method for CentraSite. Due to its flexibility the reverse proxy approach allows to apply various authentication frameworks and methods. To block any un-authenticated access the reverse proxy must not be by-passed. A proper means towards that is to establish a trusted relationship between the reverse proxy and CentraSite. This tutorial describes how the trusted relationship can be established. It applies to CentraSite 9.5.and 9.6. For newer CentraSite versions the configuration procedure is similar but has some differences which are not covered here. Overview The following diagram shows the reverse proxy set-up for the CentraSite SSO. The setup consists of a reverse proxy, a custom authenticator, CentraSite and a user repository. The reverse proxy applies a custom authenticator on the incoming requests. Usually the custom authenticator is a servlet or a servlet filter interacting with a SSO framework. On a successful authentication the servlet adds the authenticated principal to incoming request and forwards it to CentraSite. The forwarded authenticated principal references a user in the user repository. CentraSite applies a simple authentication procedure on the incoming request that just locates the referenced user in the LDAP directory. On a successful authentication CentraSite retrieves user and group information. The LDAP directory accessed by CentraSite can also be used by the custom authenticator, but does not need to. The configuration of the custom authenticator is not addressed within this tutorial, since it depends on the applied SSO solution. Instead the focus here is on the configuration of the reverse proxy to talk to CentraSite and on the CentraSite configuration for validating the forwarded authenticated principals. The reverse proxy configuration also includes the necessary configuration of SSL communication between the reverse proxy and CentraSite. For establishing a trusted relationship between the reverse proxy and CentraSite 2-way SSL authentication is configured. The tutorial also covers the configuration of SSL communication between Web Clients and the reverse proxy. Configuration Procedure The configuration procedure consists of the following steps. 1. 2. 3. 4. Reverse proxy configuration CentraSite SSO configuration CentraSite SSL configuration Reverse proxy SSL configuration
The procedure establishes the SSO configuration with the trusted reverse proxy in an iterative way. The first 2 steps establish the reverse proxy based configuration. Once the this is working the next 2 steps perform the necessary actions for establishing a trusted relationship between the reverse proxy and CentraSite. Reverse Proxy Configuration The described approach is not restricted to any specific reverse proxy. In this tutorial we show how the Apache Web server can be configured to act as a reverse proxy talking to CentraSite. For supporting SSL (HTTPS) communication an Apache version 2.2 or 2.4 with OpenSSL support is required. In this tutorial we use an Apache 2.2. The Apache configuration needs to be adapted with proper proxy rules to load the proxy modules and to provide the necessary reverse proxy settings. The necessary entries in the Apache httpd.conf look as follows: LoadModule proxy_module modules/mod_proxy.soo LoadModule proxy_http_module modules/mod_proxy_http.so # add proxy ProxyRequests Off <Proxy *> Order deny,allow Allow from all </Proxy> ProxyPreserveHost On ProxyPass /PluggableUI http://cast-host:53307/pluggableui ProxyPassReverse /PluggableUI http://cast-host:53307/pluggableui ProxyPass /CentraSiteReportEngine http://cast-host:53307/centrasitereportengine ProxyPassReverse /CentraSiteReportEngine http://cast-host:53307/centrasitereportengine ProxyPass /CentraSite http://cast-host:53307/centrasite ProxyPassReverse /CentraSite http://cast-host:53307/centrasite ProxyPass /BusinessUI http://cast-host:53307/businessui ProxyPassReverse /BusinessUI http://cast-host:53307/businessui The proxy rules ensure that CentraSite Control and BUI are accessible through the reverse proxy. Therefore the proxy rules re-route the corresponding requests to the CentraSite endpoints. In the routing rules cast-host needs to be replaced with the machine name CentraSite is running on. The reverse proxy configuration can be validated by accessing the CentraSite BusinessUI and CentraSite Control through the reverserse proxy URL. CentraSite SSO Configuration The first step of the CentraSite SSO configuration is to create a configuration for accssing the LDAP directory. Usually the LDAP directory does not allow any anonymous access. Therefore the LDAP configuration must contain a technical user. Instructions for doing this are provided in the tutoral LDAP Configuration Tutorial for CentraSite 9.0. Once the LDAP configuration has been established and verified successfully the CentraSite authentication procedure needs to be configured. CentraSite performs the authentication via jaas. The jaas configuration file can be found in the Software AG installation directory in the folder /prof iles/ctp/configuration/jaas.config. The CentraSite authentication procedure is given by the CentraSite jaas login context. For the validating incoming authenticated principles the configuration looks as follows:
CentraSite { /** Try a normal login first before doing SSO */ com.softwareag.security.jaas.login.ssx.ssxloginmodule sufficient uselog="true" options_url="http://localhost:53305/centrasite/centrasite/ino:noauth:getsinconfigurati on=" CreateGroups="false" internalrepository="c:/softwareag/common/conf/users.txt" UseDomainForOptionsURL="true"; /** Stop authentication if the first login module was successful */ com.softwareag.security.jaas.login.ssx.ssxstoploginmodule sufficient; /** Extract user id from HTTP header */ com.softwareag.security.jaas.login.modules.servletheaderloginmodule required httpheaderuser_prop_name="sag_auth" use_as_user_name=true; /** Create principal from user id and fetch information from LDAP */ com.softwareag.security.jaas.login.ssx.ssxloginmodule required useldaptechuser="true" techldapusercredfile="c:/softwareag/credentials/admin.txt" techldapuserkeyfile="c:/softwareag/common/security/ssx_32/etc/alt_keyfile.txt" ignoreldapuserpassword="true" options_url="http://localhost:53305/centrasite/centrasite/ino:noauth:getsinconfigurati on=" UseDomainForOptionsURL="true" CreateGroups="false"; }; The first login module in the CentraSite login context performs a normal login. If this is successful the SSXStopLoginModule stops the authentication. This is necessary to support a login via user name and password. The ServletHeaderLoginModule initiates the SSO by extracting the user information from the HTTP header field SAG_auth. The extracted user id is passed on to the last login module that checks if the user id exists in the LDAP user repository. If it finds the user the authentication is successful and the user related information is extracted from LDAP. Otherwise the authentication fails and the user will prompted for providing user name and password. Once the jaas configuration has beend adapted the SSO can be validated by trying to access CentraSite BusinessUI or CentraSite Control. The CentraSite SSO configuration can be validated by accessing CentraSite directly with a browser that sends an HTTP header holding the id of an LDAP login user defined in CentraSite. When accessing CentraSite Control or BusinessUI with the additional header field the configured user should be automatically logged in. If there is a problem with the jaas configuration the login screen will show up. There are several browser plugins or extensions that allow to add a dedicated header field to the HTTP requests issued by a browser. An example is the ModifyHeaders Chrome extension. For the above example jaas configuration the user id needs to be provided in the HTTP header field SAG_Auth. CentraSite SSL Configuration The CentraSite SSL configuration is established by adapting the HTTPS port configuration. The CentraSite ports are configured via properties files stored in the directory profiles/ctp/configuration/com.softwareag.platform.config.propsloader of the Software AG installation folder. The configuration of the HTTPS port is stored in the properties file com.softwareag.catalina.connector.https.pid-centrasite.properties.the SSL configuration requires a keystore for the server certificate and a truststore that holds the necessary entries for trusting the certificates sent by the reverse proxy. A sample properties file looks as follows
enabled=true description=centrasite 9.0 HTTPS maxhttpheadersize=8192 maxthreads=150 minsparethreads=25 maxsparethreads=75 enablelookups=false disableuploadtimeout=true acceptcount=100 SSLEnabled=true scheme=https keystorefile=c:/certs/keystore.jks keystoretype=jks keystorepass= truststorefile=c:/certs/truststore.jks truststoretype=jks truststorepass= clientauth=true algorithm=sunx509 sslprotocol=tls port=53308 secure=true SSLVerifyClient=true The sample configuration references the keystore.jks and the trustore.jks. For activating the client SSL authentication the parameter SSLVerifyCli ent is set to true. It makes sense to verify the CentraSite SSL configuration by accessing CentraSite directly with a browser. If your browser is not aware of any certificates configured in CentraSite it should raise SSL errors when accessing CentraSite directly. When the client certificate is missing the browser shows a client authentication related error (e.g. ERR_BAD_SSL_CLIENT_AUTH_CERT). The browser will not be able to access CentraSite without the correct client certificate. When the server certificate is missing the browser does not trust CentraSite. To fix the SSL problems the client certificate and the server certificate need to be imported into the browser. There are several tutorials on the Web explaining how to do that (e.g. http://s.omni.teonite.com/kb/importing_pkcs12.html). When the certificates are in place the CentraSite Control and BusinessUI can be accessed without any SSL problems. Reverse Proxy SSL Configuration The next steps is to enhance the SSL proxy configuration rules to use SSL for communicating to CentraSite.
LoadModule proxy_module modules/mod_proxy.soo LoadModule proxy_http_module modules/mod_proxy_http.so LoadModule ssl_module modules/mod_ssl.so # add proxy ProxyRequests Off <Proxy *> Order deny,allow Allow from all </Proxy> SSLProxyEngine On SSLProxyMachineCertificateFile c:/certs/all.pem ProxyPreserveHost On ProxyPass /PluggableUI https://cast-host:53308/pluggableui ProxyPassReverse /PluggableUI https://cast-host:53308/pluggableui ProxyPass /CentraSiteReportEngine https://cast-host:53308/centrasitereportengine ProxyPassReverse /CentraSiteReportEngine https://cast-host:53308/centrasitereportengine ProxyPass /CentraSite https://cast-host:53308/centrasite ProxyPassReverse /CentraSite https://cast-host:53308/centrasite ProxyPass /BusinessUI https://cast-host:53308/businessui ProxyPassReverse /BusinessUI https://cast-host:53308/businessui As shown by the above sample the SSL module is required. Moreover the SSLProxyEngine is activated and the SSLProxyMachineCertificateF ile configuration parameter points to a pem file. The pem file holds the key pair for the client certificate of the reverse proxy and the certificated sent by CentraSite. The proxy rules references the https protocol and the CentraSite HTTPS port. The final configuration step can be verified by accessing CentraSite Control and BusinessUI through the reverse proxy. Further Configurations If the HTTPS protocol is used between the reverse proxy and CentraSite, the same should be used for the communication between the Web Clients and the reverse proxy. It makes sense to add a SSL VirtualHost to the Apache configuration for the client communication. The proxy settings described in the previous sections can be moved to the VirtualHost configuration. Sample descriptions of an Apache SSL configurations can be found on the Web After the SSL communication is configured on the reverse proxy the Web clients have to trust the certificate provided by the reverse proxy. This can be achieved to add the necessary entries into the truststore of the Web clients. Assuming the reverse proxy provide a self signed certificate, this certificate can be added. Unfortunately the Apache is not forwarding the HTTPS protocol correctly. Therefore the protocol needs to be sent in a separate HTTP header field to be correctly picked up by CentraSite. The Apache configuration needs to be changed for adding the header field X-Forwarded-Proto to any incoming HTTPS request. For adding HTTP header fields the headers_module is required, which can be activated by un-commenting the following line in the Apache httpd.conf. LoadModule headers_module modules/mod_headers.so With the activated headers_module the X-Forwarded-Proto can be added to incoming requests with the following line in the the SSL VirtualHost.
RequestHeader set X-Forwarded-Proto "https" For eanbling the SSL communication the CentraSite report engine configuration has to be changed. Here the base_url parameter in the file "/CentraSite/cast/cswebapps/CentraSiteReportEngine/WEB-INF/viewer.properties" needs to be set to an empty value. This means the configuration file must hold the following line: # configurable variable for JSP base href. Please uncomment the below line. base_url= The trusted relationship between CentraSite and the reverse proxy can be established without using HTTPS between Web Clients and the reverse proxy. Not using HTTPS communication here, results in session handling problems in the CentraSite BUI. These problems are caused by secure HTTP session cookies sent by CentraSite BUI. Secure cookies can't be used when communicating over HTTP. The easiest way to solve the problem is to configure Apache to remove the secure flag from the session cookies. The according entry in the Apache httpd.conf looks as follows. Header edit "Set-Cookie: JSESSIONID=" Secure " "