Connect Microsoft Entra to a team

View as markdown

A managed team can connect its Microsoft Entra tenant so that members sign in to Bearly with Continue with Microsoft. The same team can also provision people and groups from Microsoft Entra, so joiners, leavers, and group changes reach Bearly without hand edits. Either part works on its own.

Before you start

You are an Admin of the managed team.
The team’s managed domain is a verified domain in your Microsoft Entra tenant, and each person’s Microsoft account has an Email in that domain. Personal Microsoft accounts and guests from other organizations cannot use Microsoft sign-in.
You have the tenant’s Tenant ID from the Microsoft Entra admin center, under Entra ID → Overview → Properties.
Someone who can grant tenant-wide admin consent in Microsoft Entra, such as a Global Administrator, Privileged Role Administrator, Cloud Application Administrator, or Application Administrator, is available to approve Bearly.

Bearly never asks for a Microsoft application secret. You provide only the tenant ID, and a Microsoft administrator approves Bearly on Microsoft’s own consent page.

Open your account menu and follow Teams → your team → Overview. Scroll to Microsoft Entra and select Setup Microsoft Entra.
Under Configure sign-in, paste the tenant ID into Directory tenant ID, make sure Allow Microsoft sign-in is on, and select Save and continue.

Bearly confirms with Microsoft Entra login updated, and the step shows Saved.
Under Grant admin consent, select Connect Microsoft. Microsoft’s approval page opens. From the desktop app it opens in your system browser.
Sign in to Microsoft with an administrator account from the same tenant, review the permissions, and accept. Bearly asks only to sign people in and read their name and email address.
When Bearly shows Microsoft connected, select Return to Bearly. If you started from the desktop app, close the browser tab and return to the app.
Under Test sign-in, confirm the connection works: in another browser or after signing out, choose Continue with Microsoft with an account whose email ends in the team’s managed domain.

The Microsoft sign-in row now shows Enabled, and its button reads Manage Microsoft Entra. A tenant can be connected to one Bearly team.

After approval, Bearly is listed under Enterprise applications in your Microsoft Entra tenant. Manage it there like any other application: require assignment under Properties, assign users and groups, or apply Conditional Access. Those Microsoft settings decide who can reach Bearly’s sign-in. Bearly’s own membership rules, described next, decide what happens after that.

On the sign-in page, members select Continue with Microsoft and choose their work or school account. On the web, the sign-in continues in the same tab. In the desktop app, Microsoft opens in the system browser, and the app comes to the front and signs in when Microsoft finishes; the browser tab can then be closed. The iOS app does not offer Microsoft sign-in, so use email sign-in there.

Signing in with Microsoft uses the same Bearly account as signing in by email with that address, so existing chats and projects are unaffected. Email sign-in stays available to every member.

What happens on a person’s first Microsoft sign-in depends on the team’s Managed-domain access setting under Overview → Settings:

Automatically add anyone with @domain: the person becomes a member immediately and receives the team’s default policy.
Require a team administrator to add each person: the person must already be on the team, either added by an administrator or provisioned from Microsoft Entra as described below. Otherwise Bearly reports that the account is not allowed to join the team.

A member whose Account access has been switched off cannot sign in with Microsoft until an administrator restores it.

Select Manage Microsoft Entra, turn off Allow Microsoft sign-in, and select Save and continue. New Microsoft sign-ins for the tenant stop. Members keep their Bearly accounts and memberships and can continue with email sign-in.

Provision members and groups from Microsoft Entra

Provisioning lets Microsoft Entra add members, keep their names current, suspend people who leave, and mirror groups into the team. Bearly administrators keep control of roles, policies, and spending limits; provisioning never changes them.

Generate the provisioning token in Bearly

Under Microsoft Entra on the team’s Overview, find User and group provisioning and select Set up provisioning.
Select Generate token.
Copy the Tenant URL and the Secret token. Bearly shows the token only once. If you lose it, generate a new one.

The row shows Configured, and its button reads Manage provisioning.

Connect the Microsoft Entra provisioning service

Provisioning uses a dedicated enterprise application in your tenant. Microsoft’s SCIM tutorial has the full walkthrough; the steps below cover what Bearly needs.

In the Microsoft Entra admin center, go to Entra ID → Enterprise apps → New application → Create your own application. Name it, choose Integrate any other application you don’t find in the gallery, and create it.
Open the application, select Provisioning, and start a new configuration. Enter Bearly’s values in Tenant URL and Secret Token, select Test Connection, and save the configuration. If your admin center shows the older layout, choose Get started, set Provisioning Mode to Automatic, and enter the same values under Admin Credentials.
Under Attribute mapping, edit the user mappings to match the table below and confirm the group mappings. Save the changes.
Under Users and groups, assign the people and groups Bearly should receive. Keep the scope at Sync only assigned users and groups.
Select Provision on-demand and provision one user and one small group. Confirm they appear under Members and Groups in Bearly before going further.
Select Start provisioning. The first cycle can take a while. After that, Microsoft checks for changes about every 40 minutes.

User attribute mappings

Microsoft Entra attribute	Target attribute	Notes
`userPrincipalName`	`userName`	The matching attribute. It must be the person’s email address in the managed domain. If user principal names differ from email addresses in your tenant, map `mail` instead, so provisioning and Microsoft sign-in refer to the same address.
`objectId`	`externalId`	Change this from the default `mailNickname`.
`Switch([IsSoftDeleted], ...)`	`active`	Keep the default expression. A person who is unassigned, disabled, or deleted in Microsoft Entra becomes suspended in Bearly.
`displayName`	`displayName`	Optional. Bearly uses it as the member’s name.

Delete every other user mapping, including given and family names, work email, phone numbers, addresses, job title, department, and manager. Bearly rejects updates to attributes it does not store, and those failures show up in Microsoft’s provisioning logs. Do not map roles.

For groups, keep the default mappings: displayName to displayName, objectId to externalId, and members to members.

What provisioning changes in Bearly

A newly assigned person is added as a Member. Someone already on the team with the same email is linked rather than duplicated, and their role, policy, and limit stay as they are.
A person who is unassigned, disabled, or deleted in Microsoft Entra is suspended, not removed. They show Suspended under Members, lose access through the team, and can no longer sign in with Microsoft, but their data is kept. Restore access by assigning them again in Microsoft Entra.
Assigned groups appear under Groups with a Synced badge. Their name and membership come from Microsoft Entra, so they cannot be renamed or deleted in Bearly. You can still assign a policy and priority and add extra members by hand; members that came from Microsoft Entra also show Synced.
A group that Microsoft Entra stops provisioning becomes Inactive in Bearly. It keeps its policy, its project shares, and any members you added by hand, and it becomes active again if Microsoft Entra provisions it later.
Changes made by provisioning appear under Activity attributed to Identity provider.

Limits to plan around:

Every provisioned person needs an email address in the managed domain. Anyone else fails in Microsoft’s provisioning logs.
Group names must be 2 to 120 characters, and a single group update can include at most 500 members.
Nested groups are not supported. Assign the groups whose direct members should sync.
Provisioning cannot suspend the team’s last active administrator. Make another member a Team admin first.

Manage provisioned people from Microsoft Entra rather than from Members. If you remove a provisioned member in Bearly while they are still assigned in Microsoft Entra, a later provisioning cycle can add them again.

Rotate or disable the token

Select Manage provisioning under Microsoft Entra.

Rotate token issues a new token and immediately stops the old one. Provisioning pauses until you paste the new token into the Microsoft Entra configuration and run Test Connection again.
Disable stops provisioning and rejects the existing token. Existing members, groups, and memberships stay as they are, and Microsoft Entra can no longer update them. To start again, select Generate token and update the Microsoft Entra configuration.

Troubleshooting

What you see	What to do
This Microsoft organization is not configured for Bearly.	The account belongs to a tenant that is not connected, or Allow Microsoft sign-in is off. Check the saved Directory tenant ID.
Your Microsoft account did not provide a work email.	Ask a Microsoft administrator to set the person’s Email in Microsoft Entra to an address in the managed domain.
Microsoft did not confirm this account’s email domain.	The address uses a domain that is not verified in the tenant, for example an external address. Use an address in a verified domain.
Use the Microsoft account for your Bearly organization.	The account’s email is outside the team’s managed domain.
Your Microsoft account is valid, but it is not allowed to join this Bearly team.	The team requires an administrator to add each person, the membership is suspended, or that email is already linked to a different Microsoft account. A team administrator can add or restore the member.
This Microsoft sign-in expired or was already used.	The sign-in must finish within a few minutes of starting. Start again from the sign-in page.
Failed to update Microsoft Entra login	Check that the tenant ID is complete and correct. A tenant can be connected to only one Bearly team.
Microsoft did not approve the connection.	Consent was declined, or the account cannot grant admin consent. Select Connect Microsoft again and sign in with an eligible administrator.
Microsoft tenant approval could not be verified.	The approving account belongs to a different tenant than the saved Directory tenant ID. Correct the ID, or use an administrator of the saved tenant.
Test Connection fails in Microsoft Entra	The Tenant URL or Secret Token is wrong, or provisioning was rotated or disabled in Bearly. Generate a new token and paste both values again.
A provisioning log entry says the user name must be an email in the managed domain	The mapped attribute for that person is outside the team’s domain. Correct the person’s address or the `userName` mapping.

For help with a connected tenant, contact Bearly Support.