> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onyx.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Certificate-Based Authentication

> Set up SharePoint connector using certificate-based authentication with optional permission sync support

## 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](/admins/connectors/official/sharepoint/client-secret).

## Setting up

### Step 1: Create Azure App Registration

<Steps>
  <Step title="Open Azure Portal">
    Log in to [Azure Portal](https://portal.azure.com/#home) for your organization.
  </Step>

  <Step title="Open App registrations">
    Navigate to "App registrations" using the search bar.
  </Step>

  <Step title="Create registration">
    Click **New Registration**.
  </Step>

  <Step title="Name and register app">
    Name it something like "Onyx SharePoint Connector - Certificate", leave everything else as default,
    and click **Register**.
  </Step>

  <Step title="Save IDs">
    Under "Essentials" in the overview tab, you will find the **Application (client) ID** and **Directory (tenant) ID**.
    Save those for later.
  </Step>
</Steps>

### Step 2: Generate and Upload Certificate

#### Option A: Generate Self-Signed Certificate

```bash theme={null}
# 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.

<Note>
  We only support PFX format for certificate uploads in Azure.
</Note>

### Step 3: Upload Certificate to Azure

<Steps>
  <Step title="Open Certificates & secrets">
    In your Azure App Registration, navigate to the "Certificates & secrets" tab.
  </Step>

  <Step title="Upload certificate">
    Click **Upload certificate**.
  </Step>

  <Step title="Select file">
    Select your certificate file (.crt, .pem, or .cer format).
  </Step>

  <Step title="Add certificate">
    Add a description and click **Add**.
  </Step>
</Steps>

### Step 4: Configure API Permissions

<Steps>
  <Step title="Open API Permissions">
    Navigate to the "API Permissions" tab in the Azure Portal.
  </Step>

  <Step title="Add a permission">
    Click **Add a permission**.
  </Step>
</Steps>

#### Basic Permissions (No Permission Sync)

If you are **not** planning to enable permission sync, you only need basic permissions:

<Steps>
  <Step title="Choose Microsoft Graph">
    Click **Microsoft Graph**, then click on **Application permissions**.
  </Step>

  <Step title="Select Sites.Read.All">
    Navigate to the "Sites" permission group. 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.

    <Accordion title="How to grant site-specific access">
      If you selected **Sites.Selected**, you need to grant your app **read** access to each site you want to index.

      The steps below use [Microsoft Graph Explorer](https://developer.microsoft.com/en-us/graph/graph-explorer),
      but you can also grant site permissions using:

      * [PnP PowerShell](https://pnp.github.io/powershell/cmdlets/Grant-PnPAzureADAppSitePermission.html) (`Grant-PnPAzureADAppSitePermission` cmdlet)
      * [Resource Specific Consent guide](https://learn.microsoft.com/en-us/sharepoint/dev/sp-add-ins-modernize/understanding-rsc-for-msgraph-and-sharepoint-online)

      To use Graph Explorer, complete these steps:

      <Steps>
        <Step title="Sign in">
          Sign in with a **Global Admin** or **SharePoint Admin** account.
        </Step>

        <Step title="Consent to permissions">
          Click your profile icon → **Consent to permissions** → enable **Sites.FullControl.All**.
          This grants Graph Explorer (not your Onyx app) permission to manage site access.
        </Step>

        <Step title="Get the site ID">
          Run a **GET** request, replacing `{tenant}` and `YourSiteName`:

          ```
          GET https://graph.microsoft.com/v1.0/sites/{tenant}.sharepoint.com:/sites/YourSiteName?$select=id
          ```

          Copy the `id` from the response (format: `onyx.sharepoint.com,guid1,guid2`).
        </Step>

        <Step title="Grant Read permission">
          Change the method to **POST**:

          ```
          POST https://graph.microsoft.com/v1.0/sites/{site-id}/permissions
          ```

          Request body:

          ```json theme={null}
          {
            "roles": ["read"],
            "grantedToIdentitiesV2": [{
              "application": {
                "id": "<Onyx App Client ID>",
                "displayName": "Onyx SharePoint Connector"
              }
            }]
          }
          ```
        </Step>

        <Step title="Verify">
          Change the method to **GET**:

          ```
          GET https://graph.microsoft.com/v1.0/sites/{site-id}/permissions
          ```

          Confirm `"roles": ["read"]` appears for the Onyx app.
        </Step>
      </Steps>

      Repeat steps 3–5 for each site you want to index.
    </Accordion>
  </Step>

  <Step title="Add and grant">
    Click **Add permissions**. Finally, click **Grant admin consent for \<Organization name>** and click **Confirm**.
  </Step>
</Steps>

#### Extended Permissions (With Permission Sync)

If you plan to enable permission sync, you'll need additional permissions:

<Steps>
  <Step title="Add another permission">
    Click **Add a permission** again.
  </Step>

  <Step title="Microsoft Graph application permissions">
    Click **Microsoft Graph**, then click on **Application permissions**.
    Add the following additional Microsoft Graph permissions:

    * **Directory.Read.All** - Used to query the overall organizational directory structure, including how users,
      groups, organizational units, and other directory objects relate to each other.
    * **Group.Read.All** - Used to read detailed group-specific information such as group properties, settings,
      types (Security vs Microsoft 365), and configurations.
    * **GroupMember.Read.All** - Used to retrieve and expand all members within a group,
      including nested group memberships.
      This allows Onyx to determine which users have access to SharePoint content through group membership.
    * **Member.Read.Hidden** - Allows reading memberships of security groups that are marked as "hidden" in Entra ID.
    * **User.Read.All** - Used to retrieve complete user profiles and enumerate all users in the directory.
      Click **Add permissions**.
  </Step>

  <Step title="Microsoft Graph delegated permission">
    Click **Add a permission** again in API Permissions tab. Click **Microsoft Graph**,
    then click on **Delegated permissions**. Add the following delegated permission:

    * **User.Read** - This delegated permission allows the application to sign in on behalf of a user and read the
      signed-in user's basic profile information. Unlike application permissions which work without a user context,
      this delegated permission is required when the app needs to establish an authenticated identity context for making
      API calls to Microsoft Graph and SharePoint. It provides the minimum required access for user authentication flows.
      Click **Add permissions**.
  </Step>

  <Step title="SharePoint application permissions">
    Click **Add a permission** again in API Permissions tab. Click **SharePoint**,
    then click on **Application permissions**. Add the following SharePoint permissions:

    * **Sites.FullControl.All** - Despite the name, Onyx only uses this to retrieve details about permissions.
      No write operations are performed.
      If you selected **Sites.Selected** and need to grant fullcontrol only for specific sites,
      see the **Using Sites.Selected with Permission Sync** section below.
    * **User.Read.All** - Used to list all users within the directory for permission mapping.
      Click **Add permissions**.
  </Step>

  <Step title="Grant admin consent">
    Finally, click **Grant admin consent for \<Organization name>** and click **Confirm**.
  </Step>
</Steps>

<Accordion title="Using Sites.Selected with Permission Sync">
  If you selected **Sites.Selected** instead of **Sites.Read.All** and plan to enable permission sync,
  you need to grant your app **fullcontrol** access to each site.

  The steps below use [Microsoft Graph Explorer](https://developer.microsoft.com/en-us/graph/graph-explorer),
  but you can also grant site permissions using:

  * [PnP PowerShell](https://pnp.github.io/powershell/cmdlets/Grant-PnPAzureADAppSitePermission.html) (`Grant-PnPAzureADAppSitePermission` cmdlet)
  * [Resource Specific Consent guide](https://learn.microsoft.com/en-us/sharepoint/dev/sp-add-ins-modernize/understanding-rsc-for-msgraph-and-sharepoint-online)

  To use Graph Explorer, complete these steps:

  <Steps>
    <Step title="Sign in">
      Sign in with a **Global Admin** or **SharePoint Admin** account.
    </Step>

    <Step title="Consent to permissions">
      Click your profile icon → **Consent to permissions** → enable **Sites.FullControl.All**.
      This grants Graph Explorer (not your Onyx app) permission to manage site access.
    </Step>

    <Step title="Get the site ID">
      Run a **GET** request, replacing `{tenant}` and `YourSiteName`:

      ```
      GET https://graph.microsoft.com/v1.0/sites/{tenant}.sharepoint.com:/sites/YourSiteName?$select=id
      ```

      Copy the `id` from the response (format: `onyx.sharepoint.com,guid1,guid2`).
    </Step>

    <Step title="Grant FullControl permission">
      Change the method to **POST**:

      ```
      POST https://graph.microsoft.com/v1.0/sites/{site-id}/permissions
      ```

      Request body:

      ```json theme={null}
      {
        "roles": ["fullcontrol"],
        "grantedToIdentitiesV2": [{
          "application": {
            "id": "<Onyx App Client ID>",
            "displayName": "Onyx SharePoint Connector"
          }
        }]
      }
      ```
    </Step>

    <Step title="Verify">
      Change the method to **GET**:

      ```
      GET https://graph.microsoft.com/v1.0/sites/{site-id}/permissions
      ```

      Confirm `"roles": ["fullcontrol"]` appears for the Onyx app.
    </Step>
  </Steps>

  Repeat steps 3–5 for each site you want to index.
</Accordion>

### Step 5: Configure in Onyx

<Steps>
  <Step title="Open SharePoint connector">
    Navigate to the Onyx Admin Panel and select the **SharePoint** Connector.
  </Step>

  <Step title="Create Certificate credential">
    Click **Create New** credential and select the **Certificate** tab.
  </Step>

  <Step title="Enter credential details">
    * **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
  </Step>

  <Step title="Save credentials">
    Click **Create** to save your credentials.
  </Step>
</Steps>

### Step 6: Enable Permission Sync (Optional)

When creating your SharePoint connector with certificate authentication:

<Steps>
  <Step title="Locate Permission Sync option">
    In the connector configuration, you'll see a **Permission Sync** option.
  </Step>

  <Step title="Enable Permission Sync">
    Enable this option to synchronize SharePoint permissions with Onyx.
  </Step>
</Steps>

<Note>
  Permission sync is available only on Cloud and the Enterprise Edition of Onyx.
</Note>

## 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](/admins/connectors/official/sharepoint/client-secret).