Architecting Solutions with Microsoft Graph API
Microsoft Entra Authentication
Getting Authorized
Before your application can read a user's emails or update a calendar event through the Microsoft Graph API, it needs permission. It gets this permission by first establishing an identity with Microsoft's cloud-based identity service, Microsoft Entra ID (formerly known as Azure Active Directory). Think of it as your app getting its own official ID card for the Microsoft 365 ecosystem.
The first step is registering your application in the Microsoft Entra admin center. This process is like applying for that ID card. Once registered, your application is assigned a few key pieces of information it will use to identify itself:
- Application (Client) ID: A unique identifier for your app, like a username.
- Directory (Tenant) ID: Identifies the specific Microsoft Entra directory (your organization) where the app is registered.
- Client Secret or Certificate: A confidential credential that your app uses to prove its identity, like a password. You must keep this secure.
These credentials are the foundation of your app's security. They allow Microsoft Entra ID to confirm that any request it receives is coming from a legitimate, registered application.
How Your App Asks for Permission
Simply having an ID isn't enough. Your app also needs to declare what it wants to do. This is handled through permissions, which fall into two distinct categories.
Delegated Permissions
adjective
The application acts on behalf of a signed-in user. The app's effective permissions are the intersection of what the user can do and what the app has been granted. This is the model for user-facing applications, like a web app that shows a user their own files.
When using delegated permissions, a user must sign in and consent to the permissions the app is requesting. The app is essentially borrowing the user's identity to perform actions.
Application Permissions
noun
The application acts on its own, with no user present. These permissions are typically used for background services or daemon apps, such as a script that runs nightly to archive old documents. Since no user is present to grant consent, an administrator must grant consent for the entire organization.
The specific permissions you request are called scopes. For instance, if you want your app to read a user's email, you'd request the Mail.Read scope. If it needs to run as a background service and read all mailboxes, you'd request the Mail.Read application permission. It is a critical security best practice to follow the and only request the scopes your application absolutely needs to function.
Acquiring an Access Token
Once your app is registered and permissions are configured, it can request an access token from Microsoft Entra ID. This token is a digitally signed string of text that proves your app is authorized to access specific resources. It's like a temporary key card that grants access to certain rooms for a limited time.
The process of getting this token follows industry-standard protocols, primarily OAuth 2.0. Here are the two most common flows:
| Flow | When to Use It | Description |
|---|---|---|
| Authorization Code Flow | Apps with a signed-in user (delegated permissions) | A multi-step process where the user logs in via a browser, grants consent, and an authorization code is sent to the app. The app then exchanges this code for an access token. |
| Client Credentials Flow | Apps without a user (application permissions) | A simpler, direct flow where the application sends its Client ID and Client Secret to Entra ID and receives an access token in return. |
Managing these flows, handling token caching, and refreshing expired tokens can be complex. To simplify this, Microsoft provides the Microsoft Authentication Library (MSAL). MSAL is a set of libraries for various languages that abstracts away the complexity of the OAuth 2.0 protocol. You tell MSAL what kind of app you're building and which permissions you need, and it handles the token acquisition and management for you.
The Microsoft Graph API provides access to Microsoft 365 data and services, such as allowing developers to programmatically interact with Excel files stored in SharePoint.
The access token you receive is a JSON Web Token (JWT). It contains claims, which are pieces of information about your application and the permissions it has been granted. When you make a call to the Microsoft Graph API, you include this token in the Authorization header of your HTTP request. The Graph API validates the token's signature and checks its claims to ensure your app has permission to perform the requested operation.
What is the primary role of Microsoft Entra ID when building an application that uses the Microsoft Graph API?
Your application needs to run a background service that scans all user mailboxes for compliance reasons, without any user being signed in. What type of permission should you request?