Connect Microsoft Graph

The Bifrost Microsoft connection is the app-only identity used for Microsoft Graph and supported Exchange operations. A workspace may separately use Microsoft CSP app-and-workflow automation for Partner Center’s app-and-user connection; that automation is not built into Bifrost and is not required for this connection.

Start With Discovery

Offer a read-only inventory before creating anything. Inspect existing provider app registrations, service principals, credentials, Graph app-role assignments, customer enterprise applications, Bifrost Microsoft integration mappings, and every workflow that uses the integration.

Classify the result as reuse, repair, or create. Reuse is appropriate only when the application is provider-owned, multi-tenant where required, has known consumers, and can be reduced to a reviewed capability-based permission profile.

Define Capabilities Before Permissions

Start with the workflows you intend to operate. Typical profiles include:

Capability	Permission design question
Tenant inventory	Which organization, domain, user, group, or license reads are required?
Identity administration	Which user and group writes are required, and which GDAP roles authorize them?
Mail and calendar	Is delegated access sufficient, or does a workflow require application access?
Exchange administration	Does the workflow require Exchange Online app-only access and an Exchange role?
Teams deployment	Which self-scoped user, team, or chat installation permissions match the supported scopes?
Teams history	Does a named workflow need messages that the bot did not receive directly? If not, omit chat-read and RSC permissions.

Verify every permission in the current Microsoft Graph permissions reference. Application consent authorizes the app-only Graph token. GDAP roles can authorize a provider’s delegated administration path to provision a customer service principal or consent, but they do not add runtime authority to that app-only token.

Register or Reuse the Application

1. Reuse a healthy provider-owned application when discovery confirms its consumers and grants. Otherwise, create a provider-owned multi-tenant application.

2. Record its application ID, object ID, supported account types, owners, and credential renewal date.

3. Add only the application permissions selected for the installed capabilities. A manifest change requests permissions; it does not grant them.

4. Create the service principal in the provider tenant and grant the reviewed application roles. Microsoft Graph supports this with appRoleAssignments when the caller has the necessary Graph permissions and Entra role.

5. Create a certificate or client secret supported by Bifrost. Store it only in the integration or approved secret manager.

Microsoft Graph can perform the registration, service-principal, owner, redirect-URI, and credential operations listed in the Partner Center guide. It can also grant application permissions by creating an appRoleAssignment for the client service principal. The caller still needs the documented Graph permissions and an appropriate Entra role.

Connect Bifrost and Map Customers

1. Configure the global Bifrost integration named Microsoft for the client credentials flow. Its token URL must contain {entity_id} and its scope must be https://graph.microsoft.com/.default.

2. Enter the application’s client ID and credential. Do not configure a refresh token for this connection.

3. For each customer, create exactly one integration mapping whose entity ID is the customer’s Entra tenant ID and whose Bifrost scope is the customer’s organization.

4. If your workspace has optional CSP automation, its tenant-link workflow can create the same mapping and provider status record. Otherwise, create the mapping through the Bifrost integration interface or CLI.

5. Reject unknown or duplicate tenant mappings before making customer-scoped calls.

Establish Customer Consent

The provider application needs a service principal and the approved application roles in each customer tenant. A workspace that includes CSP automation can use its Microsoft CSP connection to provision the service principal and apply a reviewed permission profile when the provider’s relationship and roles allow it. That automation is optional.

Without that workspace automation, a customer Privileged Role Administrator or Global Administrator can open https://login.microsoftonline.com/<customer-tenant-id>/adminconsent?client_id=<graph-app-client-id>, then review the customer-tenant enterprise application’s permissions in Entra and grant admin consent. Confirm the service principal and application-role assignments before running the mapped workflow. Microsoft documents creating a customer-tenant enterprise app for a multitenant application and granting tenant-wide admin consent.

Caution

Customer consent and GDAP are separate. A customer relationship does not automatically grant the application’s Graph permissions, and an app-role assignment does not grant the provider user a GDAP role.

For a controlled rollout:

1. Link the development tenant to its Bifrost organization.
2. Choose a consent path: the optional CSP/GDAP provisioning flow where authorized, or a customer administrator’s manual consent path.
3. Apply the selected provider permissions and complete customer consent.
4. Re-read the customer service principal and app-role assignments.
5. Run a harmless read in the mapped organization.
6. Run a write test only against an explicit disposable object and with approval.

Verify and Operate

Verify that the global Microsoft connection reports healthy, every customer has one mapping, the development customer’s grants match the selected profile, and an app-only token can call the intended Graph resource in customer scope.

Monitor credential expiration, permission drift, failed token requests, and stale mappings. When offboarding, disable customer writes, remove the mapping, remove the service principal or grants only after checking other consumers, and retain the required audit evidence.