Copy page

Guides

Connect Microsoft

This guide is for Owners and Admins, and for partners who set up Microsoft for a customer. At the end bots work with Microsoft 365 data, and, if you want, a Teams app in the customer's tenant answers with the Company Bots you chose.

The app belongs to the customer. It lives in the customer's Microsoft 365 tenant, not in yours. GEKI has no shared Teams app and no Teams store listing. A setup in the Console guides you. Every step has a script and a way by hand.

The connection has two parts that you set up one after the other:

• The connection. One app in Microsoft Entra ID, its client secret, and the admin consent. With it comes Microsoft 365 for bots.
• Teams. Optional. The Azure Bot and the Teams app. See Set up Teams.

Before you start

• You are an Owner or Admin of the organization. A partner switches into the customer's organization first. See Partners.
• Someone in the customer's tenant can help:
  • an Application Administrator runs the app script,
  • a Global Administrator grants admin consent,
  • for Teams, a Teams administrator adds the app, and an owner of an Azure subscription creates the Azure Bot.
• The app takes its name, colour, and publisher from Settings: the display name, the brand colour, and the publisher (name, website, privacy URL, and terms URL). Set them first. The Teams setup asks for publisher fields that are still missing.

The names of menus in Microsoft Entra and the Azure portal change now and then. Look for the same wording if a name differs.

1. Start the setup

Open Connections and choose Add connection, then Connect Microsoft. You can also open /connections/new/microsoft in the Console directly.

The setup shows its steps at the top: Domain, App, Admin consent, and Test. It opens the next open step. You can go back to a done step at any time to change it.

2. Domain

GEKI fills in the company email domain and looks up the tenant ID of that domain at Microsoft. Use Find tenant for another domain, or type the Tenant ID yourself. You find it in the Microsoft Entra admin center under Overview.

Then decide about Files for bots (OneDrive and SharePoint). It is off by default. With it on, bots use the files of each person who talks to them: all OneDrive and SharePoint files that person can see. There is no limit to chosen folders. With it off, the app does not get the permissions Files.ReadWrite.All and Sites.ReadWrite.All, and GEKI never asks for them. You can change it later.

Select Continue. The connection is named after the domain. You can rename it later.

3. App

GEKI needs one app in the customer's tenant.

Script. Select Get script and run it in PowerShell or in Azure Cloud Shell as an Application Administrator. The script:

• signs in to the tenant with the Microsoft Graph PowerShell module,
• creates a single tenant app, or updates the one it made before,
• adds the redirect URI https://api.geki.ai/v1/oauth/callback and the delegated Microsoft Graph permissions,
• creates a client secret that is valid for one year,
• sends the application ID, the secret, and its expiry date to GEKI.

The script carries a one-time setup token. It is valid for one hour. The step turns green by itself when the script is done.

By hand. In the Microsoft Entra admin center, open App registrations and choose New registration. Use a single tenant app. Add the redirect URI as type Web. Under API permissions, add the delegated permissions the Console lists. Under Certificates & secrets, create a client secret and copy its Value at once. Then enter the application ID, the secret value, and its expiry date in the Console.

The client secret is stored encrypted and never shown again.

4. Admin consent

A Global Administrator accepts the permissions of the app once for the whole tenant. Select Grant admin consent. Microsoft asks for the consent and then brings you back to the Console. GEKI tests the connection right away.

You can copy the link and send it to an administrator. It works without a GEKI account. If Microsoft did not bring you back, select Mark consent as done.

5. Test

Select Test connection. GEKI gets an app token from the tenant and reads which permissions are granted. When the test passes, the setup is done: the connection page says Microsoft is connected and offers Connect my account and Set up a bot.

The connection page

The page has tabs.

• Connection. The status, the tenant, Test connection, Rename, the app registration with the client secret and its expiry date, Renew secret, Run setup again, and Delete connection.
• Microsoft 365 for bots. See Microsoft 365 for bots.
• Teams app. See Set up Teams.

On Connections, the card of the connection shows its status, the expiry date of the secret, and a row for Microsoft 365 for bots and for Teams.

Microsoft 365 for bots

A bot can use the mail, calendar, people, and meetings of each person who talks to it, and the OneDrive and SharePoint files when files are on. The bot uses the account of that person and sees only what that person can reach. Channel threads in Teams and Slack and service accounts never use a person's account.

It is on for a new connection. Only one connection of the organization can have it. The tab shows how many people connected their account, the redirect URI, the delegated permissions, and the admin consent link. Turn off stops it. It needs no consent and no test.

Each person connects in Chat under Settings, then Connected accounts, in the row Microsoft 365. A person who signed in to Chat with Microsoft is connected without a screen, once an admin has consented. If some accounts lack permissions, the tab names them. Grant admin consent again, then people connect again.

Files for bots on the tab turns OneDrive and SharePoint on or off. Off, bots get no file tools from the next message. You can also remove the two file permissions from the app in Entra. On, the app needs the permissions first: run the app setup again or add them by hand, grant admin consent again, then people connect again.

Give a bot access

Open the bot in the Console, then Editor and Mail and calendar. If your organization also set up Google Workspace, choose Microsoft 365 there first. Each area has its own setting.

Select Save, then Publish. Publishing asks you to confirm each area. A bot with these areas reads data of people, so keep the internet access of its workspace restricted. The editor warns when it is open. It also warns when no connection has Microsoft 365 for bots on.

Set up Teams

Teams comes after the connection. On Connections, select Set up in the Teams row, or open the Teams app tab of the connection. Select Start setup. The setup asks only for publisher fields that are still missing in Settings. If the display name is longer than 30 characters, it also asks for a shorter app name.

The setup has two steps: Bot and Teams app.

Bot

Teams reaches your bots through an Azure Bot. It uses the app from the connection.

• With an Azure subscription. Enter the subscription ID, a resource group, and a bot name. Run the script as an owner of the subscription. It creates the Azure Bot (single tenant, your app, the messaging endpoint) and turns on the Teams channel. The step turns green by itself.
• Without an Azure subscription. Create the bot in the Teams Developer Portal under Tools, Bot management. Use your existing app, and set the endpoint address the Console shows. Then select Mark as done. GEKI has not tested this way yet. If it does not work, use the Azure portal.
• Azure portal, by hand. Create an Azure Bot resource. Choose Single tenant and the existing app with the application ID and tenant ID the Console shows. Set the messaging endpoint the Console shows. Open Channels and add Microsoft Teams. Then select Mark as done.

The messaging endpoint is the address where Teams sends messages. GEKI checks the token of every request. It accepts only requests for this app and from your tenant.

Teams app

The Console builds the Teams app package: the manifest and two icons in the brand colour.

• Script. Run it as a Teams administrator. It downloads the package from GEKI and adds it to the app catalog of the tenant with Microsoft Graph, or updates the app that is there. The step turns green by itself.
• By hand. Select Download package. In the Teams Admin Center, open Teams apps, then Manage apps, and upload the zip. Make sure the app is allowed. Then select I uploaded the package.

A team owner adds the app to each team where bots should answer, and agrees to the permissions of the app. In a personal chat, people open the app from Apps.

When the setup is done, choose which bot answers where on the Teams channel page.

Teams files

Bots read the files that people send and post the files they create. Turn on Teams files on the Teams app tab.

The permission Files.ReadWrite.All is tenant-wide. The app can read and write the files of every user and team in the tenant. Tell the customer before you turn it on. A short setup follows:

1. Run the script as an Application Administrator. It adds the permission to the app. Or add it by hand under API permissions as a Microsoft Graph application permission.
2. A Global Administrator grants admin consent. GEKI tests the connection when Microsoft brings you back.
3. Update the Teams app. The package now marks the bot as file-capable.

Files that the bot creates go to the folder Microsoft Teams Chat Files in the OneDrive of the person in a 1:1 chat, and to the SharePoint folder of the channel in a channel. Without Teams files, the bot reads the text only.

Turning Teams files off needs no consent and no test.

Update the Teams app

Update the app after a change of the display name, the brand colour, or the publisher in Settings, and when the Console shows that a newer package is available. On the Teams app tab, select Update the Teams app and use the script or the way by hand.

Renew the client secret

The client secret expires after the date you set, one year with the script. The status is Needs attention 30 days before the date and Broken after it. Teams stops answering and Microsoft 365 for bots stops working when it has expired.

On the Connection tab, select Renew secret.

• Script. Run it as an Application Administrator. It adds a new secret, sends it to GEKI, and removes the old one. The sheet closes when GEKI has the new secret.
• By hand. In the Microsoft Entra admin center, open the app, then Certificates & secrets. Add a client secret and enter its value and expiry date in the Console. Delete the old secret afterwards.

When something is wrong

The Connection tab lists the reasons for the status of the connection. A Teams problem shows on the Teams row and on the Teams channel page.

If the bot does not answer in Teams, check that the connection is Connected, that the Azure Bot has the Microsoft Teams channel on, that the app was added to the team, and that the bot is live.

Remove the connection

Select Delete connection on the Connection tab. Bots stop answering in the tenant at once, and the channel settings are deleted. The app registration, the Azure Bot, and the Teams app stay in the tenant. Remove them there.

Next

• Slack and Teams describes how bots answer and who may use them.
• Connect Slack is the same task for Slack.
• Partners covers customers that you manage.