Microsoft OAuth (Third-Party Account) — Setup Guide

Overview Use this guide to register a Delegated Microsoft app in Azure and connect it to your system as a “Third Party (Microsoft)” OAuth account. The app enables end-users to:

• Read/write/create/delete SharePoint/OneDrive files and folders
• Read and send email from their mailbox
• Read/write Teams chats and send channel messages (where supported in delegated context)
• Read/write calendar events

This document provides the exact permissions to grant, the redirect/authorization URLs to use, and the values to enter in your application. All values below use placeholders—replace them with your own.

---

1) Register a New App in Azure

1. Sign in to Azure Portal → Microsoft Enter ID → App registrations → New registration.

2. Name: e.g., MinuteView (Delegated).

3. Supported account types: Choose what fits your scenario (single tenant or multi-tenant).

4. Redirect URI (web):

   • Use your production callback URL (see “Fields to Enter in Your App” below), e.g. https://your-domain/MinuteView/PageGeneral/ServiceCallback.aspx

5. Click Register.

---

2) Collect App Credentials

From the app’s Overview page:

• Application (client) ID: YOUR-CLIENT-ID
• Directory (tenant) ID: YOUR-TENANT-ID

Create a Client secret:

1. Certificates & secrets → New client secret.
2. Copy and store the generated value securely: YOUR-CLIENT-SECRET.

---

3) Add Microsoft Graph Delegated Permissions

Go to API permissions → Add a permission → Microsoft Graph → Delegated permissions. Add:

SharePoint / OneDrive (Files)

• Files.ReadWrite.All
• Sites.ReadWrite.All

Mail (Read/Send)

• Mail.Read
• Mail.Send

Teams (Chats & Channel Messages)

• Chat.ReadWrite
• Contacts.Read
• ChannelMessage.Send
• TeamsActivity.Send (optional: for activity feed notifications)

Note: Teams APIs in delegated context operate within the signed-in user’s membership and tenant policies. Some Teams graph operations require Application permissions; this guide is strictly for Delegated.

Calendar

• Calendars.ReadWrite

OpenID Connect / Basic profile & offline access

• openid
• profile
• email
• offline_access

When your tenant enforces admin consent, click Grant admin consent for your organization.

---

4) Authorization & Token Endpoints (v2.0)

• Authorize endpointhttps://login.microsoftonline.com/{TenantId}/oauth2/v2.0/authorize

• Token endpointhttps://login.microsoftonline.com/{TenantId}/oauth2/v2.0/token

Replace {TenantId} with your tenant GUID or common/organizations if multi-tenant behavior is intended.

---

5) Recommended Authorization Request

Use the Authorization Code flow. Two common patterns for scope:

.default scope (uses app’s configured permissions)

response_type=code
scope=https://graph.microsoft.com/.default offline_access

.default relies on the permissions you configured in API permissions, typically requires admin consent up front.

---

6) Token Exchange (Server-Side)

When your app receives the code at the callback:

• POST to the token endpoint with:

  • client_id={ClientId}
  • client_secret={ClientSecret}
  • grant_type=authorization_code
  • code={authorization_code_from_callback}
  • redirect_uri={exact_same_redirect_uri}
  • scope={same scope pattern used in authorize step (if needed)}

You’ll receive:

• access_token (short-lived; use for Graph calls)
• refresh_token (because of offline_access; store securely to renew access tokens)

---

7) Testing Checklist

• Sign in with a user who has access to the target SharePoint sites/Teams/mailbox.

• Call sample endpoints to validate each capability:

  • Files: GET /me/drive/root/children and PUT /me/drive/root:/path/file.ext:/content
  • SharePoint: GET /sites/{site-id}/drive/root/children
  • Mail: GET /me/messages, POST /me/sendMail
  • Teams: GET /me/chats, POST /teams/{team-id}/channels/{channel-id}/messages
  • Calendar: GET /me/events, POST /me/events

• Confirm refresh token rotation works and tokens are stored securely.

---

8) Security & Consent Notes

• Treat Client Secret and refresh tokens as sensitive; store in a secure secret store.
• In restricted tenants, an admin must Grant admin consent for the Graph permissions.
• For multi-tenant apps, consider a consent page and tenant-scoped storage for tokens.
• Limit permissions to least privilege where possible; the list above reflects broad capabilities requested.

---

9) Troubleshooting

• 50011: Redirect URI mismatch → ensure the callback URL in the request exactly matches one of the app’s registered Redirect URIs.
• Insufficient privileges: Missing tenant admin consent or the user lacks resource permissions (e.g., SharePoint site access).
• Teams APIs: Some operations require Application permissions; verify that your use case is supported with Delegated.
• .default not honoring scopes: Ensure all required permissions are added under API permissions and admin consent was granted.

---

Appendix — Example URL Templates

Replace placeholders and URL-encode {redirect_uri}.

Authorize URL (.default pattern):

https://login.microsoftonline.com/{TenantId}/oauth2/v2.0/authorize
  ?client_id={ClientId}
  &response_type=code
  &redirect_uri={UrlEncodedCallbackUrl}
  &response_mode=query
  &scope=https://graph.microsoft.com/.default offline_access
  &state={TokenId}

Token URL:

POST https://login.microsoftonline.com/{TenantId}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id={ClientId}
&client_secret={ClientSecret}
&grant_type=authorization_code
&code={CodeFromAuthorizeCallback}
&redirect_uri={ExactSameCallbackUrl}

---

Permission Summary (Delegated)

• Files.ReadWrite.All, Sites.ReadWrite.All
• Mail.Read, Mail.Send
• Chat.ReadWrite, ChannelMessage.Send, TeamsActivity.Send (optional)
• Calendars.ReadWrite
• openid, profile, email, offline_access

This set enables the user to read/write files in SharePoint/OneDrive, read and send email, read/write Teams chats and send channel messages (within delegated constraints), and read/write calendar events.