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