Documentation

Access control of the servers

The parts server and the project server share one access model: users sign in with a local account or with a directory (Active Directory, OpenLDAP or another LDAP server), and what they may do comes from roles given to them or their groups by grants, per project (project server) or per manufacturer (parts server).

Remembered project-server sign-ins

In the editor's Project server pane, Keep me signed in is an explicit, optional setting for the selected server and account. On Windows, only the account session token goes into Windows Credential Manager. Passwords are never persisted. App settings contain only server/account metadata and the opt-in, independently per account so another editor window cannot disable a different account's sign-in. The complete server identity includes scheme, host, effective port and base path; credentials never move to another server. HTTP and HTTPS remain distinct, and this feature does not change or encrypt the existing transport.

On startup, GET /api/v1/session validates the remembered account token and returns CurrentAccount { user, access }, with current rights and no token or password. Root tokens, anonymous access, invalid and expired account tokens are refused with 401. This request does not renew the token or touch page locks. The account session currently expires 30 days after sign-in; the separate 90-second idle project session is unaffected. Older servers without this endpoint require manual sign-in; their 404 does not delete a possibly valid remembered credential. Connection failures also retain the opt-in for a later retry.

If an account token expires while a shared project is open, signing in again with the same server and account continues that project through the session recovery flow. Unsaved edits and undo history remain available; signing in does not mark them as saved or replace the project with a fresh copy.

Sign out removes the remembered credential and asks the server to revoke the account token after outstanding saves and project closes have been answered. Change user releases the project session and clears the selected user name, but keeps that account's remembered sign-in for switching back. An open shared project and its undo history remain as a local recovery copy, including unsaved changes. Local sign-out works offline; the pane reports separately if the server session could not be ended or protected storage could not be changed. OS operations run in order, including deletion after an already-running save; normal application closing waits for their results. Replies from a previous server/account selection never restore its identity or replace the open project. A delayed save confirmation still belongs to the same retained project during reauthentication; it advances the saved revision without changing the new sign-in. Background revocation does not disable the next sign-in while waiting for a server.

Invalid-token cleanup compares the rejected token before deleting it. It never writes a new opt-out: another window may already have remembered a newer sign-in. Directory logins keep their opt-in under the account name confirmed by the server, including when the typed name was domain-qualified or a user principal name.

The browser, macOS and Linux currently offer session-only sign-in. Their checkbox is disabled with an explanation; there is no token/password fallback in local storage, IndexedDB, ordinary settings or project files. Windows support reuses the existing OS credential backend also used for EPLAN PATs, with a separate namespace. These session/platform functions do not change project commands or the plugin API.

The isolated live check is scripts/test-project-sign-in.ps1 (PowerShell 7, Windows). It uses a disposable loopback project server, synthetic accounts, its own metadata folder and unique credential keys, which the test removes afterwards.

Rights and built-in roles

Project server (the scope of a grant is a project name):

RightAllows
viewsee the project in the list, open it read-only
reviewsave review records (comments, markup, approvals) without locks
edit_pageslock and change pages
edit_projectlock and change the project data (page list, devices, parts, settings)
createcreate projects (the scope is the new name)
deletedelete a project nobody has open
manage_accesschange the grants on the project
administerusers, roles and all grants (only from grants on *)
RoleRights
viewerview
reviewerview, review
editorview, review, edit_pages, edit_project, create
managereditor + delete, manage_access
admineverything

A signed-in user who creates a project becomes its manager (a grant on the new project), so project owners manage who works on their projects.

Parts server (the scope of a grant is a manufacturer, or one catalog as catalog:<id>):

RightAllows
readbrowse, search, download files, favorites (whole server)
edit_partscreate and change parts and their files, import
delete_partsdelete parts
edit_catalogscreate, change and delete catalogs
administerusers, roles and grants (whole server)

Built-in roles: reader (read), manufacturer and editor (read, edit_parts, delete_parts, edit_catalogs), admin (everything). An account's own role still works as before: a manufacturer user has the manufacturer role on their manufacturer only.

The rights on a part or a catalog are those on its manufacturer together with those on its catalog (catalog:siemens): a grant on a catalog lets users and groups change the catalog and its parts whatever their manufacturer, and a deny grant on either takes the right away. Administrators set the grants of a catalog in Administration › Catalogs › Permissions (GET / PUT /api/v1/catalogs/{id}/grants); reading stays a right of the whole server.

How rights are resolved

  1. The account's built-in role (project server: on its projects; none for users that came from a directory).
  2. Every grant of the policy whose subject matches the user ({"user": "anna"}) or one of their groups ({"group": "corp:Engineering"} of a directory, {"group": "Wiring"} defined on the parts server). Names and scopes take * and ? wildcards and are case insensitive; {"user": "*"} is every signed-in user.
  3. The role of anonymous requests (anonymous), which signed-in users have as well.
  4. Deny grants win: rights of a grant with "deny": true are taken away on its scope, whatever the other grants give.

Server-wide rights (administer, and read on the parts server) only come from grants on *. The server token (--token) keeps full access.

The settings file

access.json in the project server's data directory, <data>.access.json next to the parts database (both changeable with --access <file>). A missing file means: no directories, no defined roles or grants; on the parts server anonymous requests may read ("anonymous": "reader"). Administrators change roles, grants and anonymous through the API (GET|PUT /api/v1/access), which rewrites the file, and the directories through /api/v1/directories (GET, PUT|DELETE /{id}, POST /{id}/test). The web pages do so too: the parts server's (Administration › Access rights, which also exports and restores them) and the project server's when it runs with --web (Administration › Access rights and Directories).

{
  "directories": [
    {
      "id": "corp",
      "title": "Corporate AD",
      "kind": "active_directory",
      "url": "ldaps://dc1.corp.example",
      "base_dn": "DC=corp,DC=example",
      "bind_dn": "CN=svc-openecraft,OU=Service,DC=corp,DC=example",
      "bind_password_env": "OPENECRAFT_LDAP_PASSWORD",
      "nested_groups": true,
      "allowed_groups": ["OpenECraft *"]
    },
    {
      "id": "lab",
      "kind": "ldap",
      "url": "ldap://ldap.lab.example",
      "starttls": true,
      "user_bind": "uid={user},ou=people,dc=lab,dc=example",
      "base_dn": "ou=people,dc=lab,dc=example",
      "group_filter": "(&(objectClass=groupOfNames)(member={dn}))",
      "group_base_dn": "ou=groups,dc=lab,dc=example"
    }
  ],
  "anonymous": "",
  "roles": [
    { "name": "checker", "description": "Checks drawings", "rights": ["view", "review"] }
  ],
  "grants": [
    { "subject": { "group": "corp:Engineering" }, "role": "editor", "scope": "Plant*" },
    { "subject": { "group": "corp:Quality" }, "role": "checker", "scope": "*" },
    { "subject": { "group": "corp:Contractors" }, "role": "viewer", "scope": "Secret*", "deny": true },
    { "subject": { "group": "corp:OpenECraft Admins" }, "role": "admin", "scope": "*" }
  ]
}

On the parts server "registration": true lets users register themselves as readers (switched in Administration › Access rights; the start option --registration overrides it, see docs/parts-server.md); their accounts wait for the approval of an administrator unless "registration_approval": false. "dashboard": false hides the dashboard of the web page (Administration › Overview; the start option --dashboard overrides it).

Groups

The parts server keeps groups of users in groups (Administration › Groups, GET /api/v1/groups, PUT / DELETE /api/v1/groups/{name}):

"groups": [{ "name": "Wiring", "description": "Panel shop", "members": ["anna", "bob"] }]

Members are user names, local users and users of a directory alike (by the name they sign in with). Grants to {"group": "Wiring"} apply to the members next to the groups of their directory; group names cannot hold :, which separates the directory groups. The groups of a user (Users, groups of PUT /api/v1/users/{name}) are memberships: saving them adds the user to the named groups (new names become groups) and removes them from the others. Groups that local accounts named before are turned into groups of the server at startup. Deleting a group deletes the grants to it, deleting a user their memberships; names of members cannot be registered, and a change that would leave nobody who manages users is refused.

Directories

Administrators set the directories up in Administration › Directories too (GET /api/v1/directories, PUT / DELETE /api/v1/directories/{id}), which shows no password (an empty password keeps the stored one) and tests the settings: Test connects and binds with the service account, with a user name and password it signs the user in and shows their groups (POST /api/v1/directories/{id}/test).

KeyMeaning
idshort name; groups appear as id:group, users of the directory show it
kindactive_directory (default) or ldap
urlldap://… or ldaps://…; starttls upgrades ldap://
insecure_tlsaccept any certificate (tests only); otherwise the system's CA store is used
bind_dn, bind_password / bind_password_envservice account to look users up
user_bindwithout service account: bind name of the user, {user}@corp.example or uid={user},ou=…
base_dnwhere users are searched
user_filterdefault (&(objectClass=user)(sAMAccountName={user})) / (&(objectClass=person)(uid={user}))
name_attributeaccount name, default sAMAccountName / uid
nested_groupsActive Directory: also groups of groups (LDAP_MATCHING_RULE_IN_CHAIN)
group_filter, group_base_dnsearch the groups ({dn}, {user}) instead of reading memberOf
allowed_groupsonly members of these groups may sign in (empty: everybody)
timeout_secsconnection and request timeout (default 10)

Sign-in tries the local accounts first; a name without local account goes to the directories in order (or only to the one named in the request's provider). The first directory that knows the user checks the password (a bind as the user; empty passwords are refused before the directory is asked) and returns the groups. The server keeps an account for the directory user (no password; groups refreshed at every sign-in), so administrators see them in the user list and session tokens work as for local users. A name that already belongs to a local account cannot sign in through a directory.

Passwords of local accounts need at least 8 characters. After 5 failed sign-ins of a user name (local or directory) from one client address every further attempt of that name from there waits, 1 s at first and twice as long after every further failure, up to 5 minutes; after 30 failed sign-ins of a client with any names its attempts wait the same way. The servers answer 429 Too Many Requests meanwhile. Others cannot lock a user out this way; a successful sign-in forgets the failures of the name (not those of the client), and failures are forgotten after an hour. A name without account takes as long to refuse as a wrong password, so the answers do not tell which names exist. Errors of both servers come as {"error": "…"}, also for unknown routes and requests that do not parse.

A session (the token of a sign-in) ends at sign-out, when the password is changed and 30 days after the sign-in; a user keeps at most 20. Sessions stored by earlier versions have no start and count as ended: their users sign in once more. Requests that change something are checked before their body is read, so unknown callers cannot make a server read large bodies; sign-in (and the parts server's search) take at most 64 kB.

Both servers send X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Referrer-Policy: no-referrer and a content security policy with every answer. The user and access files (users.json, access.json, a JSON parts database) are written readable for their owner only (Unix). Prefer bind_password_env to bind_password (the servers warn about a password in the file) and OPENECRAFT_TOKEN / OPENECRAFT_PROJECT_TOKEN or the configuration file to --token, which other users of the machine see in the list of processes. Neither server speaks TLS: put a reverse proxy with HTTPS in front of a server that is reached over the network.

Values are escaped for LDAP filters and DNs. Keep the service account read-only.

Clients

This document in the repository

More documentation

Getting started: from the first page to the bill of materials

This tutorial walks through a small control circuit in OpenECraft: pages, symbols, wires, devices with parts, terminals, a PLC, the project check, reports, the panel layout and the output. Commands are written as Tab ›…

Read

Installation and building

Packages for Windows, Linux and macOS, the web version, and building from source.

Read

User interface

The editor's layout and the commands and keys of everyday work. New users start with the tutorial.

Read

Schematic editor

Pages, devices and their structure, live cross references, editing tools, navigators and project storage. The user interface lists the commands and keys.

Read

Symbols and libraries

The built-in symbol libraries (IEC, NFPA / JIC, GB, GOST, JIS, fluid power, P&ID, single-line) and the symbol editor for own symbols.

Read

Wires, cables, potentials and numbering

How connections get their cable, colour, cross-section and number, and how devices, pages and wires are numbered.

Read

Terminal strips, plugs, PLC and marking

Terminal strips with multi-level terminals and accessories, plugs, PLC cards with the exchange to PLC programming tools, and the markers for the workshop.

Read

Macros, configurator and table editing

Reuse of circuits as macros with variants and placeholders, pages generated by the configurator, and bulk changes in tables and spreadsheets.

Read

Parts management

The parts database shared by all projects (EPLAN style): commercial, technical and mounting data, function templates, connection points, 2D / 3D graphics and the import of manufacturer data. Parts are shared between…

Read

Reports, forms and the project check

Reports as windows, CSV / Excel or live report pages, title blocks and report forms (also graphical and own drawn forms), and the project check with its message management.

Read

Electrical sizing, calculations and verification

Conductor sizing, short circuit and protection coordination, load calculation, EMC, functional safety and rule sets – all part of the project check – and the inspection and test report of the installation.

Read

Panel layout, rooms and 3D routing

OpenECraft aligns the device's clip to the rail centerline. For Beckhoff's 12 × 100 × 68 mm EL I/O housings with 8 or 16 terminals, and the matching EK1100 coupler, the rail center is 63.8 mm from the top. For example…

Read

Wiring and mounting assistants

The panel layout as a checklist for the workshop, on a desktop or a tablet.

Read

Fluid power, process and plant engineering

Hoses and pipes in their own nets, electro-fluid links, PCT loops, the pre-planning of the plant and single-line / multi-line engineering.

Read

Wire harnesses

Harnesses with 3D topology, protections and fixings, KBL export, the harness interface for machines and nailboard drawings (Connections › Harnesses…). The example project conveyor has a door harness.

Read

Output and data exchange

PDF, DXF / DWG, SVG and 3D exports, DXF / DWG import, the enterprise integration layer (ERP, PDM, PLM, ECAD, MCAD, procurement, wiring machines) and Autodesk Vault.

Read

Revisions, review and change management

Revisions with locked pages and marked changes, the approval workflow, baselines with compare and merge, comments and redlining, and change requests.

Read

Command line, MCP server and plugins

Projects and the parts server without a window, for scripts and AI agents.

Read

Plugins

OpenECraft is extended through the openecraft-api crate. A plugin adds

Read

Parts server and parts manager

The data portal shared by all OpenECraft installations and the app that maintains it.

Read

Project server

Shared projects for a team: several users work on the same project, each page is locked by one of them.

Read