Skip to main content

Microsoft Setup

Configuring Microsoft Graph for use with Caddi

Updated over 2 months ago

Using Caddi with Microsoft Graph OAuth

Caddi supports two ways to authenticate against Microsoft Graph:

  1. Caddi Default Microsoft Graph Application (Caddi-Managed)

  2. Custom Entra OAuth Application (Customer-Managed)

This guide explains the difference between the two approaches and how to choose the right one for your organization.

Option 1: Caddi Default Microsoft Graph Application

What it is

Caddi hosts and maintains a shared Azure Entra application that already includes the necessary Microsoft Graph permissions for common workflows (e.g., accessing mail, calendars, files).

When to use it

  • Fastest path to getting started

  • Minimal IT effort: permissions, app registration, and consent are preconfigured

Key Considerations

  • Access: You can limit access to the Caddi Enterprise Application to specific users or groups (via “User assignment required”) and enforce Conditional Access.

  • Scopes: The permissions requested by the Caddi default app are fixed by Caddi; you can approve or deny them, but you can’t customize them. If you need custom or reduced scopes, use a customer‑managed Entra OAuth app.

Option 2: Custom Entra OAuth Application

What it is

Your IT team registers and manages its own Azure Entra ID application for Caddi. You control the OAuth configuration, including scopes, conditional access policies, and monitoring.

When to use it

  • Enterprises with strict security or compliance requirements

  • Organizations that require custom or reduced Graph scopes

  • Teams that want to align with internal governance policies for identity and access management

Key Considerations

  • Requires setup and ongoing management by your IT team

  • Full control over:

    • Which Microsoft Graph scopes are granted

    • How conditional access or MFA is enforced

    • Audit logging, monitoring, and review of OAuth tokens

  • More initial effort, but highest alignment with enterprise compliance practices

Decision area

Caddi Default Microsoft Graph OAuth

Custom Entra OAuth (customer‑managed)

Who can use the app

IT can require User assignment and assign users/groups; CA policies apply

Same

Scopes/permissions

Fixed (defined by Caddi). You can approve/deny, not change

Configurable by IT (choose only what you need)

Admin consent

Tenant‑wide grant for the app’s scopes, but effective only for allowed users/groups

Tenant‑wide grant for your chosen scopes

Conditional Access

Supported

Supported

Overhead

Lowest (fastest rollout)

High (you manage the app, scopes, reviews)

Custom Entra OAuth Application

Only applicable if you chose to go with Option 2 above.

Setup Instructions 📔

  1. Navigate to Microsoft Entra in the Azure portal here

  2. In the left bar, navigate to Identity > Applications > App Registrations

3. Click the New Registration button on the next page

4. Enter a name for the application, select Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox) , and provide a redirect URI (select Web) then click Register

5. Skip API permissions for now, see Permissions section of this article below to update.

6. On the Overview page, grab the Application (client) ID - this is the Oauth client ID

7. Click the Add a certificate or secret link, then click New client secret on the next page

8. Give the client secret a name and select an expiration time from the dropdown (default is fine)

9. Copy the new secret - this is the oauth client secret

Note that under the Authorization tab you should not tick the Access Tokens or ID Tokens boxes!

Permissions

How to add the required scopes

On the API Permissions page click Add a permission, then in the new panel click Microsoft Graph

On the next page of the panel, click Delegated permissions and then select all 4 OpenId permissions (offline_access, email, openid, and profile). Then search for the User.Read permission and add it. These 5 permissions are the mininum needed in order to be able to sign in with this Oauth application. Other permissions specific to individual APIs (such as Outlook or Teams) will be required as outlined at the end of this article.

Scopes to add

Microsoft provides a wide array of permissions spread across many possible APIs. We recommend selecting all of the scopes listed below for a given API for best compatibility with Caddi.

Items marked with a lock icon 🔒 indicate that a scope requires admin approval. This will only be necessary one time per scope, as the admin approval applies to the entire Oauth application, not just the user that requested it.

Teams

  • Member management

    • TeamMember.ReadWriteNonOwnerRole.All 🔒 - add/remove members with non-owner roles

  • Activity management (IE notifications)

  • Chats/messages for 1:1 and groups

    • Chat.ReadWrite - read and write user chat messages (1:1 and group, not channels)

    • Chat.Create - create chats

    • ChatMember.ReadWrite 🔒 - add and remove members from chats

  • Channels (separate from 1:1 and groups)

    • ChannelMessage.ReadWrite 🔒 - read and write messages in channels

    • Channel.Create 🔒 - create a new channel

    • Channel.Delete.All 🔒 - delete a channel

    • Channel.ReadBasic.All - read the names/descriptions of channels

  • Contacts

    • Contacts.ReadWrite - full access to user contacts

    • Contacts.ReadWrite.Shared - as above, but also for shared contacts

  • Calendars

    • Calendars.ReadWrite - full access to user calendars

    • Calendars.ReadWrite.Shared - and shared calendars

  • Meetings

    • OnlineMeetings.ReadWrite - read and create meetings

    • OnlineMeetingTranscript.Read.All 🔒- read meeting transcripts

  • Schedule (not full calendar)

    • Schedule.ReadWrite.All 🔒- read and write schedule items

  • Files (upload/download files to chat)

    • Files.ReadWrite.All - full access to user’s files including ones created by other users (that the current user has permissions to)

  • Users

    • User.Read.All - read all information from all users (e.g. get the email of the person in the Teams chat so you can send them an email)

Outlook

  • Mail

    • MailboxFolder.ReadWrite - read and write folders

    • MailboxItem.Read - read mailbox items

    • Mail.ReadWrite - create, read, update, and delete emails (not including sending)

    • Mail.ReadWrite.Shared - same, but also for shared mail/mail boxes

    • Mail.Send - send emails

    • Mail.Send.Shared - same, but also for shared mail/mail boxes

  • Contacts

    • Contacts.ReadWrite - manage contacts

    • Contacts.ReadWrite.Shared - same, but also for shared contacts

OneNote

  • Notes.ReadWrite.All - create, read, update, and delete notes and notebooks

SharePoint

  • Sites

    • Sites.ReadWrite.All - edit/delete items in site collections

    • Sites.FullControl.All 🔒 - full control of site collections

  • Files

    • Files.ReadWrite.All

  • Lists and ListItems

    • ListItems.SelectedOperations.Selected - access selected listitems

    • Lists.SelectedOperations.Selected - access selected lists

OneDrive and O365

These APIs only support one scope:

  • Files.ReadWrite.All - create, read, update, and delete files

Specific applications in the Office suite such as Word or Excel are not API-driven. Caddi Smart Tools will be used for these interactions.

Application and Permissions Approval/Consent Guidance

Azure Entra ID Permissions Configuration for Caddi

Quick Start Guide

This guide covers the essential permission configurations required for Caddi in Azure Entra ID at both the organization and application levels.

Organization-Level Permissions

Navigate to Entra ID → Enterprise Applications to configure the following:

1. Admin Consent Request Management

Path: Activity → Admin consent requests
Action: Configure approval workflow for application access requests across your Azure organization.

2. User Consent Settings

Path: Security → Consent and permissions → User consent settings
Action: Configure user consent controls.

⚠️ Important: If enforcing admin consent, do NOT select "Allow user consent for apps" - proceed to Admin consent settings instead.

3. Admin Consent Settings

Path: Security → Consent and permissions → Admin consent settings
Required Configuration:

  • Set "Users can request admin consent to apps they are unable to consent to" to Yes

  • Without this setting, users cannot access applications when admin consent is enforced

Additional Configuration:

  • Assign appropriate users/roles/groups as consent approvers (applies organization-wide)

  • App-specific approvers can be configured separately

4. Permission Classifications

Path: Security → Consent and permissions → Permission classifications
Action: Verify that required permissions are not classified as high-risk, which could block consent prompts.

Application-Specific Permissions (Caddi)

Navigate to Entra ID → Enterprise Applications → [Caddi Application] to configure:

1. Application Properties

Path: Manage → Properties
Required Settings:

  • "Enabled for users to sign-in": Yes

  • "Assignment required?": Configure based on organizational requirements

2. Self-Service Access

Path: Manage → Self-service
Required Settings:

  • "Allow users to request access to this application?": Yes

  • "To which group should assigned users be added?": Create and assign a dedicated Caddi group

  • "Require approval before granting access to this application?": If Yes, ensure approvers are configured

  • "Default Access role": Standard configuration is sufficient

3. Application Permissions

Path: Security → Permissions
Optional Action: Click "Grant admin consent for Caddi" to pre-approve permissions for all users

4. Access Reviews

Path: Activity → Access reviews
Action: Monitor and audit user access and permission levels

General Recommendations for Standard Organizations

For organizations with standard security requirements, the following configuration provides a good balance of security and user convenience:

Recommended Settings

  • User consent settings: Allow user consent for apps from verified publishers

  • Assignment required?: Set to No for easier user onboarding

  • Self-service access: Enable with automatic approval (no approvers required)

  • Admin consent: Pre-grant admin consent for Caddi to eliminate permission prompts

  • Dedicated group: Optional - only create if you need to track or manage Caddi users specifically

Benefits of This Approach

  • Users can access Caddi immediately without waiting for approvals

  • Reduces administrative overhead

  • Maintains reasonable security through verified publisher requirements

  • Simplifies the user experience

Recommendations for Organizations with Strict Permission Controls

Essential Configuration

  • Enable admin consent requests in admin consent settings - without this, users cannot request access when admin consent is enforced

  • Create a dedicated Caddi user group for simplified access management and clear visibility

  • Test the consent workflow early with an end-user to ensure smooth deployment

Simplifying Access Management

Access to the application and permission consent are separate processes. To streamline administration:

  • Pre-approve application permissions (grant admin consent)

  • Require approval only for application access (group membership)

  • This approach allows admins to focus solely on group membership management

Critical Warning

⚠️ Incorrect configuration combinations will prevent user access. Test thoroughly with a basic-permission test account or actual end-user before widespread deployment to avoid access issues during onboarding.

Did this answer your question?