OAuth & Authentication

Google and Microsoft require HTTPS for OAuth redirect URIs in production. If your Portal URL uses http://, OAuth login and account linking will not work. Exception: http://localhost is allowed for local development.

ClearFox includes a setup command that installs Caddy and configures HTTPS automatically (make sure DNS for your domain points to the server and ports 80/443 are open):

cd /opt/clearfox && sudo ./install.sh caddy ai.yourcompany.com

Alternatively, use nginx with Let's Encrypt, or a cloud load balancer (AWS ALB, Cloudflare Tunnel, etc.).

After setting up HTTPS, update the Portal URL in Admin → Settings to https://ai.yourcompany.com.

Then register the HTTPS redirect URIs in your OAuth provider console (Google Cloud Console or Azure Portal). Both URIs — Integration redirect URI and Sign-in redirect URI — are shown in Admin → Integrations: pick the provider in the left list and switch its OAuth block to mode My own app. Admin → Sign-in shows the sign-in URI on its own.

Connecting failed with a “needs admin approval” or “admin consent required” screen. The permissions requested (e.g. Mail.ReadWrite, Mail.Send) are not self-consentable under your identity provider’s user-consent policy, so a tenant/workspace administrator must grant consent once for the whole organization.

For Microsoft 365: an Entra admin grants consent to the ClearFox app — see Microsoft 365 OAuth Setup. For Google Workspace: see Google OAuth Setup.

After the admin grants consent once, retry the connection — the approval prompt will not reappear.

The sign-in was cancelled or consent was declined on the provider screen. Retry the connection and approve the requested permissions. If you did not expect a permission, check the integration’s setup guide for the ones it needs.

The stored token was revoked or expired (for example, a provider password change, or a Google app still in “Testing” that revokes refresh tokens weekly). Re-authorize the connection to issue a fresh token.

Workspace accounts — in Admin → Integrations select the provider and click Re-authorize next to the account under Workspace OAuth accounts.

Personal accounts — listed on the same page under User OAuth accounts, but only their owner can reconnect them: the user opens their own Integrations page and connects the account again. There is deliberately no Re-authorize button for the admin, because consent can only be granted by the account owner.

The provider returned an error that is not a consent prompt, a declined sign-in or an expired token — ClearFox reports it verbatim as Could not complete sign-in. This is almost always a misconfigured OAuth app: wrong Client ID or Secret, or a redirect URI that does not match the one registered.

Verify the setup in Admin → Integrations: pick the provider in the left list and, in the <Provider> OAuth box (mode My own app), check the Client ID and Secret and that the Integration redirect URI shown there is registered verbatim in the provider’s console. If the provider is in ClearFox proxy mode there is nothing to configure — contact support with the exact error text.