Context7 Platform -- Up-to-date docs for AI agents
CTX7-1567: Add Microsoft Entra SSO setup guide for on-premise (#2496)
Fahreddin Özcan795d5da720e1
diff --git a/docs/docs.json b/docs/docs.jsonindex cee312f4..3b6bf223 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -58,6 +58,12 @@"group": "On-Premise","pages": ["enterprise/on-premise",+ {+ "group": "Security",+ "pages": [+ "enterprise/security/entra-sso"+ ]+ },{"group": "Deployment","pages": [diff --git a/docs/enterprise/security/entra-sso.mdx b/docs/enterprise/security/entra-sso.mdxnew file mode 100644index 00000000..4bac6cda--- /dev/null+++ b/docs/enterprise/security/entra-sso.mdx@@ -0,0 +1,239 @@+---+title: "Microsoft Entra ID (SSO)"+sidebarTitle: "Entra SSO"+description: "Let your workspace sign in with Microsoft Entra ID instead of shared passwords."+---++Context7 On-Premise supports single sign-on with Microsoft Entra ID (formerly Azure AD). Once configured, anyone in your Entra tenant who is assigned one of the Context7 app roles can sign in to the dashboard with their work account, and Context7 creates a matching user record automatically on their first login.++This guide walks through the full setup end-to-end: registering an application in Microsoft Entra, wiring it into Context7, and verifying a user can sign in. Plan for about 10 to 15 minutes for the Entra side and a minute or two on the Context7 side.++## Before you start++You'll need:++- An **Entra admin** (or someone who can register applications in your tenant).+- A running Context7 On-Premise instance that you can reach in your browser.+- The Context7 admin password. This is the same account you use to open **Workspace Settings** today. On a fresh install it is `admin` / `admin` until you change it.++<Note>+Entra SSO is an **addition** to password login, not a replacement. The seeded admin account keeps working even after you turn on SSO, so you never get locked out if the Entra app goes sideways.+</Note>++## Part 1: Register the application in Microsoft Entra++### Step 1: Create a new app registration++In the [Azure portal](https://portal.azure.com), open **Microsoft Entra ID** from the left sidebar. Expand **Manage** and click **App registrations**, then **+ New registration**.++Fill in the form:++- **Name**: `Context7` (anything memorable, your users won't see it)+- **Supported account types**: *Accounts in this organizational directory only*+- **Redirect URI**: pick **Web** from the dropdown and enter `https://<your-context7-host>/api/auth/entra/callback`. For a local test deployment that's usually `http://localhost:3000/api/auth/entra/callback`.++Click **Register**.++<Frame>+ +</Frame>++<Warning>+The redirect URI has to match *exactly* what Context7 sends later: same scheme (`http` vs `https`), same host, same port, same path. Microsoft compares byte-for-byte.+</Warning>++### Step 2: Copy the Application (client) ID and Directory (tenant) ID++After registering, you land on the app's Overview page. Two values matter here:++- **Application (client) ID**+- **Directory (tenant) ID**++Copy both somewhere temporary. You'll paste them into Context7 later.++<Frame>+ +</Frame>++<Note>+These aren't secrets. The client ID is public information that's sent in every sign-in request; the tenant ID identifies your Entra directory. It's still good hygiene to treat them like configuration values rather than pasting them into public places.+</Note>++### Step 3: Create a client secret++From the app's left sidebar, open **Certificates & secrets**, stay on the **Client secrets** tab, then click **+ New client secret**.++Give it a description (for example, `Context7 on-prem`), pick an expiry (180 days or 12 months are common), and click **Add**.++<Frame>+ +</Frame>++<Warning>+The **Value** column is only shown once, right after you create the secret. Copy it immediately. If you navigate away before copying, you'll need to create a new secret and start over.+</Warning>++Copy the **Value**. This is what Context7 will use to authenticate itself when talking to Microsoft. Put it next to the client and tenant IDs you copied earlier.++### Step 4: Define the two app roles++Context7 maps Entra app roles to its own admin/member roles. You'll create one of each in the Entra app.++From the left sidebar, click **App roles**, then **+ Create app role**. Fill in the first role:++- **Display name**: `Context7 Admin`+- **Allowed member types**: *Users/Groups*+- **Value**: `Context7.Admin`+- **Description**: anything descriptive, like "Full admin access to the Context7 workspace"+- Leave *Do you want to enable this app role?* checked.++Click **Apply**.++Repeat for the member role:++- **Display name**: `Context7 Member`+- **Allowed member types**: *Users/Groups*+- **Value**: `Context7.Member`+- **Description**: "Standard member access"++<Frame>+ +</Frame>++<Note>+The **Value** column is what ends up in the sign-in token's `roles` claim. Context7 defaults to looking for `Context7.Admin` and `Context7.Member`, but if your organization has a naming convention (for example, `CTX7_ADMIN`), you can use those values instead. Just remember what you chose so you can enter the same strings in Context7 later.+</Note>++### Step 5: Require assignment and assign users++By default, any user in your tenant can attempt to sign in to an Entra-registered app. You almost certainly want to restrict that to a known group of people.++Go back to **Microsoft Entra ID → Enterprise applications** (a *different* section from App registrations, but the same app viewed differently). Find and click your **Context7** app, open **Properties**, set **Assignment required?** to **Yes**, and **Save**.++<Frame>+ +</Frame>++Now open **Users and groups** on the same app and click **+ Add user/group**. For each person you want to grant access:++1. Pick the user (or a group) under **Users**.+2. Pick a role: **Context7 Admin** for workspace administrators, **Context7 Member** for everyone else.+3. Click **Assign**.++<Frame>+ +</Frame>++At a minimum, assign yourself the **Context7 Admin** role so you can test the flow end-to-end. If you're rolling SSO out to a team, assign a second person as a **Context7 Member** for a realistic member-side sanity check.++## Part 2: Configure Context7++### Step 1: Open the Entra SSO card++Sign in to your Context7 dashboard with the password admin account. Open **Workspace Settings**, and under **Authentication** you'll find a card titled **Microsoft Entra SSO**.++<Frame>+ +</Frame>++### Step 2: Fill in the credentials++Paste the three values you copied from Azure into the form:++- **Tenant ID** → the Directory (tenant) ID from the Azure Overview page+- **Client ID** → the Application (client) ID from the same page+- **Client Secret** → the secret *Value* from the Certificates & secrets page++If your organization uses different role names from the defaults, update **Admin role value** and **Member role value** to match the strings you entered as **Value** when creating the app roles in Azure.++<Tip>+The **Callback URL** shown at the bottom of the card is exactly what Context7 will send to Microsoft during sign-in. If it doesn't match the redirect URI you registered in Step 1 of Part 1, go back to Azure → App registrations → Context7 → Authentication and fix it there. The copy button next to the URL makes it easy to paste into the Azure form verbatim.+</Tip>++### Step 3: Test the connection++Before turning SSO on for your users, click **Test connection**. Context7 will make a server-to-server request to Microsoft using the credentials you entered. You'll see one of three results:++- **Green banner**: credentials are valid. You're ready to flip the toggle on.+- **"Tenant ID is invalid"**: the Tenant ID doesn't match an Entra directory. Double-check you haven't pasted the Client ID into the Tenant field (an easy mistake, since both are GUIDs).+- **"Client ID was not found in this tenant"** or **"Client secret is invalid"**: recheck the values against the Azure Overview and Certificates & secrets pages. If the secret expired, generate a new one in Azure and paste the new value.++### Step 4: Enable SSO++Once the test passes, click the toggle at the top-right of the card, then **Save Microsoft Entra Settings** at the bottom. The status indicator should read **Configured · Sign-in button visible on /login**.++<Frame>+ +</Frame>++## Part 3: Sign in++Open `/login` in a new browser tab. Incognito is handy here because it guarantees you aren't reusing your existing admin session. You should see a **Continue with Microsoft Entra ID** button above the username/password form.++<Frame>+ +</Frame>++Click it. Microsoft handles the authentication. You may need to pick an account, consent to the app on first sign-in, or complete MFA depending on your tenant's policies. On success you're bounced back to Context7, a session cookie is set, and you're signed in.++The first time each person signs in, Context7 creates a user record with the display name, email, and role sourced from their Entra account. On subsequent sign-ins, the existing record is updated with any changes to those fields (for example, if you reassign them from Member to Admin in Entra, the promotion takes effect on their next sign-in).++## Managing roles after setup++Role assignments live entirely in Entra. To change someone's access in Context7:++- **Promote a member to admin**: in Entra, go to Enterprise applications → Context7 → Users and groups, remove their Member role, add the Admin role, and ask them to sign out and back in.+- **Revoke access**: remove the user from Users and groups in Entra. Existing browser sessions remain valid until they expire or sign out. If you need to cut them off immediately, restart Context7 (in-memory sessions are cleared on restart) or have an admin explicitly delete their user row from the workspace.+- **Audit who signed in recently**: **Workspace Settings → Users** shows every Context7 user with their auth provider and last-login timestamp.++<Frame>+ +</Frame>++## Troubleshooting++### `AADSTS50011: redirect URI mismatch`++The redirect URI Context7 sent doesn't match any redirect URI registered on the Azure app. Open the app in Azure → **Authentication** and compare the list against the **Callback URL** shown on the Context7 SSO card. Check especially:++- `http://` vs `https://` must match exactly.+- Port number: if you're running Context7 on a non-standard port, the Entra registration needs the same port.+- Path: must be `/api/auth/entra/callback` with no trailing characters.++If you're running behind a reverse proxy, make sure it forwards the `Host` header unchanged; otherwise Context7 will build a callback URL for the internal host, not the public one your users see.++### "This Microsoft Entra account is not assigned a supported Context7 app role"++The user completed Microsoft sign-in but doesn't have either the Admin or Member app role assigned. Open Enterprise applications → Context7 → Users and groups, and verify they're listed with a role. If they are, confirm the role **Value** in the app registration matches the **Admin role value** / **Member role value** you entered in Context7 (they're case-sensitive).++### "Microsoft sign-in session expired"++This means the short-lived cookie Context7 uses to track the in-flight sign-in request was dropped or didn't come back. Most common causes:++- The user started sign-in on one host (for example `localhost:3000`) and came back on a different one (`localhost:5173`). Stick to one host for the whole flow.+- A browser extension or strict privacy setting is blocking cookies.++Have them retry in a clean browser window.++### The Entra button doesn't appear on `/login`++The card's status indicator tells you why:++- **Not configured**: tenant ID, client ID, or client secret is missing. Fill them in and save.+- **Configured · Toggle on to show the sign-in button**: credentials are saved but the feature is off. Flip the toggle at the top of the card.++### Client secret expired++Entra rejects the test with `"Client secret has expired"` once the secret passes its expiry date. In Azure → Certificates & secrets, create a new secret and paste the new **Value** into the Context7 card. Then click **Test connection** to verify, and **Save**.++## What this does *not* cover++A few things that are out of scope for SSO itself but often come up when rolling it out:++- **Personal MCP API keys**. Once a user signs in via Entra, they can create their own MCP API keys from **Personal Settings → API Keys**. Those are separate from SSO and covered in the main On-Premise guide.+- **Group-based role mapping**. Context7 reads app roles, not group membership. If your team assigns access via Entra security groups, add the group to Users and groups with one of the two Context7 roles.+- **SCIM provisioning**. Users are created lazily on first sign-in. There's no background sync pulling the whole directory.++For help with Entra-side policies, conditional access, or MFA, work with your Entra admin. Those are tenant-wide concerns and Context7 respects whatever Microsoft returns at the end of the sign-in.++If you run into something not covered above, contact [[email protected]](mailto:[email protected]) with the **Request Id** from any Microsoft error page and a screenshot of the Context7 SSO card's status indicator.diff --git a/docs/images/enterprise/entra-sso/01-register-app.png b/docs/images/enterprise/entra-sso/01-register-app.pngnew file mode 100644index 00000000..20d21484Binary files /dev/null and b/docs/images/enterprise/entra-sso/01-register-app.png differdiff --git a/docs/images/enterprise/entra-sso/02-app-overview.png b/docs/images/enterprise/entra-sso/02-app-overview.pngnew file mode 100644index 00000000..99205a83Binary files /dev/null and b/docs/images/enterprise/entra-sso/02-app-overview.png differdiff --git a/docs/images/enterprise/entra-sso/03-client-secret.png b/docs/images/enterprise/entra-sso/03-client-secret.pngnew file mode 100644index 00000000..780fe6ddBinary files /dev/null and b/docs/images/enterprise/entra-sso/03-client-secret.png differdiff --git a/docs/images/enterprise/entra-sso/04-app-roles.png b/docs/images/enterprise/entra-sso/04-app-roles.pngnew file mode 100644index 00000000..8667183cBinary files /dev/null and b/docs/images/enterprise/entra-sso/04-app-roles.png differdiff --git a/docs/images/enterprise/entra-sso/05-assignment-required.png b/docs/images/enterprise/entra-sso/05-assignment-required.pngnew file mode 100644index 00000000..a937f7abBinary files /dev/null and b/docs/images/enterprise/entra-sso/05-assignment-required.png differdiff --git a/docs/images/enterprise/entra-sso/06-assign-user-role.png b/docs/images/enterprise/entra-sso/06-assign-user-role.pngnew file mode 100644index 00000000..f929ff26Binary files /dev/null and b/docs/images/enterprise/entra-sso/06-assign-user-role.png differdiff --git a/docs/images/enterprise/entra-sso/07-context7-settings-card.png b/docs/images/enterprise/entra-sso/07-context7-settings-card.pngnew file mode 100644index 00000000..f3d5880fBinary files /dev/null and b/docs/images/enterprise/entra-sso/07-context7-settings-card.png differdiff --git a/docs/images/enterprise/entra-sso/08-filled-credentials.png b/docs/images/enterprise/entra-sso/08-filled-credentials.pngnew file mode 100644index 00000000..b7167f36Binary files /dev/null and b/docs/images/enterprise/entra-sso/08-filled-credentials.png differdiff --git a/docs/images/enterprise/entra-sso/10-login-page.png b/docs/images/enterprise/entra-sso/10-login-page.pngnew file mode 100644index 00000000..a5b35284Binary files /dev/null and b/docs/images/enterprise/entra-sso/10-login-page.png differdiff --git a/docs/images/enterprise/entra-sso/11-users-tab.png b/docs/images/enterprise/entra-sso/11-users-tab.pngnew file mode 100644index 00000000..2a4066edBinary files /dev/null and b/docs/images/enterprise/entra-sso/11-users-tab.png differdiff --git a/docs/images/enterprise/entra-sso/README.md b/docs/images/enterprise/entra-sso/README.mdnew file mode 100644index 00000000..f9f28e2e--- /dev/null+++ b/docs/images/enterprise/entra-sso/README.md@@ -0,0 +1,188 @@+# Entra SSO screenshots++Checklist and capture instructions for the 11 screenshots referenced in+`docs/enterprise/security/entra-sso.mdx`. Drop the finished PNGs into this+folder using the exact filenames below. Each screenshot should capture only+the relevant Azure blade or Context7 card (crop out the surrounding Azure+sidebar when it isn't load-bearing for the step).++Suggested viewport: **1440x900**, browser zoom 100%, light theme.++---++## 01-register-app.png++**Where**: Azure Portal → Microsoft Entra ID → Manage → App registrations →+**+ New registration**.++**What to capture**: the New registration form with these fields filled in:++- **Name**: `Context7`+- **Supported account types**: *Accounts in this organizational directory only*+- **Redirect URI**: `Web` + `http://localhost:3000/api/auth/entra/callback`+ (or your real host)++Keep the **Register** button visible at the bottom so readers see the+submit action.++---++## 02-app-overview.png++**Where**: Azure Portal → App registrations → **Context7** → **Overview**.++**What to capture**: the Essentials panel showing **Application (client) ID**+and **Directory (tenant) ID** clearly. Values don't need to be redacted since+they're not secrets, but blur them if you'd rather not expose your real+tenant.++Crop tight to the Essentials block so both IDs are easy to spot.++---++## 03-client-secret.png++**Where**: Azure Portal → App registrations → Context7 → **Certificates &+secrets** → **Client secrets** tab → **+ New client secret**.++**What to capture**: the *Add a client secret* side panel showing the+description field filled in (for example, `Context7 on-prem`) and an+expiry selected. You don't need to show the secret Value itself (and+probably shouldn't).++An alternative, if the create panel feels too modal-heavy: take the shot+after the secret is created, showing the row in the Client secrets table+with the **Value** column highlighted (but redact the actual secret).++---++## 04-app-roles.png++**Where**: Azure Portal → App registrations → Context7 → **App roles**.++**What to capture**: the App roles list with both roles created and+**Enabled** = true:++- `Context7 Admin` / Value: `Context7.Admin`+- `Context7 Member` / Value: `Context7.Member`++Make sure both rows are visible in a single shot so readers see the pair.++---++## 05-assignment-required.png++**Where**: Azure Portal → **Microsoft Entra ID** → Enterprise applications+→ Context7 → **Properties**.++**What to capture**: the Properties page with **Assignment required?** set+to **Yes**. Include the **Save** button at the top so readers know they+need to save.++Note: this is the *Enterprise applications* view, not App registrations.+Worth showing enough sidebar context to make that obvious.++---++## 06-assign-user-role.png++**Where**: Enterprise applications → Context7 → **Users and groups** →+**+ Add user/group**.++**What to capture**: the *Add Assignment* page with:++- **Users**: one user selected (your own name is fine)+- **Select a role**: **Context7 Admin** (or Member, either is fine)++The role picker side panel being visible in the same shot is ideal so+readers see where to click for the role selection.++---++## 07-context7-settings-card.png++**Where**: Context7 dashboard → **Workspace Settings** → scroll to the+**Authentication** section.++**What to capture**: the entire **Microsoft Entra SSO** card with the+sticky **On this page** nav visible on the right. Toggle should be **off**+and status indicator should read *Not configured*.++This is the "empty state" screenshot. All fields blank.++---++## 08-filled-credentials.png++**Where**: same card, after pasting in values.++**What to capture**: the card with:++- **Tenant ID** filled in+- **Client ID** filled in+- **Client Secret**: either shows "Leave blank to keep the current secret"+ with the green "A client secret is already stored" check, or a fresh+ secret paste (redact the actual secret before taking the screenshot)+- **Admin role value**: `Context7.Admin`+- **Member role value**: `Context7.Member`++Toggle can stay off at this point. Status should read *Configured · Toggle+on to show the sign-in button*.++---++## 09-test-success.png++**Where**: same card, after clicking **Test connection**.++**What to capture**: the green success banner *Connection verified with+Microsoft Entra.* right above the Save/Test buttons, with the filled-in+form still visible above it.++---++## 10-login-page.png++**Where**: open `/login` in an incognito window after SSO has been enabled+(toggle on + saved).++**What to capture**: the full login card showing:++- Context7 wordmark at the top+- **Welcome back** heading+- **Continue with Microsoft Entra ID** button with the four-square logo+- *OR WITH PASSWORD* divider+- Username + password form below++Center the card in the frame. Incognito avoids any auto-fill suggestions+cluttering the fields.++---++## 11-users-tab.png++**Where**: Workspace Settings → **Users** tab, after at least one Entra+user has signed in once.++**What to capture**: the Users table showing a mix of providers:++- The seeded `admin` row with `password` under AUTH+- At least one Entra user with `entra` under AUTH, display name, email,+ and a recent **last login** timestamp++A minimum of two rows makes the mixed-provider story land. Redact email+domains if they're sensitive.++---++## Tips++- **File format**: PNG. Avoid JPEG for UI screenshots; text gets fuzzy.+- **Retina**: capture at the native device pixel ratio, then downscale if+ needed. Don't upscale low-DPI shots.+- **Redaction**: use a solid rectangle in a matching background color+ rather than blur when hiding values. Blur often leaks readable pixels+ when rendered small.+- **Consistency**: try to keep the same browser chrome, zoom level, and+ theme across the Azure shots and across the Context7 shots so the+ gallery looks cohesive.