Merge branch 'main' into release/v0.82.0

Author: junaway

docs/docs/administration/access-control/01-organizations.mdx

@@ -0,0 +1,119 @@
+---
+title: Organizations & Projects
+description: Manage organizations, projects, and team members in Agenta
+slug: /administration/access-control/organizations
+---
+
+# Organizations & Projects
+
+Agenta organizes work around **organizations** and **projects**.
+
+## Hierarchy
+
+```
+Organization
+└── Project(s)
+    └── Resources (prompts, evaluations, traces, etc.)
+```
+
+- **Organization**: Where team members, billing, and access policies reside
+- **Projects**: Where you build and operate your LLM apps (prompts, evaluations, observability)
+
+## Organizations
+
+### Creating an Organization
+
+Organizations are created during signup or from the organization switcher.
+
+### Switching Organizations
+
+If your user account is part of multiple organizations, use the organization switcher in the UI to move between them. Your role and permissions can differ per organization.
+
+## Projects
+
+Projects live inside an organization and contain:
+
+- Prompt and configuration assets
+- Evaluation artifacts (test sets, runs, results)
+- Observability data (traces/spans)
+
+Project creation and visibility depend on your organization role.
+
+### Switching Projects
+
+If your organization has multiple projects, use the project switcher in the UI to move between them. Your api keys as well as custom providers and models will differ per project.
+
+## Managing Members
+
+### Inviting Members
+
+1. Navigate to **Settings** → **Members**
+2. Click **Invite member**
+3. Enter the email address
+4. Choose a role (if RBAC is available in your organization)
+5. Send the invitation
+
+### Roles
+
+Roles control what members can do within an organization and its projects:
+
+| Role | Summary |
+|------|---------|
+| **Owner** | Full control of the organization, including billing and member management |
+| **Admin** | Administer members and organization settings |
+| **Editor** | Create and edit project resources |
+| **Viewer** | Read-only access |
+| **Evaluator** | Run and review evaluations |
+| **Deployment Manager** | Manage deployments |
+
+See [RBAC](/administration/access-control/rbac) for details.
+
+### Changing Roles
+
+Owners and Admins can change roles from **Settings** → **Members**.
+
+### Removing Members
+
+Removing a member immediately revokes access to the organization and its projects.
+
+## Billing
+
+Billing, subscription management, and usage tracking are linked to the organization.
+
+## Access Policies
+
+Organizations can configure:
+
+- **SSO providers** (Business and Enterprise)
+- **Verified domains** (Business and Enterprise)
+
+## Troubleshooting
+
+### Can't access an organization
+
+Common causes:
+
+- You're signed in with a different email than the one invited
+- The organization requires SSO and you haven't completed SSO sign-in
+- Your invitation expired
+
+### Can't invite members
+
+Common causes:
+
+- You don't have permission (need Owner or Admin)
+- You've reached member limits on your plan
+
+## FAQ
+
+### Can I belong to multiple organizations?
+
+Yes. You can switch between organizations from the organization switcher.
+
+### Can I transfer ownership?
+
+Yes. Owners can transfer ownership to another member from organization settings.
+
+### How many organizations can I create?
+
+There are no limits but subscriptions and usage are per organization.

docs/docs/administration/access-control/02-sso.mdx

@@ -0,0 +1,269 @@
+---
+title: Single Sign-On (SSO)
+description: Configure SSO with OIDC providers like Okta, Azure AD, and Google Workspace
+slug: /administration/access-control/sso
+---
+
+# Single Sign-On (SSO)
+
+Single Sign-On enables your organization to centralize authentication through your existing identity provider (IdP) such as Okta, Azure AD, or Google Workspace.
+
+:::info[Plan availability]
+SSO is available on **Business** and **Enterprise** plans. You can upgrade from your billing settings or see options at https://agenta.ai/pricing.
+:::
+
+## Why Use SSO?
+
+SSO provides team benefits:
+
+- **Centralized access control**: Manage access through your IdP
+- **Improved security**: Enforce your organization's authentication policies
+- **Better compliance**: Meet audit and compliance requirements
+- **User convenience**: One set of credentials for all applications
+- **Immediate deprovisioning**: Revoke access instantly when employees leave
+
+## Supported Protocols
+
+Agenta currently supports **OpenID Connect (OIDC)** for SSO (with SAML/SCIM coming soon). This works with most enterprise identity providers:
+
+- Okta
+- Azure Active Directory (Entra ID)
+- Google Workspace
+- Auth0
+- OneLogin
+- Any OIDC-compliant provider
+
+## Setting Up SSO
+
+### Prerequisites
+
+Before configuring SSO:
+
+1. Business or Enterprise plan subscription
+2. Owner or Admin role (organization)
+3. Admin access to your identity provider
+4. OIDC application credentials from your IdP
+
+### Step 1: Configure Your Identity Provider
+
+Create an OIDC application in your IdP with these settings:
+
+| Setting | Value |
+|---------|-------|
+| **Application Type** | Web Application |
+| **Grant Type** | Authorization Code |
+| **Redirect URI** | `https://{region}.cloud.agenta.ai/auth/callback/sso:{organization_slug}:{provider_slug}` |
+| **Scopes** | `openid`, `email`, `profile` |
+
+You'll need these values from your IdP:
+- **Issuer URL**: Your IdP's issuer endpoint
+- **Client ID**: Application/Client ID
+- **Client Secret**: Application/Client Secret
+
+### Step 2: Add Provider in Agenta
+
+1. Navigate to **Settings** → **Access & Security** → **SSO Providers**
+2. Click **"Add Provider"**
+3. Enter the provider details:
+   - Provider slu (e.g., "okta", "azure", "google")
+   - Issuer URL
+   - Client ID
+   - Client Secret
+   - Scopes (default: `openid email profile`)
+4. Click **"Save"**
+
+### Step 3: Test and Enable
+
+1. Click **"Enable"** on your provider
+2. Agenta validates the OIDC configuration
+3. If validation succeeds, the provider is active
+4. Test by signing in with SSO
+
+### Step 4: Enable SSO for Your Organization
+
+1. Navigate to **Settings** → **Access & Security** → **Authentication**
+2. Enable **"Allow SSO"**
+3. Save changes
+
+Users can now sign in using SSO.
+
+## SSO Enforcement
+
+### Gradual Rollout
+
+We recommend a phased approach to SSO adoption:
+
+#### Phase 1: SSO Available (Optional)
+
+```
+allow_email: true
+allow_social: true
+allow_sso: true
+```
+
+- SSO is available as an option
+- Users can choose any authentication method
+- Good for testing
+
+#### Phase 2: SSO Encouraged
+
+- Same settings as Phase 1
+- Communicate to users: "Please start using SSO"
+- Monitor adoption
+
+#### Phase 3: SSO Required
+
+```
+allow_email: false
+allow_social: false
+allow_sso: true
+```
+
+- Only SSO authentication allowed
+- Email and social sign-in disabled
+
+:::warning[Prevent Lockout]
+Always ensure at least one authentication method is available. Consider keeping a backup admin account with email access (`allow_root: true`) until SSO is fully tested.
+:::
+
+## Multiple SSO Providers
+
+Organizations can configure multiple SSO providers:
+
+**Use cases:**
+- Regional identity providers
+- Backup providers for redundancy
+- Different providers for different user groups
+
+Users choose which provider to authenticate with when signing in.
+
+## Provider-Specific Guides
+
+### Okta
+
+1. **Create Application**
+   - Applications → Create App Integration
+   - Sign-in method: OIDC
+   - Application type: Web Application
+
+2. **Configure Settings**
+   - Sign-in redirect URI: `https://{region}.cloud.agenta.ai/auth/callback/sso:{organization_slug}:okta`
+   - Sign-out redirect URI: `https://{region}.cloud.agenta.ai`
+   - Assignments: Assign users/groups
+
+3. **Get Credentials**
+   - Copy Client ID
+   - Copy Client Secret
+   - Issuer URL: `https://{your-domain}.okta.com`
+
+### Azure AD (Entra ID)
+
+1. **Register Application**
+   - Azure Portal → App registrations → New registration
+   - Supported account types: Choose appropriate option
+   - Redirect URI: Web, `https://{region}.cloud.agenta.ai/auth/callback/sso:{organization_slug}:azure`
+
+2. **Configure Authentication**
+   - Add platform: Web
+   - Add redirect URIs
+
+3. **Get Credentials**
+   - Copy Application (client) ID
+   - Certificates & secrets → New client secret
+   - Issuer URL: `https://login.microsoftonline.com/{tenant-id}/v2.0`
+
+### Google Workspace
+
+1. **Create OAuth Client**
+   - Google Cloud Console → APIs & Services → Credentials
+   - Create OAuth client ID
+   - Application type: Web application
+
+2. **Configure Settings**
+   - Authorized redirect URIs: `https://{region}.cloud.agenta.ai/auth/callback/sso:{organization_slug}:google`
+
+3. **Get Credentials**
+   - Copy Client ID
+   - Copy Client Secret
+   - Issuer URL: `https://accounts.google.com`
+
+## Troubleshooting
+
+### "Unable to reach issuer URL"
+
+**Causes:**
+- Incorrect issuer URL
+- Network/firewall blocking connection
+- IdP is down
+
+**Solutions:**
+- Verify the issuer URL in your IdP configuration
+- Ensure the URL is accessible from Agenta's servers
+- Check your IdP's status page
+
+### "Redirect URI mismatch"
+
+**Cause:** The redirect URI in Agenta doesn't match your IdP configuration
+
+**Solution:**
+1. Check the exact redirect URI format
+2. Update your IdP to match: `https://{region}.cloud.agenta.ai/auth/callback/sso:{organization_slug}:{provider_slug}`
+3. Ensure no trailing slashes or typos
+
+### "Invalid client credentials"
+
+**Causes:**
+- Wrong Client ID or Secret
+- Credentials have been rotated
+- Application disabled in IdP
+
+**Solutions:**
+- Verify credentials in your IdP
+- Regenerate and update if needed
+- Ensure the application is enabled
+
+### Users can't sign in with SSO
+
+**Causes:**
+- SSO not enabled for organization
+- Provider not active
+- User not assigned in IdP
+
+**Solutions:**
+- Enable "Allow SSO" in organization settings
+- Ensure provider is enabled and validated
+- Assign user to the application in your IdP
+
+## Security Best Practices
+
+1. **Rotate credentials regularly**: Update Client Secret periodically
+2. **Use strong IdP policies**: Enforce MFA in your identity provider
+3. **Monitor sign-ins**: Review authentication logs
+4. **Test before enforcing**: Verify SSO works before disabling other methods
+5. **Have a backup plan**: Keep emergency access method available
+
+## FAQ
+
+### Can I use SAML instead of OIDC?
+
+Currently, only OIDC is supported. SAML support will be added in the future.
+
+
+### Can I use SCIM along with SSO?
+
+Currently, only SCIM is not supported. SCIM support will be added in the future.
+
+### What happens if my IdP goes down?
+
+Users won't be able to authenticate via SSO. If SSO is the only allowed method, users will be locked out until the IdP is restored. Consider keeping admin access on, on a separate non-personal account (`allow_root: true`) if this is important to you.
+
+### Can users still use email/password after SSO is enabled?
+
+Yes, unless you explicitly disable email authentication. To enforce SSO-only, set `allow_email: false` and `allow_social: false`.
+
+### How do I rotate SSO credentials?
+
+1. Generate new credentials in your IdP
+2. Update the provider configuration in Agenta
+3. Test that SSO still works
+4. Revoke old credentials in your IdP