First instinct: call the API straight from the web part. It works in twenty minutes. Then you press F12, open the network tab, click any request… and there it is. The company’s master API key, in plain text, readable by every single user who ever loads that intranet page.

And it’s not “they can see the data the web part shows anyway” - the web part shows a filtered slice. The key unlocks the whole API: every customer, every record, every write operation the key is licensed for. Anyone who copies it out of the inspector can call the API from Postman on their couch.

Why the Browser Can’t Keep a Secret

It’s worth being blunt about this, because the temptation to “just obfuscate it a bit” is real:

• Everything the browser sends is in the network tab.
• Everything the bundle contains is in the sources tab (source maps or not, strings are strings).
• Everything the app holds in memory is one breakpoint away.

There is no hiding place in the client. And “it’s only our internal SharePoint” doesn’t help - internal users are exactly the people who shouldn’t be walking around with the master key to a system they’re only supposed to see a corner of.

The Proxy Function

The fix is a small reverse proxy. One catch-all Azure Function fronts the entire third-party API:

private static readonly HashSet<string> _hopByHop = new(StringComparer.OrdinalIgnoreCase)
{
    "Connection", "Keep-Alive", "Proxy-Authenticate", "Proxy-Authorization",
    "TE", "Trailer", "Transfer-Encoding", "Upgrade"
};

[Function("ApiProxy")]
public async Task<IActionResult> Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", "put", "delete",
                 Route = "api/{*path}")] HttpRequest request,
    string? path,
    CancellationToken ct)
{
    var targetUri = _settings.BaseUrl.TrimEnd('/') + "/" + (path ?? "")
                  + (request.QueryString.Value ?? "");

    using var upstream = new HttpRequestMessage(new HttpMethod(request.Method), targetUri);

    if (request.Method is "POST" or "PUT" || request.ContentLength is > 0)
    {
        upstream.Content = new StreamContent(request.Body);
        if (request.ContentType is not null)
            upstream.Content.Headers.TryAddWithoutValidation("Content-Type", request.ContentType);
    }

    foreach (var (key, values) in request.Headers)
    {
        // Never forward the client's Host, any API key they try to sneak in,
        // or hop-by-hop headers that belong to *this* connection only.
        if (key.Equals("Host", StringComparison.OrdinalIgnoreCase) ||
            key.Equals("X-Api-Key", StringComparison.OrdinalIgnoreCase) ||
            _hopByHop.Contains(key))
            continue;

        if (!upstream.Headers.TryAddWithoutValidation(key, (IEnumerable<string?>)values!))
            upstream.Content?.Headers.TryAddWithoutValidation(key, (IEnumerable<string?>)values!);
    }

    // The swap. The secret exists only here, on the outbound leg.
    upstream.Headers.Add("X-Api-Key", _settings.ApiKey);

    var client = _httpClientFactory.CreateClient("upstream-api");
    using var response = await client.SendAsync(upstream, HttpCompletionOption.ResponseHeadersRead, ct);

    _logger.LogInformation("Proxy: {Method} {Path} → {StatusCode}", request.Method, path, (int)response.StatusCode);

    var httpResponse = request.HttpContext.Response;
    httpResponse.StatusCode = (int)response.StatusCode;

    foreach (var (key, values) in response.Headers.Concat(response.Content.Headers))
    {
        if (_hopByHop.Contains(key)) continue;
        httpResponse.Headers.Append(key, values.ToArray());
    }

    await response.Content.CopyToAsync(httpResponse.Body, ct);
    return new EmptyResult();
}

What’s happening here?

1. Route = "api/{*path}" is a catch-all. GET /api/customers/123/tasks becomes GET https://the-api.example/customers/123/tasks, query string included. One function fronts the whole API surface - when the vendor adds endpoints, the proxy needs zero changes.
2. The header loop deliberately strips any inbound X-Api-Key. A caller can’t inject their own key or override yours - whatever they send in that header dies at the proxy.
3. The hop-by-hop set (Connection, Transfer-Encoding, …) is the detail naive proxies get wrong. Those headers describe one connection, not the request; forwarding them causes wonderfully confusing breakage.
4. The real key is added to the outbound request only. Response headers get copied back to the browser, but request headers are never echoed - so the key physically cannot appear in the inspector. It’s not hidden; it’s absent.
5. ResponseHeadersRead + CopyToAsync streams the upstream response straight through without buffering it in the function’s memory, and upstream status codes pass through untouched so the web part can react to a 404 or a 429 honestly.

Where the Key Lives

Server-side config, strongly typed, validated at boot:

services.AddOptions<ApiSettings>()
    .Bind(configuration.GetSection("UpstreamApi"))
    .Validate(s => IsConfigured(s.BaseUrl), "UpstreamApi:BaseUrl must be configured.")
    .Validate(s => IsConfigured(s.ApiKey), "UpstreamApi:ApiKey must be configured.")
    .ValidateOnStart();

private static bool IsConfigured(string value) =>
    !string.IsNullOrWhiteSpace(value) && !value.StartsWith('<');

The value itself comes from Function App settings - ideally as a Key Vault reference - never from a committed file. ValidateOnStart() plus the <placeholder> guard means a misconfigured secret fails the deployment at boot, not at the first user’s click three days later.

Hiding ≠ Authorizing

Here’s the part that’s easy to skip and shouldn’t be: as shown so far, the proxy hides the key from the browser, but anyone who discovers the function URL can call it - and burn your API quota with your key. We’ve moved the secret, not secured the door.

Lock the function to Entra ID. Create an app registration for the function API, expose a scope (the convention is access_as_user), and have the function validate incoming JWTs - signature, issuer, and audience, not just parsing the claims out. Parsing is reading the name tag; validating is checking the ID.

On the SPFx side, this is pleasantly little work. Declare the permission in package-solution.json:

"webApiPermissionRequests": [
  {
    "resource": "my-function-api",
    "scope": "access_as_user"
  }
]

And call the function with AadHttpClient - SPFx acquires and attaches the user’s token for you:

const client = await this.context.aadHttpClientFactory
  .getClient("api://<function-app-registration-client-id>");

const response = await client.get(
  `https://my-function.azurewebsites.net/api/customers/${customerCode}/tasks`,
  AadHttpClient.configurations.v1
);

Now open the inspector again. There is a token in the request - but it’s the user’s own token: short-lived, scoped to your function only, and useless against the third-party API. That’s the whole difference between a secret and an identity. A stolen API key is everyone’s master key forever; a stolen user token is one person’s function access for an hour.

Gotchas

• Watch what you log. Log method, path, and status - never headers. Otherwise the key you carefully kept out of the browser ends up in Application Insights, readable by everyone with portal access.
• You now front someone else’s quota. The vendor’s rate limits hit your key for all users combined. If the web part is chatty, add caching or throttling in the proxy before the vendor does it for you.
• CORS is on you. The browser is calling your function from a SharePoint origin - configure CORS on the Function App for your tenant’s SharePoint domain, not *.
• Consider narrowing the surface. A catch-all proxy forwards everything, including endpoints the web part never needed. If the API has destructive operations, whitelist the methods and paths you actually use.

Wrapping Up

A shared API key belongs on a server. Full stop. The moment it ships to a browser, every user has it, and you can’t take it back - most vendors will happily rotate the key for you, but you’ll be doing that dance on their schedule, not yours.

The proxy costs about fifty lines: catch-all route, header hygiene, one server-side header swap, and Entra ID on the front door. That turns “every intranet user carries the master key” into “every request is a named user, calling a locked endpoint, seeing exactly what the web part shows them”. 🔒

And in that second post I wrote one very casual line: “The token comes from MSAL.”

Yeah. About that.

On desktop, MSAL gets a token by opening a browser popup where the user signs in. On mobile there is no browser. Your add-in runs in a WebView inside the Outlook app. There’s no window to pop, no tab to redirect, nowhere for the classic OAuth dance to happen. My first attempt at calling Graph from the phone died right there, not on the API call, on the sign-in before it.

The fix has a name: Nested App Auth (NAA).

Why Normal MSAL Dies on Mobile

The standard MSAL flows (loginPopup, loginRedirect) both assume your code lives in a browser. A popup needs window.open. A redirect needs the page to navigate away to login.microsoftonline.com and come back with your app still knowing what it was doing.

Inside Outlook on iOS or Android, neither is true. You’re in a WKWebView (or the Android equivalent) that Outlook controls. window.open goes nowhere useful, and a redirect would navigate the task pane itself into oblivion.

But think about what’s around your WebView: the Outlook app. A fully signed-in, Microsoft-identity-aware native app that already knows exactly who the user is. NAA is the mechanism that lets your nested add-in say “hey host, you handle the identity stuff” and get tokens brokered through Outlook itself. When silent brokering isn’t enough, the host hands off to Microsoft Authenticator for the interactive part, a real native auth experience instead of a popup that can’t exist.

The Azure Part: One Weird Redirect URI

Before any code, your Entra app registration needs to opt in to being brokered. That’s done with a redirect URI of type Single-page application in this format:

brk-multihub://your-add-in-domain.com

Origin only, no subpaths:

• ✅ brk-multihub://contoso.com
• ✅ brk-multihub://localhost:3000 (for dev)
• ❌ brk-multihub://contoso.com/taskpane

This URI is you telling the Microsoft identity platform: “I consent to having my auth brokered by trusted Microsoft 365 hosts.” The multihub part means it’s not just Outlook, the same registration works when your add-in runs brokered inside Word, Excel, PowerPoint, or Teams.

One extra note if your add-in also runs in Word/Excel/PowerPoint on the web: those need an additional plain SPA redirect URI pointing at the actual page that requests tokens (your taskpane HTML), because the browser there still uses a standard flow.

The MSAL Part: One Config, Two Worlds

Here’s the neat thing about how NAA lands in code: you don’t write a mobile version and a desktop version. You write one init function and let it fall back.

import {
  createNestablePublicClientApplication,
  PublicClientApplication,
  type IPublicClientApplication,
  type Configuration,
} from "@azure/msal-browser";

let isNAAMode = false;

async function initMsal(): Promise<IPublicClientApplication> {
  const msalConfig: Configuration = {
    auth: {
      authority: "https://login.microsoftonline.com/common",
      clientId: clientId,
      supportsNestedAppAuth: true,
    },
  };

  try {
    const app = await createNestablePublicClientApplication(msalConfig);
    isNAAMode = true;
    return app;
  } catch {
    // NAA unavailable - fall back to standard MSAL
    isNAAMode = false;
    const app = new PublicClientApplication(msalConfig);
    await app.initialize();
    return app;
  }
}

What’s happening here?

1. supportsNestedAppAuth: true flags the config as NAA-capable. Without it, nothing brokers.
2. createNestablePublicClientApplication tries to hook into the host’s broker. Inside Outlook mobile, it succeeds. In a plain browser tab or an older host, it throws.
3. The catch is the desktop path. Same fallback philosophy as the Graph post: don’t ask “am I on mobile?”, try the capability and let the failure route you. One codebase, two auth worlds, zero platform sniffing.
4. Small but important: initialize this lazily, after Office.onReady() has resolved. The broker hookup needs the Office context to actually be there.

Getting a Token: Let the Host Do the Remembering

In classic MSAL you manage accounts yourself: call getAllAccounts(), pick one, pass it to acquireTokenSilent. In NAA mode you don’t have to, the broker owns the accounts. You just give it a hint about who you expect:

function getLoginHint(): string | undefined {
  return Office.context?.mailbox?.userProfile?.emailAddress ?? undefined;
}

async function getToken(scopes: string[]): Promise<string> {
  const app = await getMsalInstance();

  if (isNAAMode) {
    try {
      const result = await app.acquireTokenSilent({
        scopes,
        loginHint: getLoginHint(),
      });
      return result.accessToken;
    } catch {
      // Silent failed - interactive fallback
    }

    // On mobile this doesn't open a browser popup -
    // the host hands off to the Microsoft Authenticator app
    const result = await app.acquireTokenPopup({ scopes });
    return result.accessToken;
  }

  // Non-NAA (desktop/web): the classic dance -
  // getAllAccounts() → acquireTokenSilent(account) → popup on interaction_required
  return getTokenClassic(app, scopes);
}

What’s happening here?

1. The loginHint is just the signed-in mailbox owner’s email, straight from Office.context.mailbox.userProfile. The broker uses it to resolve the right account, which is exactly the account the user is already signed into Outlook with. No account picker, no cache management.
2. acquireTokenSilent with that hint succeeds almost every time, because of course it does, the user is signed in, that’s how they’re reading their email.
3. When interaction is genuinely needed (first consent, revoked session), acquireTokenPopup doesn’t open a popup on mobile despite its name. The host routes it to Microsoft Authenticator, and the user gets a native sign-in experience that actually works on a phone.
4. The non-NAA branch keeps doing what MSAL apps have always done on desktop. Two branches in one function, and the caller just says getToken(scopes) and never knows which world it’s in.

The first time I watched the Authenticator app slide up over Outlook, approve, and slide away with my Graph call succeeding behind it, it felt like cheating. In a good way. 🎉

Gotchas I Hit Along the Way

• The redirect URI must be SPA type. Adding brk-multihub://... under “Web” or “Mobile and desktop applications” in the app registration silently doesn’t work. It goes under Single-page application, even though nothing about it looks like a page.
• Origin only. brk-multihub://contoso.com/taskpane fails validation. Trim it to the origin.
• MSAL.js v3+. createNestablePublicClientApplication doesn’t exist in v2. Check your @azure/msal-browser version before you spend an hour on confusing import errors.
• No B2C. NAA supports Microsoft accounts and Entra ID work/school accounts. If you’re on Azure AD B2C, this door is closed.

Wrapping Up

That’s the trilogy done. Three posts, one theme: on mobile you don’t get to demand things, you get to ask and adapt.

• The manifest post got us in the door: declare a low requirement floor so mobile shows the add-in at all.
• The Graph fallback post got us the bytes: when the Office.js API isn’t there, fetch the same email from Graph.
• This post got us the token: when there’s no browser to pop, let Outlook broker the auth and Authenticator handle the interaction.

Same shape every time: try the capability, catch the failure, take the other road. Mobile support isn’t one big feature, it’s a stack of small fallbacks that each pretend nothing happened.

Microsoft Graph is the unified REST API for Microsoft 365. Think of it as a single gateway to access data across SharePoint, Teams, OneDrive, Outlook, Entra ID, and more, all through one consistent API.

Graph vs CSOM/PnP.Framework:

• Graph: Modern REST API, works across all Microsoft 365 services
• CSOM/PnP: SharePoint-specific, more SharePoint features available

When to Use Graph SDK vs PnP.Framework

Reach for the Graph SDK when you need Teams, OneDrive, Exchange or Entra ID data, when you want the built-in retry and batching, or when the feature spans several Microsoft 365 services.

Reach for PnP.Framework when you need the SharePoint-specific surface: site templates, provisioning, taxonomy, search refiners, managed metadata, content types.

Graph won’t help you with SharePoint classic features like master pages and web parts, its search is thinner than the SharePoint Search API, and it can’t talk to SharePoint Server on-premises at all.

Which SDK Version Are You On?

This is the part that costs people an afternoon, so it comes before the code.

The .NET SDK was rewritten in v5. It moved to Kiota-generated clients, and .Request() was removed from every call. That one change means a v4 sample does not compile on v5, and a v5 sample does not compile on v4. Most of the samples you’ll find online, including the first version of this post, are v4.

v6 is the current major, and v5 code compiles on it unchanged. I checked: the same file builds clean against 5.105.0 and 6.5.0. So there are really two dialects to care about, not three.

# current: v5 syntax, v6 package
dotnet add package Microsoft.Graph --version 6.5.0

# legacy: only if you're pinned to v4 already
dotnet add package Microsoft.Graph --version 4.54.0

Pin it. Install-Package Microsoft.Graph with no version gives you the newest major, and if you then paste a v4 sample into it you get a wall of does not contain a definition for 'Request'.

One thing to get out of the way: there is no Microsoft.Graph.Auth package. It never had a stable release and the namespace doesn’t exist in v4, v5 or v6. If a sample tells you to add using Microsoft.Graph.Auth;, that sample predates all of this. You want Azure.Identity.

dotnet add package Azure.Identity

Add Graph Permissions

In your existing app registration, go to “API permissions” then “Add a permission” then “Microsoft Graph” then “Application permissions”:

• Sites.ReadWrite.All: SharePoint sites and lists access

Click “Grant admin consent” after adding permissions, or every call comes back 403.

The Code, v5 and v6

Same certificate and app registration as the PnP.Framework post.

using Azure.Identity;
using Microsoft.Graph;
using Microsoft.Graph.Models;
using System.Security.Cryptography.X509Certificates;

class Program
{
    private static readonly string TenantId = "<tenant-id>";
    private static readonly string ClientId = "<client-id>";
    private static readonly string CertificatePath = @"C:\Temp\cert\appcert.pfx";
    private static readonly string CertificatePassword = "<password>";

    static async Task Main(string[] args)
    {
        var certificate = X509CertificateLoader.LoadPkcs12FromFile(CertificatePath, CertificatePassword);
        var options = new ClientCertificateCredentialOptions
        {
            AuthorityHost = AzureAuthorityHosts.AzurePublicCloud,
        };

        var credential = new ClientCertificateCredential(TenantId, ClientId, certificate, options);
        var scopes = new[] { "https://graph.microsoft.com/.default" };

        var graphClient = new GraphServiceClient(credential, scopes);

        var org = await graphClient.Organization.GetAsync();
        Console.WriteLine($"Connected to: {org?.Value?.FirstOrDefault()?.DisplayName}");

        var site = await graphClient.Sites["root"].GetAsync();
        var lists = await graphClient.Sites[site.Id].Lists.GetAsync();

        Console.WriteLine("Lists in this site:");
        foreach (var list in lists?.Value ?? [])
        {
            Console.WriteLine($"- {list.DisplayName}");
        }

        var docLib = (lists?.Value ?? []).FirstOrDefault(l => l.DisplayName == "Documents");
        if (docLib != null)
        {
            var content = System.Text.Encoding.UTF8.GetBytes("Hello from Graph SDK!");
            var drive = await graphClient.Sites[site.Id].Lists[docLib.Id].Drive.GetAsync();

            var file = await graphClient.Drives[drive.Id]
                .Items["root:/sample-document.txt:"]
                .Content
                .PutAsync(new MemoryStream(content));

            Console.WriteLine($"Uploaded file: {file?.Name}");
        }
    }
}

What’s happening here?

1. ClientCertificateCredential comes from Azure.Identity, not from Graph. It’s a TokenCredential, and GraphServiceClient takes one directly. No auth provider, no handler, no wrapper.
2. .default as the scope is what tells Entra ID to issue every application permission you consented to. You don’t list individual scopes for app-only auth.
3. No .Request() anywhere. In v5 the request builder ends in the verb, so it’s .GetAsync(), .PutAsync(), .PostAsync() straight off the path.
4. Collections come back wrapped. It’s lists.Value, not lists, and everything is nullable, so the compiler will nag you until you handle it. That nagging is correct: Sites["root"] really can hand you back a null.
5. X509CertificateLoader is .NET 9 and later. On .NET 8 or earlier use new X509Certificate2(path, password), which still works but is marked obsolete (SYSLIB0057) on newer targets.

The Same Code, v4

If you’re pinned to 4.54.0, the credential setup is identical and only the calls change.

using Azure.Identity;
using Microsoft.Graph;
using System.Security.Cryptography.X509Certificates;

var certificate = new X509Certificate2(CertificatePath, CertificatePassword);
var options = new ClientCertificateCredentialOptions
{
    AuthorityHost = AzureAuthorityHosts.AzurePublicCloud,
};

var credential = new ClientCertificateCredential(TenantId, ClientId, certificate, options);
var scopes = new[] { "https://graph.microsoft.com/.default" };

var graphClient = new GraphServiceClient(credential, scopes);

var org = await graphClient.Organization.Request().GetAsync();
Console.WriteLine($"Connected to: {org.First().DisplayName}");

var site = await graphClient.Sites["root"].Request().GetAsync();
var lists = await graphClient.Sites[site.Id].Lists.Request().GetAsync();

foreach (var list in lists)
{
    Console.WriteLine($"- {list.DisplayName}");
}

var docLib = lists.FirstOrDefault(l => l.DisplayName == "Documents");
if (docLib != null)
{
    var content = System.Text.Encoding.UTF8.GetBytes("Hello from Graph SDK!");
    var drive = await graphClient.Sites[site.Id].Lists[docLib.Id].Drive.Request().GetAsync();

    var file = await graphClient.Drives[drive.Id].Root
        .ItemWithPath("sample-document.txt")
        .Content
        .Request()
        .PutAsync<DriveItem>(new MemoryStream(content));

    Console.WriteLine($"Uploaded file: {file.Name}");
}

Three differences worth naming, because they’re the ones that break a paste:

GraphServiceClient(credential, scopes) is the same in both, which is the good news: the authentication half of this post doesn’t change between versions. Only the calls do.

Key Differences from PnP.Framework

Graph advantages: access to Teams, OneDrive and Exchange data with the same client. PnP advantages: more SharePoint-specific features like content types and site columns.

Troubleshooting

• The type or namespace name 'Auth' does not exist in the namespace 'Microsoft.Graph': you copied a sample with using Microsoft.Graph.Auth;. Delete the line, add Azure.Identity.
• 'OrganizationRequestBuilder' does not contain a definition for 'Request': v4 code on a v5 or v6 package. Drop the .Request() calls.
• SYSLIB0057: the X509Certificate2 constructor is obsolete on .NET 9 and later. Use X509CertificateLoader.LoadPkcs12FromFile.
• “Insufficient privileges”: permissions added but admin consent not granted.
• “Certificate not found”: check the path and password before you suspect anything cleverer.

Next Steps

You now have the Graph SDK working with your existing app registration, on whichever major version you’re pinned to. To reach more of Microsoft 365, add the matching application permission:

• User.Read.All for user data
• Group.Read.All for Teams and groups
• Files.ReadWrite.All for broader file operations
• Mail.Read for Exchange data

If you’re still on v4, the upgrade is mostly mechanical: delete every .Request(), add .Value where you iterate, and fix the upload path. The authentication code you just wrote carries over untouched.

It gets you a ClientContext without a human clicking a login prompt. That’s the whole job. You hand PnP.Framework.AuthenticationManager a client ID, a certificate and a tenant ID, and it deals with the OAuth flow so you don’t have to. Everything after that is ordinary CSOM.

Which is exactly what you want for a background service or a console app - anything that has to reach SharePoint at three in the morning with nobody around to sign in. Here’s the setup end to end.

If you arrived here because an app-only client secret suddenly stopped working: that’s Azure ACS. It was retired for SharePoint Online on 2 April 2026, with no extension, and certificate-based authentication against a Microsoft Entra app registration is the replacement. That’s what this post sets up - so this is the destination, not a detour.

App registration

Go to https://portal.azure.com and search for “App registrations”:

Click “New registration” and fill out the name, and leave the “Supported account types” to default for now (Default: Accounts in this organizational directory only (xxx - Single tenant))

And now just press “Register”

Just like so, you have created your app registration! Take note of the Application (client) ID and Directory (tenant) ID from the overview page - you’ll need these values later in your C# code.

Generate certificate

We need a certificate on the app registration, and in our code to authenticate our C# application. Certificates are more secure than client secrets because they’re harder to extract and can be managed through your organization’s PKI infrastructure.

Open PowerShell as Administrator and run the following commands:

$cert = New-SelfSignedCertificate `
    -Subject "CN=MyPnPAppCert" `
    -CertStoreLocation "cert:\CurrentUser\My" `
    -KeyExportPolicy Exportable `
    -KeySpec Signature `
    -KeyLength 2048 `
    -NotAfter (Get-Date).AddYears(3)

$plainText = "MySuperStrongPassword!"
$secureString = ConvertTo-SecureString $plainText -AsPlainText -Force

Export-PfxCertificate `
    -Cert $cert `
    -FilePath "C:\Temp\cert\pnpappcert.pfx" `
    -Password $secureString

Export-Certificate `
    -Cert $cert `
    -FilePath "C:\Temp\cert\pnpappcert.cer"        

This script creates a self-signed certificate that’s valid for 3 years. The certificate gets stored in your personal certificate store, and we export both the .pfx file (containing the private key) and the .cer file (public key only). Make sure the C:\Temp\cert\ directory exists before running this script.

Upload certificate

We need to upload the generated certificate - the .cer file (NOT the .pfx), to the app registration. The .cer file contains only the public key, while the .pfx contains the private key that should never be shared.

Navigate to your app registration in Azure Portal, go to “Certificates & secrets”, then click “Upload certificate”:

After uploading, you’ll see the certificate listed with its thumbprint. The thumbprint can be useful for identifying which certificate to use if you have multiple certificates.

Add permissions

Our app registration needs permission to be able to do stuff. There are two types of permissions: Delegated and Application. The differences between them are:

• Delegated permissions: Your app acts on behalf of a signed-in user. The app can only access what the user has access to.
• Application permissions: Your app runs as itself without a signed-in user. The app has access based on what you grant it.

For this example we’ll use the SharePoint permission “Sites.FullControl.All” as an application permission, which gives our app full access to all SharePoint sites.

After adding the permission, don’t forget to click “Grant admin consent” - this is crucial! Without admin consent, your app won’t be able to use the permissions even if they’re assigned.

Now our app registration is setup and ready to be used in our C# code.

C# Implementation

Now let’s write the C# code to authenticate and connect to SharePoint using our certificate. I’ll show you a complete working example that you can use as a starting point for your own projects.

First, create a new Console Application in Visual Studio and install the PnP.Framework NuGet package:

• https://www.nuget.org/packages/PnP.Framework/1.18.0

You can install it via Package Manager Console: Install-Package PnP.Framework

Here’s a complete example that connects to SharePoint and demonstrates several common operations:

using PnP.Framework;
using System.Security.Cryptography.X509Certificates;

class Program
{
    private static readonly string TenantId = "your-tenant-id";
    private static readonly string ClientId = "your-client-id";
    private static readonly string CertificatePath = @"C:\Temp\cert\pnpappcert.pfx";
    private static readonly string CertificatePassword = "MySuperStrongPassword!";
    private static readonly string SiteUrl = "https://yourtenant.sharepoint.com/sites/yoursite";

    static async Task Main(string[] args)
    {
        try
        {
            // Load the certificate
            var certificate = new X509Certificate2(CertificatePath, CertificatePassword);
            
            // Create authentication manager
            var authManager = new AuthenticationManager(ClientId, certificate, TenantId);
            
            // Get context
            using var context = authManager.GetContext(SiteUrl);
            
            // Load web properties
            context.Load(context.Web, w => w.Title, w => w.Url);
            await context.ExecuteQueryAsync();
            
            Console.WriteLine($"Connected to: {context.Web.Title}");
            Console.WriteLine($"Site URL: {context.Web.Url}");
            
            // Example: Get all lists
            context.Load(context.Web.Lists, lists => lists.Include(l => l.Title, l => l.ItemCount));
            await context.ExecuteQueryAsync();
            
            Console.WriteLine("\nLists in this site:");
            foreach (var list in context.Web.Lists)
            {
                Console.WriteLine($"- {list.Title} ({list.ItemCount} items)");
            }

            // Example: Create a new list
            await CreateSampleList(context);
            
            // Example: Upload a document
            await UploadDocument(context);
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Error: {ex.Message}");
        }
    }

    private static async Task CreateSampleList(ClientContext context)
    {
        try
        {
            var listCreationInfo = new ListCreationInformation
            {
                Title = "Sample List",
                TemplateType = (int)ListTemplateType.GenericList
            };

            var list = context.Web.Lists.Add(listCreationInfo);
            context.Load(list);
            await context.ExecuteQueryAsync();

            Console.WriteLine($"\nCreated list: {list.Title}");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"List creation error: {ex.Message}");
        }
    }

    private static async Task UploadDocument(ClientContext context)
    {
        try
        {
            var docLib = context.Web.Lists.GetByTitle("Documents");
            var fileCreationInfo = new FileCreationInformation
            {
                Content = System.Text.Encoding.UTF8.GetBytes("Hello from PnP Framework!"),
                Url = "sample-document.txt",
                Overwrite = true
            };

            var uploadFile = docLib.RootFolder.Files.Add(fileCreationInfo);
            context.Load(uploadFile);
            await context.ExecuteQueryAsync();

            Console.WriteLine($"\nUploaded file: {uploadFile.Name}");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"File upload error: {ex.Message}");
        }
    }
}

Understanding the Code

Let’s break down what this code does:

1. Certificate Loading: We load the .pfx file with the password we set earlier
2. Authentication Manager: PnP.Framework.AuthenticationManager handles the OAuth flow using the certificate. The overload used here takes (clientId, certificate, tenantId); there are others for secrets, interactive login and loading the certificate from the store by thumbprint
3. Context Creation: GetContext(siteUrl) gets a ClientContext object that represents our connection to SharePoint
4. Basic Operations: Shows how to read site properties, list all lists, create a new list, and upload a document

The beauty of PnP.Framework is that it abstracts away all the complex authentication details. Once you have the ClientContext, you can use it just like the regular SharePoint CSOM (Client Side Object Model).

Important Notes

• Replace your-tenant-id, your-client-id, and the site URL with your actual values from Azure Portal
• The certificate path should point to your .pfx file (not the .cer file)
• Make sure your app has the necessary permissions granted and admin consent given
• Store sensitive information like certificates and passwords securely in production (use Azure Key Vault or similar)
• Consider using certificate thumbprints instead of file paths in production environments
• The using statement ensures proper disposal of the ClientContext

Production Considerations

For production applications, consider these improvements:

// Load certificate from certificate store instead of file
var store = new X509Store(StoreName.My, StoreLocation.CurrentUser);
store.Open(OpenFlags.ReadOnly);
var certificate = store.Certificates.Find(X509FindType.FindByThumbprint, "your-cert-thumbprint", false)[0];
store.Close();

// Use configuration instead of hardcoded values
var tenantId = Configuration["Azure:TenantId"];
var clientId = Configuration["Azure:ClientId"];

Troubleshooting

Certificate auth fails in a small number of ways, and the error messages are unhelpfully similar. Here’s the triage order, cheapest check first.

The remote server returned an error: (401) Unauthorized. (also seen as Connect-PnPOnline : The remote server returned an error: (401) Unauthorized.)

Work down this list in order - the first two account for most of them:

1. Admin consent was never granted. The permission is listed on the app registration but nobody approved it. Azure Portal shows this clearly: the permission needs to read “Granted for [Your Organization]”, not just be present.
2. The tenant has custom app authentication disabled. This one is nasty because nothing about the error hints at tenant configuration - your app registration is perfect and it still 401s. The switch is Set-SPOTenant -DisableCustomAppAuthentication $true to block it, $false to allow it again.
3. Wrong token audience. A Microsoft Graph token does not work against SharePoint’s /_api, and vice versa. SharePoint wants https://<tenant>.sharepoint.com/.default.
4. The certificate isn’t actually associated with the app registration. Check you uploaded the .cer and that the thumbprint in the portal matches the certificate your code is loading.

Attempted to perform an unauthorized operation. and Access denied. You do not have permission to perform this action or access this resource.

You authenticated fine - the token is good, the operation is not allowed. Usually the permission is narrower than the thing you’re doing (Sites.Read.All when you need write), or the site is locked down beyond what tenant-level consent covers.

Access is denied. (Exception from HRESULT: 0x80070005 (E_ACCESSDENIED))

Same family, thrown from deeper in CSOM. Common on site-scoped operations and on template application, where one handler in the template needs a permission the rest of the run didn’t.

Microsoft.SharePoint.Client.ServerException: No User or App Context found

The ClientContext was created without a working authentication path. Check that GetContext actually returned before you used it, and that the certificate loaded.

The sign-in name or password does not match one in the Microsoft account system.

This one lies. It usually has nothing to do with the password. It’s what you get from SharePointOnlineCredentials when MFA is enabled, when Conditional Access blocks legacy authentication, or when you’re on .NET Standard where that class doesn’t exist at all. The fix isn’t a better password, it’s the app-only certificate setup on this page.

Cryptography Next Generation (CNG) is not supported on this platform.

The .pfx was generated by New-SelfSignedCertificate on Windows and is now being loaded somewhere that isn’t - a Linux build agent, or a container. Regenerate it with OpenSSL for that platform.

Certificate not found: Make sure the certificate path is correct and the password matches what you used when creating it. You can verify the certificate exists by checking it in the Windows Certificate Manager (certmgr.msc).

Tenant ID issues: You can find your tenant ID in the Azure Portal under Azure Active Directory > Properties. It’s also visible in the app registration overview page.

Certificate validation errors: If you’re using a self-signed certificate in a corporate environment, your organization’s security policies might block it. Consider using a certificate issued by your internal CA.

Testing Your Setup

Before diving into complex operations, test your connection with this minimal code:

try
{
    var certificate = new X509Certificate2(CertificatePath, CertificatePassword);
    var authManager = new AuthenticationManager(ClientId, certificate, TenantId);
    using var context = authManager.GetContext(SiteUrl);
    
    context.Load(context.Web, w => w.Title);
    await context.ExecuteQueryAsync();
    
    Console.WriteLine($"Success! Connected to: {context.Web.Title}");
}
catch (Exception ex)
{
    Console.WriteLine($"Connection failed: {ex.Message}");
}

Wrapping Up

You now have a working setup for authenticating with SharePoint using PnP.Framework and certificates. This method is perfect for background services, console applications, or any scenario where you need unattended access to SharePoint.

The certificate-based authentication is more secure than using client secrets since certificates are harder to compromise and can be managed through your organization’s certificate infrastructure.

In my next post, I’ll show you how to perform common SharePoint operations like creating lists, uploading files, and managing permissions using this authentication setup.

Audience targeting allows content administrators to direct content toward specific groups of users. This is particularly useful in organizations with a wide array of users, where not all content is relevant for everyone. By using audience targeting, you can improve the relevance of the content each user sees, leading to a more personalized and focused user experience.

Audience Targeted Wrapper 🔧

Let’s dive into how to build an SPFx component that employs audience targeting. This component acts as a wrapper, showing or hiding content based on the user’s membership in specific groups.

Group Check Logic 🔍

At the heart of our component is the logic that determines if the current user is a member of any of the specified groups.

Group Check Logic

public async isMember(group: any, context: any): Promise<boolean> {
    const _cacheName = 'CacheName_memberGroups';

    if (group == null || group == '') {
        return true;
    }
    const graph = graphfi().using(SPFx(context));
    let _cachedMemberGroups = sessionStorage.getItem(_cacheName);
    let memberGroups: string[] = [];
    if (!_cachedMemberGroups) {
        memberGroups = await graph.me.getMemberGroups();
        sessionStorage.setItem(_cacheName, JSON.stringify(memberGroups));
    } else {
        memberGroups = JSON.parse(_cachedMemberGroups);
    }
    // "c:0o.c|federateddirectoryclaimprovider|xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"
    const groupID = group.id.split('|')[2];
    if (memberGroups.filter((g: string) => g === groupID).length > 0) {
        return true;
    }
    throw new Error('User not found');
}

The wrapper component is visually minimalistic, primarily designed to function based on the logic of accessing group IDs from an array of IPropertyFieldGroupOrPerson. Its simplicity belies its utility, enabling dynamic content visibility tailored to user or group permissions with little visual footprint.

TargetAudience wrapper

export interface ITargetAudienceProps {
    pageContext: PageContext;
    context: any;
    groupIds: IPropertyFieldGroupOrPerson[];
}

const TargetAudience: React.FC<ITargetAudienceProps> = ({ pageContext, groupIds, children, context }) => {
    const [canView, setCanView] = useState<boolean>(false);

    useEffect(() => {
        const checkUserIsAllowedToViewWebpart = async () => {
            let proms: any[] = [];
            const errors: any[] = [];
            groupIds?.map((item : any) => {
                proms.push(
                    isMember(item, context)
                );
            });
            Promise.race(
                proms.map(p => {
                    return p.catch((err: any) => {
                        errors.push(err);
                        if (errors.length >= proms.length){
                            throw errors;
                        } 
                        return Promise.race(null);
                    });
                }))
                .then(val => {
                    setCanView(true);
                });
        };
        checkUserIsAllowedToViewWebpart();
    }, [groupIds, pageContext]);

    return (
        <div>
            {groupIds != null && groupIds.length >= 1 ? (canView ? children : '') : children}
        </div>
    );
};

export default TargetAudience;

How to use it

<TargetAudience groupIds={GroupsIDS} pageContext={pageContext} context={context}>
    <h1>
        This is top secret for non admins...
    </h1>
</TargetAudience>

Final Thoughts 💭

Could the logic be extended to check that only selected users can view the content, instead of it being limited to groups? Absolutely, this is entirely possible.

However, I’ve chosen to focus on the group aspect because that’s often what my solutions revolve around. This approach emphasizes the flexibility of SPFx solutions in catering to diverse requirements, allowing for both broad group-based targeting and the precision of user-specific content visibility.

It highlights the potential to tailor your SharePoint solutions even more closely to your organization’s needs, ensuring that every piece of content reaches exactly the right audience.