Skip to main content
Mitratech Success Center

TeamConnect SAML SSO Installation and Setup

The following page details prerequisites, installation instructions, and troubleshooting advice for SAML SSO in TeamConnect 6.

SSO-SAML Help

Welcome to the TeamConnect® SSO-SAML User Help.

This documentation is meant for people who need an overview of how to use TeamConnect SSO-SAML. It describes the product requirements as well as the installation and setup process. The topics are organized by the major tasks that you must perform when setting up TeamConnect SSO-SAML.

This documentation details version SAML 2.0.1
 

Installation Requirements

You must be running one of the following TeamConnect (TCE) versions in order to install the TeamConnect SSO-SAML Add-In:

  • TCE 3.3 SP3 Update19 (or later 3.3 SP3 update)
  • TCE 3.4 SP1 U17 (or later 3.4 SP1 update)
  • TCE 4.0 U3 (or later 4.0 update)
  • TCE 4.2.0 - 4.2.9
  • TCE 5.0.0 - 5.0.5
  • TCE 5.2.0 - 5.2.2
  • TCE 6.0

 

Additionally, the user implementing the TeamConnect SSO-SAML add-in must be familiar with the following:

  • SAML concepts
  • Custom Authentication Plug-ins in TeamConnect
  • Java KeyStore and KeyTool
  • Java Cryptography Extension (JCE)

 

Prerequisites

SAML Gateway is a web application and will need to be deployed on an app server. See Step 4 in the Installing SAML Gateway App section of this guide for further detail.

 

Setup and Installation

Before you begin...

Contact your IDP Administrator to obtain the XML metadata for the IDP.
Note: If you use Siteminder for your IDP, you will not be able to specify the "type" of attribute. Use NameID instead for this case.

The SAML Gateway requires a key pair to use for encryption and signing. Obtain the key pair from your administrator or use Java keytool to create a new one using the instructions listed below.

 

Create/Generate a Keystore File

The SAML Gateway requires a keystore (in either jks or jceks format) that contains a key pair to use for encryption and signing. Obtain the key pair file from your administrator or use the Java keytool program (or other utility) to create a new one.

The SAML Gateway is distributed with a sample keystore (samlKeystore.jceks) that can be used for testing purposes in a development type environment, but this should not be used for any production or pre-production installation.
It is suggested the new keystore be named something unique, like <Client>-<env>.jceks.

Use the following command to create a new Keystore file: 
keytool –v -genkeypair -storetype jceks -keystore <keystore-file> -keysize <key-bits> -alias <alias-name> -validity <days>

Where:
keystore-file is the path of the file to create, including the extension (e.g., acme-test.jceks)
key-bits is the number of bits to use for the key. Suggested value: 2048
alias-name is the name to use for the entry (must be all lowercase)
days is the number of days the certificate will be valid. Suggested value:  3650 (10 years)

The genkeypair option:
Generates a key pair (a public key and associated private key). Wraps the public key into an X.509 v3 self-signed certificate, which is stored as a single-element certificate chain. This certificate chain and the private key are stored in a new keystore entry identified by alias.

The alias can be something like “<client><env>kp”. For example, “acmetestkp”.

Once you start keytool, it will prompt you for the keystore password. Enter any password you want and write it down, you will need it later. For example, “acmeteamconnect”.

Then keytool will prompt you for several pieces of information, e.g., your first and last name, your organizational unit, your organization, etc. This information should be entered as your true information, not something fictitious. It simply documents who created the key pair. Suggested sample values:

  • First and Last Name: Your Real Name
  • Organizational Unit: Services
  • Organization: Mitratech
  • City or Locality: Austin
  • State or Province: Texas
  • Two-letter Country Code: US

Hit the Enter key on your keyboard when asked to enter the “key password”. This will make the key password the same password used for the Keystore.
 

 

Installing the SAML Gateway application

  1. Replace the file named idp.xml in the WEB-INF/classes/metadata folder of the application with the metadata for your Identity Provider (IDP).
     
  2. Import the encryption key pair into the provided keystore located at WEB-INF/classes/security/samlKeystore.jceks. You will need to provide the –storetype jceks option to Java keytool when importing. The default keystore password is teamconnect.

    Alternatively, you can replace the provided keystore with your own and update saml.properties (see below) accordingly.
     
  3. Edit the saml.properties file in the WEB-INF/classes folder of the application.
     
    Property Description
    idp.tcUsernameIdentifier SAML response element that will contain the TeamConnect username. Supported values are NameID and Attribute. Contact your Identity Provider for this information.
    idp.nameIDFormat Required only when idp.tcUsernameIdentifier is NameID e.g. urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
    idp.attributeName The name of the response Attribute containing the TeamConnect username. Required only when idp.tcUsernameIdentifier is Attribute.Contact your Identity Provider for this information.
    sp.entityID Service Provider entity ID. This is the value used to generate service provider metadata in Step 6. If you are using an existing metadata file, enter the value of the entityID attribute from the metadata file.
    gateway.admin.username Defines the credentials to access the SAML gateway administration interface. Default is admin.
    gateway.admin.password Defines the credentials to access the SAML gateway administration interface. Default is admin.
    gateway.supportIdpInitializedSS O Indicates whether IDP-initialized SSO should be supported. Supported values are true and false.
    teamconnect.loginUrl The login URL for the TeamConnect application.
    keystore.file Name of the Java keystore file containing the private key for encrypting and optionally signing SAML messages. This file must be located in the WEB-INF/classes/security folder of the application. You may use the provided sample keystore (samlKeystore.jceks) or replace it with your own.
    keystore.type Type of the keystore. Supported values are jceks and jks.
    keystore.password Keystore password
    keystore.privatekey.alias Keystore alias for the private key. For security reasons, the default private key should not be used in production.
    keystore.privatekey.password Password for the private key
    saml.signatureAlgorithm=SHA1 (Default) Only available in SAML 2.0.1


     
  4. Deploy the SAML Gateway Application using SSO .war file on app server. 
    Note: This was mentioned in the Prerequisites section above.
     
  5. In a web browser, go to <SAML gateway>/saml/web/metadata/generate.
    Example URL: http://dev.mitratech.com/Mitratech-SSO-SAML/saml/web/metadata/generate
     
  6. Log in using the credentials defined in step 3.
     
  7. On the Metadata generation page, enter the Entity ID defined in step 3. The choices for Service Provider (SP) metadata generation depend on the environment and configuration, as agreed on by the IDP and SP admins.
     
  8. Click the Generate metadata button. The Metadata detail page is displayed.
    • Replace the contents of the file named sp.xml in the WEB-INF/classes/ metadata folder of the application with the content of the Metadata field.
    • Edit the securityContext.xml file in the WEB-INF/classes folder of the application and update the ExtendedMetadata of <bean> with id="sp" to include the property values from the Configuration field.
       
  9. Restart the SAML gateway application.
     
  10. Provide service provider metadata to your IDP administrator for upload to the IDP.

 

Configure TeamConnect for SAML

Before you begin, ensure your TeamConnect version matches one of the versions on this list. You will have received an installation package from Mitratech at this point.

Edit the Files

  1. Open your TeamConnect instance and log in with administrative credentials.
  2. Open the installation folder and copy the folders to your local machine <-- this is listed on the confluence page, but it probably needs to be rewritten.
  3. Edit the following files: In 'files\pages' open the badCredentials.html and logout.html files in notepad++.

    In badCredentials.html edit the window.location.href value to your SAML server address like so and also put the value into <a> tag:
    window.location.href = "http://localhost:8082/Mitratech-SSO-SAML/saml/login"
    Step3a.png

    In logout.html edit the window.location.href value to your SAML server address like so and also put the value into <a> tag:
    window.location.href = "http://localhost:8082/Mitratech-SSO-...out?local=true"
    Step3b.png

Upload files to TeamConnect

  1. Launch your TeamConnect instance if it is not already running and log in as an admin user.
  2. Go to Documents and choose the Top-Level search view from the list. Navigate to the System folder and create a new folder here named 'Authentication'.
    TC_AuthenticationFolder.png
     
  3. Within the Authentication folder, create a new folder named 'SAML'.
    TC_SAMLFolder.png
     
  4. Within the SAML folder, create 2 new folders named classes and pages.
    TC_ClassesAndPages.png
     
  5. Now upload each of the files from the SAML folder that was copied to your local where we edited the href values into their corresponding folders on TeamConnect.
    Step5a.png

    Step5b.png
     
  6. Restart TeamConnect by stopping and restarting your TeamConnect server in eclipse to finish implementing the changes. 
  7. Set up a SAML login by logging back into your admin TeamConnect instance. 

    From the home screen click Admin Settings, select Security then change the Default Authentication Method to SAML Single Sign-On. Click Update when finished.
    SAML_Option.png
     
  8. A new SAML user needs to be created. Create a new user with the username set to the email of the person you assigned to your Okta application, and set the user to Active. There should be no password option for the user since SSO-SAML is being used.

Verify SAML is working

  1. Navigate to your TC login URL (ie, http://localhost:8081/teamconnect-4.2.0.0071-SNAPSHOT/login). This should immediately redirect you to the Okta login screen. 
  2. Input the username and password you created when you assigned your new user to the Okta application. If the information is correct you should be redirected back to TeamConnect, already logged in as your user.

 

Installing the TeamConnect Custom Authentication Plug-in for SAML

Your TeamConnect instance should be up and running before you proceed. 

  1. Update the SAML URLs in the badCredentials.html and logout.html files based on your SAML gateway deployment.
     
  2. Create the following Document folder structures in your TeamConnect instance:
    • System/Authentication/SAML/classes
    • System/Authentication/SAML/pages
       
  3. Upload the authenticationDescriptor.properties, SAMLAuthenticator.class and Crypto.class files to the System/Authentication/SAML/classes folder created in step 2.
     
  4. Upload the badCredentials.html, logout.html and sessionTimeout.html files to the System/Authentication/SAML/pages folder created in step 2.
     
  5. Restart the TeamConnect application and select SAML Single Sign-On as the Default Authentication Method under Admin Settings -> Security.
     

Testing

  1. Create a TeamConnect user configured to use default authentication (the default authentication was set to SAML SSO during installation of the SAML authentication plugin). This user must have a corresponding IDP account.
     
  2. In a web browser, navigate to the TeamConnect login URL.
     
  3. If the installation was successful, the browser will be redirected to the IDP for authentication and will eventually display the TeamConnect home page.


To log into TeamConnect without using SAML authentication, follow these steps:

  1. Create a TeamConnect user configured to use Standard Authenticator as the authentication type.
     
  2. Use /standardLogin for the login URL instead of /login and log in using the user created in Step 1.

 

Troubleshooting and Common Issues

Troubleshooting

LOGGING
Use the TeamConnect and SAML Gateway log files to troubleshoot issues.

TEAMCONNECT
Set the TeamConnect Authentication logger to DEBUG
 

SAML GATEWAY
Debug logging can be enabled on the Logging tab of the administrative console accessible via a web browser at <SAML gateway>/saml/web/logging

Note: Use different browsers when accessing the SAML Gateway administration console and logging into TeamConnect via SAML at the same time.
 

Common Issues

Issue Resolution
When generating new metadata, the dropdowns for the ‘Signing key’ and ‘Encryption key’ fields are blank. Verify that the keystore alias for the encryption key was created using lowercase letters and that the default keystore values in saml.properties have been changed to reflect the keystore being used.
TeamConnect login fails with the following exception in the SAML Gateway log: ‘org.opensaml.saml2.metadata.provider.Me tadataProviderException:  Metadata for entity <name> and role
{urn:oasis:names:tc:SAML:2.0:metadata} SPSSODescriptor wasn't found’.
Verify that the value of sp.entityID in saml.properties matches the entity ID of the Service Provider.

TeamConnect login fails with the following exception in the SAML Gateway log: ArtifactResolutionProfileBase.resolveArtifac t | Could not decode artifact response message.

org.opensaml.ws.message.decoder.Messa geDecodingException: Error when sending request to artifact resolution service.

Caused by: javax.net.ssl.SSLHandshakeException: org.springframework.security.saml.trust.Un trustedCertificateException: Peer SSL/TLS certificate
 

Check the certificate details in the log file. If the exception is for the IDP domain, import the root certificate for the IDP domain into the SAML Gateway application’s keystore. The IDP URL is defined in idp.xml in the WEB-INF/classes/ metadata folder of the application.
On login, TeamConnect displays an error message stating ‘A system error occurred during authentication. Please contact your administrator to check the system logs.’ Verify that SAMLAuthenticator.class has been uploaded to the System/Authentication/SAML/ classes folder and the application server was restarted after upload.
On login, the browser redirects endlessly.

Verify the following:

  • There is an active TeamConnect user whose username matches the IDP response credential.
  • Crypto.class has been uploaded to the System/Authentication/SAML/classes folder and the application server was restarted after upload.
On login, TeamConnect displays a Page Not Found error page instead of the home page. Verify that the TeamConnect login URL in saml.properties is correct and does not have a ‘/’ at the end i.e. the URL should end with /login and
not /login/.
Persistent URLs do not work -- the user is logged into TC successfully but the home page is displayed instead of the requested record. Verify that the TeamConnect URL in saml.properties has the same hostname as the user requested URL e.g. if the user accesses TeamConnect  using http://example.com/ TeamConnect/entityrecord/CONT_3, then the URL in saml.properties should be http://example.com/ TeamConnect/login and not http://<ip address>/ TeamConnect/login
  • Was this article helpful?