SharePoint Online Consent Authentication Configuration Guide

1. Overview

The Microsoft Graph API connection page in the SPOC Administrator Web Portal (Admin > Microsoft Graph API) controls how the SharePoint Online Connector authenticates to your Microsoft 365 tenant. This page walks through both supported authentication methods, how to switch between them, and how to grant, re-grant, or deny admin consent.

Two authentication methods are available:

• Admin Consent (Recommended) — use Gimmal's multi-tenant app registration. Requires a one-time admin consent grant from an Entra administrator.

• Certificate Authentication — use your own Azure AD app registration and an uploaded certificate.

Default behavior: A brand-new SaaS tenant defaults to Admin Consent. An existing tenant that was previously configured with Certificate Authentication will keep that method selected by default, but you can switch to Admin Consent at any time.

2 Configuring Certificate Authentication

Use this method if you prefer to manage your own app registration and certificate rather than relying on Gimmal's shared app registration.

2.1 Enter your Tenant ID and Client ID

1. Log in to the SPOC Web and navigate to Admin > Microsoft Graph API.

2. Under Authentication Method, select Certificate Authentication.

3. Enter the Tenant ID for your Azure AD directory.

4. Enter the Client ID for your Azure AD application.

5. Select the appropriate Azure Environment. The default is Public Cloud; choose China, US Government, US Government DoD, or US Government High only if your tenant requires it.

6. Click Save.

Validation: If you click Save while Tenant ID or Client ID is empty, a required-field message is shown under each empty field. Both fields must be completed before the configuration can be saved.

What happens after Save: Once the save succeeds, a Certificate section and an Upload Certificate button become visible, and the button label changes from Save to Update.

2.2 Upload your certificate

1. Click Upload Certificate. You are taken to the Microsoft Graph API Certificate Upload page.

2. Click Select File, locate your .pfx certificate file, and click Open.

3. If the certificate is password-protected, enter the Certificate Password.

4. Click Upload.

After the upload completes, the certificate's Thumbprint, Start Date, and Expires values are displayed. Confirm these match the certificate registered on your app in Entra ID (App registrations > Certificates & secrets).

2.3 Validate and save

1. Click Test Connection to confirm authentication succeeds. You should see "Test connection successful."

2. Click Update to save the configuration.

3. Configuring Admin Consent Authentication

Admin Consent is the recommended method for SaaS tenants. It uses Gimmal's own multi-tenant app registration, so no certificate management is required on the client side — only a one-time consent grant from an Entra administrator.

3.1 Granting consent as an Entra Administrator

1. Log in to the SPOC Web application.

2. Navigate to Admin > Microsoft Graph API. For a new tenant, Admin Consent is selected automatically.

3. Enter your Tenant ID.

4. Click Save. A Grant Admin Consent button appears, along with a shareable link (with a copy icon) that non-administrators can send to their Entra administrator. The button label changes to Update.

5. Click Grant Admin Consent. Microsoft's "Pick an account" page opens.

6. Select the account you are currently logged in as. A "Permissions requested" page opens for the connector application.

7. Click Accept.

Two confirmations appear: a banner reading "Admin consent granted successfully!" and, below the Admin Consent heading, "Consent Granted. Admin consent was granted on [date/time, UTC]." The button also changes from Grant Admin Consent to Re-grant Consent.

Confirming in Entra: You can confirm the connector application was created by going to entra.microsoft.com > All applications and locating the connector's app registration.

1. Click Test Connection to confirm authentication succeeds.

2. Click Update to save.

3.2 Requesting consent as a non-administrator

If you are not an Entra administrator, you cannot grant consent yourself, but you can request it from someone who can.

1. Log in to the SPOC Web and navigate to Admin > Microsoft Graph API. Admin Consent will already be selected and your Tenant ID populated if an administrator previously started the setup.

2. If consent has not yet been granted, click the copy icon next to "Share this link with your Entra administrator" and send the link to your Entra administrator through whatever channel your team normally uses.

3. Ask your administrator to open the link. It will take them to the "Pick an account" page, then a "Permissions requested" page, where they click Accept.

4. Once your administrator accepts, refresh the Microsoft Graph API page. You should see the same "Consent Granted" message and timestamp that your administrator sees.

If a non-administrator attempts to grant consent directly: Clicking Grant Admin Consent (or Re-grant Consent) as a non-administrator leads to Microsoft's "Need admin approval" page instead of a Permissions requested dialog. From there, use "Have an admin account? Sign in with that account" to switch to an administrator's credentials, or "Return to the application without granting consent" to go back — which will show a consent-denied message on the Microsoft Graph API page.

3.3 Re-granting consent

Once consent has been granted, the button changes to Re-grant Consent. This is useful if permissions have changed or consent needs to be refreshed.

1. As an Entra administrator, click Re-grant Consent.

2. Select your account on the "Pick an account" page.

3. On the "Permissions requested" page, click Accept.

4. The page returns to Microsoft Graph API Connection Settings with an updated "Consent Granted" timestamp.

3.4 What happens if consent is denied or canceled

If Cancel is clicked instead of Accept on the "Permissions requested" dialog, two messages appear:

• A temporary banner at the top of the page: "Consent was denied. If you are not an administrator, use the link below to send to your Entra administrator." (This clears after a short time or when you navigate away.)

• A persistent message under the Admin Consent heading: "Consent Required. Consent was denied or you do not have permission to grant consent. Try granting consent again if you have admin permissions," with a "Try granting consent again" link.

Clicking "Try granting consent again" restarts the flow from the "Pick an account" page. Completing it with Accept restores the normal "Consent Granted" status for all users.

Without consent granted: Actions that depend on the Graph API connection — such as adding a new site in Manage > Site Management, or adding a crawled library — will show an error message until consent is successfully granted.

4. Switching Between Authentication Methods

You can switch the Authentication Method radio button at any time. Values you previously entered for each method are preserved independently:

• Switching from Certificate Authentication to Admin Consent and back retains your Tenant ID, Client ID, Azure Environment selection, and uploaded certificate information.

• Switching to Admin Consent for the first time on an existing tenant presents the Admin Consent heading, description text, a Grant Admin Consent button, and the shareable link — exactly as it would for a new tenant.

After switching methods, click Update and then Test Connection to confirm the newly selected method is working before relying on it.

5. Verifying the Connection

After saving either authentication method, confirm the connection is functioning correctly:

1. Click Test Connection and confirm you see "Test connection successful."

2. Upload a few files to a site registered with SPOC.

3. Under Manage > Job Configuration, confirm the Incremental Classification job is scheduled to run (for example, every 5–10 minutes).

4. Confirm the uploaded files appear in Gimmal Records after the job runs.

If files do not appear and consent has not yet been granted (Admin Consent method) or the certificate/IDs are incorrect (Certificate Authentication method), correct the configuration and repeat Test Connection before re-checking the job.

6. Known Issues and Notes

The following behaviors have been observed and may not yet be resolved. They do not indicate a configuration mistake on your part:

• A non-administrator user may see an error when clicking Update or Test Connection on the Microsoft Graph API page even when the underlying configuration is valid. This has been reported and is being tracked.

• The "Pending Approval" status message (shown after a non-administrator requests consent) may display an unexpected date. This has also been reported and is being tracked.

If you hit an unexpected error: Confirm your Tenant ID (and, for Certificate Authentication, Client ID and certificate) are correct, then retry Test Connection. If the error persists, contact your support team with the exact error message and the authentication method in use.

7. Field Reference

Quick reference for every field and control on the Microsoft Graph API page: