> ## Documentation Index
> Fetch the complete documentation index at: https://danswer-docs-google-drive-connector.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Steps>
  <Step title="Open App registrations">
    Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com/)
    or the [Azure portal](https://portal.azure.com/) and go to **App registrations**.
  </Step>

  <Step title="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**.
  </Step>

  <Step title="Record the two IDs">
    On the application's **Overview** page, copy the **Application (client) ID** and the **Directory (tenant) ID**.
  </Step>
</Steps>

## Create the certificate

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

<Steps>
  <Step title="Generate the private key and certificate">
    ```bash theme={null}
    # 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"
    ```
  </Step>

  <Step title="Package the private key as a .pfx">
    ```bash theme={null}
    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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Note>
  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`.
</Note>

## Upload the public certificate to Entra

<Steps>
  <Step title="Open Certificates & secrets">
    In your app registration, go to **Certificates & secrets → Certificates**.
  </Step>

  <Step title="Upload the certificate">
    Select **Upload certificate**, choose `onyx-sharepoint.crt`, add a description, and select **Add**.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

## 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.

<Steps>
  <Step title="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](/admins/connectors/official/sharepoint/sharepoint#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.
  </Step>

  <Step title="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.

    <Note>
      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](/admins/connectors/official/sharepoint/sharepoint#limiting-the-app-to-specific-sites).
    </Note>
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Note>
  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.
</Note>

## Add the credential to Onyx

<Steps>
  <Step title="Open the SharePoint connector">
    In Onyx, go to **Admin Panel → Add Connector** and select **SharePoint**.
  </Step>

  <Step title="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
  </Step>

  <Step title="Save and continue">
    Select **Create**, confirm the new credential is selected,
    and continue to the connector settings described in [Configure the connector in
    Onyx](/admins/connectors/official/sharepoint/sharepoint#configure-the-connector-in-onyx).
  </Step>
</Steps>

## 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.

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

## Troubleshooting

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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](#create-the-certificate).
  </Accordion>

  <Accordion title="Unsupported app only token">
    The connector is using a client secret credential rather than this certificate.
    Check which credential it is attached to.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Indexing worked, then stopped on a fixed date">
    The certificate expired. Repeat [Create the certificate](#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.
  </Accordion>
</AccordionGroup>

For problems with sites, scoping, file types, and content,
see [Troubleshooting](/admins/connectors/official/sharepoint/sharepoint#troubleshooting) on the overview page.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.