TeamConnect SAML Setup

Last updated
Save as PDF

The following page details the prerequisites, IDP Setup , SP setup and TeamConnect SAML setup.

Prerequisites

Servlet to deploy on (Weblogic/Tomcat)
Keystore with encryption key created.

Note: Here the example keystore provided with the WAR file, samlKeystore.jceks is used. Clients should not use this keystore other than for testing purposes.
Certificate (.cer/.crt/.cert) generated from the keystore.

Note: Along with the example keystore, you can use the following command to generate it. (password=mitratech)
keytool -export -alias mitratechsamlsamplekp -file TestCert.cer -keystore samlKeystore.jceks -storetype jceks
This will provide a file TestCert.cer to use in the IDP for signing requests.

IDP Setup

This section details the steps for setting up an IDP for integration. SAML can be integrated into any IDP that supports the SAML 2.0 specification. The specific steps for integrating will differ depending on the individual IDP. This document will go through the process for setting up with Okta as the IDP as an example. All the same options should be configurable in other providers, but will be located and possibly named differently in their application.

Instructions	Screenshot for reference
1. Log into Okta, and go to the administrator portal.
2. Go to Applications --> Applications. Click on Create App Integration.
3. Choose SAML 2.0 sign in method, hit Next.
4. Give the application a name, hit Next.
5. Set SAML Settings a. Set the Single Sign on URL to <saml-url>/saml/SSO and mark check against 'Use this for Recipient and Destination URL' box.
b. Set the Audience URI (SP Entity ID) to the required ID. This will be the ID used throughout the integration.
c. Leave Default RelayState blank. d. Set Name ID format to Unspecified . (You can use other options, along with other adjustments in SAML server setup to match).
e. Set Application username for Okta to validate with. In this case, keep it simple with Okta username. ensure both TeamConnect user and Okta users have the same email address as their usernames.
f. Click on Show Advanced Settings
g. Set Response to Signed
h. Set Assertion Signature to Signed
i. Set Signature Algorithm to RSA-SHA256
j. Set Digest Algorithm to SHA-256
k. Leave Assertion Encryption as Unencrypted. If you do want the assertion encrypted, match this value to the same one used in the keystore. l. Upload the signing certificate to Signature Certificate (TestCert.cer if following the example)
m.Check Signed Requests
n. If you are enabling Single Logout (SLO), continue with the following settings. Else, click Next to finish SAML Settings setup. o. Check Enable Single Logout.
p. Set Single Logout URL to <saml-url>/saml/SingleLogout
q. Set SP Issuer to the same value used in Audience Restriction (TeamConnectSAML in this example).
r. Keep defaults on the remaining settings. These can be customized, but this example will not go into them. Click Next. Select App Type (This is an Internal App that we have created is recommended). Click Finish
6. Now that the Application is created, click on Sign On.
7. Click on View SAML setup instructions.
8. Scroll to Optional on the new page and copy all the contents. Save contents as a file named idp.xml.
9. Back in the Okta Application, click on Assignments and add all users who will need access to the SAML integration.

SP Setup

This section details the steps for setting up the Service Provider (SAML Server). These steps will use values from the IDP Setup example, but can be customized to the customer’s standards. Ensure that all options chosen during IDP setup are also reflected in the following SP setup (encryption algorithms, signing keys, etc should all match).

Instructions	Screenshot for reference
1. Obtain SAML WAR file. Unzip the WAR file with an archive tool like 7zip.
2. If keystore and key are created, during the Prerequisite steps, place this keystore in <WAR-file>/WEB-INF/classes/security. Delete any unused keystores for security
3. Navigate to <WAR-file>/WEB-INF/classes/metadata and replace the idp.xml file with the one that was created during IDP setup.
4. Navigate to <WAR-file>/WEB-INF/classes and edit the saml.properties file.
a. Set idp.usernameIdentifier to NameID. This matches with our choice in setting up the IDP. Okta only uses NameID, but if using a different IDP that supports a different attribute, then you can set this value to Attribute.
b. Set idp.nameIDFormat to match the type declared in the IDP setup. In this example, used Unspecified which maps to urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified. If you had set usernameIdentifier to Attribute in the previous step, leave this property blank The following are the other available options: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent urn:oasis:names:tc:SAML:2.0:nameid-format:transient urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName urn:oasis:names:tc:SAML:1.1:nameid-format:WindowsDomainQualifiedName urn:oasis:names:tc:SAML:2.0:nameid-format:kerberos urn:oasis:names:tc:SAML:2.0:nameid-format:entity .
c. Leave idp.attributeName empty, if using NameID in the previous steps. If using Attribute, then declare the attribute key here. d. Set sp.entityID to the same value we chose during IDP setup. In this example, it was TeamConnectSAML.
e. Set gateway.admin.username to required administrator login name to be. Default is admin. f. Set gateway.admin.password to required administrator password to be. For SAML 2.2.4+ this value must be encrypted with encrypt.jar that is provided with the TeamConnect installation files. g. Set application.loginUrl to the login URL of the TeamConnect application, which will be <TeamConnect-URL>/login
h. Leave application.logoutSuccessUrl empty. This will use the default logout page. The logout page can be customized for a client. To do this, either update the existing logout.jsp or add a new jsp to WEB-INF, and update securityContext.xml to remove security from the new logout endpoint. i. Set keystore.file to the name of the keystore you copied into the war file. In this working example we are just using the test store provided, samlKeystore.jceks. j. Set keystore.type to the extension type of the keystore being used. In this example we are using jceks. k. Set keystore.password to the password set in creating the keystore. In this example, it is mitratech. For SAML 2.2.4+ this value must be encrypted with encrypt.jar that is provided with the TeamConnect installation files. l. Set keystore.privatekey.alias to the alias used during keystore creation. In the example, using samlKeystore.jceks, this value is mitratechsamlsamplekp. m. Set keystore.privatekey.password to the password used for the alias. In the example, using samlKeystore.jceks and mitratechsamlsamplekp, the value is saml. For SAML 2.2.4+ this value must be encrypted with encrypt.jar that is provided with the TeamConnect installation files.
n. Set saml.signatureAlgorithm to match the value declared during IDP setup. In the example, the value would be SHA256. All valid options are: SHA1 SHA256 SHA512 o. Save the saml.properties updates. Update the WAR file with the changes.
5. Stage the WAR file in servlet, and launch the application 6. Once running, visit <SAML-URL>/saml/web/metadata.
7. Login using the admin credentials declared in saml.properties. The default values are admin/admin.
8. Click on Generate New Metadata
9. Setup SP metadata a. Set Entity ID to the value chosen during IDP setup. In the working example we are using TeamConnectSAML
b. The Entity base URL should auto generate from deployment. Double check the value matches the actual URL endpoint. If not, update it to match.
c. Leave Entity alias blank, unless you are using SAML to connect multiple applications. If so, give this a unique name to identify this specific integration.
d. Set Signing key to the value of the keystore alias being used for this integration. In the example, it will be mitratechsamlsamplepk.
e. Set Encryption key to the value of the keystore alias being used for this integration. In the example, it will also be mitratechsamlsamplepk.
f. Set Signature security profile to MetalOP (default). This requires both sp and idp to have a specific key for signatures and is highly recommended for security reasons. If using public CAs for signing, change this to PKIX (Not recommended).
g. Set SSL/TLS security profile to PKIX (default). This allows connections between the sp and idp to validate using public CA certificates. If using private keys for communication, switch this to MetalOP.
h. Set SSL/TLS hostname verification to Standard hostname verifier. If using localhost or non-public certificates* for SSL, set this value to Allow All.*
i. Leave SSL/TLS client authentication as None. If using private keys for SSL, then choose the matching alias from the keystore here.
j. Set Sign metadata to Yes. It is generally insecure to not sign the metadata, so leaving this as No is not recommended.
k. Set Sign AuthNRequests to Yes. It is generally insecure to not sign the authentication requests, so leaving this as No is not recommended.
l. Leave Require signed authentication Assertion as No. If you set up Assertion encryption during IDP Setup, then you will want to set this to Yes.
m. If you set up SLO during IDP setup and are following the example in Okta, then Require signed LogoutRequest and Require signed LogoutResponse should both be set to Yes. Other IDPs might not require SLO to have signed requests, but Okta does. If you IDP does not require it, and you choose not to have signed logout requests, then you can leave these as No.
n. Leave Require signed ArtifactResolve as No. If IDP allows configuration of this setting, you can set this to Yes if doing so. Okta does not provide this setting.
o. Leave default settings for Single sign-on bindings unless the integration uses special protocols.
p. Leave default settings for Supported NameIDs, which will allow the IDP to be slightly flexible. If needed limit the list as well to the declared in IDP setup.
q. Click Generate metadata.
r. Copy the contents of Metadata and save them in a file called sp.xml.
s. Copy the contents of Configuration to a notepad for use in the next steps.
t. Stop the SAML server. u. Open the WAR file again with 7zip. v. Replace sp.xml in <WAR-file>/WEB-INF/classes/metadata with the file that was just created.
w. Navigate to <WAR-file>/WEB-INF/classes and edit securityContext.xml. Search for the bean with class org.springframework.security.saml.metadata.ExtendedMetadata and replace it with the configuration contents copied during step 9s. Save the changes and update the WAR file. x. Redeploy the application.

TeamConnect Setup

This section goes over the steps to integrate the TeamConnect application with the SAML-IDP infrastructure. This section only details the process of integrating with our offered SAML solution. Custom SAML solutions can also be integrated with TeamConnect, but generally will require Services through Mitratech or one of our implementation vendors.

Instructions	Screenshot for reference
1. Copy the TeamConnect-SSO resources provided with SAML to an accessible place.
2. Log into TeamConnect as an administrator. 3. Navigate to Documents > Top Level > System
4. Navigate into the Authentication folder. If the folder does not exist yet, then create it. Then create a folder with the name you want this integration to have. In this case, it is called SAML. Navigate into the new folder.
5. Create two folders within the integration’s parent folder named classes and pages.
6. Navigate into the pages folder. 7. Open the badCredentials.html file from the SAML files copied earlier. Edit the root URLs listed in the file to the URL that matches the SAML server. Under isolation network environment, add the Redirect attribute displayed in the comment section below as well. This will ensure the user’s initial target page is retained through authentication and isolation.
8. Open the logout.html file from the SAML files copied earlier. Edit the root URLs listed in the file to the URL that matches the SAML server. If you are using SLO, as in the current example, set local=false and add {user.token} as an additional parameter (see screenshot below)
9. Edit the sessionTimeout.html page if you desire, but it doesn’t add any functionality other than a landing page. 10. Upload all edited html files to TeamConnect in the pages folder.
11. Navigate to the classes folder in TeamConnect 12. Open the authenticationDescriptor.properties file from the provided SAML files to edit. Set tc.displayName to what name you want to render in the UI in Admin Settings. Set tc.uniqueId to what you named the integration folder in TeamConnect > Documents > System > Authentication. SAML in this example. Set tc.isSSO to true to enable SSO flow in TeamConnect. Set tc.isSLO to true if configuring the system with SLO. Leave as false* if not implementing SLO.* Set tc.authenticatorClassName to SAMLAuthenticator. This value will be different if using a custom SSO solution. This should match the class name that handles the SSO logic on the TeamConnect side. Set tc.ssoHostURL to the base URL of the SAML server. This setting is really only important if you have custom endpoints that could be accessed from outside TeamConnect. Set page.badCredentials to badCredentials.html Set page.logout to logout.html Set page.sessionTimeout to sessionTimeout.html Save the file.
13. Upload authenticationDescriptor.properties, Crypto.class, and SAMLAuthenticator.class into the classes folder in TeamConnect.
14. Navigate to Admin > Admin Settings > Security and scroll down to the Authentication Plug-in section. Hit the Reload button and set the Default Authentication Method to SAML Single Sign-On (or as the integration was named in its properties file).