Skip to main content
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

2

Package the private key as a .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

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: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: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

You uploaded the .pfx to Entra. Upload the .crt, .cer, or .pem instead, and keep the .pfx for Onyx.
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.
The connector is using a client secret credential rather than this certificate. Check which credential it is attached to.
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.
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.
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.