diff --git a/surfsense_web/app/sitemap.ts b/surfsense_web/app/sitemap.ts index f1f0bad72..e7c0d576e 100644 --- a/surfsense_web/app/sitemap.ts +++ b/surfsense_web/app/sitemap.ts @@ -181,6 +181,12 @@ export default function sitemap(): MetadataRoute.Sitemap { changeFrequency: "daily", priority: 0.8, }, + { + url: "https://www.surfsense.com/docs/connectors/microsoft-onedrive", + lastModified, + changeFrequency: "daily", + priority: 0.8, + }, { url: "https://www.surfsense.com/docs/connectors/microsoft-teams", lastModified, diff --git a/surfsense_web/content/docs/connectors/index.mdx b/surfsense_web/content/docs/connectors/index.mdx index 501b1fc0b..93caf807d 100644 --- a/surfsense_web/content/docs/connectors/index.mdx +++ b/surfsense_web/content/docs/connectors/index.mdx @@ -53,6 +53,11 @@ Connect SurfSense to your favorite tools and services. Browse the available inte description="Connect your Microsoft Teams to SurfSense" href="/docs/connectors/microsoft-teams" /> + + Microsoft OneDrive and [Microsoft Teams](/docs/connectors/microsoft-teams) share the same Azure App Registration. If you have already created an app for Teams, you can reuse the same Client ID and Client Secret. Just make sure both redirect URIs are added (see Step 3). + + +## Step 1: Access Azure App Registrations + +1. Navigate to [portal.azure.com](https://portal.azure.com) +2. In the search bar, type **"app reg"** +3. Select **"App registrations"** from the Services results + +## Step 2: Create New Registration + +1. On the **App registrations** page, click **"+ New registration"** + +## Step 3: Register the Application + +Fill in the application details: + +| Field | Value | +|-------|-------| +| **Name** | `SurfSense` | +| **Supported account types** | Select **"Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant) and personal Microsoft accounts"** | +| **Redirect URI** | Platform: `Web`, URI: `http://localhost:8000/api/v1/auth/onedrive/connector/callback` | + +Click **"Register"** + +After registration, add the Teams redirect URI as well (if you plan to use the Teams connector): + +1. Go to **Authentication** in the left sidebar +2. Under **Platform configurations** > **Web** > **Redirect URIs**, click **Add URI** +3. Add: `http://localhost:8000/api/v1/auth/teams/connector/callback` +4. Click **Save** + +## Step 4: Get Application (Client) ID + +After registration, you will be taken to the app's **Overview** page. Here you will find: + +1. Copy the **Application (client) ID** - this is your Client ID +2. Note the **Directory (tenant) ID** if needed + +## Step 5: Create Client Secret + +1. In the left sidebar under **Manage**, click **"Certificates & secrets"** +2. Select the **"Client secrets"** tab +3. Click **"+ New client secret"** +4. Enter a description (e.g., `SurfSense`) and select an expiration period +5. Click **"Add"** +6. **Important**: Copy the secret **Value** immediately. It will not be shown again! + + + Never share your client secret publicly or include it in code repositories. + + +## Step 6: Configure API Permissions + +1. In the left sidebar under **Manage**, click **"API permissions"** +2. Click **"+ Add a permission"** +3. Select **"Microsoft Graph"** +4. Select **"Delegated permissions"** +5. Add the following permissions: + +| Permission | Type | Description | Admin Consent | +|------------|------|-------------|---------------| +| `Files.Read` | Delegated | Read user files | No | +| `Files.ReadWrite` | Delegated | Read and write user files | No | +| `offline_access` | Delegated | Maintain access to data you have given it access to | No | +| `User.Read` | Delegated | Sign in and read user profile | No | + +6. Click **"Add permissions"** + + + The `Files.ReadWrite` permission is required for HITL (Human-in-the-Loop) tools like creating and trashing files. If you only need read access for indexing, `Files.Read` is sufficient, but HITL tools will not work. + + +--- + +## Running SurfSense with Microsoft OneDrive Connector + +Add the Microsoft OAuth credentials to your `.env` file (created during [Docker installation](/docs/docker-installation/docker-compose)): + +```bash +MICROSOFT_CLIENT_ID=your_microsoft_client_id +MICROSOFT_CLIENT_SECRET=your_microsoft_client_secret +ONEDRIVE_REDIRECT_URI=http://localhost:8000/api/v1/auth/onedrive/connector/callback +``` + + + The `MICROSOFT_CLIENT_ID` and `MICROSOFT_CLIENT_SECRET` are shared between the OneDrive and Teams connectors. You only need to set them once. + + +Then restart the services: + +```bash +docker compose up -d +``` diff --git a/surfsense_web/content/docs/connectors/microsoft-teams.mdx b/surfsense_web/content/docs/connectors/microsoft-teams.mdx index aba64da20..166004c1f 100644 --- a/surfsense_web/content/docs/connectors/microsoft-teams.mdx +++ b/surfsense_web/content/docs/connectors/microsoft-teams.mdx @@ -7,6 +7,10 @@ description: Connect your Microsoft Teams to SurfSense This guide walks you through setting up a Microsoft Teams OAuth integration for SurfSense using Azure App Registration. + + Microsoft Teams and [Microsoft OneDrive](/docs/connectors/microsoft-onedrive) share the same Azure App Registration. If you have already created an app for OneDrive, you can reuse the same Client ID and Client Secret. Just make sure both redirect URIs are added (see Step 3). + + ## Step 1: Access Azure App Registrations 1. Navigate to [portal.azure.com](https://portal.azure.com) @@ -33,11 +37,18 @@ Fill in the application details: Click **"Register"** +After registration, add the OneDrive redirect URI as well: + +1. Go to **Authentication** in the left sidebar +2. Under **Platform configurations** > **Web** > **Redirect URIs**, click **Add URI** +3. Add: `http://localhost:8000/api/v1/auth/onedrive/connector/callback` +4. Click **Save** + ![Register Application Form](/docs/connectors/microsoft-teams/azure-register-app.png) ## Step 4: Get Application (Client) ID -After registration, you'll be taken to the app's **Overview** page. Here you'll find: +After registration, you will be taken to the app's **Overview** page. Here you will find: 1. Copy the **Application (client) ID** - this is your Client ID 2. Note the **Directory (tenant) ID** if needed @@ -54,7 +65,7 @@ After registration, you'll be taken to the app's **Overview** page. Here you'll ![Certificates & Secrets - Empty](/docs/connectors/microsoft-teams/azure-certificates-empty.png) -6. **Important**: Copy the secret **Value** immediately - it won't be shown again! +6. **Important**: Copy the secret **Value** immediately. It will not be shown again! ![Certificates & Secrets - Created](/docs/connectors/microsoft-teams/azure-certificates-created.png) @@ -90,14 +101,18 @@ After registration, you'll be taken to the app's **Overview** page. Here you'll ## Running SurfSense with Microsoft Teams Connector -Add the Microsoft Teams credentials to your `.env` file (created during [Docker installation](/docs/docker-installation/docker-compose)): +Add the Microsoft OAuth credentials to your `.env` file (created during [Docker installation](/docs/docker-installation/docker-compose)): ```bash -TEAMS_CLIENT_ID=your_microsoft_client_id -TEAMS_CLIENT_SECRET=your_microsoft_client_secret +MICROSOFT_CLIENT_ID=your_microsoft_client_id +MICROSOFT_CLIENT_SECRET=your_microsoft_client_secret TEAMS_REDIRECT_URI=http://localhost:8000/api/v1/auth/teams/connector/callback ``` + + The `MICROSOFT_CLIENT_ID` and `MICROSOFT_CLIENT_SECRET` are shared between the Teams and OneDrive connectors. You only need to set them once. + + Then restart the services: ```bash