# MS Excel

This guide walks you through **app registration** in Microsoft Entra (Azure AD) and configuring your **on-premise Nected** deployment so users can connect Microsoft Excel (OneDrive/SharePoint) as an integration from the Nected UI. The Excel connector is used in **Workflows** for reading and writing workbooks.

### Prerequisites

* Access to your on-premise Nected deployment (Helm values and cluster)
* A **Microsoft account** with permissions to register applications in [Microsoft Entra](https://entra.microsoft.com) (Azure AD)
* Your Nected UI base URL (e.g. `https://nected.yourcompany.com`)
* **Requires Garuda.** Enable the Garuda service before adding MS Excel. See [How to enable integrations](https://docs.nected.ai/nected-docs/self-hosting/additional-configuration/additional-integrations/..#how-to-enable-integrations) in the Overview.

### App Registration (Microsoft Entra)

Complete the following steps in the Microsoft Entra admin center so Nected can use OAuth to connect to Excel/OneDrive/SharePoint.

#### Step 1: Open Entra and Create the App

1. Go to <https://entra.microsoft.com> and sign in.
2. In the left sidebar, expand **Entra ID** and select **App registrations**.\
   ![](https://4290782554-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLg716fCfV8IUwXQygkTG%2Fuploads%2FfRGw3ThILb5rIIPMuLZF%2F1.png?alt=media\&token=b861eb44-c89f-47b2-bdea-c03088fa254d)
3. Click **+ New registration**.
4. On the **Register an application** form, fill in:<br>

   * **Name:** A user-facing display name (e.g. `Nected Excel`). This can be changed later.
   * **Supported account types:** Choose one:
     * **Accounts in any organizational directory (Any Microsoft Entra ID tenant – Multitenant)** if users from any Azure AD / Microsoft 365 tenant should sign in.
     * **Single tenant only (Default Directory)** if only your organization’s directory should be allowed. Use **Help me choose** if unsure.
   * **Redirect URI (optional):** Under **Web**, add your Nected OAuth redirect URI: `https://<nected-ui-domain>/oauth/redirect` (e.g. `https://nected.yourcompany.com/oauth/redirect`). You can also add this later under **Authentication**.

   <figure><img src="https://4290782554-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLg716fCfV8IUwXQygkTG%2Fuploads%2FCQvrUsCccMB9gntUSAkb%2F3.png?alt=media&#x26;token=9e858a49-7c50-46b8-b5a2-5c9576fd4f82" alt=""><figcaption></figcaption></figure>
5. Click **Register**. You’ll land on the app’s **Overview** page.

#### Step 2: Add API Permissions

<figure><img src="https://4290782554-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLg716fCfV8IUwXQygkTG%2Fuploads%2F0GaX1YfdkWT8QvVWKP7H%2F7.png?alt=media&#x26;token=f226d389-44d6-48d8-be17-677c87a244f3" alt=""><figcaption></figcaption></figure>

1. In the left menu, go to **Manage** → **API permissions**.
2. Click **+ Add a permission**.
3. In **Request API permissions**, leave **Microsoft APIs** selected. Under **Commonly used Microsoft APIs**, select **Microsoft Graph** (it includes access to Excel, OneDrive, SharePoint, and related services).
4. When asked **“What type of permissions does your application require?”**, choose **Delegated permissions** (your app will access the API as the signed-in user, which is required for Excel/OneDrive in Nected).
5. Search for and add the following delegated permissions.

   **Microsoft Graph** (add these first via **Add a permission** → **Microsoft APIs** → **Microsoft Graph** → **Delegated**):

   * **Files.Read** — Read user files
   * **Files.ReadWrite** — Have full access to user files
   * **offline\_access** — Maintain access to data you have given it access to
   * **openid** — Sign users in
   * **profile** — View users’ basic profile
   * **User.Read** — Sign in and read user profile

   **SharePoint** (add via **Add a permission** → **APIs my organization uses** or search for **SharePoint** → **Delegated**):

   * **MyFiles.Read** — Read user files
   * **MyFiles.Write** — Read and write user files

   Your **Configured permissions** should show both **Microsoft Graph (6)** and **SharePoint (2)**. Optionally check **Grant admin consent for Default Directory** if your organization requires it.
6. Click **Add permissions** after each API. Your list should look like the following (Microsoft Graph only) or include SharePoint as above.

<figure><img src="https://4290782554-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLg716fCfV8IUwXQygkTG%2Fuploads%2F8BYPvHi5qCJBHBeezs4W%2F12-configured-permissions-with-sharepoint.png?alt=media&#x26;token=787af0d7-8bac-4997-90d2-e5483e422058" alt=""><figcaption></figcaption></figure>

#### Step 3: Create a Client Secret

<figure><img src="https://4290782554-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLg716fCfV8IUwXQygkTG%2Fuploads%2FZ7FpvuMJ629wWOPrxz3E%2F5.png?alt=media&#x26;token=ab935c85-077b-4797-8ce5-efa6afff225a" alt=""><figcaption></figcaption></figure>

1. In the left menu, go to **Manage** → **Certificates & secrets**.
2. Open the **Client secrets** tab and click **+ New client secret**.
3. Enter a **Description** (e.g. `Nected Excel`) and choose an **Expires** value (e.g. **365 days (12 months)**), then click **Add**.
4. In the **Client secrets** table, copy the **Value** of the new secret using **Copy to clipboard**. Store it securely; the value is shown only once.

<figure><img src="https://4290782554-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLg716fCfV8IUwXQygkTG%2Fuploads%2FUaYDKULAE3J7hq45w8Ud%2F6.png?alt=media&#x26;token=d4486237-b550-4f64-85cc-426eae60fe4f" alt=""><figcaption></figcaption></figure>

You will use this value as the Microsoft Excel **client secret** in `nected-values.yaml`.

#### Step 4: Confirm Redirect URI (If Not Set in Step 1)

If you didn’t set the redirect URI during registration:

1. Go to **Manage** → **Authentication (Preview)**.
2. Under **Platform configurations** → **Web**, add a **Redirect URI**: `https://<nected-ui-domain>/oauth/redirect`.
3. Replace `<nected-ui-domain>` with your actual Nected UI host (no trailing slash) and save.

#### Step 5: Update Logo (Optional)

For a consistent experience in the Nected Integrations UI, you can upload a logo under **Manage** → **Branding & properties**. This step is optional.

#### Step 6: Note Application (Client) ID, Tenant ID, and Endpoints

1. Go to **Overview**. In the **Essentials** section, copy:

   * **Application (client) ID**
   * **Directory (tenant) ID**

   Use `organizations` in your Nected config for multitenant; for single tenant, use this Directory (tenant) ID.
2. For **authUrl** and **tokenUrl** in `nected-values.yaml`, use the **OAuth 2.0** endpoints from **Endpoints** (or build them from your tenant ID):
   * **OAuth 2.0 authorization endpoint (v2):** `https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/authorize`
   * **OAuth 2.0 token endpoint (v2):** `https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token`\
     Replace `<tenant-id>` with your **Directory (tenant) ID** or use `organizations` for multitenant.

<figure><img src="https://4290782554-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLg716fCfV8IUwXQygkTG%2Fuploads%2FzLfOAhkuwKSUryVcbyOY%2F11-endpoints.png?alt=media&#x26;token=319edf8f-f6d9-4b63-ba10-7a6e59610e43" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
**You will use the Client ID, client secret (from Step 3), tenant ID, and these URLs in the next section.**
{% endhint %}

### Update \`nected-values.yaml\` — CREDENTIAL\_CONFIG\_MAP

In `nected-values.yaml`, **CREDENTIAL\_CONFIG\_MAP** and **SYNC\_PLUGINS** are set under the **nalanda** section, under the **envVars** section. They are not present in the file by default—copy the default values from the Overview and append your integration entries. Both must be single-line (no newlines); do not remove existing values.

1. Open your **`nected-values.yaml`** file.
2. Under the **nalanda** section, under **envVars**, locate or add **`CREDENTIAL_CONFIG_MAP`**.
3. `CREDENTIAL_CONFIG_MAP` must be a **single-line JSON** string (no newlines or pretty-printing). Add the **msexcel** entry to the existing JSON object; do not remove other integrations.

MS Excel supports two config types. Choose one:

**Organizations** (multiple organizations / multi-tenant):

```yaml
nalanda:
  envVars:
    CREDENTIAL_CONFIG_MAP: '{"msexcel":{"clientId":"<<YOUR-CLIENT-ID>>","clientSecret":"<<YOUR-CLIENT-SECRET>>"}, "slack":{...}}'
```

**Tenant** (single tenant; explicit auth and token URLs):

```yaml
nalanda:
  envVars:
    CREDENTIAL_CONFIG_MAP: '{"msexcel":{"clientId":"<<YOUR-CLIENT-ID>>","clientSecret":"<<YOUR-CLIENT-SECRET>>","authUrl":"https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/authorize","tokenUrl":"https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token"},"slack":{...}}'
```

* Replace **`<<YOUR-CLIENT-ID>>`** with the Application (client) ID from Step 6.
* Replace **`<<YOUR-CLIENT-SECRET>>`** with the client secret value from Step 3.
* If you need custom **scopes** or a **redirectUri**, add them to the same `msexcel` object.
* For a **single tenant**, replace `organizations` in `authUrl` and `tokenUrl` with your **Directory (tenant) ID** (from Step 6 / Endpoints).

### Update `nected-values.yaml` — SYNC\_PLUGINS

1. In the same **`nected-values.yaml`**, under the **nalanda** section, under **envVars**, locate or add **`SYNC_PLUGINS`**.
2. `SYNC_PLUGINS` is a **single-line** comma-separated list. **Append** `msexcel` to the existing list; do not remove existing plugins. For example:

```yaml
nalanda:
  envVars:
    SYNC_PLUGINS: mysql,mongodb,postgres,sqlserver,redshift,oracle,snowflake,restAPI,anthropic,googleai,openai,vertex,sagemaker,slack,msexcel
```

Use your current plugin list and add `msexcel` at the end (or after the last plugin you use).

### Apply Changes and Run Plugin Migrations

#### Helm upgrade

```bash
helm repo update
helm upgrade -i nected nected/nected -f nected-values.yaml
```

#### Restart Nalanda (if needed)

If the Nalanda deployment does not pick up the new plugin:

```bash
kubectl rollout restart deploy nected-nalanda
```

#### Run plugin migrations

To ensure the MS Excel integration is registered and appears under the Integrations tab:

1. Get the Nalanda pod name:

   ```bash
   kubectl get pods -l app=nected-nalanda
   ```
2. Run plugin migrations from inside the pod:

   ```bash
   kubectl exec -it <<nalanda-pod-name>> -- /bin/bash
   ./nalanda sync plugin
   exit
   ```

Replace **`<<nalanda-pod-name>>`** with the actual pod name.

After this, refresh the Nected UI and open **Integrations**. You should see the option to connect to **Microsoft Excel** (Sign in with Microsoft). Users can then use the Excel connector in **Workflows** as described in the Microsoft Excel integration guide.

### Summary Checklist

1. Open [entra.microsoft.com](https://entra.microsoft.com) → **Entra ID** → **App registrations** → **New registration**.
2. Fill in **Name**, **Supported account types**, and **Redirect URI** (Web: `https://<nected-ui-domain>/oauth/redirect`).
3. Add **API permissions**: **Microsoft Graph** (Delegated) — Files.Read, Files.ReadWrite, offline\_access, openid, profile, User.Read; **SharePoint** (Delegated) — MyFiles.Read, MyFiles.Write. If needed, add custom scopes as described in the CREDENTIAL\_CONFIG\_MAP section above.
4. Create a **client secret** under **Certificates & secrets** and copy the Value.
5. Copy **Application (client) ID** and **Directory (tenant) ID** from **Overview** (and OAuth endpoints from **Endpoints** if needed).
6. (Optional) Update logo under **Branding & properties**.
7. Under **nalanda** → **envVars** in `nected-values.yaml`: add **msexcel** to **`CREDENTIAL_CONFIG_MAP`** (Organizations or Tenant config) and **msexcel** to **`SYNC_PLUGINS`**.
8. Run **Helm upgrade**, restart the deployment if needed, then run **plugin sync** (`./nalanda sync plugin`).

### Troubleshooting

* **Excel not in Integrations list:** Ensure **msexcel** is in `SYNC_PLUGINS` and run `./nalanda sync plugin` inside the Nalanda pod.
* **OAuth or redirect errors:** Confirm the redirect URI in Entra exactly matches the value in `CREDENTIAL_CONFIG_MAP` (including `https` and no trailing slash).
* **Consent or permission errors:** Verify delegated permissions in Entra (Microsoft Graph and, if used, SharePoint) and grant admin consent if required. If issues persist, try the alternative scopes (including `email` and `https://<tenant>-my.sharepoint.com/AllSites.Read`).
* **Using Excel in Nected:** The Excel integration is available only in **Workflows**, not in Rules. See Microsoft Excel for workflow usage.