Configuring the server for single sign-on after installation

After you install the Remote Control server, you can configure it to support SAML 2.0 authentication.

Before you begin

You must create a keystore with a single self-signed certificate (or CA signed certificate) before you start the configuration. Select a Key Size of 2048 and select sha256 for the Signature Algorithm. The keystore file can be a .p12 or .jks file. Do not save the file to the server installation directory because that might conflict with the server self-signed certificate. Set a long validity period for the keystore. For more information about creating a keystore file, see Creating a self signed certificate.

About this task

Note: SSO support in Remote Control is done through the Open Liberty samlWebSso20 feature. By default, the NameID that is returned by the Identity Provider to our service must contain an email field in the following format.

URI: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

You can configure a Liberty server as a SAML web browser Single-Sign-On (SSO) service provider by enabling the samlWeb-2.0 feature in Liberty.

To configure the Remote Control server, complete the following steps:

Procedure

Create an sso.xml file in the following directory:

Windows™ operating system

C:\Program Files\BigFix\TRC\server\wlp\usr\servers\trcserver or
C:\Program Files (x86)\BigFix\TRC\server\wlp\usr\servers\trcserver if available

Linux™ operating system

/opt/BigFix/TRC/server/wlp/usr/servers/trcserver
Add the following content to the sso.xml file:
```
<server>
<featureManager> }}
<feature>samlWeb-2.0</feature>}}
</featureManager> }}
<samlWebSso20 id="defaultSP" keyStoreRef="samlKeyStore" httpsRequired="true"
signatureMethodAlgorithm="SHA256" spHostAndPort="https://[hostname:port]"/>
<keyStore id="samlKeyStore" location="[samlKey.file]"
password="[yourkeystorepassword]" type="[filetype]"/>
</server>
```
[hostname:port]

Defines the host name and SSL port of your remote control server. For example, https://example.com:443/.

[samlKey.file]

Defines the path to your keystore file. For example, c:\trc\samlKey.p12.

[yourkeystorepassword]

Defines the password for your keystore file. For example, password="mypassword".

[filetype]

Defines the file type of your keystore file. For a .p12 file, set type to PKCS12. For a .jks file, set type to JKS.

The keyStore id value must match the keyStoreRef value in the <samlWebSso20> element.
You can add more configuration parameters. For more information, see SAML Web SSO 2.0 Authentication (samlWebSso20)

In a default configuration, the following values are used:

AssertionConsumerService URL

https://<hostname>:<sslport>/ibm/saml20/defaultSP/acs.

Service Provider (SP) metadata URL

https://<hostname>:<sslport>/ibm/saml20/defaultSP/samlmetadata
Where <hostname> is the host name of your Remote Control server and <sslport> is the SSL Port value. For example, 443.

Edit the application.xml file in the following directory:

Windows™ operating system: C:\Program Files\BigFix\TRC\server\wlp\usr\servers\trcserver or
C:\Program Files (x86)\BigFix\TRC\server\wlp\usr\servers\trcserver if available
Linux™ operating system: /opt/BigFix/TRC/server/wlp/usr/servers/trcserver

Add the following <application-bnd> statement to the file.

<server>
 <application   context-root="/trc" type="ear" id="trcserver"
 location="TRCAPP.ear" name="trcserver"  autoStart="true" >
 <application-bnd>                                                 
  <security-role name="any-authenticated">                      
  <special-subject type="ALL_AUTHENTICATED_USERS" />            
  </security-role>                                              
 </application-bnd>
 </application>
 <application   context-root="/" type="ear" id="trcredir"
 location="REDIR.ear" name="trcredir"  autoStart="true" />
 <applicationMonitor updateTrigger="disabled" dropinsEnabled="false" />
</server>

Get the SAML metadata XML file from the Identity Provider (IdP).
How this file is obtained varies, depending on the IdP. Rename the file to idpMetadata.xml and copy it to the following directory on the server:

Windows™ operating system

C:\Program Files\BigFix\TRC\server\wlp\usr\servers\trcserver\resources\security or
C:\Program Files (x86)\BigFix\TRC\server\wlp\usr\servers\trcserver\resources\security if available

Linux™ operating system

/opt/BigFix/TRC/server/wlp/usr/servers/trcserver/resources/security
Edit the common.properties file and set sso.enabled to True.
The file is in the following directory:

Windows™ systems

[installdir]\wlp\usr\servers\trcserver\apps\TRCAPP.ear\trc.war\WEB-INF\classes
Where [installdir] is the directory in which the Remote Control server is installed.

Linux™ systems

[installdir]/wlp/usr/servers/trcserver/apps/TRCAPP.ear/trc.war/WEB-INF/classes
Where [installdir] is the directory in which the Remote Control server is installed.
Restart the Remote Control server.
After the server restarts, type the following URL into your browser to download the metadata for this service provider (SP) which is the BigFix® Remote Control Server:
https://<hostname>:<sslport>/ibm/saml20/defaultSP/samlmetadata, where <hostname> is the host name of your remote control server and <sslport> is the SSL port of the server. Provide the metadata to the SAML identity provider to establish federation between this SP and Identity Provider (IdP).

Results

When you access the Remote Control server application, and you did not previously log on, you are redirected to the IdP. If you did previously log on by using the same IdP, you are automatically logged on to the Remote Control server application.

Note: After you enable SAML 2.0 authentication, if you reinstall or upgrade your server, the sso.xml file must be copied to a temporary directory before you start. Replace the sso.xml file that is installed during the upgrade with the backed-up file. Also, ensure that sso.enabled is set to True in the common.properties file.