> ## Knowledge Base Index > Fetch the complete knowledge base index at: https://docs.brainframe.com/sitemap.xml > Use this file to discover available pages before exploring further. > Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash). # Microsoft Entra ID Integration # πŸ”‘ **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](#-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** | Permission | Used for | | ---- | | `User.Read.All` | Identities β†’ Users | | `Group.Read.All` | Identities β†’ Groups | | `Application.Read.All` | Identities β†’ Apps & Service Principals | | `Device.Read.All` | Devices β†’ Registered | | `RoleManagement.Read.Directory` | Privileged Access (active + PIM eligible) | | `Policy.Read.All` | Conditional Access | | `SecurityEvents.Read.All` | Security signals | | `IdentityRiskyUser.Read.All` | Identity Protection β†’ Risky users | | `IdentityRiskyServicePrincipal.Read.All` | Identity Protection β†’ Risky SPs | | `IdentityRiskEvent.Read.All` | Identity Protection β†’ Risk detections | | `AccessReview.Read.All` | Governance β†’ Access reviews | | `EntitlementManagement.Read.All` | Governance β†’ Access packages | | `AuditLog.Read.All` | Sign-in / audit context | | `DirectoryRecommendations.Read.All` | Secure Score | | `DeviceManagementManagedDevices.Read.All` *(optional)* | Devices β†’ Managed (Intune) | > πŸ“Œ 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: | Status | Meaning | | ---- | | 🟒 **Enabled** | Permission consented and the module returns data. | | 🟒 **Enabled (missing license)** | Permission is consented, but the tenant needs an extra license (e.g. P1/P2/Governance) before data appears. | | 🟠 **Enabled (unavailable)** | Permission consented, but the feature probe failed (often a license/feature gate). | | πŸ”΄ **Disabled** | The permission has **not** been consented β€” add it and grant admin consent in Azure. | > || 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: | Module / sub-menu | Minimum license | | ---- | | Identities (Users, Groups, Apps & SPs) | Any tenant (Entra ID Free) | | Privileged Access β†’ Active assignments | Any tenant | | Devices β†’ Registered | Any tenant | | Secure Score | Any tenant (fuller recommendations with a paid plan) | | **Conditional Access** | **Entra ID P1** | | **Identity Protection** (Risky users / SPs / Risk detections) | **Entra ID P2** | | **Privileged Access β†’ Eligible (PIM)** | **Entra ID P2 / Governance** | | **Governance** (Access reviews / Access packages) | **Entra ID Governance** (or P2) | | **Devices β†’ Managed (Intune)** | **Microsoft Intune** license | > πŸ’‘ 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. | Card | What it shows | Click takes you to | | ---- | | **Identity Secure Score** | Your identity secure score as a % (current / max). | Secure Score tab | | **High risk users** | Count of users flagged high risk. | Identity Protection β†’ Risky users (High) | | **Medium risk users** | Count of users flagged medium risk. | Identity Protection β†’ Risky users (Medium) | | **Low risk users** | Count of users flagged low risk. | Identity Protection β†’ Risky users (Low) | | **Privileged Roles** | Active privileged assignments, split into *permanent* vs *eligible (PIM)*. | Privileged Access | | **Conditional Access** | Enabled policies, plus *report-only* and *disabled* counts. Warns **"No MFA policy enabled"** if none enforce MFA. | Conditional Access | | **Devices** | Registered devices and how many are *non-compliant*. | Devices | | **Identities** | Total users, plus *guests*, *disabled*, and *apps with expiring credentials*. | Identities β†’ Users | | **Governance** | Reviews in progress, decisions pending, and access-package requests pending. | Governance | > πŸ“Œ 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) | Entra object | Imported as | Best used to… | | ---- | | User / Risky user | **Person** | Track a person tied to an access risk, incident or awareness action. | | Group | **Group** | Document a security/M365 group governing access to an asset or process. | | App / Service Principal / Risky SP | **Application** | Register a workload/app as an asset and link it to risks and controls. | | Role assignment / Eligible (PIM) | **Role** | Evidence privileged-access governance and least-privilege reviews. | | Registered / Managed device | **Workstation** | Add an endpoint to your asset inventory and its dependency chain. | | Risk detection | **Incident** | Open an incident from a detection and drive it through remediation. | | Conditional Access policy | **Policy** | Treat a CA policy as a control linked to compliance requirements. | | Secure Score control | **Corrective / Preventive Action (CAPA)** | Turn a recommendation into a tracked remediation task. | | Access review | **Access Review** | Keep periodic access-certification evidence for audits. | | Access package | **Access Package** | Document entitlement-management scope and approvals. | ### πŸ”— 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 * [x] App registration created in Entra ID * [x] Required application permissions added **and admin consent granted** * [x] Client secret + Tenant ID + Client ID entered in Brainframe * [x] **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](https://learn.microsoft.com/en-us/graph/auth-v2-service). For anything Brainframe-specific, contact us at support@brainframe.com.