Setting Up O365 Legacy Connector with App-Only Authentication

Applies to: LiveTiles Directory Windows Agent v4.2.54 and later

Background

Microsoft has retired legacy authentication (username + password) for SharePoint Online as part of their broader initiative to deprecate Basic Auth and older token-based protocols. Starting with agent version 4.2.54, the O365 Legacy Connector supports App-Only authentication using an Azure Entra ID App Registration and a certificate — no user credentials required.

This guide walks you through the Azure/M365 side of the setup. Once complete, hand the four values in the summary table to your LiveTiles Directory administrator to enter into SPOConnectorSettings.json.

Prerequisites

• Global Administrator or Application Administrator role in Microsoft Entra ID
• Access to the SharePoint Admin Center
• PowerShell 5.1+ (for certificate generation)

Step 1 — Create an Azure Entra ID App Registration

1. Go to https://entra.microsoft.com → App registrations → New registration

2. Fill in:

   Field	Value
   Name	LiveTiles Directory O365Legacy (or any descriptive name)
   Supported account types	Accounts in this organizational directory only (Single tenant)
   Redirect URI	Leave blank

3. Click Register.

4. On the overview page, note down:

   • Application (client) ID — this is your ClientId
   • Directory (tenant) ID — this is your TenantId

Step 2 — Create and Upload a Certificate

The connector authenticates using a certificate (no client secret). Generate a self-signed certificate and upload the public key to Entra ID.

Generate the certificate (run on the machine where the agent will be installed)

# Generate a self-signed certificate valid for 3 years
$cert = New-SelfSignedCertificate `
    -Subject "CN=LiveTilesO365Legacy" `
    -CertStoreLocation "cert:\LocalMachine\My" `
    -KeyExportPolicy Exportable `
    -KeySpec Signature `
    -KeyLength 2048 `
    -NotAfter (Get-Date).AddYears(3)

# Export the public key (.cer) — upload this to Entra ID
Export-Certificate `
    -Cert $cert `
    -FilePath "C:\Certs\LiveTilesO365Legacy.cer"

# Export the private key (.pfx) — this stays on the agent machine only
$password = Read-Host -AsSecureString "Enter PFX password"
Export-PfxCertificate `
    -Cert $cert `
    -FilePath "C:\Certs\LiveTilesO365Legacy.pfx" `
    -Password $password

Security note: Keep the .pfx file and its password on the agent machine only. Never share the private key. The .cer file is public and safe to upload.

Upload the certificate to Entra ID

1. In your App Registration → Certificates & secrets → Certificates tab
2. Click Upload certificate
3. Select the LiveTilesO365Legacy.cer file
4. Click Add

Step 3 — Grant API Permissions

The connector needs two permissions depending on what it writes:

SharePoint Online (profile attributes)

1. In the App Registration → API permissions → Add a permission
2. Select SharePoint → Application permissions
3. Add: Sites.FullControl.All

Exchange Online (profile photo)

1. Add a permission → Microsoft Graph → Application permissions
2. Add: User.ReadWrite.All

Why User.ReadWrite.All and not a narrower scope?
Writing the Exchange Online mailbox photo requires this permission. There is no more narrowly scoped application permission available for this operation.

After adding both permissions:

4. Click Grant admin consent for <your tenant>
5. Confirm the status shows a green checkmark for both permissions

Step 4 — Provide Values to Your LiveTiles Directory Admin

Collect and securely share the following four items:

These values go into SPOConnectorSettings.json on the Windows agent machine, under SpoConfig.AuthMode: "AppOnly".

Step 5 — Update SPOConnectorSettings.json

SPOConnectorSettings.json is located in the agent's settings directory on the Windows agent machine (typically %PROGRAMDATA%\Hyperfish\ or the path shown in the agent configuration UI).

Open the file in a text editor as Administrator and apply the changes below.

Required changes

1. Set AuthMode to "AppOnly" inside SpoConfig

"SpoConfig": {
  "AuthMode": "AppOnly",
  ...
}

2. Add ClientId, TenantId, CertificatePath, and CertificatePassword at the top level

{
  "TenantName": "<your-tenant>",
  "ClientId": "<Application (client) ID from Entra ID>",
  "TenantId": "<Directory (tenant) ID from Entra ID>",
  "CertificatePath": "C:\\Certs\\LiveTilesO365Legacy.pfx",
  "CertificatePassword": "<your PFX password in plain text — the agent will encrypt it on first load>",
  ...
}

Note on CertificatePassword: Enter the plain-text password the first time. On startup the agent will automatically encrypt it in-place using DPAPI. After that, the field will contain an encrypted value — do not modify it.

Complete example

Below is a minimal but complete SPOConnectorSettings.json for App-Only mode. The Attributes array can be left at its default (the agent auto-populates it if missing).

{
  "TenantName": "contoso",
  "ClientId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "TenantId": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
  "CertificatePath": "C:\\Certs\\LiveTilesO365Legacy.pfx",
  "CertificatePassword": "YourPfxPassword",
  "ExoConfig": {
    "PhotoUpload": true,
    "ServiceUri": "https://outlook.office365.com/EWS/Exchange.asmx"
  },
  "SpoConfig": {
    "PhotoUpload": true,
    "AuthMode": "AppOnly",
    "AuthTokens": [],
    "TenantName": "contoso",
    "MySiteHostPhotoLocationPath": "/User Photos/Profile Pictures"
  }
}

Replace contoso with your actual SharePoint tenant name (the part before .sharepoint.com).

Migrating from an existing settings file

If you already have a SPOConnectorSettings.json from a previous installation (Standard or FedAuth mode), make only these targeted edits — do not replace the entire file, as it may contain a customized Attributes list:

AdminUserName / AdminPassword are no longer used in AppOnly mode and can safely be left in the file — they will simply be ignored.

Restart the agent

After saving the file, restart the LiveTiles Directory Windows Agent service:

Restart-Service -Name "Hyperfish*" -Force

Or via Services (services.msc) → find Hyperfish → Restart.

Check the agent log (typically %PROGRAMDATA%\Hyperfish\logs\) for a line like:

INFO  [O365Legacy] LoadSettings: parsed OK. AuthMode=AppOnly, TenantName=contoso

If you see an error instead, see the Troubleshooting section below.

Troubleshooting

Known Limitations

User-Editable SharePoint Profile Fields Cannot Be Written

SharePoint Online enforces a platform-level restriction: user-editable profile properties cannot be modified via App-Only (application) permissions, regardless of what API permissions are granted. This is by Microsoft design — these fields are reserved for the user to fill in themselves.

The following 9 fields are silently skipped when AuthMode is AppOnly. The agent will log a warning for each:

Reference: SharePoint user profile properties — properties marked "User can edit" in the SharePoint Admin Center cannot be overridden by application-level API calls.

Workaround: Use the O365 Connector for These Fields

For the 9 blocked fields above, use the O365 Connector (non-legacy) in parallel. The O365 Connector authenticates as a delegated user (service account) and can write user-editable properties.

Recommended split configuration:

Profile Photo

Photo upload to SharePoint Online and Exchange Online is fully supported in App-Only mode:

• SPO photo — written to the MySite photo library via CSOM (PictureURL). ✅ Works in App-Only mode.
• EXO photo — written via Exchange Web Services (EWS). ✅ Works in App-Only mode.

Upcoming: Microsoft will retire EWS for Exchange Online on April 1, 2027 (disabled by default from October 1, 2026). A future agent release will migrate EXO photo upload to Microsoft Graph API before that deadline.

Supported SharePoint Profile Fields (App-Only Mode)

The following fields work fully in App-Only mode:

Frequently Asked Questions

Q: Can I use a certificate from a commercial CA instead of self-signed?
A: Yes. Any certificate with an exportable private key works. Upload only the .cer (public key) to Entra ID.

Q: How long does the certificate last?
A: The example above generates a 3-year certificate. Set a reminder to rotate it before expiry — an expired certificate will cause all profile sync to fail with an authentication error.

Q: Do I need a dedicated service account?
A: No. App-Only authentication runs as the application identity itself, not as any user. No service account or licensed user is required for the O365 Legacy Connector.

Q: The O365 Connector (non-legacy) requires a service account. Is that still needed?
A: Only if you want to sync the 9 user-editable fields listed above. If those fields are not in scope for your deployment, the O365 Legacy Connector alone is sufficient.

Q: Where is SPOConnectorSettings.json located?
A: On the Windows agent machine, in the agent's settings directory (typically %PROGRAMDATA%\Hyperfish\ or the path configured during installation).