nmemmertandClaude Sonnet 5.5
5c224521d3
build-container / build (push) Successful in 21m40s
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
75 lines
3.9 KiB
Markdown
75 lines
3.9 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
|
|
|
|
Add these to your `.env` (or your stack's environment settings):
|
|
|
|
```
|
|
MS_CLIENT_ID=<the Application (client) ID>
|
|
MS_CLIENT_SECRET=<the secret Value>
|
|
PUBLIC_URL=https://hub.necloud.us
|
|
```
|
|
|
|
Then redeploy the hub:
|
|
|
|
```
|
|
docker compose up -d
|
|
```
|
|
|
|
Leave `MS_CLIENT_ID` empty to switch Mail off.
|
|
|
|
## 7. Connect
|
|
|
|
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.
|