SharePoint Integration

This guide covers the additional steps required when hosting the Airgentic secure widget on a SharePoint Online intranet. It builds on the general Adding the Secure Widget to Your Site guide — complete those steps first, then follow the SharePoint-specific guidance below.

Overview

SharePoint Online has security restrictions that affect how external scripts are loaded and executed. The key things to be aware of are:

1. Content Security Policy (CSP) — SharePoint enforces a Content Security Policy that blocks external scripts unless explicitly trusted.
2. Custom scripts are restricted — Modern SharePoint pages do not allow arbitrary <script> tags. You cannot simply paste the Airgentic embed code into a page editor.
3. The widget works best as an SPFx web part — A SharePoint Framework (SPFx) web part is the recommended way to load the Airgentic widget on SharePoint Online.

Step 1: Add Airgentic as a trusted script source

SharePoint Online's Content Security Policy blocks external scripts that are not explicitly trusted. Your SharePoint administrator must add the Airgentic script domain as a trusted source.

1. Sign in to the SharePoint Admin Center and navigate to SharePoint settings. The admin center URL is typically https://<your-tenant>-admin.sharepoint.com.
2. Look for script or CDN settings — for example, Settings → Script management or similar. The exact location varies depending on your Microsoft 365 version and admin center layout.
3. Add the following domain as a trusted script source:

https://chat.airgentic.com

1. Save the change. It may take a few minutes to propagate.

Note: If you cannot find this setting in the admin center UI, your SharePoint administrator may need to configure it via PowerShell or the SharePoint API. Microsoft's documentation on allowing custom scripts provides additional guidance.

Without this step, the Airgentic widget script will be blocked by the browser and the widget will not load.

Step 2: Deploy the Airgentic SPFx web part

On modern SharePoint pages, you cannot insert a <script> tag directly. Instead, you need a SharePoint Framework (SPFx) web part that loads the Airgentic script.

Download the pre-built package

Airgentic provides a ready-to-deploy SPFx package. No build step required — just download, upload to your App Catalog, and configure.

Download airgentic-webpart.sppkg

To deploy:

1. Download the .sppkg file using the link above.
2. Open your SharePoint App Catalog site (typically https://<your-tenant>.sharepoint.com/sites/appcatalog).
3. Go to Apps for SharePoint and upload the .sppkg file.
4. When prompted, check Make this solution available to all sites in the organization if you want it available tenant-wide, then click Deploy.
5. Navigate to a SharePoint page, edit it, and add the Airgentic web part from the web part picker.
6. Configure the web part by clicking the edit (pencil) icon and entering your Account ID, Service ID, and Redirect URI in the property pane.

Airgentic will provide your Account ID and Service ID.

Optional: Search UI integration

If you want to use Airgentic's Search UI (a unified site search + chat overlay), the web part also supports these optional settings:

You can provide one or both. When configured, Airgentic will bind to your existing search elements and activate the Search UI overlay when users interact with them.

Building your own SPFx web part

If your organisation has a SharePoint developer and prefers to build or customise the web part, you can create your own SPFx project. This gives you full control over the web part's behaviour, allows you to integrate it into your existing SharePoint development workflow, and enables customisation such as styling or additional features.

<script
  id="airgentic-script"
  src="https://chat.airgentic.com/airgentic-1.4.js"
  data-account-id="your_account_id"
  data-service-id="your_service_id"
  data-auth-mode="oidc"
  data-auth-redirect-uri="https://yourorg.sharepoint.com/sites/intranet/SitePages/callback.aspx"
></script>

yo @microsoft/sharepoint

import { Version } from '@microsoft/sp-core-library';
import { BaseClientSideWebPart } from '@microsoft/sp-webpart-base';
import {
  IPropertyPaneConfiguration,
  PropertyPaneTextField
} from '@microsoft/sp-property-pane';

export interface IAirgenticWebPartProps {
  accountId: string;
  serviceId: string;
  redirectUri: string;
  searchInputId: string;
  searchButtonId: string;
}

export default class AirgenticWebPart extends BaseClientSideWebPart<IAirgenticWebPartProps> {

  private static SCRIPT_ID = 'airgentic-script';
  private static SCRIPT_SRC = 'https://chat.airgentic.com/airgentic-1.4.js';
  private scriptLoaded: boolean = false;
  private scriptError: boolean = false;

  public render(): void {
    const { accountId, serviceId, redirectUri } = this.properties;

    // Validate required properties
    if (!accountId || !serviceId || !redirectUri) {
      this.domElement.innerHTML = `
        <div style="padding: 20px; border: 1px solid #c7c7c7; border-radius: 4px; background: #f9f9f9;">
          <p style="margin: 0 0 10px 0; font-weight: 600;">Airgentic Widget - Configuration Required</p>
          <p style="margin: 0; color: #666;">Please configure the web part properties:</p>
          <ul style="margin: 10px 0 0 0; color: #666;">
            ${!accountId ? '<li>Account ID</li>' : ''}
            ${!serviceId ? '<li>Service ID</li>' : ''}
            ${!redirectUri ? '<li>Redirect URI</li>' : ''}
          </ul>
          <p style="margin: 10px 0 0 0; color: #666;">Click the edit (pencil) icon on this web part to open the property pane.</p>
        </div>
      `;
      return;
    }

    // Show error state if script failed to load
    if (this.scriptError) {
      this.domElement.innerHTML = `
        <div style="padding: 20px; border: 1px solid #d93025; border-radius: 4px; background: #fce8e6;">
          <p style="margin: 0; color: #d93025; font-weight: 600;">Failed to load Airgentic widget</p>
          <p style="margin: 10px 0 0 0; color: #666;">Please check that chat.airgentic.com is added to your SharePoint trusted script sources.</p>
        </div>
      `;
      return;
    }

    // Show loading state while script loads
    if (!this.scriptLoaded) {
      this.domElement.innerHTML = `
        <div style="padding: 20px; text-align: center; color: #666;">
          Loading Airgentic widget...
        </div>
      `;
    } else {
      this.domElement.innerHTML = `<div id="airgentic-container"></div>`;
    }

    // Only inject script once
    if (!document.getElementById(AirgenticWebPart.SCRIPT_ID)) {
      this.injectScript();
    }
  }

  private injectScript(): void {
    const { accountId, serviceId, redirectUri, searchInputId, searchButtonId } = this.properties;

    const script = document.createElement('script');
    script.id = AirgenticWebPart.SCRIPT_ID;
    script.src = AirgenticWebPart.SCRIPT_SRC;
    script.setAttribute('data-account-id', accountId);
    script.setAttribute('data-service-id', serviceId);
    script.setAttribute('data-auth-mode', 'oidc');
    script.setAttribute('data-auth-redirect-uri', redirectUri);

    if (searchInputId) {
      script.setAttribute('data-search-input-id', searchInputId);
    }
    if (searchButtonId) {
      script.setAttribute('data-search-button-id', searchButtonId);
    }

    script.onload = () => {
      this.scriptLoaded = true;
      this.render();
    };

    script.onerror = () => {
      this.scriptError = true;
      this.render();
    };

    document.body.appendChild(script);
  }

  protected onDispose(): void {
    // Clean up the script when the web part is removed
    const script = document.getElementById(AirgenticWebPart.SCRIPT_ID);
    if (script) {
      script.remove();
    }
    super.onDispose();
  }

  protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration {
    return {
      pages: [{
        groups: [
          {
            groupName: 'Airgentic Settings',
            groupFields: [
              PropertyPaneTextField('accountId', {
                label: 'Account ID',
                description: 'Your Airgentic account ID (provided by Airgentic)'
              }),
              PropertyPaneTextField('serviceId', {
                label: 'Service ID',
                description: 'Your Airgentic service ID (provided by Airgentic)'
              }),
              PropertyPaneTextField('redirectUri', {
                label: 'Redirect URI',
                description: 'The callback page URL (e.g. https://yourorg.sharepoint.com/sites/intranet/SitePages/callback.aspx)'
              })
            ]
          },
          {
            groupName: 'Search UI (Optional)',
            groupFields: [
              PropertyPaneTextField('searchInputId', {
                label: 'Search Input ID',
                description: 'The ID of your site\'s search input element (no # prefix). Leave blank if not using Search UI.'
              }),
              PropertyPaneTextField('searchButtonId', {
                label: 'Search Button ID',
                description: 'The ID of your site\'s search button element (no # prefix). Leave blank if not using Search UI.'
              })
            ]
          }
        ]
      }]
    };
  }

  protected get dataVersion(): Version {
    return Version.parse('1.0');
  }
}

npm install
npx heft build --production
npx heft package-solution --production

Alternative: classic pages with custom scripts enabled

If your SharePoint environment uses classic pages and your administrator has enabled custom scripts, you can use a Script Editor web part to paste the embed code directly. However, this approach is being phased out by Microsoft and is not recommended for new deployments.

Step 3: Set up the callback page

The authentication flow requires a callback page — the page your identity provider redirects users to after sign-in. On SharePoint, we recommend creating a dedicated callback page rather than using the same page that hosts the widget.

How authentication works

Understanding the authentication flow helps explain why the callback page is needed:

1. User starts on Page A — they interact with the Airgentic widget, which detects they need to sign in.
2. Browser redirects to Microsoft — the user signs in with their organisation credentials.
3. Microsoft redirects to the callback page — after successful sign-in, Microsoft sends the user to the redirect URI you registered (the callback page), not back to Page A.
4. Widget completes authentication — the Airgentic widget on the callback page sees the authorisation code in the URL, exchanges it for tokens, and stores the session.
5. User is now authenticated — the widget is ready to use on the callback page.

The user stays on the callback page after sign-in — they are not automatically returned to the page they started from. This is standard OIDC behaviour.

Why a dedicated callback page?

• SharePoint pages often have long URLs that vary across site collections. Using one dedicated page avoids redirect URI mismatches.
• You register a single, stable URL in your identity provider, reducing the risk of configuration errors.
• The callback page URL must exactly match what's registered in Entra ID — character for character.

How to set it up

1. Create a new SharePoint page — for example, https://yourorg.sharepoint.com/sites/intranet/SitePages/callback.aspx. You can name it anything (callback, airgentic-login, etc.).
2. Add the Airgentic web part — edit the page and add the same Airgentic SPFx web part.
3. Configure the web part — enter your Account ID, Service ID, and set the Redirect URI to this page's own URL.
4. The page can otherwise be blank — no other content is needed. The widget handles authentication automatically.
5. Register this URL in Entra ID — add this exact URL as a redirect URI in your app registration (see Registering Airgentic in your Identity Provider).

Configure other pages to use the callback

On every other page where you add the Airgentic web part, set the Redirect URI property to point to your callback page — not to the page itself.

For example, if your callback page is https://yourorg.sharepoint.com/sites/intranet/SitePages/callback.aspx, then:

All pages point to the same callback URL.

Where should users land after sign-in?

Since users stay on the callback page after authentication, consider making it a page where they'd naturally want to use the widget — such as your main intranet homepage — rather than a blank page.

Alternatively, you can create a simple callback page with a message like "You're now signed in. Return to [Homepage] to continue." with a link back.

Step 4: Configure your allowed origin

Your SharePoint origin must be included in the Airgentic service configuration. When you send your details to Airgentic (see Registering Airgentic in your Identity Provider), include your SharePoint origin:

https://yourorg.sharepoint.com

If your organisation uses a custom domain for SharePoint (e.g. https://intranet.yourorg.gov.au), use that instead.

Important considerations

Avoid wrapping the SharePoint page in another iframe

The Airgentic widget itself uses iframes internally — this is normal and works correctly on SharePoint.

However, if the SharePoint page that hosts the widget is loaded inside another iframe (for example, if someone embeds the SharePoint page within Microsoft Teams using an iframe, or wraps it in a third-party portal), the authentication redirect may fail. Identity providers such as Microsoft Entra ID block their sign-in pages from rendering inside nested iframes.

Ensure the SharePoint page with the Airgentic widget is loaded as a top-level page in the browser, not embedded inside another frame.

Microsoft Teams and Viva Connections

If your intranet is accessed through Microsoft Teams or Viva Connections, be aware that these environments can wrap SharePoint pages in ways that interfere with redirect-based authentication. If your users access the intranet through Teams or Viva, test the widget in those environments specifically to confirm the sign-in flow works correctly.

Session storage

The widget stores authentication state in the browser's session storage, scoped to the top-level window. This means:

• Session storage is shared across tabs within the same browser window, so users typically don't need to sign in again when opening new tabs.
• However, if a user opens a completely new browser window (not just a new tab), they will need to sign in again.
• This is normal and expected behaviour.

Group claims with many groups

If your organisation uses group-based authorisation and users belong to a large number of groups (more than 150), Microsoft Entra ID may not include all groups directly in the token. In this case, Entra ID returns a link to the Microsoft Graph API instead. If you plan to use group-based authorisation, let Airgentic know how many groups your users typically belong to so we can ensure the configuration handles this correctly.

Checklist

Troubleshooting

Widget does not appear on the page

• Check the browser's developer console (F12 → Console) for CSP errors mentioning chat.airgentic.com. If present, the trusted script source has not been added (Step 1).
• Confirm the SPFx web part is deployed and added to the page.

"Redirect URI mismatch" error after sign-in

• The callback URL in data-auth-redirect-uri does not exactly match the redirect URI registered in Entra ID. SharePoint page URLs are case-sensitive and include the full path — ensure they match character for character.

Sign-in redirects in a loop

• This can happen if the callback page does not include the Airgentic widget script/web part. The widget needs to run on the callback page to complete authentication.

Widget works but chat returns "unauthorised"

• Your account does not match the authorisation rules. Check with Airgentic that your email domain, address, or group membership is included.

If you need help, contact Airgentic support — see Contacting Airgentic.

← Back to Secure Services overview