How can I use SSO in teamecho?

In this article you will find everything you need to know about SSO and how to set it up.

The big advantage of a Single Sign On (SSO) is clearly that your employees can log in to teamecho without a password. Your employees receive the registration email for the first log-in, then only have to set the desired language and can start directly in teamecho. This simplifies participation enormously and can contribute to a better response rate. How you and your company can use SSO and how the short setup session with our teamecho developers works is explained here. 

OpenID connect

We have implemented OpenID connect in our system, which can be used to authenticate your users in teamecho. So for the interface to work, your company needs a simple OIDC compatible authorization server, which most user and identity management tools like Azure Active Directory and Keycloak can provide. The server shall be able to include the email address of the users which is entered in teamecho either in the ID token or at the user information endpoint.

If you are using another system and are not sure if it is compatible, our developers might be able to provide some guidance.

Setup meeting and specifications

The setup will be carried out by your Customer Happiness Manager and tested by you or your IT department. (If necessary, we offer a joint review of the SSO setup with your IT in a short, approximately 15 minute appointment. Our IT team is generally available for this from Monday to Friday between  9.30 and 11.00 am. Please note that a registered teamecho account is required for the appointment.)
An already registered teamecho account is required for the appointment. So before SSO can be set up, the account set-up must have been done with your Customer Happiness Manager.

In addition, we need an already registered user to check if the registration works. For the SSO setup you do not need an admin account. It is sufficient if your IT can log into teamecho.

Depending on your system, we will need some data on the day before the agreed date, as described in the following sections.

Microsoft Entra ID

If you are using Microsoft Entra ID, you can simply add our application: https://azuremarketplace.microsoft.com/en-US/marketplace/apps/aad.teamecho?tab=Overview

After the activation of your Tenant ID by our customer support, the Enterprise App can be added by logging into your teamecho account. Depending on the configuration, administrator rights in your Entra tenant may be required for the first login.

If you still want to configure your client manually, you can check the information for Other providers.

Required information:

• Entra ID Tenant-ID
  We will only use the Tenant-ID to make sure only your Entra ID is able to authenticate users in your company.
  https://learn.microsoft.com/en-us/azure/active-directory/fundamentals/active-directory-how-to-find-tenant 
• Username-claim
  Find claims available by default in the Microsoft Documentation: https://learn.microsoft.com/en-us/azure/active-directory/develop/id-tokens
  If you are using a custom claim, we need to know the name of the claim to read the teamecho-username from the ID token.
• (Optional) If you do not want to enable SSO for all users in your teamecho account, you can provide a list of all email domains to be passed to the SSO: e.g. customer.com, customer-external.com

Microsoft Active Directory Federation Service (AD FS)

• Open AD FS Management and create a new Application Group with a name of your choice (e.g. teamecho), select the Server application accessing a Web API template, and click Next.
• You will now see the Client Identifier (client-id) we need for the setup.
• Add the Redirect URI that we will provide. This will be in the form of https://app.teamecho.com/login/oauth2/code/{registrationId}. Click Next.
• Check Generate a shared secret and send it to us over a secure channel (e.g. video call)
• Add the Identifier https://app.teamecho.com and click Next.
• Select the policy that best suits your teamecho users and click Next.
• Make sure that Scopes openId and email are enabled and complete the setup.

Other providers

Our Customer Happiness Team will provide you with the redirect URLs which need to be registered in your SSO.

Please configure your system before the appointment and provide the required information.

Required information:

• client-id
• client-secret
• Username-claim
  We need to know the name of the claim which contains the username(=email) of the teamecho user. Typically, the systems provide some default claims which might be used, e.g. https://learn.microsoft.com/en-us/azure/active-directory/develop/id-tokens
• (Optional) Scope
  Please tell us which additional scopes are required to receive the Username-claim. We will always request at least “openid”
•  (Optional) If you do not want to enable SSO for all users in your teamecho account, you can provide a list of all email domains to be passed to the SSO: e.g. customer.com, customer-external.com

You can provide your OpenID Provider Configuration Document or just the following values:

• JWK SET URI: e. g.. https://sso.customer.com/common/discovery/keys
• Authorization URI: e. g. https://sso.customer.com/abcd-abcd-abcd-abcd-abcd/oauth2/authorize
• Token URI: e. g. https://sso.customer.com/abcd-abcd-abcd-abcd-abcd/oauth2/token
• (Optional) Userinfo Endpoint
  If the ID token does not contain the username, please specify the Userinfo endpoint URI: e. g. https://sso.customer.com/abcd-abcd-abcd-abcd-abcd/oauth2/userinfo
  
  

Good to knows

• When using SSO, it is important to maintain your own users. Due to incorrect configuration, it is possible that an existing user is locked out of the tool and cannot participate in the survey. Name changes, for example, are a common source of errors. Internally, the email address has already been updated, but in teamecho the "old" one is still in use (or vice versa). Then SSO does not work and the user cannot access teamecho.
• If SSO is in use and the user is generally logged in/active via SSO, he/she will be automatically logged in to the teamecho account. I.e., even if you click on 'log out' in teamecho, you can get back in directly without a password as long as you are logged into the company's own SSO. The teamecho logout will only end the users teamecho session and does not have any influence on any other systems, as we do not offer Single Sign-out.
• SSO can be set up at any time even after teamecho has been started. In order to use teamecho with your internal users, the e-mail address with which your users are registered in teamecho must be reported back during authentication via SSO.