# Entra Integration Health — User guide

## Installation and first scan

Extract the full installer ZIP on Windows Server 2016 or newer, x64, and run Setup.cmd as administrator. Step 1 checks the server, package files, free space, Microsoft connectivity and previous installations. Use Upgrade for a working installation.

Step 2: create a single-tenant Entra app registration in the customer tenant. Leave Redirect URI blank. Copy Directory (tenant) ID and Application (client) ID from Overview. Add Microsoft Graph Application permission Directory.Read.All and grant administrator consent. Enter your local Display Name; port and recovery options are under Advanced settings. No client secret is needed.

Step 3: select Prepare certificate. Python 3.13.16 x64 and bundled tools are installed locally. Open certificate folder or Copy certificate path, then upload only collector.cer to the same app registration under Certificates & secrets → Certificates. Never share private-key.dpapi. Plan replacement before the certificate expires after one year.

Step 4: select Test connection after certificate upload. Authentication and both Graph inventory checks must pass. The scrolling log keeps stage and failure details. Correct the indicated Entra setting and retry; installation is blocked until verification succeeds.

Step 5: select Install. Setup retests access and installs the same certificate already uploaded. Select Open dashboard and collect your first report. Start free 7-day trial opens License & Billing, where Microsoft tenant verification completes activation. Configure schedules and email after a successful scan.

Online setup guide is available throughout the wizard. The unique protected preparation workspace is removed on normal exit; a crash may leave it for administrator review. The shared Python prerequisite remains if setup is canceled. Future Python minor versions require compatibility testing.

The dashboard is local to the Windows server. Use the administrator Start-menu shortcut to establish a session. Installed Apps / Add or remove programs lists Entra Integration Health. Uninstall preserves local data and does not cancel billing or revoke Entra permissions.

## Dashboard and tracked information

App registrations describe applications registered in the tenant. Enterprise applications are service principals in the tenant. The two counts represent directory objects, not unique business integrations.

Top cards open the relevant collapsed section. Search filters application names, IDs and visible permission details. Expand an application to inspect owners, credential metadata, granted permissions, and review findings.

Sensitive access highlights selected high-impact API grants. A flag is a review prompt, not proof of misuse or unnecessary access. Confirm business need and usage before changing permissions.

An empty owner list means no owner was returned; unavailable means collection could not establish ownership. Vendor and system applications may legitimately have no recorded owner.

The report is a saved snapshot. Refresh Entra to collect newer data. Collection details list errors and assessment boundaries; a completed request does not imply that every endpoint succeeded.

Small arrows show count growth or decline against a complete same-tenant snapshot from seven to eight days before the latest scan. A dash means unchanged; missing history or incomplete collection yields no comparison. Arrows show quantity changes, not a security score.

## Credential expiration and action

Upcoming expirations counts secrets and certificates expiring within 90 days of the snapshot time. Expired credentials are counted separately. Refresh before making a time-sensitive decision.

Red marks expired or due within 7 days. Amber marks due within 30 days. Purple marks renewal planning within 90 days. Unknown expiration requires investigation.

Confirm the consuming service and owner. Add a replacement credential, update the service, test authentication, and only then retire the old credential. An expired credential does not by itself prove an outage.

Only credential metadata is collected, never secret values or private keys. Vendor-managed credentials outside this tenant may not be visible. The collector authentication certificate lasts one year; automated rotation is not implemented. Plan administrator-assisted renewal before it expires.

## Reporting, exports and growth

Reporting provides application inventory, ownership, secrets and certificates, granted API permissions, review findings, collection errors, and app growth. The first six reports use the latest saved snapshot.

Choose an object type and Apply filters. Download CSV exports the selected report and filters. Use the browser Print menu to print or save a PDF. Exports contain customer metadata and must be handled accordingly.

App growth accepts From and Through dates, inclusive, and app-registration or enterprise-app filters. It uses retained scan snapshots, not audit events. At least two complete inventories within the range are needed for change counts.

Net change is the difference in object counts. Added and removed compare object IDs with the previous complete inventory in the selected range. Incomplete inventories do not establish removals or a baseline. Objects created and deleted between scans can be missed. History retention limits the available date range.

Granted permission rows belong to enterprise applications to avoid double-counting the corresponding app registration. Collection errors are tenant collection results, not limited by the object-type filter.

## Scan history and statuses

Scan history shows the latest 100 retained attempts with UTC start times and results. Reload history to see updated status.

Complete means the saved scan reported no collection errors. Partial means data or endpoints were missing. Failed means no new successful snapshot was stored; the dashboard may still show an earlier snapshot. Running means collection is in progress.

Email failure is shown separately in the scan result and does not discard collected data. Check the snapshot timestamp before interpreting a dashboard after a failed scan.

## Scheduled collection

Open Settings → Scheduled refresh. Enable collection, choose daily or weekly, choose the day for weekly runs, set a time, and Save changes.

Schedules use the Windows server’s local time, whereas report/history timestamps use UTC. A missed schedule runs once when the dashboard service resumes. Scheduling should be enabled after the first successful scan.

Jobs require the server and dashboard service to run. Failed scans are not automatically retried repeatedly; inspect the error and refresh manually.

Default discovery is daily at 06:00 in the Windows server local timezone. Saved settings take precedence and are preserved during upgrades. Scheduling requires an eligible Business license and the background dashboard process running. A missed scheduled run is attempted once after the process resumes.

## Automatic report email

Open Settings → Report email and choose Graph, SMTP relay/password, or Microsoft 365 SMTP OAuth. Configure sender and recipients; SMTP modes also need host, port and TLS settings. Save before choosing Send summary now.

Microsoft 365 — Send with Graph uses HTTPS port 443 and the installed collector app certificate. In Entra, add Microsoft Graph Application permission Mail.Send and grant tenant administrator consent. This permission is broad by default: have an Exchange administrator restrict app access to the designated sender mailbox using supported Exchange application access controls. Use the sender mailbox user principal name. No SMTP host, password, SMTP AUTH setting or connector is required. Save settings, then Send test email and confirm inbox arrival. Graph accepts requests asynchronously; acceptance is not delivery. Detailed reports stay inside the app; email contains only an aggregate summary.

Before first SMTP OAuth use, an Exchange administrator must add Office 365 Exchange Online Application permission SMTP.SendAsApp to the installed app and grant admin consent, register its enterprise-application service principal in Exchange Online, and authorize only the intended sender mailbox (including SendAs where required). SMTP AUTH must be allowed for that mailbox under tenant policy. This one-time Exchange setup is outside this GUI; Microsoft documents it through Exchange Online PowerShell.

Send test email uses saved settings and works before enabling automatic delivery or collecting a report. It sends no inventory attachment. Graph or SMTP acceptance is not proof of inbox delivery; check the recipient inbox.

Save valid email settings to enable automatic summary delivery. The default is Action alerts + weekly digest. Email contains aggregate counts only, with no inventory attachment. Incomplete or failed scans withhold inventory counts; check scan history on the server.

Use STARTTLS or implicit TLS with a valid server certificate. Microsoft 365 OAuth is supported with the installed app certificate. Select Microsoft 365 SMTP OAuth (certificate), enter the authorized sender and recipients, save, and use Send test email. Blank password preserves the saved password. The saved SMTP password is protected by Windows DPAPI.

Summary emails contain operational counts. Confirm recipients before testing; the Send summary now action sends a real email.

## Logs and retention

Open Settings → Logs and disk usage to set retention days and the total log-size limit. Save changes. Clean up now applies cleanup; Download today’s collector log provides plain text.

Logs roll over daily. Old recognized logs are removed by age and disk cap. Today’s logs are not truncated; if they fill the cap, new entries pause and LOGGING-PAUSED.txt records the condition.

The log cap does not cover the database or backups. Log messages intentionally omit tokens, secrets and raw exception text.

## Database backup and restore

Open Settings → Database backups. Enable daily backups, select time and retention, and Save changes. Back up now creates and verifies a database backup.

To restore, select a saved backup and choose Restore selected backup. Confirmation is required. The application checks integrity, checksum, schema and tenant, and creates a safety backup of the current database first.

Backups remain in ProgramData\EntraIntegrationHealth\backups. Protect the disk with encryption and use your normal off-server backup system. Local backups do not protect against server loss.

Database backups do not include portable authentication credentials. DPAPI private keys are machine-bound; replacement-server recovery requires a new certificate and consent/configuration checks.

## Offline updates, update channel and rollback

For an existing installation without file upload support, extract the entire EntraHealth-Upgrade-VERSION.zip into a new folder and double-click Upgrade.cmd. Accept elevation and confirm. Leave the upgrade window open until it reports completion.

The progress window reports stages, not a time estimate. Some stages take several minutes. The launcher temporarily disables the scheduled updater and re-enables it afterward; after a power loss or forced termination, check EntraHealth-Updater in Task Scheduler.

For later updates, Settings → Software updates → Install update from file accepts EntraHealth-Offline-Update-VERSION.zip. Use the inner signed offline bundle, not the outer Upgrade ZIP.

For hosted delivery, save the publisher HTTPS latest.json URL, check for updates, then install. Action feedback appears beneath the button that initiated it. The update page shows installed and available versions, the last successful check, and a prominent new-version notice. Open What’s new to read publisher notes included in the signed release. A failed check is not confirmation that you are up to date. Automatic checking does not automatically install. No customer inventory is uploaded to the publisher.

Updates validate the pinned signing key, signature, expiry, checksum and schema, back up the database, install offline dependencies, and check dashboard startup. Go back one version rolls back software, not customer data. Reopen the Start-menu dashboard after an update.

Signed manifests expire after 90 days. Request a refreshed package if expired. Never replace the pinned signing key with a key supplied by an unverified package.

## Troubleshooting

Graph HTTP 403: check that tenant/client IDs match the app, Microsoft Graph Directory.Read.All is an Application permission, and administrator consent is granted. Refresh again for a new token. If it persists, review tenant access policies with the tenant administrator.

Windows error 32 is a sharing violation: a file is still open. Record the full error and named upgrade stage. Use the latest corrected package; do not delete the database or credential files to work around it.

Upgrade failure: record the stage, exception type and OS code from the window or ProgramData\EntraIntegrationHealth\update-status.txt. Verify free space, runtime availability, package version and signature. Do not uninstall to retry an upgrade.

No growth data: collect at least two complete scans in the selected range. A new installation has no earlier history. Empty permissions can mean no grants or incomplete collection; inspect coverage and collection errors.

Unauthorized dashboard: reopen it from the installed Start-menu shortcut. Email failure: check saved recipients, TLS settings, relay authentication and the scan result.

## Security boundaries and limitations

This is a customer-hosted preview, not a NIST certification or proof of compliance. Windows installation, restart and rollback require customer pilot validation. Installer launchers are not code-signed.

The dashboard binds to loopback. Administrative access is required for its launcher. Application tasks use LOCAL SERVICE; updates use a privileged fixed-function task. Protect local administrator access and avoid untrusted services sharing that identity.

SQLite databases and backups are not encrypted by the application; use BitLocker or equivalent storage encryption. Optional aggregate usage sharing is off by default; no inventory is uploaded. See Licensing and optional usage sharing for details.

The report does not establish sign-in activity, credential usage, directory-role assignments, Exchange/SharePoint effective access or functional integration health. Always validate business impact before remediation.

## License duration and optional usage sharing

Your subscription paid-through date is separate from the local license expiry. Business licenses are signed for up to three days and renew online every six hours while the app service is running. Use **Check for updated license** after reconnecting. A free trial lasts until its original trial end date and has no card requirement or automatic charge; reinstalling does not reset it. Free trials are tracked by the publisher licensing service, not as Stripe subscriptions.

In **Settings → License & Billing → Help improve the app**, optional usage sharing is off by default. If enabled, the app sends aggregate page-visit counts for dashboard, reporting, history, settings, and licensing, associated with your licensed tenant. Reports, inventory, usernames, credentials, and page contents are excluded. Uploads occur at most hourly while connected and the service runs. Turn sharing off to stop uploads and delete queued counts; this does not affect your license. Previously sent aggregates are retained for up to 90 days, with expiry cleanup on the next publisher overview or upload. See PUBLISHER-OPERATIONS.md for the publisher's complete data dictionary and retention details.

## Verify or correct collector tenant and application IDs

Setup validates nonempty GUIDs and verifies the tenant's Microsoft discovery endpoint before installing prerequisites or application files. Client registration, certificate and Graph permissions are verified only after uploading collector.cer and granting consent.

From an elevated PowerShell prompt, run `Check-EntraConnection.ps1` from the extracted package or installed application folder. To test proposed IDs without saving: `./Check-EntraConnection.ps1 -TenantId 'DIRECTORY-TENANT-GUID' -ClientId 'APPLICATION-CLIENT-GUID'`. Add `-Save` to save only after successful certificate authentication and Graph inventory checks. The tool pauses the dashboard for a save and restarts it afterward. Upload the existing public collector.cer to the corrected registration before testing. Never copy the private DPAPI key to Entra.

A different tenant is accepted only before any report snapshots exist. That correction clears old failed scan records and tenant-bound licensing/usage state, preserving the collector certificate. A populated installation must use a separate clean installation to avoid mixing tenant reports. Same-tenant client-ID corrections preserve reports and licenses. A config backup is kept as config.before-connection-change.json. The check verifies basic Graph inventory access, not every permission-specific collector endpoint.

## Credential calendar reminders

Expand Credential & certificate expirations and select Add to calendar (.ics) on an upcoming credential row. Import the file into Outlook or another iCalendar-compatible application. The event marks the exact UTC expiry time (displayed in your calendar's timezone), with a seven-day reminder; calendar software controls notification behavior. If already inside seven days, adjust the reminder after importing. No invitation is emailed and no attendee is added. The download includes app/object/credential identifiers and display names, never credential secret values. Import into an appropriately protected calendar. Events are static: refresh the report and update your calendar after renewal or date changes.

## Trial reuse protection

Free trial dates are stored server-side against the Microsoft-verified tenant ID. Reinstallation, another device, and deleting local licenses do not restart them. A different tenant has its own trial entitlement. Preserve the publisher database and backups: deleting an account's server-side history would remove this protection for that tenant. The trial is not a Stripe subscription.

## Microsoft 365 — Send with Graph

Version 0.2.20 adds Graph email delivery while retaining SMTP relay/password and Microsoft 365 SMTP OAuth. Existing installations keep their saved delivery mode.

1. In Entra admin center, open the app registration matching this installation's client ID. Confirm the installed app certificate's public certificate is uploaded and unexpired. Keep its private key on the app computer.
2. Under API permissions, add Microsoft Graph → Application permissions → Mail.Send, then grant administrator consent. This application permission grants broad mailbox sending access by default; have your Exchange administrator restrict the app to approved sender mailboxes using supported Exchange application access controls.
3. Open Settings → Report email and select **Microsoft 365 — Send with Graph**. Enter the sender mailbox's user principal name and approved recipient addresses. The sender must have an Exchange Online mailbox.
4. Save changes, then choose **Send test email** and confirm arrival. Enable automatic report email when ready.

Graph uses outbound HTTPS on port 443. It does not require an Exchange connector, mailbox password, or SMTP AUTH. It reuses the installation's tenant ID, client ID, and certificate. Existing SMTP settings remain available when switching back.

A successful test means Microsoft accepted the message, not that inbox delivery is guaranteed. Check mailbox access and Mail.Send authorization after a permission denial. After a timeout, check the sender mailbox before retrying: the message may already have been accepted. Automatic and manual report emails contain summaries only, with no detailed attachment.

Microsoft reference: https://learn.microsoft.com/en-us/graph/api/user-sendmail?view=graph-rest-1.0

## Graph email: access denied (HTTP 403)

If the test reaches Submitting email through Microsoft Graph over HTTPS and then reports Graph denied sending, token acquisition completed but Graph returned HTTP 403. This does not prove the app has permission to send or identify the exact mailbox restriction.

First compare the Application (client) ID on the Entra app registration Overview page with the client ID configured in the Windows installation. Use the collector registration, not the separate Render billing registration. Confirm the tenant IDs also match.

Under that registration’s API permissions, verify Microsoft Graph contains Directory.Read.All — Application — Granted and Mail.Send — Application — Granted for your tenant. Add Mail.Send through Add a permission → Microsoft Graph → Application permissions, then grant administrator consent. Mail.Send under Office 365 Exchange Online is a different API permission and does not authorize this Graph flow. Delegated Mail.Send, delegated SMTP.Send, and Exchange SMTP.SendAsApp do not substitute for Microsoft Graph application Mail.Send.

In Settings → Report email, confirm Microsoft 365 — Send with Graph is selected. Use the existing Exchange Online sender mailbox’s user principal name, not an alias or distribution list. Save changes before testing.

If consent was just granted, allow time for propagation and test again. Each test requests a token using the installed certificate. If the IDs and Graph permission are correct and the failure persists, ask the Exchange administrator to review existing application access policies or application RBAC assignments and their mailbox scope. Mention any mailbox restrictions configured during earlier SMTP OAuth setup; SMTP authorization alone does not establish Graph authorization. Do not remove restrictions merely to bypass the error.

For an existing legacy application access policy, an Exchange administrator can use Test-ApplicationAccessPolicy -Identity sender@yourdomain.com -AppId COLLECTOR-CLIENT-ID. This checks that policy only; it is not proof that all Graph authorization requirements pass. Policy changes can take longer than one hour to affect Graph even when this test allows access. For application RBAC, have the administrator inspect the app’s role assignments and resource scope.

After a successful test, confirm receipt in the destination inbox. Microsoft accepting the request does not guarantee inbox delivery. When requesting support, provide the stage, timestamp, permission API/type/status and whether configured IDs match. Never share the private certificate key, access tokens, client secrets or publisher administrator key.

Microsoft references: https://learn.microsoft.com/en-us/graph/api/user-sendmail?view=graph-rest-1.0 and https://learn.microsoft.com/en-us/exchange/permissions-exo/application-access-policies and https://learn.microsoft.com/en-us/exchange/permissions-exo/application-rbac

## Private summary emails, alerts and weekly digest

From version 0.2.22, detailed HTML inventory attachments are removed from both automatic and manual report emails. The branded email includes a plain-text alternative, scan status and UTC scan time, aggregate application and credential counts, ownerless-object and sensitive-access counts, and added/removed object counts when a previous complete same-tenant snapshot exists. No application names, tenant/client IDs, owner identities, credential identifiers, permission lists or raw diagnostic errors are included. Sender/recipient addresses remain necessary for delivery.

Open Settings → Report email. Choose Email delivery, save valid settings to enable delivery, and send a connection test. Send summary now sends an aggregate summary of the latest saved scan immediately without consuming the automatic digest schedule. Previously enabled email settings remain enabled; installations without a saved report mode use Action alerts + weekly digest. Existing discovery schedules are preserved.

Action alerts + weekly digest is recommended. A weekly digest is sent after the first complete scan in each Monday-based week using server local time, including the first eligible scan after enabling. It includes available seven-day count comparisons. It is not a separate timed email job: if no complete scan runs, no digest is produced. First configure daily discovery under Settings → Scheduled refresh.

Action alerts are sent when a credential newly appears in an expired, within-seven-days or within-thirty-days bucket, or discovery transitions to incomplete or failed. The first eligible scan may alert on existing findings. Repeated identical conditions are suppressed until they clear or change. Incomplete scans preserve the last complete credential baseline. Ownerless-object and sensitive-access totals are review indicators included in summaries; they do not trigger alerts. Changes can only be detected when discovery runs.

Other delivery choices are Action alerts only, Weekly digest only, or Summary after every scan. Weekly-only mode does not send failure alerts. A digest and credential alert due on the same complete scan are combined into one digest. Failed delivery does not consume the digest or alert state; a subsequent scan can try again. There is no immediate automatic resend loop, and acceptance does not guarantee inbox delivery.

Incomplete or failed discovery emails show status without inventory counts or changes so missing data cannot be mistaken for improvement. A failure before or during collection can trigger an alert through the normal scan launcher. A stopped server or unavailable email service cannot notify you; review scan history and infrastructure monitoring.

The Open Entra Integration Health button uses http://127.0.0.1 with the configured app port. It works only on the Windows server hosting the app. From another device, connect to that server first. If access is denied, open the Entra Integration Health Start-menu shortcut to establish an authenticated local session. No authentication token is placed in the email link; email clients may block local HTTP links.

Local email-summary-state.json retains the last discovery condition, last sent digest week and hashes of credential warning identities for duplicate suppression. No raw identifiers from this state are emailed. Deleting it resets suppression and may cause repeat alerts. Aggregate counts are still organizational information: use approved recipients.

## Support cases

Open Support from the app navigation. First connect the installation through License & Billing; trial, paid and expired linked accounts can open cases. Enter a contact email, category, subject and a description, then confirm the data-sharing checkbox and submit. A case number confirms that the case was saved.

The support service receives only the contact email, subject, description, app version and linked tenant ID. Reports, logs, certificates, API keys and inventory are not attached automatically. Do not paste secrets or private inventory into the message.

Use Your cases to read publisher replies and add information. Cases are shared with administrators using the same linked tenant. Contact emails are not independently verified; choose an approved support contact and share only information suitable for that address.

Publisher replies are visible in the app after they are saved. Email delivery is a separate publisher action and requires the support mailbox to be configured. Accepted means the provider accepted the message; it does not guarantee inbox delivery. Incoming email replies stay in the publisher support mailbox; they are not imported automatically. Reply in the app to keep the case conversation complete.

The publisher portal lists open, in-progress, waiting-on-customer, resolved and closed cases. Cases are retained until the publisher applies its documented retention and deletion policy. Ask the publisher to remove a case when appropriate.

## Guided update progress

After reviewing What’s new, select Install version. Confirm the restart to queue the update. A progress panel appears beneath the initiating button and shows the actual updater stage, elapsed time, download percentage when the server supplies a file size, and a readable update log.

Keep the browser tab open. The Windows updater normally claims the request within one minute. It backs up the database, verifies and installs the release, restarts the dashboard and checks the running version. Other stages show activity without an invented percentage.

The existing authenticated local session is preserved for an update restart using a temporary handoff file in the protected data directory, valid for up to 15 minutes. The page reconnects automatically. If the session cannot be restored, reopen the Windows Start-menu shortcut and return to Software updates.

A completed update shows the running version and an Open dashboard button. A failed update shows its failed stage and recovery result. Review View update log before using Retry update. If status is unavailable after 15 minutes, check the Windows updater and reopen the app before starting another installation. Native Windows execution must be validated on a supported server.

## Activation refresh and email defaults

After a trial, paid, online or offline license installs successfully, the entire app reloads, including the dashboard around the License & Billing page. This updates feature access and plan labels together. The reload keeps the current page selection.

In Settings → Report email, changing Send with to a Microsoft 365 option sets SMTP defaults to smtp.office365.com, port 587 and STARTTLS. Graph sends over HTTPS and hides the SMTP fields. Choosing SMTP relay with an empty server also fills these defaults; an existing custom relay address is preserved. Save changes before sending.

Before the first report, the getting-started page provides separate, spaced links for Scan history, Settings, Setup guide and Support. Product information and sales questions can be sent to support@veritasnext.com.

## Installer connection-test status

Test connection checks certificate authentication and Microsoft Graph access without saving the entered IDs. The window shows elapsed time and a scrolling list of stages. Wait for Success or Failed; activity alone does not mean the connection passed.

Test and save IDs runs the checks and applies the verified IDs only after success. It pauses and restarts the dashboard. Reopen the dashboard from the Start menu after saving. A failed test preserves the existing IDs; read the failure details below the buttons before retrying.

Authentication success is only the first stage. Both app-registration and enterprise-application Graph checks must also succeed. Check the public certificate upload and Directory.Read.All application consent if a stage fails.