# Data Connectors in Kamiwaza

Data connectors in Kamiwaza allow administrators to configure external data source connectors. Once configured, users can connect their accounts to access data from these services, enabling integration with Microsoft 365, Google Workspace, and other cloud services.

## Overview

External data connectors enable users to access their data from cloud services like Microsoft 365 and Google Workspace. Administrators configure the connector settings (such as Azure AD application registration for Microsoft 365), and then users can connect their personal or work accounts to access data from these services.

The connector configuration includes:

- **Service configuration**: Application credentials and settings required to connect to the external service
- **Access controls**: Permissions and scopes that determine what data users can access
- **Status tracking**: Whether the connector is configured and ready for users to connect their accounts

Connectors are managed through the Kamiwaza web UI at **Settings** → **Data Connectors**.

## Configuring a Connector

### Prerequisites

- Administrative access to the Kamiwaza platform
- Application credentials for the external service (e.g., Azure AD app registration for Microsoft 365)
- Knowledge of the service's authentication and API requirements

### Using the Web UI

1. Navigate to **Settings** → **Data Connectors**
2. You'll see available connector types:
   - **Microsoft 365** - Connect to SharePoint, OneDrive, Outlook, and Calendar
   - **Google Workspace** - Connect to Drive, Gmail, and Calendar (read-only)
   - **Dropbox** - Connect to Dropbox storage
3. Click **Configure** on the connector you want to set up
4. Fill in the required configuration details:
   - For Microsoft 365: Azure AD application credentials (Client ID, Client Secret, Tenant ID)
   - For Google Workspace: Google Cloud OAuth credentials (Client ID, Client Secret, Redirect URI) plus the read-only capabilities (Gmail, Drive, Calendar) to request
   - Service-specific settings and permissions
5. Click **Save** to complete the configuration

Once configured, the connector status will show as "Configured" and users will be able to connect their accounts to access data from these services.

## Managing Connectors

### Viewing Connectors

In the **Settings** → **Data Connectors** page, you can view all available connector types. Each connector card shows:

- Connector name and logo
- Associated services (e.g., "SharePoint, OneDrive, Outlook, Calendar" for Microsoft 365)
- Configuration status ("Configured" or "Not configured")
- Availability status (some connectors may show "Coming Soon")

### Viewing Connector Configuration

Click on a configured connector to view its configuration details, including:

- Application credentials and settings (sensitive values are redacted)
- Configured permissions and scopes
- Connection status

### Updating a Connector

To update a connector's configuration:

1. Navigate to **Settings** → **Data Connectors**
2. Click **Configure** on the connector you want to update
3. Modify the configuration fields as needed:
   - Application credentials (Client ID, Client Secret, etc.)
   - Service-specific settings
   - Permissions and scopes
4. Click **Save** to apply changes

**Note**: Updating connector configuration may require users to reconnect their accounts if authentication settings change.

### Removing a Connector Configuration

To remove a connector configuration:

1. Navigate to **Settings** → **Data Connectors**
2. Click **Configure** on the connector
3. Click **Delete** to remove the configuration

**Warning**: Removing a connector configuration will disconnect all users who have connected their accounts. Users will need to reconnect after the connector is reconfigured.

## User Connection Flow

Once an administrator has configured a connector, users can connect their accounts:

1. Users navigate to their profile or data sources section
2. They see available connectors that have been configured by administrators
3. Users click to connect their account (e.g., "Connect Microsoft 365")
4. They are redirected to authenticate with the external service (OAuth flow)
5. After successful authentication, their account is connected and they can access data from that service

The connector configuration determines what permissions and data scopes are available to users when they connect their accounts.

## Security and Access Control

### Application Credentials

- **Secure Storage**: Application credentials (Client IDs, Client Secrets) are encrypted at rest
- **Credential Rotation**: Update the connector configuration in the UI to rotate application credentials when needed
- **Least Privilege**: Configure application permissions to request only the minimum scopes needed

### User Access

- **OAuth Authentication**: Users authenticate directly with the external service (Microsoft, Google, etc.) using OAuth
- **User-Level Permissions**: Each user's access is limited to their own account and the permissions they grant during the OAuth flow
- **Admin Control**: Administrators control which connectors are available to users, but users control which accounts they connect

### Data Access

- **Scoped Access**: Users can only access data from accounts they have connected
- **Permission Boundaries**: The connector configuration determines what permissions are requested from users during the OAuth flow
- **Data Isolation**: Each user's connected accounts and data are isolated from other users

## Connector Status

Each connector displays its configuration status:

- **Not configured**: The connector has not been set up yet. Administrators need to click **Configure** to set up the connector.
- **Configured**: The connector is ready for users to connect their accounts. Users will see this connector as available in their data sources.

View connector status on the **Settings** → **Data Connectors** page. The status indicator shows whether each connector type is configured and ready for use.

## Supported Connector Types

| Connector | Services | Status |
| --- | --- | --- |
| **Microsoft 365** | SharePoint, OneDrive, Outlook, Calendar | Available |
| **Google Workspace** | Drive, Gmail, Calendar (read-only) | Available |
| **Dropbox** | Dropbox storage | Coming Soon |

### Microsoft 365 Connector

The Microsoft 365 connector allows users to connect their Microsoft accounts to access:

- **SharePoint**: Document libraries and sites
- **OneDrive**: Personal file storage
- **Outlook**: Email messages
- **Calendar**: Calendar events and meetings

**Configuration Requirements**:

- Azure AD application registration
- Client ID and Client Secret
- Tenant ID (for single-tenant apps)
- Required API permissions configured in Azure AD

### Google Workspace Connector

The Google Workspace connector lets users connect their Google accounts to access, **read-only**:

- **Google Drive**: files and folders
- **Gmail**: email messages
- **Google Calendar**: calendar events

Administrators register a Google Cloud OAuth client once; each user then connects their own Google account through Google's consent screen. The connector requests **read-only** scopes only — it cannot send mail, modify files, or change calendar events.

**Configuration Requirements**:

- A Google Cloud project
- An **OAuth 2.0 Client ID** of type **Web application** (provides the Client ID and Client Secret)
- The required Google APIs **enabled** in that project: **Gmail API**, **Google Drive API**, **Google Calendar API**
- An **Authorized redirect URI** that exactly matches Kamiwaza's callback
- A configured **OAuth consent screen** (the requested scopes are _sensitive/restricted_, so external apps may require Google verification)

#### Step 1 – Create the OAuth client in Google Cloud Console

1. Open the [Google Cloud Console](https://console.cloud.google.com/) and create or select a project.
2. **Enable the APIs** under **APIs & Services → Library** — enable each capability you plan to offer:
   - **Gmail API**, **Google Drive API**, **Google Calendar API**
3. Configure the **OAuth consent screen**:
   - Choose **Internal** (recommended for a single Google Workspace organization) or **External** (requires adding test users, or publishing the app + Google verification).
   - Add the scopes you will request: `gmail.readonly`, `drive.readonly`, `calendar.readonly`, plus the basic `userinfo.email` and `userinfo.profile` sign-in scopes.
4. Create the credential under **APIs & Services → Credentials → Create credentials → OAuth client ID**:
   - **Application type: Web application.**
   - Under **Authorized redirect URIs**, add Kamiwaza's callback URL (exact match).
5. Copy the **Client ID** (ends with `.apps.googleusercontent.com`) and the **Client Secret** (starts with `GOCSPX-`).

#### Step 2 – Configure the connector in Kamiwaza

1. Go to **Settings → Data Connectors** and click **Configure** on **Google Workspace**.
2. Fill in:
   - **Display Name** — a friendly label for the connector.
   - **Client ID** and **Client Secret** — from Step 1.
   - **Redirect URI** — prefilled from your current browser origin as `https://<host>/api/connectors/public/google/callback`.
3. Under **Google Workspace Capabilities**, check the services to request — **Gmail (read-only)**, **Google Drive (read-only)**, **Google Calendar (read-only)**.
4. Click **Save**. The connector status changes to **Configured** and users can connect their Google accounts.

## Best Practices

1. **Application Registration**: Create dedicated Azure AD applications for Kamiwaza connectors rather than reusing existing applications
2. **Principle of Least Privilege**: Request only the minimum API permissions needed for the connector's functionality
3. **Credential Security**: Store application credentials securely and rotate them regularly
4. **User Communication**: Inform users about what data and permissions will be requested before they connect their accounts
5. **Testing**: Test connector configuration with a test account before making it available to all users
6. **Documentation**: Document the required Azure AD permissions and configuration steps for your team
7. **Monitoring**: Regularly review which users have connected accounts and ensure connectors remain properly configured

## Troubleshooting

### Connector Configuration Fails

- Verify you have administrative access to the Kamiwaza platform
- Check that all required fields are provided (Client ID, Client Secret, etc.)
- Ensure application credentials are valid and not expired
- Verify the Azure AD application has the required permissions configured

### Users Cannot Connect Their Accounts

- Verify the connector shows as "Configured" in the admin interface
- Check that the OAuth redirect URIs are correctly configured in Azure AD
- Ensure the application credentials are still valid and haven't expired

### Authentication Errors

- Check that the Client ID and Client Secret are correct
- Verify the redirect URI in Azure AD matches Kamiwaza's callback URL
- Ensure the Azure AD application permissions are properly configured

### Google Workspace: a capability needs reconnect after enabling an API

If users connect successfully but a capability does not work — or the connection reports that it needs re-authentication, the corresponding API is not enabled in the Google Cloud project:

1. In Google Cloud Console, open **APIs & Services → Library** and enable the named API
2. Ask affected users to **reconnect** their account

### Google Workspace: `redirect_uri_mismatch`

A `redirect_uri_mismatch` error during the Google consent flow means the connector's **Redirect URI** does not exactly match an **Authorized redirect URI** on the Google Cloud OAuth client. Confirm both are identical and that you edited the correct OAuth client.