🔑 Microsoft Entra ID Integration

"Bring your directory into Brainframe — identities, devices, risk, conditional access and governance, all in one place."
Read Microsoft Entra ID (formerly Azure AD) data live through the Microsoft Graph API, spot security gaps at a glance, and import the objects you want to govern as linked Brainframe documents.

The Microsoft Entra ID integration connects Brainframe to your tenant using an app-only (application permission) Microsoft Graph connection. Once configured, you get a live security dashboard and a browsable, filterable view of your directory — and you can import any object as a Brainframe document so it can be linked to risks, non-conformities, assets, controls and compliance requirements.

1️⃣ Before You Begin

To configure the integration you will need:

• 🛠 A Brainframe workspace administrator account (integration configuration is admin-only).
• 🔐 Access to the Microsoft Entra admin center (or Azure portal) with rights to create an App registration and grant tenant admin consent.
• 🪪 The right Entra ID licensing for the modules you want to use (see license limitations below). The core identity modules work on any tenant; advanced modules need Entra ID P1, P2, Governance or Intune.

⚠️ If this workspace already has a Microsoft Graph credential configured for email (Mail.Send), it cannot be reused for directory APIs. Create a dedicated Entra app registration for this integration with the permissions listed below.

2️⃣ Configure the Integration

Step 1 — Create an App Registration in Entra ID

1. Open the Microsoft Entra admin center → App registrations → New registration.
2. Give it a name (e.g. Brainframe GRC – Directory) and register it. A redirect URI is not required.
3. Go to API permissions → Add a permission → Microsoft Graph → Application permissions and add the permissions below.
4. Click Grant admin consent for your tenant — this step is required; without it, modules stay disabled.
5. Go to Certificates & secrets → New client secret, then copy the secret Value immediately (it is shown only once).
6. From the app Overview page, note the Directory (tenant) ID and Application (client) ID.

Required application permissions

📌 These are read-only permissions. Brainframe never writes back to your tenant.

Step 2 — Enter Credentials in Brainframe

Go to Workspace Settings → Integrations → Microsoft Entra ID → Configure and fill in:

• Tenant ID — the Directory (tenant) ID (must be a valid GUID).
• Application (client) ID — the Application (client) ID (must be a valid GUID).
• Client secret — the secret value you generated.

Then:

1. Click Test connection. Brainframe probes every module and shows the Module capability status table. At least one module must be available before you can save.
2. Click Save. Credentials are encrypted at rest and are never returned to the browser after saving.

📌 To change or remove the connection later, return to the same Configure screen (gear icon on the integration page). Removing the integration deletes the stored credentials but leaves any already-imported documents intact.

Step 3 — Read the Module Capability Status

After testing, each module shows one of four states:

If everything shows Disabled, the most common cause is that permissions were added but admin consent was not granted. Go to App registrations → API permissions → Grant admin consent for your tenant.

🪪 License Limitations

The connection succeeds with a basic tenant, but individual modules depend on your Entra licensing:

💡 Missing a license is not an error — Brainframe simply marks the affected cards and tabs as "Missing license" and keeps the rest of the integration fully usable.

3️⃣ Using the Integration

Open the integration from Workspace Settings → Integrations → Microsoft Entra ID (or the Integrations tile grid). Any workspace user can browse and import; only admins can edit credentials.

The Refresh button re-fetches live data; the gear icon opens the credential configuration.

📊 Top Cards (tenant health at a glance)

The row of cards summarises your tenant's security posture. Each card is colour-coded (green = healthy, amber = attention, red = risk) and is clickable — it jumps straight to the matching tab, pre-filtered.

📌 If a module lacks its license or permission, the card shows "Missing license" or "Missing permission" instead of a number.

🗂 Tabs & Sub-menus

Below the cards, seven tabs give you the full, filterable inventory. Several tabs have sub-menu buttons:

• 🛡 Secure Score — Microsoft's identity recommendations with score, priority, implementation cost, user impact and status. Filter by status (achieved / partial / gap) and implementation cost.

👤 Identities

• Users — UPN, display name, type (member/guest), enabled, licensed, on-prem synced. Filter by type and enabled state.
• Groups — name, type (Security / Microsoft 365 / Dynamic), role-assignable, member count. Filter by type and role-assignable.
• Apps & SPs — service principals & applications with app ID, type, and credential status (valid / expiring ≤30 days / expired).

🔐 Privileged Access

• Active assignments — who holds which directory role right now, permanent vs time-bound.
• Eligible (PIM) — just-in-time eligible role assignments (requires P2/Governance).
• Filter by role name and assignment type.

💻 Devices

• Registered — Entra-registered/joined devices with OS, compliance and trust type.
• Managed (Intune) — Intune-managed devices with compliance state and management agent (requires Intune).
• Filter by OS, compliance and enabled state.

⚠️ Identity Protection (requires P2)

• Risky users — users flagged at risk, with level and state.
• Risky SPs — risky service principals / workload identities.
• Risk detections — individual detection events (type, IP, location, time).
• Filter by risk level and state (at risk / confirmed compromised / remediated / dismissed).
• 🚦 Conditional Access (requires P1) — policies with state, target (users/apps) and grant controls. A Notes flag highlights a security gap where a disabled policy would otherwise enforce MFA.
• ⚖️ Governance (requires Governance/P2)
• Access reviews — review campaigns with status and pending decisions.
• Access packages — entitlement-management package requests and their state.

Common controls on every tab:

• 🔎 Search box (press Enter or click Search).
• 🔗 Open Entra dashboard — opens the matching page in the Microsoft Entra admin center in a new tab.
• ⏭ First page / Next pagination (Microsoft Graph uses cursor-based paging).

4️⃣ Importing into Brainframe

Browsing is read-only until you import. Importing turns an Entra object into a native Brainframe document so it becomes part of your linked GRC web.

How to import

• Single object — use the import action on any row.
• Bulk — tick the checkboxes (selection is remembered across pages) and use Import selected in the toolbar.

Either way, the folder selection modal opens so you can pick the destination folder and confirm the document type (pre-filled from the mapping below). On confirm, Brainframe creates/links the documents and reports an outcome per item: created, updated, skipped (already exists) or failed. Re-importing the same object updates or skips it, so you won't create duplicates.

What each object becomes (document-type mapping)

🔗 Import directly linked to a document

You don't have to start from the settings page. From any Brainframe document — a risk, non-conformity, asset, control, etc. — open the integration / link action and choose Microsoft Entra ID. The Entra browser opens scoped to that document, and anything you import is automatically linked to it (bi-directionally).

💡 This is the recommended workflow. For example:

• From a general risk ("Excessive standing privileges"), import the relevant PIM/role assignments and risky users so the risk shows exactly which identities it concerns.
• From a non-conformity ("Non-compliant endpoints in scope"), import the affected managed devices as evidence.
• From an asset (a core service), import its backing application/service principal and groups to complete the dependency chain.
• From a control/requirement, import the Conditional Access policy or Secure Score control that satisfies it.

5️⃣ Best Practices

• 🧭 Start from the dashboard cards — the red/amber cards point to your highest-value imports first (high-risk users, non-compliant devices, no-MFA warning).
• 🔗 Import from the document, not the settings page, whenever the object relates to a specific risk, control or asset — the automatic linking saves manual work.
• 🎯 Import selectively. You rarely need every user or device — import the objects you actually want to govern or evidence, and rely on the live browser for the rest.
• 🔄 Re-import to refresh imported documents after major directory changes; existing documents are updated, not duplicated.
• 👤 Own via roles — when importing People, keep ownership pointed at role documents so your governance survives staff changes.
• 🪪 Match modules to licensing — hide the noise by focusing on the tabs your tenant is licensed for; upgrade licenses only where a module delivers governance value.

6️⃣ Troubleshooting

• A card or tab says "Missing permission" → the application permission wasn't consented. Add it in Azure and Grant admin consent, then Refresh.
• A card or tab says "Missing license" → the permission is fine, but the tenant needs P1/P2/Governance/Intune for that feature.
• Test connection fails with "at least one module must be available" → admin consent hasn't been granted for any permission, or the secret/IDs are wrong.
• Email Graph credential doesn't work for directory data → expected; configure a separate app registration for this integration.
• Everything is Disabled right after adding permissions → consent can take a moment to propagate; re-run Test connection.

🎯 Visual Checklist

• App registration created in Entra ID
• Required application permissions added and admin consent granted
• Client secret + Tenant ID + Client ID entered in Brainframe
• Test connection passed (≥ 1 module available) and saved
• Module capability status reviewed against your licenses
• Dashboard cards reviewed for high-risk items
• Key objects imported and linked to their risks / controls / assets

💬 Need help? For Microsoft Graph app-only authentication details, see the Microsoft Graph app-only auth docs. For anything Brainframe-specific, contact us at support@brainframe.com.

Updated on: 14/07/2026