Provide the attendant console as a Teams app

What it is for

Attendants who work in Microsoft Teams all day can open the EasyUC attendant console right there. For this the attendant console is provided as a personal, tenant-internal Teams app. Teams loads the attendant console page as a tab in the app bar.

Sign-in uses the active Teams account: the user clicks Sign in with Teams, Teams issues an access token for the user who is already signed in, EasyUC validates it and opens the attendant console session. The user’s password is not transmitted to EasyUC.

The app package is a ZIP file with a manifest and two icons. It contains no passwords, client secrets or tokens. EasyUC hostname, client ID and the addresses of the privacy statement and terms of use are public details.

Prerequisites

• Licence modules acd (attendant console) and teams.
• A full DNS name for EasyUC, for example easyuc.kunde.de, with HTTPS on port 443 and a publicly trusted certificate chain. Plain IP addresses and self-signed certificates are not suitable for a Teams tab.
• Reachable pages for privacy and terms of use over HTTPS.
• In the customer’s Microsoft tenant, the right to create an app registration and to upload and release a custom Teams app.
• In EasyUC the customer’s Teams tenant exists and is active, with Directory (tenant) ID and Application (client) ID. EasyUC validates the Teams token against these two values.
• The attendants are entered as enabled attendants and mapped to their Microsoft account (chapter on assigning attendants and devices).
• The package generator from the EasyUC delivery (tools/teams-attendant-app) and Python 3 on a workstation.

Step by step: Prepare the app registration for Teams sign-in

1. In the Microsoft Entra admin center, open Identity → Applications → App registrations and the app registration whose application ID is stored at the tenant in EasyUC. Otherwise create one with New registration and enter its ID at the tenant.
2. In the manifest of the Entra app, set the value requestedAccessTokenVersion under api to 2.
3. Under Expose an API, create the Application ID URI in the form api://EASYUC-HOSTNAME/CLIENT-ID, for example api://easyuc.kunde.de/00000000-0000-0000-0000-000000000000.
4. Create a delegated scope there with the name access_as_user, consent by admins and users, state enabled.
5. Under Authorized client applications, enter Microsoft’s two Teams clients: 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams desktop and mobile) and 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web). Authorise the scope for both.
6. No Microsoft Graph permission and no client secret are needed for this sign-in.

Step by step: Generate and validate the app package

1. On the workstation, change to the directory of the EasyUC delivery.
2. Generate the package: python3 tools/teams-attendant-app/generate-package.py --fqdn easyuc.kunde.de --client-id CLIENT-ID --privacy-url https://www.kunde.de/datenschutz --terms-url https://www.kunde.de/nutzungsbedingungen.
3. The ZIP file is then under tools/teams-attendant-app/dist/. It contains exactly manifest.json, color.png and outline.png.
4. Validate the package: python3 tools/teams-attendant-app/validate-package.py followed by the path of the ZIP file.

Step by step: Upload and release the app in Teams

1. Open the customer’s Teams admin center.
2. Select Teams apps → Manage apps.
3. Open Actions → Upload new app and upload the ZIP file.
4. Release the app for the group of attendants.
5. Optionally pin the app in the app bar through a setup policy.
6. The user opens the EasyUC Attendant app in Teams. It appears among the apps of the user’s own organisation.
7. On the page Attendant console in Microsoft Teams, the user clicks Sign in with Teams. The attendant console opens.

Step by step: Update the package

1. Generate the package with the same client ID and a higher version, for example --version 4.5.1. This way the app keeps its identity.
2. Validate the new ZIP file with validate-package.py.
3. Upload it in the Teams admin center as an update of the existing app.

Fields and options

Check the result and narrow down errors

• Success: the app appears in Teams, the tab loads the sign-in page, and after Sign in with Teams the attendant console opens without a password prompt.
• The tab does not load: check the HTTPS certificate and DNS of the EasyUC hostname and whether the hostname in the package is exactly right.
• Teams reports a wrong resource: compare the Application ID URI in Microsoft Entra character by character with api://EASYUC-HOSTNAME/CLIENT-ID.
• “Sign-in with your Microsoft Teams account failed. Please try again.” Check the scope access_as_user, the two pre-authorised Teams clients and whether directory ID and application ID at the EasyUC tenant belong to this Entra app.
• “This Microsoft account is not enabled for the attendant console.” The user is not an enabled attendant or is not mapped to their Microsoft account.
• “Microsoft sign-in has not been fully configured yet. Please contact your administrator.” There is no unique active tenant in EasyUC for the directory ID.
• “Microsoft sign-in is not available in this installation.” The Teams module is not active.
• “The attendant console could not be initialized in Microsoft Teams. Please reopen it in Teams.” Close the tab and open the app again.
• The upload is rejected: check with validate-package.py and review the tenant’s app management policy for custom apps.