Setting up Microsoft
Registering an Entra application, the permissions each service needs, and the optional certificate that makes group-based file access work.
Register one Microsoft directory application. Members connect their accounts, and the assistant uses each person's permissions. Connectors covers policy.
Azure Cloud Shell
In authenticated Azure Cloud Shell, run:
curl -fsSLo setup-microsoft-connector.sh \
https://docs.asteria-labs.com/scripts/setup-microsoft-connector.sh
bash setup-microsoft-connector.shPress Enter at the services prompt to enable every available service, which is the recommended setup, or type a smaller list. The script shows the permission plan before making changes and prints the values to paste into Asteria Cloud. Manual steps follow.
Manual setup
1. Register the application
In the Microsoft Entra admin centre, go to Identity, then Applications, then App registrations, then New registration.
- Name: for example,
Asteria Cloud connector. - Supported account types: Accounts in this organizational directory only. Single tenant is the right answer, and it also means Microsoft's publisher verification does not apply to you.
- Redirect URI: platform Web, and the address
https://app.asteria-labs.com/api/connectors/callback.
From the Overview page, copy the Application (client) ID and the Directory (tenant) ID. You need both.
Then Certificates & secrets, New client secret. Copy its Value immediately, because Microsoft shows it once. Note the expiry date somewhere you will see it again: when a secret lapses, every member's connection stops working and only an administrator can fix it.
2. Grant the permissions your members will use
API permissions, then Add a permission, then Microsoft Graph, then Delegated permissions.
Add only the rows for services you intend to offer. Everyone who connects approves what the application asks for, so an unused permission is one your members have to accept for no benefit.
| Service | Permissions | What it is used for | Admin consent |
|---|---|---|---|
| Always | openid, email, profile, offline_access | Signing in and staying connected. offline_access is what keeps a connection alive without asking the member to sign in repeatedly. | No |
| Files | Files.Read.All | Reading OneDrive and SharePoint files, and mirroring a folder into a collection. | No |
| File editing | Files.ReadWrite.All | Creating, uploading and replacing files, and saving deliverables back to a folder. | No |
| SharePoint sites | Sites.Read.All | Listing the SharePoint sites a member follows, and the document libraries in them, so they can browse to a folder when setting up a synced collection instead of pasting a link. | No |
Mail.Read | Reading and searching a member's mailbox. | No | |
| Mail sending | Mail.ReadWrite, Mail.Send | Drafting, editing and sending mail as the member. | No |
| Calendar | Calendars.ReadWrite | Reading the calendar and creating events, including Teams meeting links. | No |
| Directory | User.Read.All, GroupMember.Read.All | Looking people up by name, their photos, managers and group membership. | Yes |
| Teams | Chat.Read, Team.ReadBasic.All, Channel.ReadBasic.All, ChannelMessage.Read.All | Reading chats and channel messages, and triggering workflows on new ones. | Yes, for ChannelMessage.Read.All |
| Teams sending | ChatMessage.Send, ChannelMessage.Send | Posting messages to a chat or channel. | No |
Rows marked Yes need a Microsoft 365 administrator to approve them once for the whole directory. Use Grant admin consent on this page after adding them. Without it, a member selecting that service sees a consent screen they cannot complete.
Microsoft returns the union of everything your directory has approved for the application, not only what a member selected. So a member who ticks Files and Mail may end up holding whatever else you have granted. Add permissions as you decide to offer the services, not all at once up front.
3. Register it in Asteria Cloud
In the console, go to Connectors, then Microsoft, and enter the client ID, client secret and directory (tenant) ID. The form refuses a Microsoft registration without the tenant ID, because Microsoft's sign-in addresses are specific to your directory.
Turn the Microsoft 365 switch on. Members cannot connect until it is on.
Members then go to Profile, then Connections, and connect their own account.
4. Optional: group access to shared files
Skip this section and everything above still works. What you lose is specific, and worth understanding before deciding.
What it fixes
When a collection mirrors a SharePoint library, Asteria Cloud only shows each person the documents they can already open in SharePoint. To do that it has to know who a document was shared with.
Without this step, two things do not work:
Documents shared with a group stay hidden. If a file is shared with a Microsoft 365 group or a SharePoint group such as Site Members, we cannot check who belongs to that group, so we show it to nobody. Since group sharing is how most SharePoint libraries are set up, this is usually the larger half.
Documents in a library the person adding it does not own may be hidden from their colleagues. Microsoft shows the full list of who a file is shared with only to that file's owner. Anyone else is shown just their own access. So when someone connects a library they are a member of rather than the owner of, we see only their access and hide the file from everyone else.
Both fail in the safe direction: files are hidden from people who should see them, never shown to people who should not. But hidden files look like the product losing documents, so it is worth closing.
What to set up
A certificate. Microsoft requires certificate authentication for this, and will reject a client secret no matter what permissions it carries. Generate one, keep the key where you keep your other secrets, and give it a lifetime you will remember to renew:
openssl req -x509 -newkey rsa:2048 -nodes -days 730 \
-subj "/CN=asteria-acl" -keyout acl-key.pem -out acl-cert.pemUpload acl-cert.pem only, the certificate, in Entra under Certificates & secrets, then Certificates. Never upload the key file there.
Application permissions, on two different APIs. These are a different tab from everything in step 2. Where the permissions above act as the member who connected, these act as the application itself, with no person involved.
Under Add a permission, then Microsoft Graph, then Application permissions:
| Permission | What it is used for |
|---|---|
Files.Read.All | Reading the complete list of who a file is shared with |
User.ReadBasic.All and GroupMember.Read.All | Checking which groups a person belongs to. Microsoft requires both together. |
Under Add a permission, then SharePoint, then Application permissions:
| Permission | What it is used for |
|---|---|
Sites.Read.All | Checking who belongs to a SharePoint site group such as Site Members |
Then Grant admin consent.
SharePoint and Microsoft Graph both offer a permission called Sites.Read.All, and they are not the same permission. You need the one under SharePoint.
If you grant only the Microsoft Graph one, group access will half work: Microsoft 365 groups resolve, SharePoint site groups never do, and documents shared through Site Members stay hidden with nothing to indicate why.
Install the certificate in Asteria Cloud. In the console, go to Connectors, then Microsoft, then Update, and paste the contents of both files, the certificate followed by the key, into Certificate for group access.
The card then shows the certificate's fingerprint, which must match the one Entra shows, and its expiry date. We store the key encrypted and use it only to check who may read a document. It is never used to open files: those are still read using the connected member's own account, so Asteria Cloud can never hold a file that person could not open themselves.
Renew the certificate before it expires. When it lapses, group access stops and documents shared with a group go quiet, while everything else keeps working. The expiry date on the connector card is there so you can see it coming.
These permissions are broad, and that is the trade
The application permissions above let Asteria Cloud read, across your whole directory, who may open a file and who belongs to which group. That is what allows an answer for a library nobody with a personal connection owns.
They do not grant reading file contents on their own behalf: content is always read using a connected member's account and their permissions. If that trade is not one you want to make, skip this section. Everything else works, and files shared with groups simply stay hidden.