# Cloud Credentials Management System

> Centralized authentication and credential management for external service integrations in Wallboard.

---

## Microsoft Credentials Architecture

### Authentication Flow Types:

#### 1. **Personal Account**
- **Authentication method**: Delegated permissions
- **User flow**: User logs in, backend receives token
- **Use case**: Individual Microsoft account integration

#### 2. **Work or School Account** 
- **Authentication method**: Delegated permissions
- **User flow**: User logs in via Azure AD, backend receives token
- **Enterprise integration**: Full Azure AD organizational access

#### 3. **Service Principal (Client Credentials)**
- **Authentication method**: Client credential flow
- **Automated access**: No user interaction required
- **Use case**: Unattended data source operations

### Microsoft Credential Scopes:

When creating Microsoft credentials, users must select scope types that determine requested permissions:

- **Calendar**: Access to calendar data and meeting information
- **Excel**: Microsoft Excel file access and data extraction
- **SharePoint Lists**: SharePoint list data and metadata
- **OneDrive**: File and folder synchronization capabilities
- **Power BI**: Power BI dashboard and report integration
- **User Active Directory**: Employee directory and organizational data (Teams user list equivalent)

### Advanced Permission Management:

#### **Manager User System:**
- **Beyond team permissions**: Separate authorization layer from standard team system
- **Manager assignment**: Specific user designated as credential manager
- **Permission control**: Manager user controls granular access permissions
- **Fallback behavior**: If no manager assigned, any user with credential access can manage permissions

#### **Granular Access Control (Microsoft Only):**
**SharePoint Calendar Example:**
- **Site-level filtering**: Manager selects which SharePoint sites are accessible
- **Calendar-level filtering**: Within selected sites, specify which calendars are available
- **User visibility control**: Regular users only see pre-filtered SharePoint structure
- **Security isolation**: Prevent exposure of full organizational structure

**Technical Implementation:**
- **Token scope limitation**: Despite full delegated permissions, system restricts visible data
- **UI filtering**: Data source configuration shows only manager-approved options
- **Permission inheritance**: Respects both Microsoft permissions AND manager restrictions

### Enterprise Integration Challenges:

#### **Admin Consent Requirements:**
- **On-premise deployments**: Customer creates own Azure app registration
- **Enterprise application**: Must be added to customer's Azure AD directory
- **Cloud deployments**: Uses Wallboard's official Azure app registration
- **Admin consent required**: Scopes require administrator approval
- **Common misconception**: Regular users cannot grant organization-wide access

#### **Server-side Microsoft API setup (Excel / M365 sign-in):**
- Excel and other Microsoft-scoped credentials need the **server** to have Microsoft API / Azure app configuration in place — not only a user clicking Sign in in the editor.
- **On-premise / customer-hosted servers:** missing server-side Microsoft API setup commonly presents as Excel or M365 sign-in failure at the client. Check System/server Microsoft (Azure app) configuration before treating it as a product regression.
- **Cloud Wallboard servers:** use Wallboard’s official Azure app registration (see Admin Consent above).

#### **Authentication Recovery:**
- **Re-authentication capability**: Broken connections can be restored
- **SSO flow restart**: Re-initiate OAuth login process
- **Token refresh**: Automatic token renewal handling

---

## Google Credentials Architecture

### **Simplified Authentication:**
- **Personal accounts only**: Individual Google account authentication
- **Scoped permissions**: Service-specific access control
- **No enterprise features**: Limited organizational integration

### **Google Credential Scopes:**
- **Google Sheets**: Access to Google Sheets API only
- **Google Calendar**: Calendar event access
- **Google Drive**: File and folder access

### **Limitations:**
- **No Google Workspace**: Enterprise Google features not supported
- **No granular permission management**: Unlike Microsoft, no manager-controlled filtering
- **SME-focused**: Designed for small/medium enterprise use cases

---

## Canva Credentials Architecture

| Area | Behavior |
|------|----------|
| User path | **Settings > Cloud Credentials > Canva** supports add/edit/authenticate/remove Canva credentials. |
| Instance setup | **System Settings > Canva API settings** stores the Canva API client ID and client secret used by the OAuth flow. |
| Primary use | **Files > Connect Canva folder** uses Canva credentials for Canva folder sync; this is file/folder synchronization, not a generic datasource credential. |
| Access control | Credential team assignments and optional manager user follow the standard Cloud Credentials lifecycle; UI profiles can hide See/Add/Manage Canva credentials. |
| Runtime use | Backend refreshes/uses the credential token during sync, exports Canva designs, and stores exported files as normal Wallboard files. |

---

## Amadeus Credentials Architecture

| Area | Behavior |
|------|----------|
| User path | **Settings > Cloud Credentials > Other > Amadeus** supports Amadeus credential add/edit/manage. |
| Instance setup | **Administrator > System Settings > Integrations > Amadeus API settings** stores the Amadeus API base URL and environment toggle. |
| Required fields | Credential name, Client ID, Client secret, Subscription Key from Amadeus. |
| Primary use | **Amadeus event** external datasource lists Amadeus locations, then fetches upcoming definite events for a selected property/location. |
| Access control | Team assignments, optional manager user, and UI Profile hidden-UI rules follow the standard Cloud Credentials lifecycle. |
| Runtime use | The integration service authenticates with Amadeus, refreshes tokens, and supplies event data to datasource-bound content. |

---

## Notion Credentials Architecture

| Area | Behavior |
|------|----------|
| User path | **Settings > Cloud Credentials > Other > Notion**. Enter a name, save, then **Authenticate** and grant access to the intended Notion data source. |
| Instance setup | **Administrator > System Settings > Integrations > Notion API settings** requires the server's Notion API client ID and client secret. Callback: `{serverBase}/public-api/oauth/callback`. |
| Primary use | **Notion** external datasource discovery and read-only row import. |
| Access control | Team assignment, read-only restrictions, and Other-credential UI Profile rules apply. **Authenticate / Re-authenticate** is offered to the assigned manager, or an eligible user when no manager is assigned. Owner/admin can change the manager. |
| Datasource selection | After a Notion datasource is created, its **Credentials** selector is locked in the UI; its **Datasource** selector remains editable. This lock does not prevent editing or re-authenticating the credential itself. |
| Renewal | **Re-authenticate** reconnects the account. Automatic renewal on expiry is conditional on Notion having returned a refresh token. |

---

## Other/Custom Credentials

**Other** groups named standard integrations, including Notion and Amadeus, alongside project-specific credentials. Selecting Notion does not require bespoke integration development.

### **Project-Specific Development:**
Custom credentials developed for specialized integration requirements that cannot be met by standard OAuth or API key authentication.

#### **Common Use Cases:**
- **On-premise integrations**: Custom authentication for internal systems
- **Educational institutions**: University-specific authentication systems
- **Complex OAuth flows**: Multi-step authentication processes
- **Data aggregation**: Combining data from multiple APIs requiring coordinated authentication
- **Legacy system integration**: Authentication for older systems without modern OAuth support

#### **Development Triggers:**
- **Insufficient standard data sources**: JSON/XML data sources with headers insufficient
- **Complex authentication**: Multi-factor or certificate-based authentication required
- **Data mapping complexity**: Aggregating data from 8+ different APIs
- **Custom business logic**: Authentication tied to specific business processes

#### **Implementation Approach:**
- **Custom OAuth implementations**: Tailored OAuth flows for specific services
- **Multi-API coordination**: Orchestrated authentication across multiple services  
- **Advanced data mapping**: Complex data transformation during authentication
- **Enterprise-specific protocols**: Integration with proprietary authentication systems

### **UI Terminology:**
- **"Other Credentials"**: User-facing group for named integrations and custom authentication
- **"Other Data Sources"**: Paired with custom credentials for complete custom integration

---

## Team-Based Credential Management

### **Standard Team Integration:**
- **Team assignment**: Credentials can be assigned to teams
- **Access inheritance**: Team members inherit credential usage rights
- **Multi-team support**: Single credential can be shared across teams

### **Manager User Override:**
- **Independent of teams**: Manager user system operates separately from team permissions
- **Granular control**: Manager user can restrict access beyond team permissions
- **Permission hierarchy**: Manager restrictions apply even to team members

### **Operational Workflow:**
```
Credential Creation:
├── Admin creates credential with required scopes
├── Manager user assigned (optional)
├── Teams assigned for basic access
└── Manager configures granular permissions

Data Source Usage:
├── User selects credential for data source
├── System checks team permissions
├── Manager restrictions filter available options
└── User sees only approved organizational structure
```

## Security Architecture

### **Multi-Layer Permission Control:**
1. **External Service Permissions**: Microsoft/Google native permissions
2. **Wallboard Team Permissions**: Team-based access control
3. **Manager User Restrictions**: Granular filtering of available options
4. **Data Source Configuration**: Final selection from filtered options

### **Enterprise Security Benefits:**
- **Principle of least privilege**: Multiple restriction layers ensure minimal access
- **Organizational privacy**: Hide internal structure from non-authorized users
- **Flexible delegation**: Manager users can delegate without full admin access
- **Audit capability**: Track credential usage and permission changes

### **Credential Lifecycle:**
- **Creation**: Scope selection and initial authentication
- **Management**: Manager user configuration and team assignment
- **Usage**: Data source integration and ongoing token refresh
- **Recovery**: Re-authentication and connection restoration
- **Retirement**: Secure credential removal and access revocation