Organisations, Entra and workplace registration

FAQ › Profile server › Organisations · Nederlands

What is it?

An organisation on the profile server groups everything that belongs to a company:

• its Microsoft Entra tenant id and its allowed e-mail domains, so employees can log in on an EUZOS PC with their Microsoft work account (an EUZOS account is created for them just in time);
• its admins (org-admin), who may manage the company's workplace servers from an EUZOS PC with Server Admin;
• its registered EUZOS PCs (device keys, pc-register);
• its workplace servers (EUZOS Server with the Workplace management package), registered from the server installer or with the CLI;
• optionally its own offline-login policy (offline-policy @domain …).

Organisations are managed with the CLI (there is no organisation page on the admin page in the code).

How do I…?

How do I set up an organisation for Microsoft login?

euzos-profielserver org-create "Company Ltd"
euzos-profielserver org-tenant "Company Ltd" <tenant id (GUID)>
euzos-profielserver org-domain "Company Ltd" company.example
euzos-profielserver orgs

A tenant and a domain each belong to at most one organisation. The server also needs entra_client_id (the client id of the EUZOS Entra app); without it /api/pc/entra gives 404. The customer's admin gives admin consent for the app once.

What happens at the first Microsoft login of an employee?

The server checks the ID token (RS256 with Microsoft's keys, iss, aud = entra_client_id, tid/oid, times, single use). The tid must belong to an organisation and the address (preferred_username, otherwise email) must have one of its domains. Then (tid, oid) is linked to an existing account with that address, or a new account is created: active, business profile only, without a password. Guests with another domain do not get in.

How does offboarding work?

On the status poll of a PC that logged in with Microsoft, the server refreshes the user's Microsoft refresh token from the vault in the background, at most once per entra_check_s (default 900 s) per account:

An employee recreated in Entra (new oid, same address) is refused (reden=account); delete the old EUZOS account first (user-delete).

How do I make someone an admin of an organisation?

org-admin <org> <email> (remove with --off). An organisation admin may manage the workplace servers of that organisation; a server admin (role beheerder, see Admin page) may manage those of any organisation.

How do I register an EUZOS PC so it may run Server Admin?

On the PC: pckey create, then pckey shows the public key and the fingerprint. On the profile server: pc-register '<name>' <key> <org> (compare the printed fingerprint); list with pcs, revoke with pc-revoke <key>.

How do I register a workplace server?

Normally the server installer of EUZOS Server does it: the admin logs in in the installer's Account step, and the installer sends POST /api/workplace/v1/register?token=<pc-token> with the server's public key and name. Only an admin (organisation admin, or server admin naming the organisation) may do this. By hand on the VPS: workplace-register <name> <key> [--network <ip>[,<ip>]], then workplace-org <id> <organisation>.

How do I revoke a workplace server or limit where PCs see it?

workplace-revoke <id>. workplace-network <id> <ip>[,<ip>]|auto sets for which (public) networks the catalogue names the workplace server (auto: the public address of its last sign-in).

Details

Tables (schema 13, 15, 16; English names since schema 18): organizations, org_domains, entra_links (tenant, oid → account, by_entra), org_admins, pc_keys (device key, name, organisation, revoked), workplaces (id, name, key, networks, lan, tls, public address, last sign-in, revocation, organisation, installed_by, installed, external). Before schema 18 these were organisaties, org_domeinen, entra_koppelingen, org_beheerders, pc_sleutels, werkplekken.

Workplace server sign-in: the workplace server gets a challenge (POST /api/workplace/v1/challenge, 60 s, single use), signs the EUZOS-werkplek-aanmelden-v1 document with its Ed25519 key and gets a workplace token eze_… (1 hour, only as SHA-256 in memory), the server time and the download key line. It signs in again every 30 minutes. The server stores its LAN address, TLS pin, public IP and the time; that is how the app catalogue can point PCs on the same network to it (see Apps and downloads).

Admin proof for Server Admin: when an admin runs Server Admin on a registered PC, the kernel asks POST /api/workplace/v1/admin-proof?token=<pc-token> (werkplek=, pcsleutel=). The server checks: the PC is registered and not revoked; the user is a server admin or admin of the organisation; workplace, PC and admin belong to the same organisation. It answers with an admin proof signed with the environment's signing key (10 minutes), plus the workplace server's LAN address and TLS pin. The workplace server checks the proof itself and the command with the PC key (TCP port 8446 on the workplace side; see the EUZOS Server pages of this FAQ).

Registration limits: 10 per minute per network, 10 per hour per account (workplace_registration::PER_NET, PER_ACCOUNT); the external address is at most 253 characters.

Reference

CLI commands

Legacy names: org-maak, org-domein, --wis, org-beheerder, --uit, pc-registreer, pc-intrek, werkplek-registreer, werkplekken, werkplek-intrek, werkplek-netwerk, werkplek-org, --netwerk.

Functions and modules

Config files

On the PC: \EOS\FW\MSAPP.TXT (client id and tenant common) enables the "Log in with Microsoft" button; \EOS\FW\PCKEY.TXT holds the PC's device key seed (never copied by the installer).

API endpoints

Protocol messages and formats

Register (body lines):

sleutel=<64 hex>        public Ed25519 key of the workplace server
naam=<name>
organisatie=<id>        only needed with more than one organisation
extern=<address>        optional: public IP or DNS name (behind NAT)
→ ok / werkplek=<id> / organisatie=<id> / organisatie_naam=<name>
→ 401 token | 403 geen_beheerder | 409 kies_organisatie (+ organisatie=<id>\t<name> lines)
  | 409 al_geregistreerd | 400 ongeldig | 429 te_vaak

Workplace sign-in document (Ed25519 with the workplace key over EUZOS-werkplek-aanmelden-v1\0 and everything up to the \n before handtekening=):

EUZOS-werkplek-aanmelden-v1
omgeving=<environment>
server=<domain>
sleutel=<64 hex>
uitdaging=<32 hex>
tijd=<Unix time>
lan=https://<lan address>:8445/
tls=<SHA-256 of the SPKI, 64 hex>
naam=<name from WORKPLC.TXT (name=, legacy naam=)>
handtekening=<128 hex>
→ ok / werkplek=<16 hex> / token=eze_<64 hex> / verloopt= / servertijd= / downloadsleutel=<kid> <64 hex>

Admin proof (signed with the environment's key, domain EUZOS-werkplek-beheerbewijs-v1\0, 10 minutes): lines omgeving=, server=, werkplek=, organisatie=, pcsleutel=, account=, beheer=werkplek, uitgegeven=, geldig-tot=, sleutel-id=, handtekening=.

Admin list: ok, then per workplace werkplek=<id>\t<name>\t<lan>\t<actief|niet actief>\t<installed by>\t<date>\t<external address>.

See also

• docs/WORK-LOGIN.md
• docs/WORKPLACE.md, "Phase E2" and "The protocol of the MVP"
• docs/WORKPLACE-PROTOCOL.md
• docs/OFFLINE-LOGIN.md
• PC login · Apps and downloads · CLI · API