# Identity & Access
Manage who can run Droid with SSO, Directory Sync, roles, service accounts, and Factory API keys.
Identity and access management controls **who can run Droid**, in which environments, and under what policies. This page covers the identity model and roles, Single Sign-On and SCIM directory sync, and service accounts for automation.
---
## Identity model
Every Droid run is associated with several dimensions of identity:
| Identity dimension | What it controls |
| --- | --- |
| User or machine identity | Human developers authenticate via SSO (SAML/OIDC), inheriting their directory groups and roles. Automation (CI/CD, scheduled jobs, scripts) runs under **service accounts** with their own API keys. |
| Org / project / folder | The active repo and `.factory/` folders determine the **org, folder, and project context**. Policies at these levels decide which models, tools, and integrations Droid may use. |
| Runtime environment | Whether Droid runs on a laptop, in a CI runner, or in a sandboxed VM is captured as environment attributes. Policies can treat these differently, such as allowing higher autonomy only in CI or sandboxes. |
| Session metadata | Each Droid session records metadata such as session ID, CLI version, and git branch, which is available for audit and OTEL telemetry. |
Identity and environment information feed two systems: **policy evaluation** (managed settings use identity and context to decide which configuration applies; see [Enterprise Controls & Managed Settings](/enterprise/hierarchical-settings-and-org-control)) and **telemetry and audit** (OTEL metrics and audit events carry attributes such as `user.id`, `organization.id`, and `session.id`; see [Compliance & Audit](/enterprise/compliance-audit-and-monitoring)).
---
## Roles
Factory organizations have three roles. Role information flows from your IdP (via SSO claims or SCIM groups) into Factory.
| Role | Capabilities |
| --- | --- |
| **Owner** | Full control of the organization, including billing, deletion, all settings, members, and API keys. |
| **Manager** | Manage members, organization settings, API keys, and service accounts. Manage org-level `.factory` policy (models, command allow/deny lists, telemetry, autonomy ceilings). |
| **User** | Standard member. Run Droid locally, in IDEs, in CI, or via team scripts, and customize personal preferences in `~/.factory/`, but cannot change any setting locked at the org, folder, or project level. |
The managed settings engine enforces what each role can effectively change. See [Enterprise Controls & Managed Settings](/enterprise/hierarchical-settings-and-org-control) for the exact precedence rules.
## Domains, SSO, and SCIM
Factory uses **WorkOS** for enterprise identity, supporting domain verification, SSO (SAML/OIDC), and Directory Sync (SCIM). Contact your Factory representative or [support@factory.ai](mailto:support@factory.ai) to start setup; you will receive a secure setup link to configure your identity provider.
WorkOS handles the technical configuration. The setup wizard generates the
SAML/OIDC parameters and SCIM endpoint for your specific provider, so you do
not configure ACS URLs, certificates, or attribute mappings by hand. For
provider-specific screenshots and steps, follow the WorkOS admin guide linked
in your setup flow.
### Domain verification (required first)
Domain verification proves your organization owns specific email domains and is a **prerequisite for SSO**. You add each domain, WorkOS issues a TXT record, and you add it to your DNS; verification typically completes within 1-24 hours depending on propagation.
Once a domain is verified:
{/* sweep-allow: term-bullets */}
- **Automatic claiming** - existing and new users with that email domain join your organization.
- **Identity governance** - you can require SSO for domain users and apply org security policies (MFA, session controls, IP restrictions) consistently.
- **SSO readiness** - you can enable SSO for the verified domains.
Verify your primary domain first, then add subsidiary, legacy, or alias domains. Each domain is verified separately but shares the same organizational policies.
SSO cannot be enabled without verified domains. All users authenticating via
SSO must have email addresses from verified domains.
### Single sign-on (SAML / OIDC)
With SSO enabled, users sign in through your IdP instead of a password:
1. The user chooses "Sign in with SSO" and is redirected to your IdP.
2. They authenticate with corporate credentials.
3. The IdP returns a SAML assertion or OIDC token to Factory.
4. The user is authenticated and, if **Just-In-Time (JIT) provisioning** is enabled, created on first login with a profile populated from the IdP claims.
WorkOS supports all major IdPs (Okta, Microsoft Entra ID, Google Workspace, OneLogin, Ping, JumpCloud) plus generic SAML 2.0 and OIDC. Organizations that do not use SSO can use passwordless magic-link sign-in, which is also useful for external collaborators.
### Directory sync (SCIM)
SSO controls **how users authenticate**; SCIM controls **which users and groups exist** in Factory. With Directory Sync enabled through your IdP:
- Adding a user to a synced directory group **provisions** them in Factory.
- Updating directory attributes **syncs** to Factory.
- Removing a user from the directory **deactivates** their access (soft delete - work history is preserved).
- Group membership changes propagate automatically, so RBAC stays defined in your IdP.
Sync only the groups that need Factory access (for example, `factory-*` groups), and keep the SCIM token secret - store it only in your IdP's application configuration.
#### Group-to-role mapping
Map your directory groups to Factory's three roles. WorkOS role slugs resolve as follows: `owner` maps to **Owner**; `admin` or `manager` maps to **Manager**; every other slug maps to **User**.
| Example IdP group | Factory role |
| --- | --- |
| `factory-owners` | Owner |
| `factory-managers` (or `factory-admins`) | Manager |
| `factory-developers`, `factory-contractors`, any other group | User |
Use descriptive, prefix-based group names (`factory-*`) so IdP configuration stays maintainable and auditable alongside your other enterprise apps.
### Data priority and conflict resolution
When a user exists from multiple sources (SCIM, SSO JIT, manual invite, API):
1. **Directory Sync data wins** - SCIM attributes overwrite other sources.
2. **Email-based matching** - users are matched by email, case-insensitively (`John.Doe@company.com` equals `john.doe@company.com`).
3. **Custom data is preserved** - Factory-specific fields not present in your directory are retained.
4. **Soft deletes only** - removed users are deactivated, not deleted.
When both SSO JIT and SCIM are enabled, choose one primary method to avoid duplicate-user conflicts: either disable JIT and require directory provisioning (directory-first), or use JIT for creation and the directory for updates (SSO-first).
### Troubleshooting
Verify ACS / redirect URLs match what Factory provided and confirm certificates have not expired or rotated.
Check group memberships and the group-to-role mapping, and ensure the intended groups are included in SAML assertions or ID tokens.
Confirm SCIM is enabled in both Factory and your IdP, and check your IdP's SCIM logs for invalid token, URL, or schema errors.
Keep a small pilot group for initial rollout, and manage all role changes and access reviews in your IdP to reuse existing governance.
## Service accounts
Service accounts are non-human identities that automate work on behalf of your organization: CI/CD pipelines, scripts, Slack automations, or Droid Computers. Use one when a workload should belong to your organization instead of a specific teammate. A service account authenticates with a Factory API key and runs as its own principal, so sessions, computers, billing, and audit events are attributed to it rather than a human user.
| Step | What to configure |
| --- | --- |
| Create a service account | Add a stable identity from the **API Keys** section of organization Settings. Give it a clear name and description. Only **Owner** and **Manager** roles can create or edit service accounts. |
| Generate API keys | Create keys for scripts, CI jobs, and other automated workloads. A key value is shown **only once** at creation - copy it and store it securely. |
| Attach Droid Computers | Create Droid Computers owned by the service account so long-running work continues under the same identity instead of a teammate's account. |
| Configure Git access | Use your organization's **GitHub App** installation for GitHub. For GitLab, add a service-account **GitLab token (PAT)** in Settings. For a self-managed server, see [Self-Managed Source Control](/enterprise/self-managed-scm). |
A service account must be **active** to authenticate. Marking one inactive or deleting it causes new requests with its keys to fail, so move or restart dependent workloads first. Names are immutable identifiers - create a new account if you need a different name.
### Service account key hygiene
| Practice | Why it matters |
| --- | --- |
| Use short-lived keys when possible | Set expiration dates for keys used in temporary automation to limit blast radius if a key is exposed. |
| Rotate keys regularly | Create a new key, update the workload, then revoke the old key. |
| Delete when finished | Deleting a service account revokes its access and cleans up owned Factory resources where possible. |
---
## Devices, environments, and workspace trust
Because Droid is a CLI, it can run on developer laptops, remote dev servers, CI runners, and hardened VMs or devcontainers. Enterprises typically combine Droid with endpoint management and environment-aware policy:
### Endpoint and workspace controls
| Control | Recommended use |
| --- | --- |
| Endpoint and MDM controls | Use Jamf, Intune, or other MDM solutions to control where Droid binaries can be installed, which users can run them, and which configuration files they can read. Common patterns: run only under managed user accounts, restrict configuration directories to corporate-managed volumes, and enforce OS-level disk encryption and screen lock. |
| Workspace trust | Treat Droid as trusted only in known repositories. Pin Droid to specific paths or repos, require elevated approval or sandboxed environments for untrusted code, and use project-level `.factory/` folders to mark which repos are "Droid-ready." |
| Environment-aware policies | The same developer may run Droid on a laptop, in CI, or in an isolated container. Policies can allow higher autonomy or more powerful tools **only** inside devcontainers or CI runners, restrict network access on laptops, and tag OTEL telemetry with environment attributes for environment-specific alerting. |
Define which roles can change which policy levels in the settings hierarchy.
Map identity and access events to audit trails and compliance workflows.