An API that connects multiple Microsoft services, enabling data access and automation across platforms
Persist a securely serialized MSAL token cache per user in your database or distributed cache, rather than designing a table that directly reads, writes, and refreshes individual refresh-token strings.
Microsoft explicitly recommends securely persisting the token cache between application instances, with encryption and access control tied to the owning user or workload identity.^1^
Recommended design
- Use authorization code flow with a confidential server-side client.
- Request the delegated Graph permission required for event subscriptions, such as
Calendars.Read. - Explicitly request
offline_accesson the v2 endpoint so that a refresh token can be issued.^2^
- Request the delegated Graph permission required for event subscriptions, such as
- Let MSAL own the refresh tokens.
- After redeeming the authorization code, MSAL stores the access token, refresh token, account metadata, and expiration information in its cache.
- Your renewal worker calls silent token acquisition. MSAL returns a valid cached access token or uses the cached refresh token when necessary.^3^
- Do not parse access tokens or implement refresh-token rotation manually when MSAL supports your platform.
- Persist one encrypted cache partition per user.
- A suitable cache key is a stable account identifier incorporating both user and tenant, rather than an email address or UPN.
- Microsoft recommends one token cache per account for web applications, serialized separately for security and scalability.^4^
- The database record should contain an opaque serialized MSAL cache blob—not columns exposing individual access and refresh tokens.
- Protect the cache as credential material.
- Encrypt cache contents at rest and in transit.
- Keep the encryption key separate from the database, preferably in Azure Key Vault or an equivalent hardened key-management service.
- Grant decrypt/read access only to the renewal workload’s identity.
- Enable audit logging and network restrictions, and exclude cache contents from application logs, traces, exception messages, and backups exported without equivalent protection.^5^
For Microsoft.Identity.Web, encryption of the distributed token cache can be enabled as follows:
services.AddDistributedSqlServerCache(options =>
{
options.ConnectionString = configuration["ConnectionStrings:TokenCache"];
options.SchemaName = "dbo";
options.TableName = "TokenCache";
});
services.AddDistributedTokenCaches();
services.Configure<MsalDistributedTokenCacheAdapterOptions>(options =>
{
options.Encrypt = true;
});
For a multi-instance deployment, all instances must share the ASP.NET Core Data Protection key ring; otherwise, one instance may be unable to decrypt cache entries written by another. Microsoft documents protecting the shared key ring with Azure Key Vault.^6^
Refresh-token lifecycle
Refresh tokens must be treated like access tokens or application credentials. When redeemed, Microsoft Entra can return a replacement refresh token. The old token is not automatically revoked merely because it was used, so implementations managing raw tokens must securely delete the old value after storing the replacement.^7^
Using MSAL avoids having to implement that replacement logic directly. Nevertheless:
- Refresh tokens can expire or be revoked before their normal expiration.
- If silent acquisition reports that interaction is required, mark that user connection as requiring reauthorization and send the user through interactive sign-in again.
- Do not assume continued background access is guaranteed indefinitely.
- Avoid concurrent refresh operations for the same cache partition; use cache-level concurrency control so that a newer serialized cache is not overwritten by stale data.
Subscription renewal behavior
Track each Graph subscription’s ID, user/account key, tenant, and expiration separately from the token cache. Before expiration, the worker should:
- Load the user’s MSAL cache partition.
- Acquire a Graph access token silently.
- Update the subscription expiration.
- Persist any cache changes made by MSAL.
Graph requires Outlook subscriptions to be extended before they expire; delegated permissions cover only the signed-in user’s mailbox. Calendars.Read is the least-privileged delegated permission documented for event subscriptions.^8^
Also configure lifecycleNotificationUrl when creating subscriptions. Handle reauthorizationRequired, subscriptionRemoved, and missed events. Renewing a subscription also reauthorizes it, but reauthorization alone does not extend its expiration.^9^
In short: an encrypted database is an acceptable persistence layer, but persist MSAL’s encrypted, per-user token cache rather than treating refresh tokens as ordinary application data.
References
- Increase the resilience of authentication and authorization in client applications you develop
- Scopes and permissions in the Microsoft identity platform
- Acquire and cache tokens using the Microsoft Authentication Library (MSAL)
- Microsoft identity platform best practices and recommendations
- Best practices for protecting secrets
- Token cache in Microsoft.Identity.Web
- Refresh tokens in the Microsoft identity platform
- Change notifications for Outlook resources in Microsoft Graph
- Reduce missing subscriptions and change notifications