Microsoft profile photos

Who this is for: Tenant owner, Admin
What you'll achieve: Show staff Entra / Microsoft 365 profile photos instead of initials, after portal access is set up

Requires role

integrations.outlook.configure

Included unless the operator turns it off

Admin → School → Microsoft profile photos is available for new and existing schools. Photos do not appear until your IT team enters Entra app details, runs a health check, and enables the integration. Your platform operator can turn the entra_profile_photos flag off if the school should not see this page.

What it does

SchoolRota reads each staff member's Microsoft profile photo through Microsoft Graph and shows it on:

• The timetable person cards
• My schedule
• The staff directory

Initials stay in place when:

• The integration is off
• The person has no portal access yet (invite, SCIM, or SSO)
• Their directory email does not match an Entra user
• Entra has no photo for that account

Photos are cached in SchoolRota. They are not loaded live in the browser, and Graph tokens never reach the client.

Before you begin

1. Confirm Admin → School → Microsoft profile photos is visible. If it is hidden, ask your platform operator to enable entra_profile_photos.
2. Staff emails in the SchoolRota directory should match Entra user principal names (the same matching Outlook calendar uses).
3. Give those staff portal access: invite them, or provision them with SCIM / SSO. Photos are fetched only for people who already have an active linked login.
4. Set INTEGRATION_ENCRYPTION_KEY in your deployment environment (see Deployment).

Register the Entra app

You can reuse the Outlook calendar app, or create a photos-only app.

Option A: Reuse the Outlook calendar app

1. In Microsoft Entra admin center, open the SchoolRota Outlook app registration.
2. API permissions → Add a permission → Microsoft Graph → Application permissions → User.Read.All.
3. Grant admin consent.
4. In SchoolRota, open Microsoft profile photos and choose Use Outlook app details.

Option B: Create a photos-only app

1. Microsoft Entra admin center → Identity → Applications → App registrations → New registration.
2. Name: SchoolRota profile photos. Accounts in this organisational directory only.
3. Certificates & secrets → New client secret. Copy the secret value once.
4. API permissions → Add a permission → Microsoft Graph → Application permissions:

Permission	Why
User.Read.All	Look up staff by email and read /users/{id}/photo

5. Grant admin consent.
6. Copy Directory (tenant) ID and Application (client) ID from the app Overview page.

Restrict the app to your school tenant. A client secret is required.

Configure in Admin

1. Open Admin in the sidebar, then School, then Microsoft profile photos.
2. Enter Microsoft tenant ID, application client ID, and client secret. Or copy them from Outlook if that integration is already saved.
3. Enter a health-check mailbox in the same Microsoft tenant.
4. Save configuration, then Run health check. A missing photo on that mailbox is fine; the check only needs to find the user.
5. Enable photos. SchoolRota fetches photos for staff who have portal access and a matching email.
6. Use Refresh photos after new staff get access, or wait for the daily refresh.

Staff without photos

Situation	What you see
No portal user linked to the person	Initials. Invite or provision them first
Email missing or not an Entra UPN	Initials
Entra user has no photo	Initials
Photo later added in Microsoft 365	Appears after Refresh photos or the daily job

Disconnect

Disconnect turns photos off, clears the saved client secret, and deletes cached images. Initials return immediately.

Privacy

Cached photos are only served to signed-in users in the same school. They are not public URLs. Disconnecting removes the cache.

Troubleshooting

Symptom	Check
Integration hidden	Operator flag entra_profile_photos off
Health check fails	Entra app User.Read.All, admin consent, correct tenant ID, health-check mailbox in this tenant
Photos stay as initials	Person has portal access, directory email matches Entra UPN, and the integration is enabled
One person missing	Last error on the Staff table: usually a renamed mailbox or missing Graph permission
Outlook already works, photos fail	Add User.Read.All to that app and re-consent, then run the health check again

See also

• Microsoft Entra ID pilot runbook
• Outlook calendar
• Admin users
• Deployment