Configuring the server for single sign-on after installation

After you install the BigFix® 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 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 BigFix® Remote Control is done through the WebSphere 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 BigFix® Remote Control server, complete the following steps:

Procedure

  1. Create an sso.xml file in the following directory:
    Windows operating system
    C:\Program Files (x86)\IBM\Tivoli\TRC\server\wlp\usr\servers\trcserver
    Linux operating system
    /opt/IBM/Tivoli/TRC/server/wlp/usr/servers/trcserver
  2. 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.jks.
    [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 BigFix® Remote Control server and <sslport> is the SSL Port value. For example, 443.

  3. Edit the application.xml file in the following directory:
    Windows operating system
    C:\Program Files (x86)\IBM\Tivoli\TRC\server\wlp\usr\servers\trcserver
    Linux operating system
    /opt/IBM/Tivoli/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> 
  4. 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 (x86)\IBM\Tivoli\TRC\server\wlp\usr\servers\trcserver\resources\security
    Linux operating system
    /opt/IBM/Tivoli/TRC/server/wlp/usr/servers/trcserver/resources/security
  5. 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 BigFix® 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 BigFix® Remote Control server is installed.

  6. Restart the BigFix® Remote Control server.
  7. 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 BigFix® 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 BigFix® 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.