Forem: Nikolay Belykh

Using a certificate authentication to call SharePoint REST API (CSOM)

Nikolay Belykh — Fri, 03 Nov 2023 23:38:08 +0000

Motivation

Imagine you have a .NET app that stopped working because there is a requirement for 2FA. This article shows how you can take care of that and upgrade your app to use a certificate to call SharePoint instead of username/password or client secret. Please note that this article is referring to the "never" version where you register your app with Azure AD, not the old one where you register your app with SharePoint directly (as an add-in).

I am assuming that we want to call SharePoint unattended, i.e. NOT on behalf of the user, but on behalf of the application itself. If you want a delegated call on behalf of a user, then you don't need this "certificate" authentication. Also, if your app that needs to call SharePoint is itself hosted on azure, you could consider using managed identities instead.

The certificate

To authenticate using a certificate, we need that certificate, to start with. You can get one in many ways, the easiest (for Windows) is probably the PowerShell New-SelfSignedCertificate command or the button "make new self-signed certificate" in IIS (if you have IIS installed). For Linux, it's OpenSSL.

As an output from this step, we should have a .PFX certificate file (say, "my.pfx"). The certificate may be for any domain (i.e. "localhost" is fine) and may be "self-signed", it works fine. The PFX file should include both private and public keys.

In addition to the PFX, we need a public-key-only version of it to use for app registration. If you are using Windows, you could just export a PFX (right mouse click), or you could also use a PowerShell script. Let's name this second file "my.cer".

Below is a simple PowerShell script to make the "my.pfx" file and "my.cer" files:



$cert = New-SelfSignedCertificate -DnsName localhost -CertStoreLocation cert:\CurrentUser\My
$pwd = ConvertTo-SecureString -String "P@ss0word!" -Force -AsPlainText
Export-PfxCertificate -Cert $cert -FilePath .\my.pfx -Password $pwd
Export-Certificate -Cert $cert -FilePath .\my.cer

So now you should have 2 files ready, my.pfx and my.cer

The Azure app registration

After completing this step, we should have an App registered with Azure ID to be used for authenticating the requests to SharePoint API that are coming from our CSOM application.

First, register an App to be used with this certificate:

Go to your Azure portal (where the SharePoint belongs to).
Go to "App registrations"
Click "New registration"
Give your app a name, say "MyApp", and click "Register"

Upload the certificate created at the first part for this app:

Click tab "Certificates & secrets"
Select "Certificates" tab.
Click "Upload certificate" and choose the "my.cer" file

Add SharePoint API permissions set for the app (unless you have already done that before):

Add API Permissions to the app to call SharePoint.
Select the "API permissions"
Click "Add permission"
Choose the "SharePoint" in the list. Do not select "Graph".

Select the exact permissions you want the app to have

Choose "Application permissions" (we want to run unattended) and then appropriate permission for your app. I've selected Sites.FullControl.All for simplicity (it will grant all SharePoint permissions to the app). You may want to be more precise here. Click "Add".

Now you should get that in the list of application permissions. You need to consent to these permissions. Note that only admin can do that. Click "Grant admin consent". You should have a green checkbox next to that permission:

That's it. We are done with App registration, and should be able to call it from our application using CSOM. There is one more thing we want for our dotnet code, its application ID and tenant ID. You can find these on the app overview page:

The dotnet app

Now we can use the above setup from the dotnet code. For the PnP.Framework library, the code to call SharePoint using that certificate may look somewhat like this:



var authMgr = PnP.Framework.AuthenticationManager
  .CreateWithCertificate(
    @"11e0257c-66b1-4896-88dd-xxxxx", // Your Azure AD App ID
    @"c:\path\to\my.pfx", 
    @"Pass@word!", 
    @"6ca33c8e-996a-4de8-a843-xxxxx" // Your Tenant ID
  );

var siteUrl = "https://contoso.sharepoint.com";

using (var ctx = authMgr.GetContext(siteUrl))
{
  ctx.Load(ctx.Web, p => p.Title);
  Console.WriteLine(ctx.Web.Title);
}

Basically, you just tell the AuthenticationManager to use the certificate to connect. For the newer PnP Core library, it will look similar, but the details (like the names of methods) will differ a bit.

For the old SharePoint.Online.CSOM it could look like (this one was built in pre-azure times):



...

var siteUrl = "https://contoso.sharepoint.com";

var clientId = "11e0257c-66b1-4896-88dd-xxxxxx";

var tenantId = "6ca33c8e-996a-4de8-a843-xxxxxx";

var certificate = new X509Certificate2(

  @"C:\path\to\my.pfx", "Pass@word!");

var confidentialClient = ConfidentialClientApplicationBuilder

    .Create(clientId)

    .WithTenantId(tenantId)

    .WithCertificate(certificate)

    .Build();

var token = await confidentialClient

    .AcquireTokenForClient(new[] { $"{siteUrl}/.default" })

    .ExecuteAsync();

var context = new ClientContext(siteUrl);

context.ExecutingWebRequest += (sender, e) =>

{

  e.WebRequestExecutor.RequestHeaders["Authorization"] = 

    "Bearer " + token;

};

context.Load(context.Web, web => web.Title);

await context.ExecuteQueryAsync();

Conclusion

I hope this walkthrough was useful. Would appreciate any comments or notes.

Using .NET as WebAssembly from JavaScript (React)

Nikolay Belykh — Fri, 27 Oct 2023 18:58:07 +0000

Motivation

I maintain a small project with quirky tools for dinosaurs. The project’s code is fully open and available on GitHub. It can process Microsoft Office (Visio) files without having it installed, using OpenXml and PdfSharp libraries. File processing is done in .NET (C#).

Before, the document processing was done on the server (i.e., the file was sent to the server via the internet). However, this has at least the following drawbacks:

File transfer over the network takes time,
Server hosting isn’t free, even if it’s Azure Function or AWS Lambda,
Users are afraid to send their valuable files to an unknown location.

So, I decided to try using the new .NET 7 features for compiling .NET code to WebAssembly. Earlier, something similar could be done, but Blazor was everywhere, meaning it’s a special type of app, not that easy to add to an existing one. Also, call me biased, but I don’t really like “hyped” things. Now, in .NET 7, they’ve “detached” Blazor, and it can compile to WASM without weird extras.

Essentially, all I had to do was replace the server API call with a local WASM code call (from a React component). I’ll explain the process step-by-step next.

.NET Project

Detailed instructions can be found on Microsoft’s website or in this blog. Here’s a quick rundown. It’s assumed you’re using the command line (personally I am using Visual Studio Code as an editor). So:

Install WASM compilation support. This is installed as a separate workload. It works starting from .NET 7:

    dotnet workload install wasm-tools

Create a new project:

    dotnet new console

Modify it for WASM compilation. Alternatively, you can install wasm-experimental, which adds a project template. But basically, to change a console app project to compile to WASM, you just need to add a few lines to the project. Details can be found again on Microsoft's website. In addition to modifying the project, you also need to create an (empty is fine) "main.js" file (needed for the toolset to work properly; this might change in the future). In my case, I just created an empty file.

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net7.0</TargetFramework>

    <!-- add this piece -->
    <RuntimeIdentifier>browser-wasm</RuntimeIdentifier>
    <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
    <WasmMainJSPath>main.js</WasmMainJSPath>
    <!-- end -->

    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>

</Project>

Next, write your actual code in Program.cs. For this example, I’m just returning the length of the given data (a “file” in this case). Obviously, there should be some actual processing. You can see what I really do in the GitHub repository (files are processed with OpenXml and PdfSharp).

using System.Runtime.InteropServices.JavaScript;
using System.Threading.Tasks;

// one more artifct to please the toolset
return;

public partial class FileProcessor
{
    // Экспортируем метод
    [JSExport]
    internal static async Task<int> ProcessFile(byte[] file)
    {
  await Task.Delay(100); // эмулируем работу
        return file.Length;
    }
}

Compile (or directly publish for a smaller size):

    dotnet publish -c Release

You’ll get an output folder with files in “bin/Release/net7.0/browser-wasm/AppBundle”. All DLL files are in the “managed” folder. On the frontend, you’re only interested in the “dotnet.js” file, which is intended for integration into a JavaScript application. But you upload the entire folder to hosting, including all its files and subdirectories. The size is not too bad; for a “Hello World,” it’s just a few megabytes.

Files after compilation:

Web Project (vite/react)

For VisioWebTools, I use Astro, but for the sake of this article, let’s assume our frontend is vite + react. Below, I simply create a new project “myapp” for illustration.

npm create vite@latest myapp --template react-ts
cd myapp
npm install
npm run dev

Now, we actually complete the remaining part and call our function from .NET. The code simply displays the size of the selected file by calling the .NET function from the above project. The file selection button is disabled during loading.

import { useDotNet } from './useDotNet'

function App() {

  const { dotnet, loading } = 
      useDotNet('/path/to/your/AppBundle/dotnet.js')

  const fileSelected = async (e: any) => {

    const file = e.target.files[0];
    const data = new Uint8Array(await file.arrayBuffer());

    const result = await dotnet.FileProcessor.ProcessFile(data)

    alert(`Result: ${result}`);
  }

  return (
    <>
    <input disabled={loading} type="file" onChange={fileSelected}></input>
    </>
  )
}

export default App

For convenience, I created a custom hook (“loader”), useDotNet (code below). I couldn’t get the bundler (neither vite nor webpack) to properly package the code from AppBundle (including DLLs and other “interesting” files), so dynamic loading of all this stuff is done via await import(url). The “url” parameter should point to the “dotnet.js” generated by .NET.

import { useEffect, useRef, useState } from 'react';

export const useDotNet = (url: string) => {

  const dotnetUrl = useRef('');
  const [dotnet, setDotNet] = useState<any>(null);
  const [loading, setLoading] = useState(true);

  const load = async (currentUrl: string): Promise<any> => {

    const module = await import(/* @vite-ignore */ currentUrl);

    const { getAssemblyExports, getConfig } = await module
      .dotnet
      .withDiagnosticTracing(false)
      .create();

    const config = getConfig();
    const exports = await getAssemblyExports(config.mainAssemblyName);
    return exports;
  }

  useEffect(() => {
    if (dotnetUrl.current !== url) { // safeguard to prevent double-loading
      setLoading(true);
      dotnetUrl.current = url;
      load(url)
        .then(exports => setDotNet(exports))
        .finally(() => setLoading(false))
    }
  }, [url]);
  return { dotnet, loading };
}

Building (CI) and hosting the project on GitHub

My goal was partly to provide completely free hosting for the VisioWebTools project while still being able to run .NET code.

For building the project, I used GitHub Actions; for hosting, GitHub Pages. GitHub provides 2000 free build minutes per month, which is more than enough for me. The logic is:

Build the .NET project,
Upload the contents of the “AppBundle” folder to the “public” folder of the React/Vite project. The contents of this folder will simply be copied to the root of the built application (i.e., into the “dist” folder in this case),
Build the React application in “production” mode. The URL for loading dotnet.js is set to “/AppBundle/dotnet.js”, i.e., a link to the application root.

GitHub Pages handles this fine; it doesn’t complain about strange file types like “.dll” or “.blat” (IIS does, and you have to add them explicitly there). You can see an example configuration for GitHub Actions here.

Conclusion

You can find a test (“pet”) repository here. Everything works on my machine :) I don’t claim it’s an impeccable method, and I’m totally open to any feedback or suggestions. I’ll try to answer any questions to the best of my understanding. I hope you find this article useful.