Set up SSO‌

Configure trusted certificate authorities

For SSO and smart card installations, the certificate for user, services, and other purposes must be issued by a trusted Certificate Authority (CA). To configure CAs correctly you need a certificate of your authority (it can be CA on a Microsoft Domain Controller or externally based on OpenSSL).

Add a certificate to a Java key store

You can use the standard Java tool "keytool" to create a new keystore or add a new certificate to existing keystore. Enter the following command:

"%JAVA_HOME%\bin\keytool" -import -keystore
   <your_keystore_file_name> -storepass
   <your_keystore_password> -file <cert_to_import> -alias
   <your_cert_alias>

where:

Keytool Command Description
<your_keystore_file_name> Keystore file name to which to add the certificate.
<your_keystore_password> Password for the keystore.
<cert_to_import>

Certificate to add to the keystore. Can be: *.PEM, *.CER (Base64 or DER encoded), or *.CRT.
<your_cert_alias> Alias of certificate in the keystore. Each certificate has an unique alias.

Configure truststore in the security server

To configure trusted CAs, specify one or more keystore and certificate aliases from the keystores in the X509-LDAP or X509-BASE authenticators of the STS. To do this, edit the STS configuration file:

<TOMCAT_HOME>\webapps\idp\WEB-INF\conf\Configuration.xml

The following sample shows how to configure trusted CAs, pay special attention to the "CertificateIssuerTrustMatcher" section:

Copy code 
<Setting Name="serena-ldap-authenticator" Type="htf:map">
<Setting Name="Provider" Type="xsd:string">X509-LDAP</Setting>
<Setting Name="CertificateMustExistInLDAP" Type="xsd:boolean">false
</Setting>
<Setting Name="CertificateAttributeName" Type="xsd:string"></Setting>
<Setting Name="SearchFilter" Type="xsd:string">(objectclass=*)</Setting>
<Setting Name="CompatibleRequestMatchers" Type="htf:namedlist">
<Setting Name="CredentialsTypeMatcher" Type="xsd:string">X509
</Setting>
<Setting Name="AuthenticationTypeMatcher" Type="xsd:string">*
</Setting>
<Setting Name="CertificateIssuerDNMatcher" Type="xsd:string">*
</Setting>
<Setting Name="CertificateIssuerTrustMatcher" Type="htf:map">
<!-- Sample Entry -->
<Setting Name="serena-truststore" Type="htf:keystore">
<Setting Name="Type" Type="xsd:string">JKS</Setting>
<Setting Name="File" Type="htf:file">serenaca.jks</Setting>
<Setting Name="Password" Type="xsd:string">changeit</Setting>
</Setting>
<Setting Name="serenaca" Type="htf:certificate">
<Setting Name="KeyStoreName" Type="xsd:string">serena-truststore
</Setting>
<Setting Name="Alias" Type="xsd:string">serenaca</Setting>
</Setting>
<!-- Template Entry -->
<Setting Name="[your_keystore_alias]" Type="htf:keystore">
<Setting Name="Type" Type="xsd:string">JKS</Setting>
<Setting Name="File" Type="htf:file">[your_keystore_file_name]
</Setting>
<Setting Name="Password" Type="xsd:string">[your_keystore_password]</Setting>
</Setting>

<Setting Name="[your_certificate_alias(2)]" Type="htf:certificate">
<Setting Name="KeyStoreName" Type="xsd:string">[your_keystore_alias]</Setting>
<Setting Name="Alias" Type="xsd:string">[your_certificate_alias]
</Setting>
</Setting>
</Setting>
</Setting>
<Setting Name="JNDI.Environment" Type="htf:map">
<Setting Name="java.naming.factory.initial" Type="xsd:string">com.sun.jndi.ldap.LdapCtxFactory</Setting>
<Setting Name="java.naming.provider.url" Type="xsd:string"> ldap://serena.com:389</Setting>
<Setting Name="java.naming.security.authentication"  Type="xsd:string">simple</Setting>
<Setting Name="java.naming.security.principal"  Type="xsd:string">ldapuser</Setting>
<Setting Name="java.naming.security.credentials"  Type="xsd:string">changeit</Setting>
</Setting>
</Setting>

where:

Keytool Command Description
<your_keystore_alias> Any unique keystore alias (for example,my_company_ca_store)
<your_keystore_file_name> The keystore filename and full or relative path to the directory where Configuration.xml is located.
<your_keystore_password>

The keystore password.
<your_certificate_alias> The existing certificate alias from <your_keystore_file_name>.
<your_certificate_alias(2)> Any unique certificate name/alias (for example,my_company_ca-01). Can be the same as <your_certificate_alias>.

Important: After upgrading, if you use custom certificates with passwords that are not the default, you need to update the configuration file displayed above.The pre-14.x file is saved in the Tomcat directory as:

backup_config.pre<current CM version number>

Default password: changeit

Disable username and password authentication‌‌

Dimensions CM supports dual username/password and smart card authentication for certain power users, for example, administrators and those who require the running of unattended batch jobs.

If other users should not have access to username/password authentication, the OS administrator should either:

  • Not assign such users username/password authentication in the first place (the recommended option); or

  • Remove username/password authentication from all normal smart card users who have such authentication (for example, users with usernames that existed before smart card authentication was introduced).

Establish a certificate revocation list‌‌

A Certificate Revocation List (CRL) is a common method for maintaining a list of subscribers paired with digital certificate status. The list enumerates revoked certificates and the reasons for revocation. The certificate issue dates and the entities that issued them are also included. Each list contains a proposed date for the next release. When a potential user attempts to access a server, the server allows or denies access based on the CRL entry for that user. You can compare user certificates against one or more CRLs. For details on configuring the Dimensions CM Security Token Service (STS), see the Administration Guide.

Add smart card support after installing CM with SSO‌‌

To implement smart card authentication support after installing Dimensions CM with SSO (Single Sign-on) support, do the following:

  1. Open the following file in an XML or text editor: 

    <TOMCAT_HOME>\webapps\idp\WEB-INF\conf\ fedsvr-core-config.xml

  2. Locate the AllowedPrincipalAuthenticationTypes parameter and add CLIENT_CERT to it. This enables the Smart Card Login button. The resulting parameter looks like this:

    <parameter name="AllowedPrincipalAuthenticationTypes" Type="xsd:string">CLIENT_CERT</parameter>

  3. Save the fedsvr-core-config.xml file.

  4. Open the following file in an XML or text editor: 

    <TOMCAT_HOME>\webapps\idp\
  WEB-INF\conf\Configuration.xml file

  5. Uncomment the X.509 authenticators by removing the <!--X509- NAME and X509-NAME--> markup from them.

    For example, remove the following markup to uncomment the X509-BASE, X509-LDAP, or X509-CRL authenticator, respectively.

    <!--X509-BASE ... X509-BASE-->
<!--X509-LDAP ... X509-LDAP-->
<!--X509-CRL ... X509-CRL-->

  6. Configure the Certificate Authorities (CA) in the X509-BASE and X509-LDAP authenticators, as described in Configure trusted certificate authorities.

  7. For the X509-LDAP authenticator, the following parameters must be substituted: 

    $X509_LDAP_HOST
$X509_LDAP_USER
$X509_LDAP_PASSWORD

    By default the installer configures the X509-LDAP authenticator when the smart card option is selected.

  8. The X509-CRL authenticator can be used in addition to X509-BASE or X509-LDAP. In this case, the $X509_CRL_PATH parameter must be substituted and the specified folder must contain *.CRL files.

  9. Save the Configuration.xml file.

  10. Restart the OpenText Common Tomcat Service.

The Configuration.xml file contains the following commented out example of an authenticator. To use it, you must remove the comments and substitute the variables appropriate to your setup:

Copy code

<!-- =========================================================== -->

<!-- =========================================================== -->
<!-- CRL validator against file based Certificate Revocation List   -->
<!-- =========================================================== -->
<!--X509-CRL
<!Setting Name="serena-crl-validator" Type="htf:map">
<!Setting Name="Provider" Type="xsd:string">X509-CRL<!/Setting>
<!Setting Name="CompatibleRequestMatchers" Type="htf:namedlist">
<!Setting Name="CredentialsTypeMatcher" Type="xsd:string">X509<!/Setting>
<!Setting Name="AuthenticationTypeMatcher" Type="xsd:string">*<!/Setting>
<!Setting Name="CertificateIssuerDNMatcher" Type="xsd:string">*<!/Setting>
<!/Setting>
<!Setting Name="CRLDir" Type="xsd:string">$X509_CRL_PATH
<!/Setting>
<!Setting Name="CacheFileName" Type="xsd:string">crl_cache.xml<!/Setting>
<!Setting Name="RefreshPeriod" Type="xsd:string">1200
<!/Setting>
<!/Setting> X509-CRL-->

Configure smart card for SBM‌

To use Dimensions CM SSO in conjunction with SSO and smart card on a Solutions Business Manager (SBM) installation:

  1. Add the following SSO entries to the Dimensions CM server dm.cfg file.

    • SSO_SERVER_CERTIFICATE

    • SSO_SERVER_PRIVATE_KEY

    • SSO_SERVER_PRIVATE_KEY_PASSWORD

  2. Restart the Dimensions CM listener.