​
Certificate-Based Authentication

Certificate-based authentication provides a secure way to connect to SharePoint and supports both basic integration and permission sync functionality. Use certificate authentication when:
  • You need permission sync capabilities
  • You prefer certificate-based security over client secrets
  • Your organization requires certificate-based authentication
For basic SharePoint integration without permission sync, you can also use client secret authentication.

​
Setting up

​
Step 1: Create Azure App Registration

  1. Log in to Azure Portal for your organization.
  2. Navigate to “App registrations” using the search bar.
  3. Click New Registration.
  4. Name it something like “Onyx SharePoint Connector - Certificate”, leave everything else as default, and click Register.
  5. Under “Essentials” in the overview tab, you will find the Application (client) ID and Directory (tenant) ID. Save those for later.

​
Step 2: Generate and Upload Certificate

​
Option A: Generate Self-Signed Certificate

# Generate private key
openssl genrsa -out sharepoint-cert.key 2048

# Generate certificate signing request
openssl req -new -key sharepoint-cert.key -out sharepoint-cert.csr

# Generate self-signed certificate (valid for 1 year)
openssl x509 -req -days 365 -in sharepoint-cert.csr -signkey sharepoint-cert.key -out sharepoint-cert.crt

# Convert to PFX format 
openssl pkcs12 -export -out sharepoint-cert.pfx -inkey sharepoint-cert.key -in sharepoint-cert.crt

​
Option B: Use Organization Certificate

Obtain a certificate from your organization’s Certificate Authority (CA) following your internal security policies.
We only support PFX format for certificate uploads in Azure.

​
Step 3: Upload Certificate to Azure

  1. In your Azure App Registration, navigate to the “Certificates & secrets” tab.
  2. Click Upload certificate.
  3. Select your certificate file (.crt, .pem, or .cer format).
  4. Add a description and click Add.

​
Step 4: Configure API Permissions

  1. Navigate to the “API Permissions” tab in the Azure Portal.
  2. Click Add a permission.

​
Basic Permissions (No Permission Sync)

If you are not planning to enable permission sync, you only need basic permissions:
  1. Click Microsoft Graph, then click on Application permissions.
  2. Navigate to the “Sites” permission group.
  3. Select the checkbox for Sites.Read.All.
    • Advanced: If you want to limit the sites this app has access to, select Sites.Selected. However, if you do this, you will need to add the App you are currently registering to each site you want to index.
  4. Click Add permissions.
  5. Finally, click Grant admin consent for <Organization name> and click Confirm.

​
Extended Permissions (With Permission Sync)

If you plan to enable permission sync, you’ll need additional permissions:
  1. Click Add a permission again.
  2. Click Microsoft Graph, then click on Application permissions.
  3. Add the following additional Microsoft Graph permissions:
    • Directory.Read.All - Read directory data
    • Group.Read.All - Read all groups
    • GroupMember.Read.All - Read all group memberships
    • Member.Read.Hidden - Read all hidden memberships
    • User.Read.All - Read all users’ full profiles
  4. Click Add permissions.
  5. Click Add a permission again in API Permissions tab.
  6. Click Microsoft Graph, then click on Delegated permissions.
  7. Add the following delegated permission:
    • User.Read - Sign in and read user profile
  8. Click Add permissions.
  9. Click Add a permission again in API Permissions tab.
  10. Click SharePoint, then click on Application permissions.
  11. Add the following SharePoint permissions:
    • Sites.FullControl.All - Have full control of all site collections
    • User.Read.All - Read user profiles
  12. Click Add permissions.
  13. Finally, click Grant admin consent for <Organization name> and click Confirm.

​
Step 5: Configure in Onyx

  1. Navigate to the Onyx Admin Dashboard and select the SharePoint Connector.
  2. Click Create New credential and select the Certificate tab.
  3. Provide the following information:
    • Application (client) ID from Step 1
    • Directory (tenant) ID from Step 1
    • Certificate File: Upload your certificate file (.pfx file)
    • Certificate Password: Enter password which you used to export the certificate file
  4. Click Create to save your credentials.

​
Step 6: Enable Permission Sync (Optional)

When creating your SharePoint connector with certificate authentication:
  1. In the connector configuration, you’ll see a Permission Sync option.
  2. Enable this option to synchronize SharePoint permissions with Onyx.
Permission sync is available only on Cloud and the Enterprise Edition of Onyx.

​
Permission Sync Details

When permission sync is enabled:
  • Document-level permissions: Onyx will respect SharePoint document permissions
  • Site-level permissions: Users will only see documents from sites they have access to
  • Group permissions: SharePoint group memberships are synchronized
  • Real-time sync: Permissions are updated regularly to reflect SharePoint changes
For basic SharePoint integration without permission sync, you can use client secret authentication.