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

In a short 15 minute meeting with your IT and our development team, SSO will be set up and checked if everything has been configured correctly. Our development team is usually available between 9.30 and 11.00 am. The appointments are coordinated exclusively via the Customer Happiness Team.

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.

Azure Active Directory

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

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

Required information:

• Azure AD Tenant-ID
  We will only use the Tenant-ID to make sure only your Azure AD 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

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.