====== App Registration & API Permissions ====== This guide walks you through creating an App Registration in Entra ID (formerly Azure Active Directory) for Chipmunk, and assigning the necessary Microsoft Graph and Exchange permissions. ===== Overview ===== Chipmunk uses Microsoft Graph and Exchange APIs to back up OneDrive, Exchange, and Teams data for disabled users. You'll need to register an app in your Azure tenant and grant it the correct permissions. ===== Step 1: Decide Your Internal DNS Name ===== Before you register the app, decide what DNS name your Chipmunk appliance will use (e.g., ''chipmunk.yourcompany.local''). This will be used in the redirect URI. Also ensure you have: * A TLS certificate matching that DNS name. * A DNS A-record pointing to your Chipmunk appliance’s internal IP. ===== Step 2: Create the App Registration ===== 1. Go to [[https://portal.azure.com|Azure Portal]] 2. Search for **App registrations** and click **+ New registration** 3. Enter: * **Name**: ''ChipmunkApp'' * **Supported account types**: *Accounts in this organizational directory only* * **Redirect URI** (Web): - `https://chipmunk.YOURDOMAIN/api/auth/callback/azure-ad` - `https://chipmunk.YOURDOMAIN:3000/api/auth/callback/azure-ad` *(optional, see below)* 4. Click **Register** **Note:** During initial setup, Chipmunk may temporarily use port 3000 for configuration access. You should include both redirect URIs above during deployment. Once Chipmunk is fully configured and using port 443, you may safely remove the port 3000 URI from the App Registration for security tightening. ===== Step 3: Save Your App Details ===== After registration, copy these values from the Overview page: * **Application (client) ID** * **Directory (tenant) ID** You'll use these during Chipmunk's first-time configuration. ===== Step 4: Add a Client Secret ===== 1. Go to **Certificates & secrets** 2. Click **+ New client secret** 3. Name it something like ''ChipmunkSecret'' 4. Set expiry to 12 or 24 months 5. Click **Add** → **Important**: Copy the **Value** immediately — you won't be able to see it again. ===== Step 5: Assign API Permissions ===== Navigate to **API permissions** > **+ Add a permission** > **Microsoft Graph** > **Application permissions** Add the following: ^ Type ^ Permission Name ^ Description ^ | Application | `User.Read.All` | Read all users' full profiles | | Application | `Group.Read.All` | Read all groups | | Application | `Files.Read.All` | Read all files in site collections | | Application | `Files.ReadWrite.All` | Read and write files in site collections | | Application | `Mail.Read` | Read mail in all mailboxes | | Application | `Mail.Send` | Send mail as any user | | Application | `ChannelMessage.Read.All` | Read all Teams channel messages | | Application | `Chat.Read.All` | Read all Teams chat messages | | Application | `Chat.ReadBasic.All` | Read names and members of chat threads | | Application | `Sites.Read.All` | Read SharePoint site items | | Application | `Sites.ReadWrite.All` | Read/write SharePoint site items | | Application | `Team.ReadBasic.All` | List all Microsoft Teams | | Application | `TeamMember.Read.All` | Read members of all Teams | | Application | `TeamSettings.Read.All` | Read all Teams’ settings | | Application | `TeamSettings.ReadWrite.All` | Read/change Teams’ settings | | Application | `Contacts.Read` | Read contacts in all mailboxes | | Application | `Calendars.Read` | Read calendars in all mailboxes | | Application | `AuditLog.Read.All` | Read audit logs | | Application | `Directory.Read.All` | Read directory data | Then click: * **+ Add a permission** * Choose **Office 365 Exchange Online** * Select `full_access_as_app` (Application) ===== Step 6: Grant Admin Consent ===== Click **Grant admin consent for [Your Tenant Name]** and confirm. All permissions should show as "Granted". ===== Configure Authentication Settings ===== Under **Authentication**, verify: * Redirect URIs include both `https://chipmunk.YOURDOMAIN` and `https://chipmunk.YOURDOMAIN:3000` * ✅ **ID tokens** checked under "Implicit grant and hybrid flows" ===== Step 7: Create Admin Group ===== Chipmunk uses an Entra ID (Azure AD) group to determine who has access to the dashboard. 1. In the Azure Portal, go to **Microsoft Entra ID** > **Groups** 2. Click **+ New Group** 3. Choose: * **Group Type**: Security * **Group Name**: e.g. ''chipmunkadmins'' * **Membership Type**: Assigned 4. Add any users who should be able to access the Chipmunk dashboard You will enter this exact **group name** during the appliance setup wizard. → Only members of this group will be granted admin access. ===== What to Use During Chipmunk Setup ===== When the Chipmunk appliance launches, you’ll enter: * ✅ Tenant ID * ✅ Client ID * ✅ Client Secret * ✅ Redirect URI domain (must match your DNS/cert setup) ----- Need help with DNS or TLS? → [[software:chipmunk:setup:certificate_dns|View DNS & Certificate Setup]] {{tag>chipmunk azure appregistration graphapi permissions setup}}