# Organization admin access ## Organization onboarding and project access 1. The super admin creates an organization with its primary owner's email. Mailgun sends a one-time setup link valid for 24 hours. The owner opens it, sets a password, and enters the organization dashboard. If delivery fails, the super admin can resend from **Organizations**; resending invalidates the previous link. 2. In **Admin access → Join settings**, the owner can enable self-registration and optionally enable member password login. With self-registration enabled, Google, Okta and brokered SAML can enroll members with verified email. With password login also enabled, members can choose **Request to join** on `/login` and verify their mailbox through a setup link. The email address is the username. Membership alone grants no project access. 3. In **Projects → Manage project**, search or scroll through active organization users. **Add** grants project access; **Remove** revokes both membership and any agent tokens the member issued for that project. Select **Make project admin** to delegate membership, visibility, and policy management for this project. A delegated admin manages the project from **My agents**; organization admins manage who holds project admin roles. 4. In **Project settings**, attach published custom policies or set visibility. **Private** projects require assignment by an admin; **Public to organization** projects let active organization members select **Join project** from **My agents**. When creating an organization with a primary owner, bonsai3 creates a private **Default project** and auto-assigns new users when their account becomes active. An organization admin can change or clear the default from **Projects**; existing memberships are unaffected. 5. In **Project settings**, choose which built-in policies apply. Secure-development policies start selected and can be removed. PCI DSS policies start unchecked and apply only when explicitly selected for that project. Select **Save project settings** to apply changes. 6. An assigned member can open **My agents**, register an agent, and copy its project token into their MCP client as a bearer token. Use `https://bonsai3.ai/mcp` on the primary deployment. The token selects the project for `security_context`; no project or tenant argument is needed. Published revisions of attached custom policies take effect automatically. Configure `POLICY_GATE_PUBLIC_URL=https://bonsai3.ai` for canonical invite links and OAuth redirects. `https://bonsai3.io` is also in the default MCP origin allowlist. Set up DNS, TLS, and reverse proxy routing for these domains in your deployment. For a local password-login test set `POLICY_GATE_PUBLIC_URL=http://localhost:4000` and use that exact origin in your browser. Existing organizations without explicit project scope retain inherited custom policies until you save their project scope. ## Configure single sign-on 1. Create the organization with the super-admin dashboard. Copy its ID from Organizations or Admin access. 2. Set `POLICY_GATE_PUBLIC_URL` to the externally accessible bonsai3 origin, with no path or trailing slash (e.g. `https://bonsai.example.com`). Plain HTTP is accepted only for `localhost` or `127.0.0.1` development. Serve HTTPS through your reverse proxy for deployed environments. 3. Register a confidential web client in each identity provider with the exact redirect URI `https://bonsai.example.com/auth/sso/callback`. Set the server's `POLICY_GATE_SSO_CONFIG` to a JSON object keyed by bonsai3 organization ID. Include only the providers you want enabled. Supply client secrets via your host's secret manager, not version control. For dashboard-managed SSO, set `POLICY_GATE_SSO_ENCRYPTION_KEY` to a persistent Base64-encoded 32-byte secret (`openssl rand -base64 32`). Then use **Admin access → Configure** next to a provider. Stored provider secrets are encrypted and are not returned to the browser. For custom Okta issuers and SAML brokers, list the exact approved issuer URLs in `POLICY_GATE_OKTA_ISSUERS` and `POLICY_GATE_SAML_ISSUERS` respectively (comma-separated). Google, Okta and SAML broker logins can link to verified existing accounts. Microsoft admin sign-in uses the Entra object ID supplied through the SSO admin invitation flow. ```json { "YOUR_BONSAI3_ORG_ID": { "google": {"client_id": "…", "client_secret": "…"}, "okta": {"issuer": "https://example.okta.com/oauth2/default", "client_id": "…", "client_secret": "…"}, "microsoft": {"tenant_id": "11111111-1111-1111-1111-111111111111", "client_id": "…", "client_secret": "…"}, "saml": {"issuer": "https://identity.example.com/realms/bonsai3", "client_id": "…", "client_secret": "…"} } } ``` - **Google:** Register an OAuth client of type Web application. - **Okta:** Register an OIDC Web Application, use the issuer of your authorization server, and assign the app to permitted users. The token endpoint must support client-secret basic authentication. - **Microsoft Entra ID:** Register a single-tenant Web app, supply the directory tenant ID, and enter each invited admin's **user object ID from that tenant** in bonsai3. The app binds to the directory object ID, not to a writable email or username claim. - **SAML:** Configure a SAML identity provider in a broker such as Keycloak. Connect bonsai3 to a dedicated OIDC client/realm in the broker configured to require that upstream SAML identity provider for sign-in. Register the broker's SAML ACS URL and signing requirements with the upstream IdP; register the bonsai3 callback with the broker's OIDC client. Configure the broker to emit a trustworthy `email_verified: true` only for verified email addresses. bonsai3 verifies the broker's OIDC tokens; it does not expose a native SAML ACS. Google, Okta and the SAML broker must provide a verified email in the ID token for initial binding to an invited admin. The issuer/client and provider subject identify that admin on subsequent sign-ins. Restart bonsai3 after deploying the configuration. ## Invite admins with Mailgun Configure these server environment variables to send email: | Variable | Value | | --- | --- | | `MAILGUN_API_KEY` | Mailgun sending key (`POLICY_GATE_MAILGUN_API_KEY` is also accepted) | | `POLICY_GATE_MAILGUN_DOMAIN` | Verified Mailgun sending domain | | `POLICY_GATE_MAILGUN_FROM` | Sender address on that domain | | `POLICY_GATE_MAILGUN_REGION` | `eu` for Mailgun EU; otherwise US | In the dashboard, open **Admin access → Invite admin**. Enter the invited email, add the Entra user object ID if using Microsoft, and select **Send an invitation email via Mailgun**. The link prefills their organization name on the sign-in page. Mailgun acceptance means queued for delivery, not confirmed delivery. If delivery fails, membership is still saved; retry the invitation or share the organization name separately. To enroll without email, uncheck the box. At `/login`, enter the organization name for password login, signup, or SSO. Names are unique for new organizations and are matched without regard to case. Existing ID-based invitation links still work. If legacy organizations share the same name, use their original invite links to select the intended organization. Browser sessions last up to eight hours and end on server restart or when the admin signs out. Removing an SSO admin invalidates their current sessions. Bootstrap super-admin and organization API tokens retain their existing sign-in paths.