nmemmertandClaude Sonnet 5.5
2d8d4f4d82
build-container / build (push) Successful in 20m34s
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
73 lines
4.7 KiB
Markdown
73 lines
4.7 KiB
Markdown
# Setting up Outlook.com mail (Microsoft app registration)
|
|
|
|
NE Hub reads and sends your Outlook.com (personal) mail through Microsoft Graph. Microsoft requires every app that does this to be registered once. It is free and takes about five minutes. The steps follow the Entra portal; Microsoft changes the layout now and then, so a label may differ slightly.
|
|
|
|
## 1. Open the registration page
|
|
|
|
1. Go to **entra.microsoft.com** and sign in with any Microsoft account. It does not have to be the mailbox you will read.
|
|
2. If it says you need a directory or Azure subscription, accept the free "Default Directory" it offers. The free tier is enough and costs nothing.
|
|
3. In the left menu open **Entra ID -> App registrations -> New registration**.
|
|
|
|
## 2. Fill in the registration
|
|
|
|
- **Name:** `NE Hub`.
|
|
- **Supported account types:** choose **Personal Microsoft accounts only**. This matches the hub, which signs in through Microsoft's "consumers" endpoint.
|
|
- **Redirect URI:** set the platform to **Web** and enter `https://hub.necloud.us/api/mail/callback`. Use your real hub address. It must match `PUBLIC_URL` in your `.env` exactly: same `https`, same host, no trailing slash.
|
|
- Press **Register**.
|
|
|
|
## 3. Copy the client ID
|
|
|
|
On the app's **Overview** page, copy the **Application (client) ID** (a long GUID). It goes in `MS_CLIENT_ID`.
|
|
|
|
## 4. Add the mail permissions
|
|
|
|
1. Open **API permissions -> Add a permission -> Microsoft Graph -> Delegated permissions**.
|
|
2. Tick these four and press **Add permissions**:
|
|
- `Mail.ReadWrite`
|
|
- `Mail.Send`
|
|
- `User.Read`
|
|
- `offline_access`
|
|
3. You do not need "Grant admin consent". Personal accounts approve these themselves the first time they connect.
|
|
|
|
## 5. Create a client secret
|
|
|
|
1. Open **Certificates & secrets -> New client secret**.
|
|
2. Give it any name and choose the longest expiry (24 months).
|
|
3. Copy the **Value** column right away. Microsoft shows it only once. It goes in `MS_CLIENT_SECRET` (not the "Secret ID").
|
|
4. Put a reminder in your calendar for about 23 months from now. When the secret expires, Connect fails until you make a new one and update `MS_CLIENT_SECRET`.
|
|
|
|
(If you would rather not have a secret, register the redirect under the platform **Mobile and desktop applications** instead of **Web** and leave `MS_CLIENT_SECRET` empty. The hub signs in with PKCE either way.)
|
|
|
|
## 6. Give the hub the values
|
|
|
|
**In the app (easiest):** sign in as an admin, open **Settings -> Microsoft app (admin)**. It shows the exact redirect address to register (with a Copy button), and has boxes for the Application (client) ID, the client secret Value and the date the secret expires. Press **Save**; Mail switches on straight away, no restart needed. The secret is stored encrypted on the server and is never shown again. NE Hub warns you in Settings, and with a push notification if you turned reminders on, in the month before the secret expires.
|
|
|
|
**Or in the environment** (these win over anything saved in the app, and then the Settings box is read-only):
|
|
|
|
```
|
|
MS_CLIENT_ID=<the Application (client) ID>
|
|
MS_CLIENT_SECRET=<the secret Value>
|
|
PUBLIC_URL=https://hub.necloud.us
|
|
```
|
|
|
|
then redeploy with `docker compose up -d`. Leave both empty (and nothing saved in the app) to switch Mail off.
|
|
|
|
## 7. Connect
|
|
|
|
Microsoft cannot check an app registration without a real sign-in, so the first Connect is the test: it checks the ID, the secret and the redirect address, and if something is wrong it says what. After one good connection, Settings -> Microsoft app shows the date of the last successful connection.
|
|
|
|
1. Open the hub, go to **Mail**, and press **Connect Outlook.com**.
|
|
2. Sign in with your Outlook.com account on Microsoft's page and approve the permissions.
|
|
3. You land back on the Mail tab with your inbox showing.
|
|
|
|
Each person who has the Mail tab connects their own mailbox. The hub keeps only the sign-in token, encrypted, in that person's own folder.
|
|
|
|
## If something goes wrong
|
|
|
|
- **"redirect URI doesn't match" (AADSTS50011):** the address in step 2 differs from what the hub sends. Compare `PUBLIC_URL` and the registered URI character by character.
|
|
- **"invalid client secret" or `invalid_client`:** you pasted the Secret ID instead of the Value, or the secret has expired. Make a new one.
|
|
- **"app not found in directory/consumers":** the account type was not set to personal accounts only. Check it under **Authentication -> Supported account types**.
|
|
- **The Mail tab says "Mail is not set up on this server":** `MS_CLIENT_ID` is empty or the container was not restarted after you added it.
|
|
- **Connect works, then later says Microsoft signed you out:** the sign-in token was revoked, for example after a password change. Press Connect again.
|
|
- **Installed iPhone/iPad app:** Microsoft's page may open in Safari. Sign in there, then reopen the app.
|