Wie kann ich in teamecho SSO nutzen?

Im Artikel findest du alles Wissenswerte über SSO und wie die Einrichtung abläuft.

Der große Vorteil von Single Sign On (SSO) ist ganz klar, dass sich deine Mitarbeiter*innen ohne ein Passwort in teamecho einloggen können. Deine Mitarbeiter*innen bekommen für den ersten Log-In das Registrierungsmail, müssen dann nur mehr die gewünschte Sprache einstellen und können direkt in teamecho loslegen. Das vereinfacht die Teilnahme enorm und kann zu einer besseren Rücklaufquote beitragen. Wie dein Unternehmen SSO nutzen kann und wie der kurze Einrichtungstermin mit unseren teamecho-Developer*innen abläuft, erklären wir dir hier. 

OpenID Connect

Wir haben in unser System OpenID Connect implementiert, was du nutzen kannst, um deine teamecho User*innen zu identifizieren. Damit die Schnittstelle funktioniert, braucht dein Unternehmen einen OIDC kompatiblen Authorization-Server. Die meisten Identity-Management-Tools wie Microsoft Entra ID und Keycloak bieten diese Funktion an. Der Server muss die E-Mail-Adresse aller in teamecho hinterlegten User*innen im IT-Token oder Userinfo-Endpoint liefern.  

Falls dein Unternehmen ein anderes System verwendet und du nicht sicher bist, ob es kompatibel ist, können unsere Developer*innen weiterhelfen.

Einrichtungstermin und Spezifikationen

In einem ca. 15-minütigen Termin gemeinsam mit eurer und unsrer IT wird SSO eingerichtet und überprüft, ob auch alles korrekt konfiguriert wurde. Unser IT steht dafür in der Regel von Mo - Fr zw. 9.30 und 11.00 Uhr zur Verfügung. Die Termine werden ausschließlich über das Customer-Happiness-Team koordiniert. 

Für den Termin ist ein bereits registrierter teamecho-Account notwendig.

Bevor SSO eingerichtet werden kann, muss also der Account Set-Up mit eurer Customer-Happiness-Managerin durchgeführt worden sein.

Darüber hinaus benötigen wir eine*n bereits registrierte*n User*in, mit dem überprüft werden kann, ob die Anmeldung klappt. Für die SSO-Einrichtung braucht es keinen Admin-Account. Es reicht, wenn sich deine IT grundsätzlich in teamecho einloggen kann.

Je nach System brauchen wir euere Daten einen Tag  im Voraus. Im Folgenden erklären wir dir welche Daten relevant sind.

Microsoft Entra ID

Wenn du Microsoft Entra ID verwendest, kannst du einfach unsere App nutzen: https://azuremarketplace.microsoft.com/en-US/marketplace/apps/aad.teamecho?tab=Overview

Falls du deinen Client manuell hinzufügen möchtest, findest du weiter unten eine ausführliche Erklärung. 

Benötigte Daten: 

• Entra ID Tenant-ID
  Wir nutzen die Tenant-ID nur, um sicherzustellen, dass nur dein Entra ID User*innen in deinem teamecho Account identifizieren kann. 
  https://learn.microsoft.com/en-us/azure/active-directory/fundamentals/active-directory-how-to-find-tenant 
• Username-claim
  Finde Standard Claims in der Microsoft Dokumentation: https://learn.microsoft.com/en-us/azure/active-directory/develop/id-tokens
  Falls du einen custom claim verwendest, benötigen wir den Namen, um den teamecho Usernamen auszulesen.
• (Optional) Falls du SSO nicht für alle User*innen in deinem teamecho-Account verwenden möchtest, kannst du uns eine Liste aller E-Mail-Domains zur Verfügung stellen: z. B. customer.com, customer-external.com

Microsoft Active Directory Federation Service (AD FS)

• Erstelle im AD FS Management eine neue Application Group mit einem Namen (frei wählbar z.B.: teamecho) und wähle die Vorlage Server application accessing a Web API aus und klicke auf Next.
• Hier siehst du den Client Identifier (client-id) den wir für die Einrichtung benötigen.
• Gib die Redirect URI ein die du von uns bekommst. Diese hat das Format https://app.teamecho.com/login/oauth2/code/{registrationId}. Klicke auf Next.
• Setze das Hakerl bei Generate a shared secret und übermittle uns dieses über einen sicheren Kanal (z.B.: Video-Call) an uns weiter.
• Füge den Identifier https://app.teamecho.com hinzu und klicke auf Next.
• Wähle die Policy aus die am besten zu den teamecho Benutzern passt und klicke auf Next.
• Stelle sicher, dass die Scopes openid und email aktiviert sind und schließe die Konfiguration ab.

Andere Anbieter

Unser Customer Happiness Team wird euch die redirect URLs mitteilen, die ihr in euer System eintragen müsst.

Folgende Informationen sind am Tag vor dem vereinbarten Termin an uns zu retournieren:

• client-id
• client-secret
• Username-claim: Wir benötigen den Namen des Claims, um den teamecho-User*innen-Name auszulesen. Üblicherweise stellen die Systeme Standard-Claims zur Verfügung z. B. https://learn.microsoft.com/en-us/azure/active-directory/develop/id-tokens
• (Optional) Scope
  Bitte lass uns wissen, welchen Scope wir benötigen, um den Username-claim zu erhalten. Wir werden immer min. “openid” anfordern.
• (Optional) Falls du SSO nicht für alle User*innen in deinem teamecho-Account verwenden möchtest, kannst du uns eine Liste aller E-Mail-Domains zur Verfügung stellen: z. B. customer.com, customer-external.com

Du kannst uns dein OpenID Provider Configuration Document oder die folegenden Daten übermitteln:

• JWK SET URI: z. B.. https://sso.customer.com/common/discovery/keys
• Authorization URI: z. B. https://sso.customer.com/abcd-abcd-abcd-abcd-abcd/oauth2/authorize
• Token URI: z. B. https://sso.customer.com/abcd-abcd-abcd-abcd-abcd/oauth2/token
• (Optional) Userinfo-Endpoint: Sofern das Attribut Username nicht Teil der ID Token ist, gebt bitte den Userinfo-Endpint-URI an: z. B. https://sso.customer.com/abcd-abcd-abcd-abcd-abcd/oauth2/userinfo

Good to knows

• Bei einer SSO-Nutzung ist es wichtig, die eigenen User*innen gut zu warten. Durch fehlerhafte Konfiguration kann es sein, dass ein*e bestehende*r User*in aus dem Tool ausgesperrt wird und nicht (mehr) an der Befragung teilnehmen kann. Namensänderungen sind da z. B. eine beliebte Fehlerquelle. Intern wurde die E-Mail-Adresse schon upgedatet, in teamecho ist aber noch die "alte" in Verwendung (oder umgekehrt). Dann funktioniert SSO natürlich nicht und der*die User*in kann nicht auf teamecho zugreifen. 
• Wenn SSO in Verwendung ist und man als User*in generell über SSO gerade eingeloggt/aktiv ist, bleibt man auch im teamecho-Account eingeloggt. D. h., auch wenn man in teamecho auf ‘abmelden’ klickt, kommt man direkt wieder ohne PW rein, solange man im unternehmenseigenen SSO eingeloggt ist. Der teamecho-Logout beendet nur die Session in teamecho und hat keinen Einfluss auf andere System. Ein Single-Sign-Out bieten wir nicht an. 
• SSO kann jederzeit auch nach einem teamecho-Start eingerichtet werden. Um teamecho mit euren internen User*innen verwenden zu können, muss über SSO die E-Mail-Adresse, mit der eure User*innen in teamecho registriert sind, bei der Authentifizierung zurückgemeldet werden.