# Teams Phone CLI Scripts

This directory contains scripts for setting up and maintaining the Teams Phone CLI.

## Prerequisites

### 1. Install MicrosoftTeams PowerShell Module

```powershell
# Install the module (run as Administrator on Windows)
Install-Module -Name MicrosoftTeams -Force -AllowClobber

# Or update if already installed
Update-Module -Name MicrosoftTeams
```

**Minimum version required:** 4.9.2 or later (for certificate object support)

### 2. Azure AD App Registration

You need an Azure AD App Registration (service principal) with the following configuration:

#### Required Entra ID Role

The service principal needs the **Teams Administrator** role:

1. Azure Portal → Microsoft Entra ID → Roles and administrators
2. Search for "Teams Administrator"
3. Click "Add assignments"
4. Select your app registration's service principal
5. Click "Add"

#### Required Graph API Permissions

Add these **Application** permissions to your app registration:

| Permission | Purpose |
|------------|---------|
| `TeamsUserConfiguration.Read.All` | Read user voice configuration |
| `TeamsTelephoneNumber.Read.All` | Read phone number inventory |
| `TeamsTelephoneNumber.ReadWrite.All` | Assign/unassign phone numbers |
| `TeamsPolicyUserAssign.ReadWrite.All` | Assign policies to users |
| `User.Read.All` | Read user profiles |
| `Directory.Read.All` | Read tenant information |
| `RoleManagement.Read.Directory` | Required as of Sept 2025 |
| `GroupMember.Read.All` | Required as of Sept 2025 |

After adding permissions, click "Grant admin consent for [your tenant]".

#### Certificate Setup

Upload your certificate's public key (.cer file) to the app registration:

1. Azure Portal → App Registrations → Your App
2. Click "Certificates & secrets"
3. Click "Upload certificate"
4. Select your .cer file
5. Note the **Thumbprint** displayed after upload

## Export-TeamsPhoneData.ps1

Exports emergency locations and voice policies to CSV files for use by the Teams Phone CLI.

### Usage

#### Windows (Certificate in Certificate Store)

```powershell
./Export-TeamsPhoneData.ps1 `
    -TenantId "12345678-1234-1234-1234-123456789012" `
    -ApplicationId "87654321-4321-4321-4321-210987654321" `
    -CertificateThumbprint "ABC123DEF456789..."
```

#### Cross-Platform (Certificate File)

```powershell
# Create secure password
$password = ConvertTo-SecureString "YourCertPassword" -AsPlainText -Force

./Export-TeamsPhoneData.ps1 `
    -TenantId "12345678-1234-1234-1234-123456789012" `
    -ApplicationId "87654321-4321-4321-4321-210987654321" `
    -CertificatePath "./certs/TeamsPhoneCLI.pfx" `
    -CertificatePassword $password
```

#### Custom Output Path

```powershell
./Export-TeamsPhoneData.ps1 `
    -TenantId "..." `
    -ApplicationId "..." `
    -CertificateThumbprint "..." `
    -OutputPath "C:\Teams\cache"
```

### Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `-TenantId` | Yes | Azure AD tenant ID (GUID) |
| `-ApplicationId` | Yes | App registration client ID (GUID) |
| `-CertificateThumbprint` | No* | Thumbprint for cert in Windows cert store |
| `-CertificatePath` | No* | Path to .pfx certificate file |
| `-CertificatePassword` | No | SecureString password for .pfx file |
| `-OutputPath` | No | Output directory (default: `~/.teams-phone/cache/`) |

*One of `-CertificateThumbprint` or `-CertificatePath` is required.

### Output Files

The script creates three files in the output directory:

| File | Description |
|------|-------------|
| `locations.csv` | Emergency locations (civic addresses and locations) |
| `policies.csv` | Voice policies (calling, voicemail, emergency, etc.) |
| `export-metadata.json` | Export timestamp and record counts |

### CSV Schemas

#### locations.csv

```csv
locationId,civicAddressId,description,companyName,address,city,stateOrProvince,postalCode,countryOrRegion,isDefault
```

#### policies.csv

```csv
policyType,policyName,policyId,description,isGlobal
```

Policy types exported:
- `TeamsCallingPolicy`
- `TeamsVoicemailPolicy`
- `CallingLineIdentity`
- `TenantDialPlan`
- `OnlineVoiceRoutingPolicy`
- `TeamsEmergencyCallingPolicy`
- `TeamsEmergencyCallRoutingPolicy`

## Troubleshooting

### "MicrosoftTeams module is not installed"

Install the module:
```powershell
Install-Module -Name MicrosoftTeams -Force
```

### "Access denied" or "Insufficient privileges"

1. Verify the service principal has the **Teams Administrator** role assigned
2. Ensure all Graph API permissions are granted and admin consent is provided
3. Check that the certificate is properly uploaded to the app registration

### "Certificate not found"

For `-CertificateThumbprint`:
- Verify the certificate is installed in `Cert:\CurrentUser\My`
- Check the thumbprint matches exactly (no spaces, correct case)

For `-CertificatePath`:
- Verify the file path is correct
- Ensure you have read access to the file
- If password-protected, provide `-CertificatePassword`

### "Connect-MicrosoftTeams failed"

Common causes:
- Wrong tenant ID or application ID
- Certificate not uploaded to app registration
- Certificate expired
- Service principal doesn't have Teams Administrator role

### PowerShell Core Issues

The MicrosoftTeams module works best with Windows PowerShell 5.1. If you encounter issues on PowerShell 7+, try running the script with Windows PowerShell:

```powershell
powershell.exe -File ./Export-TeamsPhoneData.ps1 -TenantId "..." ...
```

## Recommended Schedule

Run this script periodically to keep the CSV cache up-to-date:

- **Minimum:** Monthly
- **Recommended:** Weekly
- **After changes:** When emergency locations or policies are modified

The Teams Phone CLI will warn if the CSV files are older than 30 days.

## Security Notes

- Never commit certificates or credentials to source control
- Use environment variables or secure vaults for sensitive values
- The script only performs read operations (Get-* cmdlets)
- Audit logs are generated in Azure AD for all API calls
