Authentication
Agentweaver uses Microsoft Entra ID for browser sign-in and platform authorization. Sign in with your organization account. Entra App Roles and project assignments control your Agentweaver actions.
The deployed OAuth issuer is pinned to the configured public HTTPS origin, and the MCP resource is always that exact origin plus /mcp. It is not inferred from request headers. Hosted signing and encryption keys come from the active and previous usable versions of configured Azure Key Vault certificate families.
GitHub access is separate from sign-in. The Copilot App provides AI access. The Repo App provides repository access. MCP clients use the separate broker flow described in MCP OAuth.
Signing in
When your session expires, select Sign in with Microsoft Entra ID. Browser sign-in uses an authorization code with PKCE.
After a successful sign-in, Agentweaver sets a host-only, HttpOnly, Secure, SameSite=Lax browser-session cookie. It lets additional tabs in the same browser profile restore the signed-in Agentweaver session without repeating Entra sign-in. The session has a fixed eight-hour lifetime from successful sign-in. Activity does not extend that deadline; signing in again replaces the current browser session with a new eight-hour session. Signing out revokes the server-side session immediately and expires the cookie. The cookie is never shared with another host or browser profile.
This browser-session lifetime does not extend the Microsoft Entra access token. The tab-local bearer token remains a compatibility mechanism and is kept only in sessionStorage; Agentweaver does not put bearer tokens in cookies or localStorage. The opaque browser cookie restores identity for new tabs and binds OAuth handoffs, but does not replace bearer authorization for platform API operations.
For a TLS-terminating reverse proxy, configure Auth:OAuth:ForwardedHeaders:TrustedNetworks with only the proxy network(s), and forward the original HTTPS scheme and public host. Agentweaver applies forwarded headers before authentication. Do not terminate the public browser flow over HTTP or broaden the trusted proxy list: a Secure host-only cookie will not persist over HTTP, and untrusted forwarded headers weaken the origin boundary.
If no platform role exists, ask a Platform Admin to assign one in Microsoft Entra ID. Then reload Agentweaver.
Complete required setup
A model provider is the required activation milestone. Agentweaver blocks AI work until this setup is ready.
A Platform Admin can choose one active model provider:
- GitHub Copilot with a platform account
- A custom-key provider
The Platform Admin can add more providers during required setup. Only one provider is active at a time.
An active platform custom-key provider (BYOK) applies to both personal sessions and project work, subject to the requested operation's eligibility. Platform-default Copilot supplies inheriting project/background work, not personal session chat.
Unattended work never reuses a browser bearer token. Before schedule, event, or heartbeat execution, Agentweaver captures the selected durable provider authority in an activation and copies a purpose-bound capability snapshot to the run. Project provider bindings take precedence over platform providers. If an active project binding is expired or revoked, execution fails closed instead of falling through to a different identity. A configured BYOK provider follows the same activation and run-snapshot boundary.
If you cannot manage this setup, Agentweaver shows Unavailable to you. Ask a Platform Admin to complete the setup.
When the provider is ready, select Continue to Agentweaver. Agentweaver checks the current platform provider again, then returns to the page that sent you to setup. The app does not use a cached setup result. If the provider is unavailable, the setup page stays open and tells you to refresh its status. Agentweaver starts a short product tour after the first successful setup.
The tour introduces Projects, Sessions, and Start task. You can skip the tour or press Escape.
To start the tour again, open the settings menu. Then select Take product tour.
GitHub capabilities
Repository access is optional. Local agent work can continue without a GitHub repository.
Pull-request publishing and GitHub repository operations require repository access. Authorize the Repo App when you start one of these actions.
When you create a project from GitHub, authorize the Repo App. Then select a repository from the bounded list. The list is the intersection of repositories you can access and repositories granted to the Agentweaver GitHub App installation. Installation settings can grant all repositories or only selected repositories. If the saved Repo App access token expires or GitHub rejects it, repository browsing renews it through the stored Repo App refresh token and retries once. A temporary GitHub or refresh failure returns 503 github_capability_transient; retry later rather than reconnecting. If the refresh token is rejected, repository selection returns 409 github_binding_unavailable; authorize repository access again. The connected GitHub login in Account settings reports the saved authorization, not proof that an installation still grants a particular repository.
Agentweaver verifies the repository selection on the server. It does not accept an unverified repository identifier.
The project readiness check reports separate capability dimensions:
unattended_ready: a durable project or platform provider can execute the unattended purpose, and required repository access is ready.interactive_ready: the current user can run interactively, but no durable provider can run unattended work.repository_ready: required Repo App access is ready, but the unattended model provider is not.reauthorization_required: a selected provider credential expired or was revoked and must be connected again.unavailable: neither the current interactive session nor unattended execution can use a provider for the requested purpose.
A repositoryless project does not require a Repo App installation. A GitHub-backed project is repository-ready only when the Repo App installation and its project repository grant are both current. For GitHub-origin projects, accepting a new BYOK run also captures and fences the project's repository grant before creating the run. If that grant is unavailable, the start request returns 409 repo_app_repository_grant_required; reconnect the Repo App and grant the selected repository, then prepare a new execution context and retry. Readiness is a point-in-time check, not a promise that a grant cannot later be revoked. Static workflow fan coordinators and their selected child agents each inherit and revalidate the same run-bound repository grant. A grant revoked or changed after acceptance still blocks child launch rather than falling back to ambient access.
Repository status alone never makes a project unattended-ready. For GitHub Copilot, the readiness check verifies that the selected live binding still has the complete grant and credential tuple required to issue an UnattendedCopilot run snapshot, refreshes the credential when possible, and rechecks the binding after the vault read. For custom-key providers, it verifies that the exact selected provider configuration is still active.
After you connect the Repo App, Account settings → GitHub connections shows a GitHub installation settings link for each installation available to your signed-in account. Use these GitHub-managed links to change repository grants. The connected GitHub login and the repository installation grants remain separate; if Agentweaver cannot retrieve an installation-management link, it keeps the connection status and does not show a link.
Provider hierarchy
| Work scope | Resolution order | Failure boundary |
|---|---|---|
| Project orchestration and background work | Active project Copilot binding; otherwise platform BYOK, then platform-default Copilot | An unusable active project binding fails closed; it does not fall through |
| Personal Assistant sessions | Platform BYOK, then personal BYOK, then personal Copilot | No platform-default Copilot or ambient browser credential fallback |
Repository access is a separate capability. Provider readiness does not grant repository access or make an otherwise ineligible operation available.
A project can use a project GitHub Copilot account. Otherwise, project work inherits the active platform GitHub Copilot account or custom-key provider. This project hierarchy applies to orchestration and background work.
Open Project settings → Background to see the effective model provider. The status identifies the provider and its project or platform scope.
Project and platform Copilot authorization creates a durable server-side binding. Agentweaver does not borrow the token of whichever user is currently signed in, and the Copilot App has no repository installation screen. Repository authorization remains a separate Repo App capability. Personal session chat uses a separate account-level hierarchy:
- An active platform custom-key provider applies automatically to every user.
- Otherwise, the user can select a personal custom-key provider.
- Otherwise, the user must authorize their own GitHub Copilot account.
Agentweaver does not use the platform-default Copilot credential for personal session chat because Copilot entitlement belongs to the individual GitHub account. Open Account settings → AI Access to authorize Copilot or add a personal provider. These settings do not change project background execution. When the resolved account-level hierarchy has no usable provider, Agentweaver shows a one-time, dismissible setup prompt that links directly to these settings.
A Copilot binding keeps the refresh token that GitHub returns with its access token. GitHub access tokens expire after about eight hours. Agentweaver redeems the refresh token automatically, shortly before the access token expires, and stores the new pair. You do not reconnect after an expiry. Agentweaver asks you to connect again only when GitHub rejects the refresh token, for example after you revoke the authorization.
GitHub authorization does not replace your Entra identity. It does not grant an Agentweaver platform role or project membership.
Project roles in Agentweaver do not translate to GitHub permissions. Repository and Copilot capabilities are granted only through their respective GitHub Apps.
Callback registration
One exact Copilot App callback serves project-scoped, platform-default, and personal-user OAuth completion flows. Persisted one-time state selects the correct flow. The MCP browser handoff enters the project-scoped flow.
https://<public-host>/auth/github/copilot-app/callbackRegister it with wildcard matching disabled. GitHub currently allows up to 10 callback URLs. Apps created before 2026-08-03 with one callback URL may have wildcard matching enabled by default; explicitly inspect and disable it for exact matching. Repo App authorization uses the separate /auth/github/repo-app/callback, while Entra sign-in uses /auth/entra/callback; each belongs on its corresponding application. A wildcard for one callback path does not match a sibling path.
When migrating a Copilot App client ID shared by older deployments, add the new exact URL first. Keep the old exact URL temporarily, inventory deployment versions and the shared client ID, upgrade everything to v0.23.1 or later, then wait 15 minutes after the last older deployment stops before removing the old URL. On deployed staging, verify project-scoped, platform-default, and personal-user completion, plus the MCP browser handoff into the project-scoped flow. Local end-to-end testing may be impossible when Entra redirects are deployment-only, so deployed staging is the end-to-end proof. See Configuration for the full operator sequence.
Signing out and errors
To sign out, open the account menu and select Sign out. Its footer also shows the current Agentweaver version and API status. In-flight runs continue on the server.
If sign-in fails, make sure that your Entra account has an Agentweaver App Role.
If the redirect fails, make sure that the Entra redirect URI matches the deployed Agentweaver URL.
Authentication and authorization callbacks use the same lightweight Agentweaver dialog, including flows that finish outside the main web app. Each dialog identifies success, pending approval, cancellation, expiry, or failure and tells you whether to return to Agentweaver, return to the MCP client, retry, or close the tab. These pages do not show OAuth codes, tokens, state values, callback cookies, or raw identity-provider errors. Unknown provider errors are replaced with safe guidance.
MCP browser handoffs keep polling in the client while the completion tab shows its final status. Closing that tab does not cancel or repeat the authorization. If the browser cannot close the tab automatically, close it with the browser controls and return to the MCP client.