Microsoft Graph App Registration for Hotmail (Device Code Flow)

This document explains how to create and configure a Microsoft application so that Arpia Workshop objects can pull emails and calendar events from a Hotmail/Outlook.com account using the Microsoft Graph API and Device Code OAuth flow.

🛡️

Data governance note: This pattern pulls a personal mailbox into your workarea's data repository. Once synced, that data inherits the repository's access profile — everyone with access to the repository can read it. Only connect accounts whose contents are appropriate for the workarea, and confirm this fits your organization's data-classification rules before setting it up.

1️⃣ Create an App Registration

1. Go to Entra admin center → App registrations → New registration.
2. Name: e.g., Arpia Hotmail Pull.
3. Supported account types:
   • Choose "Accounts in any organizational directory and personal Microsoft accounts" (recommended) OR "Personal Microsoft accounts only."
   • This is required for @hotmail.com / @outlook.com accounts.
4. Redirect URI: leave blank (Device Code does not need one).
5. Click Register.
6. Copy the Application (client) ID. You'll paste this into Arpia Workshop config.

✅ At this point you have a registered app.

Note: The Client ID is an identifier, not a secret — it's safe to store in config.html/config.json. The sensitive material in this setup is the token cache created later (see Security & Token Handling below).

2️⃣ Enable Public Client Flow

1. In your new app, go to Authentication → Advanced settings.
2. Set Allow public client flows to Yes.
   • This is required for Device Code / native apps (which cannot store a client secret).
3. Save changes.

3️⃣ Configure API Permissions

1. Go to API permissions → Add a permission → Microsoft Graph → Delegated permissions.
2. Add the following delegated permissions:
   • Mail.Read
   • Calendars.Read
3. No client secret or admin consent is needed for personal accounts. You will grant consent during sign-in.

MSAL also requests openid, profile, and offline_access automatically. These provide identity info and refresh tokens so the session can persist.

Least privilege: Keep the scopes read-only. Do not request Mail.ReadWrite, Calendars.ReadWrite, or Mail.Send unless the object genuinely needs to modify or send — every added scope widens what a leaked token can do.

4️⃣ Use in Arpia Workshop

In your Arpia Workshop object (config.html form):

• Client ID → paste the Application (client) ID you copied.
• Authority → https://login.microsoftonline.com/consumers (best for Hotmail accounts).
• Scopes → keep as: openid profile offline_access Mail.Read Calendars.Read.

📄

New to configurable objects? See the Configurable Objects Overview and the step-by-step configurable object guide this page belongs to.

5️⃣ Running the Flow

1. Run your Arpia object.
2. On first run, you'll see a Device Code prompt:
   • A Microsoft URL
   • An 8-character code
3. Open the URL in a browser, enter the code, and approve the requested permissions.
4. The job will continue and fetch emails + calendar data.

⏳

Expect periodic re-authentication. Refresh tokens for personal Microsoft accounts expire on a sliding window (roughly 90 days of inactivity, and they can be invalidated earlier by password changes or Microsoft security events). When that happens, the object will show the Device Code prompt again on its next run. This is normal — repeat the sign-in, not a debugging session.

6️⃣ Security & Token Handling

Device Code with offline_access means a refresh token is persisted in the object's MSAL token cache after the first sign-in. Treat it accordingly:

• The token cache is a credential. It grants standing read access to the connected mailbox and calendar. "No client secret required" does not mean the object holds no secrets.
• Anyone with code access to the object can read the cache. Restrict who can open the object's files to the same set of people you'd trust with the mailbox itself. Use Security Profiles to scope access.
• Don't copy the cache. Never commit the token cache file to shared/global files, clone it into other objects, or include it when duplicating the project.
• One account, one purpose. Prefer a dedicated mailbox for integrations over a person's primary account — it shrinks the blast radius and survives staff changes.

7️⃣ Revoking Access (Off-boarding)

When the integration is decommissioned, the connected person leaves, or you suspect the token cache was exposed:

1. Revoke consent for the app on the connected account: account.live.com/consent/Manage (personal accounts) — remove Arpia Hotmail Pull.
2. Delete the token cache file from the workshop object.
3. If the app registration itself is no longer needed, delete it in the Entra admin center.

Revoking consent invalidates the refresh token; deleting the cache removes the local copy. Do both.

8️⃣ Troubleshooting

• invalid_client / public client not allowed → Ensure Allow public client flows = Yes.
• Consent screen loops → Ensure account type = Any directory + personal or Personal Microsoft accounts only.
• Token works once then fails → Ensure you requested offline_access scope so refresh tokens are issued.
• Device Code prompt reappears after weeks of working fine → The refresh token expired or was invalidated (see Running the Flow). Sign in again — no configuration change needed.

✅ Summary

• No client secret required — but the token cache is a credential; protect and revoke it like one.
• Only need App ID + read-only delegated scopes.
• Works with Device Code login; expect periodic re-authentication.
• Supports Hotmail/Outlook personal accounts directly.
• Pulled mail and calendar data inherits the repository's access profile — classify accordingly.

This configuration allows your Arpia Workshop object to authenticate securely and sync emails and calendar events from Microsoft Graph.