chrome_extension.mdx

title	description	icon
Chrome Extension	Use Onyx in Chrome from any page	chrome

Onyx Chrome Extension

Use the Onyx extension to ask questions from anywhere. You can also replace your new-tab page with a custom Onyx page:

• Onyx Search on new tabs
• Favorite website bookmarks
• Onyx as a sidebar to any page in Chrome

In the future, the Onyx Chrome Extension will allow you to ask questions about the page you are currently on and optionally index the recent pages into the Onyx knowledge base. You'll be able to ask questions about recently visited pages via both the extension and the Onyx web app.

Setting up

If you are using Onyx Cloud, you can simply install the extension from the Chrome Web Store.

The following steps are for users self-hosting Onyx.

This feature is only available in Onyx versions v0.19.0 and above.

1. Visit chrome://extensions/ in your Chrome browser.
2. In the upper right corner, click Developer mode.
3. Click Load unpacked.
4. Select the folder that is the base of the Onyx Chrome Extension repository (for example, onyx-chrome-extension).
5. Click Load.
6. You will now have the Onyx Chrome Extension installed.
7. To configure settings, click the ... (three dots) next to the extension and select Options.
8. Set the Root Domain to your self-hosted Onyx instance's URL.

The Onyx Chrome Extension will now be able to connect to your self-hosted Onyx instance and can be used from any page in Chrome!

Chrome Extension Installation and Update Guide

This guide provides instructions for installing, managing, and updating Chrome extensions in both enterprise and self-hosted settings.

Enterprise Installation

Use these guidelines if you need to install and manage the Onyx Chrome Extension for a large group of users using Google Admin.

Step 1: Access Chrome Management

1. Log in to your Google Admin console.
2. Navigate to "Devices → Chrome → Apps and extensions".

Step 2: Install Extension

1. Obtain a copy of the custom published Chrome extension from an Onyx team member. They will provide you with the Chrome extension ID.
2. Inside the Admin console's Apps & extensions page, click the yellow plus icon to add the extension.
3. Specify the Chrome extension ID provided by the Onyx team member.
4. Click Add to confirm the installation.

Step 3: Configure Settings

1. In the Google Admin console, under "Devices → Chrome → Apps and extensions", locate the Onyx Chrome Extension.
2. Click on the extension to access its configuration settings.
3. Here, you can manage various deployment options, such as:
   • Force installation for all users or specific organizational units
   • Allow or block the extension for certain users or groups
   • Configure update settings and version pinning
   • Set installation policies (e.g., allowed, forced, or blocked)

Step 4: Save Changes

Don't forget to save your changes after configuring the extension.

Self-Hosted Installation

1. Clone or download the Onyx Chrome Extension repository.
2. Follow the steps in "Setting up" above to load the unpacked extension.
3. If you wish to serve the extension to a group of users, consider publishing it to the Chrome Web Store (see the next section on publishing) or hosting the CRX file yourself if you want a private distribution.

Publishing to Chrome Web Store (Optional)

Instead of loading the extension manually, you can package your extension and publish it as private or unlisted on the Chrome Web Store, making it available for force-installs or distribution to managed Chrome instances.

Updating Extensions

Below are strategies to keep the Onyx Chrome Extension up to date.

Enterprise Updates

If you have force-installed the extension through the Admin console, Google Chrome will handle automated updates. Updates typically occur when Chrome launches and then every five hours.

If you ever need to pin a specific Onyx Chrome Extension version (for compatibility reasons), you can set "Version pinning" for force-installed extensions within your Admin console. Avoid pinning for extended periods, because pinned extensions do not receive security updates.

Self-Hosted Updates

1. In your local Onyx Chrome Extension project, increment your extension's version in the manifest.json file (e.g., from "1.0" to "1.1").
2. Repack the extension (creating a new CRX file).
3. Replace or update the CRX file where your users install it from (if you're self-hosting).
4. If you're force-installing via Group Policy (GPO), update the extension version and URL in your GPO settings so that Chrome knows to download the new CRX.

Managing Extensions in Your Enterprise

If you manage a large organization, here are options to oversee which extensions users can install and how they're updated. Many of these guidelines align with enterprise best practices from Google's documentation on Chrome extension management.

Overview of Enterprise Extension Management Policies

Several policy-driven strategies can be enforced on managed devices:

Below is a brief overview of how to enforce these via Google Admin console or Windows Group Policy (GPO).

Allow or Block Extensions from the Google Admin Console

1. Go to Devices → Chrome → Apps & extensions → Users & browsers (or Managed browsers) and select your organizational unit.
2. Under Additional Settings, set your Allow/Block mode.
3. Allow all but block some: "Allow all apps, admin manages blocklist."
4. Block all but allow some: "Block all apps, admin manages allowlist."
5. To block or allow one extension, add it by Chrome Web Store URL or by Extension ID. Adjust its status to Block, Allow install, or Force install.

Force-Installing Extensions

Force-installing an extension ensures users have the extension silently added and cannot remove it:

1. Inside the Admin console/Apps & extensions page, add the extension (via the yellow plus).
2. In the Installation policy dropdown, select Force install.
3. Save changes.

Force-installed extensions will automatically update unless you pin them to a specific version.

Managing Extensions by Permissions

You can refine extension management by blocking or allowing certain permissions (for example, USB access, cookie access, etc.).

In the Admin console, go to your organizational unit at Devices → Chrome → Apps & extensions → Users & browsers → Additional settings (gear icon). Under Permissions and URLs, choose which permissions to block or allow. You can also override global permission settings on a per-extension basis in this section.

Protect Sensitive Websites: runtime_blocked_hosts

In many enterprise scenarios, you may want to block extensions from modifying or reading data on specific domains (for instance, internal corporate portals). This is done via runtime_blocked_hosts:

In the Admin console, go to Devices → Chrome → Apps & extensions → Users & browsers → Additional settings (gear icon). Under "Runtime blocked hosts," add patterns such as: ``` *://*.sensitive-domain.com ``` Under "Runtime allowed hosts," include host patterns you want to allow if they fall under a larger blocked domain.

This effectively prevents most extension-level script injections, web requests, or cookie access on specified sites.

Group Policy (GPO) Method (Windows)

If you're not using the Admin console, you can still manage Onyx (and other) Chrome extensions via Windows Group Policy:

Install the Chrome ADM/ADMX policy templates. Open gpedit.msc → Computer Configuration → Administrative Templates → Google → Google Chrome → Extensions. Configure: - Configure extension installation blocklist (ExtensionInstallBlocklist) - Configure extension installation allowlist (ExtensionInstallAllowlist) - Configure the list of force-installed apps and extensions (ExtensionInstallForcelist) - Extensions Management Settings (ExtensionSettings) Use JSON or registry entries to specify details (e.g., blocked_permissions, runtime_blocked_hosts, etc.).

For details on each policy, refer to Google's Chrome Enterprise policy list.

Self-Hosting the Onyx Chrome Extension

If you want to avoid the Chrome Web Store:

In Chrome, go to chrome://extensions, Enable Developer Mode, then click "Pack Extension." This creates a CRX file (and a private key PEM). Keep your PEM safe. Host the CRX & an Update Manifest XML on your server or intranet. Use either Google Admin console or GPO settings to point clients to your CRX update URL so Chrome will install/update automatically.

• Control release cycle
• Avoid Chrome Web Store listing

• Bypasses some security scans
• More maintenance overhead

Best Practices

- Regularly review and audit installed extensions. - Keep a short blocklist of known problematic extensions. - If possible, manage by permissions to allow only what's safe. - Use force-install for business-critical extensions (like Onyx). - Periodically update pinned extensions to reduce security risks.

For more detailed information, refer to:

• Official Google Chrome Enterprise documentation
• Onyx documentation and best practices for self-hosted environments