Guidance on secure storage of OAuth refresh tokens (delegated access) for Microsoft Graph Outlook event subscriptions in a multi-tenant app

Bourai, Nitin 0 Reputation points
2026-11-20T09:18:13.35+00:00

We are building a multi-tenant application that receives Outlook calendar events from our customers’ mailboxes via Microsoft Graph change notifications (webhooks).

  • Authorization model: Delegated permissions. Each user grants consent individually.
  • Scale: Potentially thousands of users across multiple tenants.
  • Subscription lifecycle: Graph subscriptions for Outlook events expire after a short period (a few days), so we must renew them continuously. Because the renewals run in the background without user interaction, we need to acquire access tokens silently using refresh tokens.

Current approach We plan to persist each user’s refresh token (encrypted token) in our database so a background service can obtain new access tokens and renew subscriptions

Questions :
Does this align with Microsoft guidance to store the refresh token in database?

can you please share guidance from Microsoft, any reference documents or standards for storing refresh token in database.

Microsoft Security | Microsoft Graph
0 comments No comments

1 answer

Sort by: Most helpful
  1. AI answer

    2026-11-20T09:19:15.58+00:00

    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^

    1. 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_access on the v2 endpoint so that a refresh token can be issued.^2^
    2. 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.
    3. 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.
    4. 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:

    1. Load the user’s MSAL cache partition.
    2. Acquire a Graph access token silently.
    3. Update the subscription expiration.
    4. 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

    1. Increase the resilience of authentication and authorization in client applications you develop
    2. Scopes and permissions in the Microsoft identity platform
    3. Acquire and cache tokens using the Microsoft Authentication Library (MSAL)
    4. Microsoft identity platform best practices and recommendations
    5. Best practices for protecting secrets
    6. Token cache in Microsoft.Identity.Web
    7. Refresh tokens in the Microsoft identity platform
    8. Change notifications for Outlook resources in Microsoft Graph
    9. Reduce missing subscriptions and change notifications
    AI-generated content may be incorrect. Read our transparency notes for more information.

    Was this answer helpful?

Your answer

Answers can be marked as 'Accepted' by the question author and 'Recommended' by moderators, which helps users know the answer solved the author's problem.