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 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? → View DNS & Certificate Setup

This is step 1 of the four-step Chipmunk setup. Next: Azure Storage Setup.

---

Common questions

Q: Do I need both Microsoft Graph and Exchange permissions?

• Yes. Microsoft Graph covers OneDrive, Teams chat, and modern Exchange Online APIs. Exchange Web Services (EWS) covers the deeper mailbox archive scenarios that Graph doesn't fully expose yet (especially around shared mailboxes and certain item types). Chipmunk uses whichever path is most reliable for each item type, so the app registration needs admin-consented permissions on both.

Q: My organisation requires app registrations to be reviewed before admin consent. What do I tell our security team?

• The app needs application (not delegated) permissions for read across OneDrive, Exchange mailboxes, and Teams chat - all read-only. It doesn't need write permissions because the data is copied out to your own Azure Blob Storage, not modified in-place in Microsoft 365. Point your security team at the explicit permission list above; everything Chipmunk does in Graph is read-only.

Q: Can I rotate the client secret without re-running the entire setup?

• Yes. Generate a new secret in the App Registration, then update it in the appliance via the Configuration page. Tenant ID and Application (client) ID stay the same; only the secret value changes. Old secrets expire on Entra's normal rotation schedule.

Q: What if I already have a Chipmunk-like App Registration from another tool?

• You can reuse it as long as it has all the permissions Chipmunk needs. In practice it's cleaner to create a dedicated ChipmunkApp registration so the audit trail in Entra ID and the Monitoring & Logs on the appliance clearly attribute reads to Chipmunk rather than mixing them with another tool's activity.

Q: I don't see Chipmunk reading any data after setup. Where do I look?

• Three things to check, in order: (1) the App Registration has admin consent applied (not just permissions granted), (2) the Tenant ID, Client ID, and Client Secret were entered correctly during First-Time Configuration, and (3) the admin group you specified actually contains the user account you signed in with. Errors from any of these surface in the appliance logs covered on the Monitoring & Logs page.