Certificate authentication

Register a SharePoint application that authenticates with a certificate, the method required for permission sync

A certificate identifies the Entra application with a key file instead of a password. Use it when you want permission sync, or when your organization does not permit client secrets.

If you only need your documents indexed, and every document can share one access level in Onyx, use the client secret method instead.

What you create

You need two files, and both come from the same certificate:

• A public certificate (.cer, .pem, or .crt) that you upload to Entra ID
• A .pfx file, protected by a password, that you upload to Onyx

Sending the wrong file to the wrong place is the most common problem in this setup.

Register the application

1. Open App registrations

   Sign in to the Microsoft Entra admin center or the Azure portal and go to App registrations.

2. Create the registration

   Select New registration. Name it something recognizable, such as Onyx SharePoint Connector. Leave the supported account types and redirect URI at their defaults. Select Register.

3. Record the two IDs

   On the application’s Overview page, copy the Application (client) ID and the Directory (tenant) ID.

Create the certificate

Either get a certificate from your organization’s certificate authority, or create a self-signed one.

1. Generate the private key and certificate

   # Private key
   openssl genrsa -out onyx-sharepoint.key 2048
   
   # Self-signed certificate, valid for two years
   openssl req -new -x509 -days 730 \
     -key onyx-sharepoint.key \
     -out onyx-sharepoint.crt \
     -subj "/CN=Onyx SharePoint Connector"
   
2. Package the private key as a .pfx

   openssl pkcs12 -export \
     -inkey onyx-sharepoint.key \
     -in onyx-sharepoint.crt \
     -out onyx-sharepoint.pfx
   

   You are prompted for an export password. Record it. Onyx asks for it later, and it cannot be recovered.

3. Check what you have

   File	Goes to
   onyx-sharepoint.crt	Entra ID
   onyx-sharepoint.pfx	Onyx
   onyx-sharepoint.key	Neither. Keep it somewhere safe, or delete it.

   Store the .pfx and its password securely.

If your certificate authority issues you a .pfx only, extract the public half for Entra with openssl pkcs12 -in yourcert.pfx -clcerts -nokeys -out yourcert.crt.

Upload the public certificate to Entra

1. Open Certificates & secrets

   In your app registration, go to Certificates & secrets → Certificates.

2. Upload the certificate

   Select Upload certificate, choose onyx-sharepoint.crt, add a description, and select Add.

Entra takes .cer, .pem, and .crt files only. Uploading the .pfx fails with Upload a certificate (public key) with one of the following file types: .cer, .pem, .crt. The .pfx goes to Onyx, not to Entra.

Grant permissions

The permissions come from two places in the portal, Microsoft Graph and SharePoint. Add them all first, then grant consent once at the end.

1. Add the Microsoft Graph application permissions

   Go to API permissions → Add a permission → Microsoft Graph → Application permissions, and add:

   Permission	What it is for
   Sites.Read.All	Reading your sites, document libraries, files, and pages. To limit the app to named sites, use Sites.Selected instead. See Limiting the app to specific sites.
   GroupMember.Read.All	Working out who is in a group, including groups nested inside other groups
   Group.Read.All	Telling security groups apart from Microsoft 365 groups
   Directory.Read.All	Reading how users and groups relate to each other in your directory
   User.Read.All	Matching the people in your directory to their Onyx accounts
   Member.Read.Hidden	Reading the membership of groups whose members are hidden in Entra ID

   Indexing needs only Sites.Read.All. The rest are for permission sync. Add them now if you expect to turn it on later, or come back and add them when you do.

2. Add the SharePoint application permissions

   Select Add a permission → SharePoint → Application permissions, and add:

   Permission	What it is for
   Sites.FullControl.All	Seeing who has access to each site, folder, and document
   User.Read.All	Matching those access lists to the people in your directory

   Add these under SharePoint, not Microsoft Graph. The two list permissions with the same names, and adding the Graph one by mistake is a common cause of permission sync failing later.

   Despite the name, Onyx only reads with Sites.FullControl.All. It never writes to SharePoint. If the grant is too broad for your organization, use Sites.Selected and give the app full control of named sites only. See Limiting the app to specific sites.

3. Grant admin consent

   Select Grant admin consent for <your organization> and confirm. Every permission in the list should then show Granted. Until you do this, none of them take effect.

   This step needs the Global Administrator or Privileged Role Administrator role. No other role can consent to Microsoft Graph application permissions, so if the button is unavailable or consent fails, ask someone with one of those roles to do it.

A new registration already lists a delegated User.Read permission. The connector never uses it, since it signs in as an application rather than as a person. Leave it or remove it, as you prefer.

Add the credential to Onyx

1. Open the SharePoint connector

   In Onyx, go to Admin Panel → Add Connector and select SharePoint.

2. Create a certificate credential

   Select Create New, then the Certificate Authentication tab, and enter:

   • Application (client) ID and Directory (tenant) ID, from the app registration Overview page
   • Certificate File: upload onyx-sharepoint.pfx
   • Certificate Password: the export password you set
3. Save and continue

   Select Create, confirm the new credential is selected, and continue to the connector settings described in Configure the connector in Onyx.

Enable permission sync

On the connector form, set the access type to Auto Sync Permissions. Each document then keeps the access it has in SharePoint, and an Onyx user finds it in search only if they can open it in SharePoint.

Permission sync is a paid feature: Onyx Cloud, or the Enterprise Edition when self-hosted.

Troubleshooting

Upload a certificate (public key) with one of the following file types

You uploaded the .pfx to Entra. Upload the .crt, .cer, or .pem instead, and keep the .pfx for Onyx.

Failed to load certificate

Onyx could not open the .pfx, usually because the password is wrong or the file is not a .pfx at all. Repeat Create the certificate.

Unsupported app only token

The connector is using a client secret credential rather than this certificate. Check which credential it is attached to.

missing the required SharePoint permission to read role assignments

Sites.FullControl.All was added under Microsoft Graph instead of SharePoint, admin consent was never granted, or a site under Sites.Selected was not given full control.

invalid_client

Entra does not recognize the certificate Onyx is using. Usually the certificate has expired, or the .pfx and the uploaded public certificate came from different certificates.

Indexing worked, then stopped on a fixed date

The certificate expired. Repeat Create the certificate, upload the new public certificate to Entra alongside the old one, then update the credential in Onyx with the new .pfx and its password. Delete the expired certificate in Entra once an indexing attempt has succeeded.

For problems with sites, scoping, file types, and content, see Troubleshooting on the overview page.