Skip to content

Connect to SharePoint Online with certificate credentials

SharePoint app-only automation authenticates with an X.509 certificate — the SharePoint REST endpoints (/_api) do not accept a client secret. This folder contains an automated setup script plus the manual steps.

Recommended: use Getting started for the full cycle (register/reuse the app, attach the certificate, grant Sites.Selected with admin consent, grant site access, and write .env). The script here is the narrower certificate + site grant path: it assumes the app already has the Sites.Selected application permission with admin consent.

Automated setup

certificate_auth.py is the narrower certificate + site grant path:

uv run python examples/sharepoint/auth/setup/certificate_auth.py \
    --site https://contoso.sharepoint.com/sites/project

The script:

  1. generates tests/selfsigncert.crt and tests/selfsigncert.pem,
  2. uploads the public certificate to your app registration,
  3. grants the app access to the target site (Sites.Selected),
  4. prints the values to put in .env, including the certificate thumbprint.
OFFICE365_TENANT=contoso.onmicrosoft.com
OFFICE365_CLIENT_ID=00000000-0000-0000-0000-000000000000
OFFICE365_CERT_THUMBPRINT=<thumbprint>

It authenticates as a tenant administrator (OFFICE365_ADMIN_USERNAME) via interactive sign-in and requires the Global Administrator or Privileged Role Administrator role. It prints a paste-ready block (OFFICE365_TENANT=…, OFFICE365_CLIENT_ID=…, OFFICE365_CERT_THUMBPRINT=…). See README-dev.md for the full local setup and the other flows.

Manual setup

  1. Create a self-signed certificate (Azure Cloud Shell or locally):
openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 \
    -keyout privateKey.key -out selfsigncert.crt
cat selfsigncert.crt privateKey.key > selfsigncert.pem

  1. Register the certificate with your app in Entra ID — see the official steps.

  2. Grant SharePoint permissions: Add a permission → Microsoft APIs → SharePoint → Application permissions → e.g. Sites.FullControl.All (or Sites.Selected for per-site access).

  3. Note the thumbprint (hex, no colons) and point OFFICE365_CERT_THUMBPRINT at it.

Use in code

from office365.sharepoint.client_context import ClientContext

ctx = ClientContext("https://contoso.sharepoint.com/sites/team").with_client_certificate(
    tenant="contoso.onmicrosoft.com",
    client_id="00000000-0000-0000-0000-000000000000",
    thumbprint="0000000000000000000000000000000000000000",
    cert_path="tests/selfsigncert.pem",
)

web = ctx.web.get().execute_query()
print(web.url)

For other variants (private key as a string, custom scopes) and the user-context flows, see the modern authentication examples.

References