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) and telemetry and audit (OTEL metrics and audit events carry attributes such as user.id, organization.id, and session.id; see Compliance & Audit).
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 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 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:
- 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:
- 1The user chooses "Sign in with SSO" and is redirected to your IdP.
- 2They authenticate with corporate credentials.
- 3The IdP returns a SAML assertion or OIDC token to Factory.
- 4The 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):
- 1Directory Sync data wins - SCIM attributes overwrite other sources.
- 2Email-based matching - users are matched by email, case-insensitively (
John.Doe@company.comequalsjohn.doe@company.com). - 3Custom data is preserved - Factory-specific fields not present in your directory are retained.
- 4Soft 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
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. |
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. |