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.

Entra registration and access

Before provisioning or deploying an Entra-enabled installation, reconcile the exact application registration and its deployed callback URI:

npm run azure:setup-entra-app -- \
  --app-id "$ENTRA_CLIENT_ID" \
  --redirect-uri "https://<public-host>/auth/entra/callback"

This idempotent setup enables the delegated access_as_user API scope on the Agentweaver app, requests v2 access tokens, adds the app's own resource as a delegated permission, and preauthorizes only the app's own public client for that scope. If the app has no API identifier URI, it also adds api://<client-id>; an existing identifier URI is preserved. The self-client preauthorization tells Entra that this client is already approved for this delegated scope, suppressing the user-consent prompt for it. No separate global-admin consent operation is required for this self-preauthorized scope. This does not preauthorize other clients or grant an Agentweaver App Role. It preserves unrelated scopes, permissions, preauthorized clients, roles, redirects, and settings. Re-run it when the registration or callback changes. Do not add a directory-wide Graph permission or grant broad consent to repair this sign-in flow.

Setup writes and verifies the API scope/resource before sending a second Graph update for self-preauthorization. Microsoft Graph rejects a new preauthorization reference until its delegated scope ID exists in the app's permission set; the setup command allows bounded propagation time and verifies the persisted scope before continuing.

The delegated permission and App Roles do different jobs: access_as_user allows the app to request a token for its own API; an assigned App Role such as PlatformAdmin, ProjectCreator, Contributor, or Viewer authorizes Agentweaver actions. A successful token request alone does not grant a role. Use the least-privileged platform role that meets the user's needs. PlatformAdmin already has access across all projects and does not need project memberships.

For a fresh-user verification, assign the appropriate platform App Role to a test user who has not previously consented to the app, then sign in as that user. Verify that Entra completes sign-in without prompting that user for consent to access_as_user. If Entra reports AADSTS650057 (invalid resource), verify the exact app has an enabled delegated access_as_user scope, its own client ID and scope ID appear in requiredResourceAccess, its public client is preauthorized for that scope, and api.requestedAccessTokenVersion is 2. Reconcile with the command above, then retry the fresh-user check.

Provisioning, local deployments, and non-dry-run release deployments perform a read-only preflight against the active Azure CLI tenant and exact app registration before making infrastructure or image changes. If the preflight reports that the registration is incomplete, reconcile it first. If it cannot read the tenant or app, run az login --tenant "$ENTRA_TENANT_ID" and ensure the operator can read the application registration, then rerun installation.

Project membership uses the Entra user Object ID (a UUID), not an email, display name, application ID, or service-principal ID. Find it in the user's Entra profile or resolve it with az ad user show --id "<user-principal-name>" --query id -o tsv, then enter that UUID in Project settings → Access. Existing email-based assignments are invalid and must be removed and re-added with the user's Object ID; they are not automatically mapped or migrated. Only grant project roles where needed; do not add project memberships for a PlatformAdmin.

Carry-forward to 1.x

Do not copy the 0.x self-resource .default registration fix into 1.x. The 1.x installer registers /signin-oidc, and the Broker authorizes its local sub identity through the Projects membership model; see the 1.x follow-up.

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:

1. An active platform custom-key provider applies automatically to every user.
2. Otherwise, the user can select a personal custom-key provider.
3. 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/callback

Register 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.