RandomCoffee Help Center
EnglishFrançais
Type to search documentation.

Microsoft Teams integration

Install the RandomCoffee app in Microsoft Teams, link it to a program, and understand its SSO, provisioning and permissions.

View as MarkdownOpen in ChatGPTOpen in ClaudeOpen in GrokOpen in Perplexity

The Microsoft Teams integration works by associating a RandomCoffee program with one or several Microsoft Teams teams. The RandomCoffee bot then sends the program’s invitations and matches to the members of these teams, directly in Teams. The integration is available on every plan.

This page covers the technical side: installation, single sign-on, provisioning and permissions. It also refers to Microsoft protocols, which Microsoft may update over time. For questions about a contract implementation, contact support@random-coffee.com.

What the app adds to Teams

The RandomCoffee app for Microsoft Teams contains:

  • A bot, available in teams and in personal chat. It sends the opt-in and match cards and answers three commands: “Help”, “Feedback” and “Snooze”.
  • A channel tab, added to the team when you link a program. It shows the program’s context, schedule and activity.
  • Three personal tabs: “My Activity”, “My Network” and “My Programs”.

What members see in Teams is described in How RandomCoffee works.

Before you start

  • A program to link. We recommend creating at least one program in your RandomCoffee workspace before installing the app. If your workspace has no program yet, the installation window lets you create one from a template (“Create a program now”). If you do not have a RandomCoffee workspace yet, it offers “Create a Program on RandomCoffee”, and you continue once the program exists.
  • Permissions in Microsoft Teams. You need to be allowed to add apps to a team in your Microsoft Teams environment (depending on your organization’s policy). If the RandomCoffee app is blocked or not available in your tenant, your IT team can allow it by following Set up RandomCoffee in the Teams Admin Center.

Install the RandomCoffee app

  1. Start from RandomCoffee.

    Open “Settings”, go to “Configuration”, select the “Microsoft Teams integration” card and click “Install”.

  2. Add the app to a team.

    Microsoft Teams opens on the RandomCoffee app. Open the menu next to “Add” and select “Add to a team”.

    The RandomCoffee app in Microsoft Teams, with the Add to a team option

  3. Choose the team.

    The app is installed in a team, starting from one of its channels. Select your team (and channel), then click “Set up”.

    The Add RandomCoffee to a team window, with a team and channel selected and the Set up button

    Choose a standard channel. RandomCoffee does not work in private channels for the moment.

  4. Select the program to associate.

    In the RandomCoffee window, select the program to link to the team, then click “Save”.

    If you select an existing running program, this resets its communication templates to make them compatible with Microsoft Teams cards. Adapt your message templates once the installation is complete: see Personalize messages.

  5. Check the confirmation.

    Your program is now associated with the team. The RandomCoffee bot sends you, privately, a “New RandomCoffee program for the team!” card.

  6. Finish setting up the program.

    Click “⚙️ Setup your program” in the card, or go to your RandomCoffee workspace, to choose your matching rules, personalize your messages and schedule the upcoming sessions.

In RandomCoffee, the “Communication” section of the program’s “Settings” now shows “Microsoft Teams” as its channel, and the team appears in “Microsoft Team”, in the “Registration” section.

You can associate several teams with one program: the program then selects people from all of them.

Who takes part in the program, and what happens when people join or leave a team, is explained in Sync members from Slack or Microsoft Teams.

Single sign-on (SSO)

How it works

RandomCoffee uses a discreet SSO protocol in Microsoft Teams. A person who has a RandomCoffee account is recognized automatically by their email address and linked to their Microsoft Teams account. The step is invisible to them.

This is what allows an admin, when adding the app to a team, to see the data of their RandomCoffee account (such as their existing programs) directly in Teams. An admin who has no RandomCoffee workspace yet is invited to create one, with a first program, before continuing.

For app users, this means:

  • Teams gets the access token for the current user from Microsoft Entra ID (formerly Azure AD), without the user leaving Teams.
  • Consent is needed only once. If the app and the user are in the same tenant, no consent is needed at all.
  • A tenant administrator can grant consent on behalf of all users, so that nobody sees a consent dialog.
  • Teams pre-fetches the token, which speeds up loading, and users have no extra password to remember.

When consent is missing, the app shows “Grant user or admin Consent” with a “Grant Consent” button.

Sequence at runtime

#InteractionWhat happens
1Tab app to Teams clientThe tab calls getAuthToken() to ask Teams for an access token.
2Teams client to Microsoft Entra IDTeams requests an access token for the current user, based on their Teams identity.
3Microsoft Entra ID to consent promptOn first use, if the app needs protected data, the user (or the administrator) is asked to consent. A step-up authentication, such as two-factor authentication, can also be requested.
4Microsoft Entra ID to Teams clientMicrosoft Entra ID returns the access token, a JSON Web Token (JWT). Teams caches it for later calls.
5Teams client to tab appTeams returns the token in the result of getAuthToken().
6Tab app (client and server)The RandomCoffee server exchanges the token (on-behalf-of flow) for a Microsoft Graph token with the User.Read scope and identifies the user.

To learn more, see Microsoft’s documentation: Overview of authentication for tabs using SSO in Teams with Microsoft Entra ID.

User provisioning

Once the RandomCoffee bot is installed in your team, RandomCoffee retrieves the list of the team’s members from Microsoft Teams. It reads only the basic information it needs for each member: first name, last name and email address. RandomCoffee then generates the matches and posts them in Teams.

Data flow between Microsoft Teams and RandomCoffee: RandomCoffee pulls each user's first name, last name and email, adds its own categories, generates the matches and posts them in Teams

App permissions

The RandomCoffee app can call Microsoft APIs once users or admins have granted their consent.

Teams app manifest permissions

  • identity
  • messageTeamMembers

Microsoft Entra ID delegated permissions

  • User.Read (Microsoft Graph)
  • email
  • openid
  • profile
  • offline_access

Uninstall the app

  1. In Microsoft Teams, right-click the RandomCoffee app in the left bar, then select “Uninstall”.
  2. Confirm with “Remove”.

FAQ

Can the Microsoft Teams integration and the HRIS integration work together?

Yes. Users provisioned from Microsoft Teams who also exist in your HRIS are recognized by their email address and enriched with the data from your HRIS, which you can use in your matching rules. See HRIS integration.

Members get an error when they click a button in a RandomCoffee card

The app is probably blocked or not available to them in your tenant. See Set up RandomCoffee in the Teams Admin Center.

Set up RandomCoffee in the Teams Admin Center

Make the RandomCoffee app available in your organization's Teams.

Single sign-on (SSO)

Let your team sign in with your identity provider.

Slack integration

Install RandomCoffee in your Slack workspace.