# Microsoft Sign-In Setup (Entra ID / Azure AD)

**Time: ~10 minutes. Cost: free.** Covers both personal Microsoft accounts (Outlook.com, Hotmail, Live) and work/school accounts. Given your day job, this one should feel like home.

---

## Step 1 — Register the application

1. Go to **https://entra.microsoft.com** (or portal.azure.com → Microsoft Entra ID)
2. Left nav → **App registrations** → **+ New registration**
3. Fill in:
   - **Name:** `Paddlers Cove Community Site`
   - **Supported account types:** **Accounts in any organizational directory (Any Entra ID tenant) and personal Microsoft accounts**

     > This is the critical choice. Pick anything narrower and your neighbors with Hotmail addresses get a hard error. It corresponds to `MS_TENANT=common`.
   - **Redirect URI:** platform **Web**, URI:
     ```
     https://paddlerscove.org/auth/microsoft/callback
     ```
4. **Register**

---

## Step 2 — Copy the Application (client) ID

On the **Overview** blade, copy **Application (client) ID** into `.env`:

```ini
MS_CLIENT_ID=00000000-1111-2222-3333-444444444444
MS_TENANT=common
```

---

## Step 3 — Create a client secret

1. Left nav → **Certificates & secrets** → **Client secrets** tab → **+ New client secret**
2. Description: `Paddlers Cove web secret`
3. Expires: **24 months** (the max). Put a calendar reminder at 22 months — an expired secret takes the sign-in button down with zero warning.
4. **Add**
5. **Copy the Value column immediately.** Not the Secret ID — the *Value*. It is displayed exactly once and is unrecoverable afterward.

```ini
MS_CLIENT_SECRET=abc8Q~xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

---

## Step 4 — Configure API permissions

1. Left nav → **API permissions**
2. You should already see **Microsoft Graph → User.Read** (delegated). That's sufficient.
3. If missing: **+ Add a permission** → **Microsoft Graph** → **Delegated permissions** → check `openid`, `email`, `profile`, `User.Read` → **Add permissions**
4. No admin consent needed — these are all user-consentable.

---

## Step 5 — Configure token claims (recommended)

By default the ID token may not include an email claim for some account types.

1. Left nav → **Token configuration** → **+ Add optional claim**
2. Token type: **ID** → check **email** and **upn** → **Add**
3. If prompted to turn on the Microsoft Graph profile permission, say **yes**.

The app already falls back through `email` → `upn` → `preferred_username`, but adding the claim makes it reliable.

---

## Step 6 — Branding (optional but nice)

**Branding & properties** → upload the logo, set the home page URL, add publisher domain. Makes the consent screen look legitimate instead of sketchy.

---

## Step 7 — Test

1. `https://paddlerscove.org/login` → **Continue with Microsoft**
2. Sign in with a personal Microsoft account to confirm `common` is working
3. You should land on `/register/address`

---

## Troubleshooting

| Error | Cause | Fix |
|---|---|---|
| `AADSTS50011` redirect URI mismatch | URI not registered | Add the exact callback URL under Authentication → Web |
| `AADSTS700016` app not found in tenant | Account types set too narrow | Change to "any directory + personal accounts" |
| `AADSTS7000215` invalid client secret | Copied the Secret ID instead of Value | Create a new secret, copy the Value |
| Works for work accounts, fails for Hotmail | `MS_TENANT` set to a tenant GUID | Set `MS_TENANT=common` |