SAML 2.0 SSO Installation and Configuration Guide for TeamConnect Enterprise v8.0+

a. For Okta

Steps to follow	Screenshot for reference
1. Login to your Okta admin console and navigate to Applications.
2. Click Create App Integration and select SAML 2.0 as the sign-in method.
3. General Settings: Give your app a name (e.g., “TeamConnect”) and click Next.
4. Configure SAML: Single sign-On URL: Enter your TeamConnect ACS (Assertion Consumer Service) URL. The format is https://<your-tc-host>/login/saml2/sso/{RegistrationID} Replace <your-tc-host> with your TeamConnect’s public hostname. The {RegistrationID} is a unique name you will define in TeamConnect’s setup in the next step (e.g., OKTA). Audience URI (SP Entity ID): Set this to the TeamConnect SAML metadata (SP Issuer) URL, using the format: https://<your-tc-host>/login/saml2/service-provider-metadata/{RegistrationID}. Note: Make sure the Audience URI / SP Entity ID you configure in the IdP exactly matches the value configured for this SAML registration in TeamConnect. If you change the Registration ID or hostname in TeamConnect later, you must update the Audience URI / SP Entity ID in the IdP to keep them in sync. Name ID format: Set this to EmailAddress. Application username: Set this to Email. Note: You can leave the rest of the fields as they are. You don’t need to change anything else in this section.
5. Scroll to the bottom of the page and click Next.
6. Feedback: Select the checkbox It’s required to contact the vendor to enable SAML and click Finish. You will be taken to the application’s Sign On tab.
7. Get Metadata for TeamConnect: On the application’s Sign On tab, you will find the necessary information to connect with TeamConnect: Metadata URL: Locate and copy the Metadata URL. You will paste this into TeamConnect.               Signing Certificate: You may need to click on More details to see the Signing Certificate. Download the Signing Certificate file.
8. Click on the View SAML setup instructions button. A new page will open.
9. Gather the following details to enter manually into TeamConnect: Identity Provider Issuer: Locate and copy this value if your organization needs it for validation or documentation. TeamConnect treats the IdP as authoritative via the Metadata URL and certificate; the Entity ID in TeamConnect represents TeamConnect’s own SP identifier, which is derived from your TeamConnect host and Registration ID. Note: Do not paste the Identity Provider Issuer into the Entity ID field in TeamConnect. The TeamConnect Entity ID is the TeamConnect SAML metadata URL: https://<your-tc-host>/login/saml2/service-provider-metadata/{RegistrationID} Replace <your-tc-host> with your TeamConnect’s public hostname. The {RegistrationID} is a unique name you will define in TeamConnect’s setup in the next step (e.g., OKTA). NameID Format: From the optional section labeled “Provide the following IdP metadata to your SP provider,” copy the NameID Format value. You will paste this into the NameID Format field in TeamConnect.

b. For Azure

Steps to follow	Screenshot for reference
1. Go to Microsoft Azure portal and sign in with your admin account. In the left hand menu, select Azure Active Directory. Under Manage, select App registrations. (or) You can also select App registrations under Azure services.
2. Click the + New registration button at the top of the page.
3. Register the Application / Fill in the following fields: Name: Enter a descriptive name for your application (e.g., “TC-SAML”). Supported account types: Select Accounts in this organizational directory only (Default Directory only - Single tenant). Click the Register button.
4. Access the Enterprise Application: After the app registration is created, you will be on its Overview page. Find the link named Managed application in the local directory and click on it. This will take you to the associated Enterprise Application where Single Sign-On is configured.
5. Set up Single sign-on: From the Enterprise Application’s navigation menu (on the left), under Manage, click on Single sign-on. Select the SAML tile as the single sign-on method.
6. Configure SAML: In section 1, Basic SAML Configuration, click Edit. Identifier (Entity ID): Set this to the TeamConnect SAML metadata (SP Issuer) URL, using the format: https://<your-tc-host>/login/saml2/service-provider-metadata/{RegistrationID} Replace <your-tc-host> with your TeamConnect’s public hostname. The {RegistrationID} is a unique name you will define in TeamConnect’s setup in the next step (e.g., AZURE).         Reply URL (ACS URL): Click Add reply URL. This is the Single Sign-On URL where TeamConnect will receive the SAML assertion. The format is https://<your-tc-host>/login/saml2/sso/{RegistrationID} Replace <your-tc-host> with your TeamConnect’s public hostname. Replace {RegistrationID} with a unique ID you will also use in the TeamConnect settings (e.g., AZURE). Logout Url (optional): Enter the Single Logout URL in the IdP to the TeamConnect logout endpoint that accepts a SAML LogoutRequest. The format is: https://<your-tc-host>/logout Replace <your-tc-host> with your TeamConnect’s public hostname. For more information, see the Enabling SLO in the Identity Provider section. Click Save at the top of the pane.
7. Gather Metadata for TeamConnect: On the SAML-based Sign-on page, scroll down to section 3, SAML Signing Certificate. App Federation Metadata Url: Copy this URL to your clipboard. You will paste it into the Metadata URL field in TeamConnect. Certificate (Base64): Click Download to save the certificate file. Federation Metadata XML: From this, copy the NameID Format value. You will paste this into the NameID Format field in TeamConnect.
8. Assign Users to the Application: In the Enterprise Application’s menu, navigate to Manage → Users and groups.                 Click + Add user/group and assign the specific users or groups who will be permitted to log in to TeamConnect using this method. Users must be assigned here to be able to sign in.

Repeat for Additional IdPs (Optional)

TeamConnect supports multiple concurrent IdPs. Users pick the IdP from a drop-down on the SAML login screen. Ensure each registration has a unique Registration ID.

Here is an example screenshot for your reference of how multiple IdPs would look on the login screen:

[image]

Automatic Redirect for a Single IdP

When you configure only one Identity Provider (IdP), TeamConnect simplifies the login process for your users.

If SAML login is enabled with a single active IdP, the user journey is seamless. When a user navigates to the TeamConnect login page, the system automatically redirects them directly to that IdP’s login page, as shown here.

Furthermore, if the user is already authenticated with the IdP in their browser, they will be redirected straight to their TeamConnect homepage, providing a true one-click login experience.

If multiple Identity Providers (IDPs) are configured, the login page will display an SSO login selector screen. To know more about how the login screen appears when multiple IdPs are configured, see the Repeat for Additional IdPs section.

Now, proceed with the following validation steps:

Steps to follow	Screenshot for reference
1. Create or map a user: Ensure a user exists in TeamConnect whose email address matches the NameID (Email Address used in the SSO IdP) that will be issued by the IdP. To view and verify a user’s email address in TeamConnect: Go to Admin → All Users. Click the username you want to check. In the General tab, under the Account Information section, click on the user’s Contact record. You will be able to see the email address that must match the NameID sent by the IdP.
2. Enable SAML Authentication: Set the default authentication method for your TeamConnect instance.
3. Test the Login Flow: Log out of TeamConnect and browse to your login page (e.g.,  https://<tc-host>/login. Select your newly configured IdP from the drop-down menu. You will be redirected to your IdP. Authenticate with your user credentials. Verify that you are successfully redirected back to the TeamConnect homepage as the expected user.

Option A – SAML for Select Users (Default = Password)

Use this method when most users will log in with a standard password, but a specific group needs to use SAML.

1. Leave the global default set to Standard Authenticator (or your current non-SAML method) in Admin → Admin Settings → Security.
2. For each user who should use SAML, navigate to their user profile (Admin → All Users → [Username]) and in the General tab, set their Authentication dropdown to your named SAML Authenticator.
3. Provide these specific (SAML) users with the direct SAML login URL: https://<your-tc-host>/login/saml2/sso/{RegistrationID}.
4. All other users will continue to log in with passwords at the standard /login page.

Option B – SAML for Most Users (Default = SAML)

Use this method when most users will use SAML, but a few (like administrators or external users) need to use a standard password.

1. Set the global Default Authentication Method to your SAML Authenticator in Admin → Admin Settings → Security.
2. For any user who must still use a password, navigate to their user profile (Admin → All Users → [Username]) and in the General tab, set their Authentication dropdown to your named Standard Authenticator.
3. Provide these specific users with the direct standard login URL to bypass SSO: http(s)://<your-tc-host>/standardLogin .

Direct Login URLs

• Default Login: .../login

  • This URL follows your currently configured default authentication method.

• Standard/Password Login: .../standardLogin

  • Use this URL to force a password login (Standard Authentication), which is useful for password-based users when SAML is the default.

• SAML-Specific Login: .../login/saml2/sso/{RegistrationID}

  • This URL forces authentication against a specific IdP configuration.

Logout Redirection Behavior

It’s helpful to know that TeamConnect remembers which login URL you used.

Upon logout, the system automatically returns users to their original login page. For instance, a user who logged in via /standardLogin will be redirected to /standardLogin after logging out, rather than the default /login page. This maintains consistency by ensuring users are directed to the appropriate login method for subsequent sessions.

Prerequisites for Single Logout (SLO)

Before you begin, make sure that:

• Your IdP supports SAML 2.0 Single Logout.
• You have administrator access to the IdP application configuration.
• You have already created and configured a SAML registration in TeamConnect (see Step 3: Add IdP Registration to TeamConnect).
• You have generated an SP private key and certificate (see the Private Key example in Step 3, or your organization’s standard certificate generation process).

Configuring Single Logout (SLO) in the Identity Provider

Use the following settings in your IdP’s SAML application configuration.

1. Generate and Upload the Signature Certificate

• TeamConnect uses a Service Provider (SP) signing certificate to sign SAML assertions and Single Logout requests.
• The following OpenSSL commands are examples only. You can run them from any directory and adjust file names or locations to meet your organization’s standards.
• Note: The private key generated in this step must correspond to the certificate uploaded to both the Identity Provider and TeamConnect.

a. Generate the private key: You need a private key for the Service Provider, which is TeamConnect in this case. This can be created using a standard tool like OpenSSL.

• Open a command prompt or terminal and run the following command to generate a 2048-bit RSA private key:
  openssl genpkey -algorithm RSA -out sp-key.pem -pkeyopt rsa_keygen_bits:2048
• This command generates a private key and saves it in the file sp-key.pem, which you can then upload.

b. Generate the X.509 certificate: Run the following command to generate a self-signed Service Provider certificate:
    openssl req -new -x509 -key sp-key.pem -out sp-cert.pem -days 365

• This command generates an X.509 certificate and saves it to the file sp-key.pem, which you can then upload as the Signature Certificate in the IdP SAML application configuration.
  
  
   
• ❗Important: If the Identity Provider encrypts assertions or requires the Service Provider to sign SAML or Single Logout messages, this certificate is required. The certificate must match the private key uploaded to TeamConnect.

2. Enable Single Logout in the Identity Provider:  In the IdP SAML application configuration, enable application-initiated Single Logout.

Examples:

• In Okta, select the Allow application to initiate Single Logout checkbox.
  
• In Azure, In the Logout URL (optional) field, enter: https://<your-tc-host>/logout
  • Replace <your-tc-host> with your TeamConnect’s public hostname.

3. Configure the Single Logout URL: Set the Single Logout URL in the IdP to the TeamConnect logout endpoint.

• The format is: https://<your-tc-host>/logout
• Replace <your-tc-host> with your TeamConnect’s public hostname.

4. Configure the SP Issuer / Identity ID: Set the SP Identity ID or Issuer in the IdP to the TeamConnect SAML metadata URL.

• The format is: https://<your-tc-host>/login/saml2/service-provider-metadata/{RegistrationID}

  • Replace <your-tc-host> with your TeamConnect’s public hostname.

  • Replace {RegistrationID} with the actual Registration ID you configured in TeamConnect (for example, OKTA).

Configuring Single Logout (SLO) in the TeamConnect Setup

After the IdP is configured to send and receive SLO messages, update the corresponding SAML registration in TeamConnect.

1. Go to Setup → System Settings → SAML Authentication Settings.
2. In the Add New SAML Registration form, add a new registration with the SLO configuration.
   Important: You cannot modify the existing SAML registration. To include the SLO configured settings, either you must delete the existing registration or add a new one with the updated settings. To know more, see the Certificate Maintenance section.
3. In the SAML registration form, configure the following fields:

• Single Logout URL: Enter the Single Logout URL in the IdP to the TeamConnect logout endpoint that accepts a SAML LogoutRequest. 
  • The format is: https://<your-tc-host>/logout/saml2/slo
  • Replace <your-tc-host> with your TeamConnect’s public hostname.
• Single Logout Response URL (optional): Enter the IdP endpoint that returns the SAML LogoutResponse if the SLO flow is asynchronous.
• Certificate: Upload the signing certificate you downloaded from your IdP. This certificate is used to validate SAML assertions and SLO responses from the IdP (i.e., to verify that the login assertions are coming from a trusted source).
• Private Key: Upload the SP private key only if your IdP encrypts assertions with TeamConnect’s public key or requires the SP to sign SLO messages.
  • Note: The private key must match the public certificate (sp-cert.pem) you uploaded to the IdP so TeamConnect can decrypt the assertions

4. Click Add Registration. The entry appears in the SAML Registration section.
5. Click Save and Close on the main System Settings page to persist all changes.

How it works

• When you select Log Out in TeamConnect, a confirmation screen appears.
• The dialog box displays the following message: Are you sure you want to log out? Logging out means that you will need to sign in again for all your apps. There may be a delay of up to an hour before you are signed out of everywhere.
• You have two options:
  • Continue: Logs you out of TeamConnect and all other applications associated with your SSO session.
  • Cancel: Returns you to TeamConnect without logging you out.

Here is a screenshot for reference that shows how the confirmation screen appears in the TeamConnect application:

When is the confirmation screen displayed?

The confirmation screen appears only if:

• Single Sign-On (SSO) is enabled in the SAML Authentication settings.
• Single Logout (SLO) is configured for your Identity Provider (meaning, a valid Single Logout URL was provided during the IdP setup in Step 3: Add IdP Registration to TeamConnect).

Audit Logging: Single Logout events are recorded in the TeamConnect audit logs for security and compliance monitoring. To know more about Viewing Logs in TeamConnect, see here.

Important Note: This feature does not affect:

• Users who log in using Standard/Password authentication.
• Users authenticated via SSO Identity Providers that do not support or have not configured Single Logout (SLO).

Confirming the Upgrade

After you complete these steps and re-enable SAML using the new configuration, you will notice a name change for the authentication method.

• Previous Version: The method was named SAML Single Sign On. This was the option available with the previous SAML server.
   
• New Version: The method is now named SAML Authenticator. This is the new option that appears after you have deleted the old files and enabled SAML through the Authentication Settings page.

Here is an example screenshot for your reference:

Deeper Debugging: View and Decode SAML Assertions

When troubleshooting SAML SSO login issues, viewing the SAML assertion helps you verify the information your identity provider (IdP) is sending. The assertion is a security token that includes the user’s identity and authentication details, which TeamConnect uses to grant access.

Follow these steps to capture, decode, and inspect the SAML assertion.

Capture the SAML Assertion

Use your browser’s developer tools to capture the SAML assertion during the login process.

Error Messsage	Resolution
1. Open the Developer Tools panel in your web browser. Shortcut: Press F12 or Ctrl+Shift+I (Windows) / Cmd+Option+I (macOS).
2. Select the Network tab and select the Preserve log checkbox.
3. In a new tab, initiate the SAML login flow and complete authentication via your IdP (e.g., Okta).
4. After the redirect back to TeamConnect, look for a POST request in the Network tab with a path matching your ACS URL (e.g., /login/saml2/sso/{RegistrationID}).
5. Locate the Payload tab, and copy the entire Base64-encoded value of the SAMLRequest parameter.

 

Decode the SAML Assertion

After copying the SAML assertion, decode it to view its contents in XML format.

Error Messsage	Resolution
1. Go to an online SAML decoder, such as https://www.samltool.io.
2. Paste the copied SAMLRequest value into the field labeled SAML Token.
3. The tool will show you the decoded XML output.

 

Viewing Audit Logs to Identify IdPs

To explicitly identify which IdP was used during a login attempt and view other details, you can inspect the TeamConnect audit logs.

The log entries can capture the following IdP details:

• <RegistrationID>

• <EntityID>

• <NameIdFormat>

• <SingleLogoutUrl>

Example Log Entry:

2025-08-19 20:15:51,734 [name@example.com] <audit.login> Logged In (Remote Host: 0:0:0:0:0:0:0:1, Session:*****************,
RegistrationId: ExampleSSO, EntityId: https://<your-tc-host>/login/saml2/service-provider-metadata/{RegistrationID},
NameIDFormat: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress)