Crayonic Badge Sign-in Setup
Set up Windows PCs so that people sign in by holding their Crayonic badge close to a Crayonic bridge plugged into the PC. You install the Crayonic Agent, open its settings window, choose a sign-in method and press one button, Set up this PC; for many PCs you then copy the same settings out with Group Policy, and none of this needs the Crayonic Device Manager (CDM).
Applies to Crayonic Agent 1.0.692 and later
The page describes the settings window of Crayonic Agent 1.0.692 and later, which has a dark sidebar on the left and the Set up this PC button. Until it is promoted to STABLE, take it from the ALPHA channel (where to download it). Older agents (1.0.634 on STABLE today) have the same checks behind tabs and three separate buttons, and no Set up this PC. 1.0.689 and 1.0.690 have this window, but the older settings pages: a tick box in front of every setting, the update policies as plain fields, the Status page as raw text, and Logon screen and Machine-local where 1.0.692 says Sign-in screen and Support switches. 1.0.691 has the new pages, but Choose another version lists a channel only when you press Show bridge versions or Show agent versions. The credential provider that shows the badge tiles (CP3) comes with the agent; there is nothing else to install. The screenshots come from a test machine with made-up names. They show 1.0.692 after its promotion to STABLE: while it is on ALPHA, the window says ALPHA where the pictures say STABLE, for example pinned to 1.0.692 on the ALPHA channel. That is just as good (Pin the updates).
Which sign-in method?
A badge signs a user in to Windows in one of two ways. Which one depends on how your PCs are joined:
| Your PCs are… | Use | What it needs |
|---|---|---|
| Joined to an on-premises Active Directory domain | Smartcard (PIV certificate) | A certificate on each badge, strongly mapped to its user in AD |
| Microsoft Entra joined (not in a domain) | Entra FIDO | A passkey on each badge, registered to its user's Entra account |
| Hybrid joined (in a domain and in Entra) | Either one | Smartcard: as for AD. Entra FIDO: Windows 10 2004 or later, and Microsoft Entra Kerberos set up in AD |
| In a workgroup (no domain, no Entra) | Not supported | A smartcard sign-in needs a domain controller, and an Entra FIDO sign-in needs an Entra join |
| Windows Server | Not supported | Windows does not offer an Entra FIDO sign-in on Windows Server, and Crayonic does not test the smartcard sign-in there |
How the two differ:
| Smartcard (PIV certificate) | Entra FIDO | |
|---|---|---|
| The badge proves who the user is with | a smart card certificate, checked by your domain controller | a passkey, checked by Microsoft Entra ID |
| The bridge works as | a smart card reader (Crayonic KeyVault 0) | a FIDO security key |
| The user | holds the badge close and picks its tile | holds the badge close, picks its tile and confirms on the badge |
Before you start
Tick these off before you go to the PC. Most failed first sign-ins come from the last two groups, not from the agent.
For every PC:
- Administrator rights on the PC, to install the agent and to open its settings window.
- A Crayonic bridge, plugged into a USB port of the PC.
- A badge per user, carrying that user's certificate (smartcard) or passkey (Entra FIDO).
- Outbound HTTPS to
release.crayonic.io. The agent runs as the Windows service Crayonic Agent (LocalSystem) and downloads agent and bridge firmware updates from there. Allow it through directly: the service uses a proxy only if one is set for the SYSTEM account (its Internet Settings) or in a system-wideHTTPS_PROXYenvironment variable. It does not use a proxy script (PAC or WPAD), the WinHTTP proxy (netsh winhttp) or a proxy that asks for a sign-in; behind one of those, automatic updates fail without a message on the PC, and Install updates says Could not check for updates. Nothing else is needed on a PC that CDM does not manage.
For a smartcard sign-in:
- The PC is in the Active Directory domain (Windows 10 or 11).
- Each badge carries a smart card (PIV) certificate issued to its user by your certificate authority.
- Strong certificate mapping (Microsoft KB5014754): each certificate carries the user's SID extension, or the user account maps it in
altSecurityIdentities. Without it, the domain controller refuses the sign-in with the user name or password is incorrect. - The Windows Smart Card service (
SCardSvr) is not disabled.
For an Entra FIDO sign-in:
- The PC is Microsoft Entra joined, or hybrid joined with Microsoft Entra Kerberos.
dsregcmd /statusshowsAzureAdJoined : YES. - Windows 10 1909 or later (2004 or later when hybrid joined), or Windows 11. Not Windows Server.
- The Passkey (FIDO2) authentication method is enabled for these users in Microsoft Entra ID.
- Each badge carries a passkey registered to its user's Entra account.
- The sign-in screen can reach Microsoft Entra ID: the network is up before anyone signs in, and the proxy lets the PC through.
Quick start: one PC
Six steps, about fifteen minutes. Each step says what you should see.
1. Install the agent
Download the agent installer, CrayonicAgent_x64_1.0.692.msi:
- Until 1.0.692 is promoted to STABLE, take it from the ALPHA channel: release.crayonic.io/Agent/ALPHA (CrayonicAgent_x64_1.0.692.msi). ALPHA keeps its builds, so the link stays. Do not take the agent from DEV: DEV holds only the newest development build, and it changes without notice.
- Once it is promoted, take it from release.crayonic.io/Agent/STABLE. That page also lists much older builds; take the newest.
- The same page lists the transform
CrayonicAgent_x64_<version>_CloudSyncDisabled.mst. Download it too if you will install with Group Policy.
On a PC that CDM will not manage, install it from an administrator Command Prompt with cloud sync off:
msiexec /i CrayonicAgent_x64_1.0.692.msi CLOUDSYNCENABLED=0 /qn
Double-clicking the MSI also works, but it is meant for PCs that CDM manages: there is no wizard and no question to answer, so after the administrator prompt it installs with cloud sync on. With cloud sync on and no CDM, Set up this PC leaves the update pin to CDM (step 4), which never comes.
Cloud sync off works only on a first install
CLOUDSYNCENABLED=0, and the matching transform CrayonicAgent_x64_<version>_CloudSyncDisabled.mst, take effect only on a PC that never had the Crayonic Agent. On an upgrade, or on a PC that had the agent before, the earlier value stays. There, turn cloud sync off with:
reg add HKLM\SOFTWARE\Policies\Crayonic\Agent /v CloudSyncEnabled /t REG_DWORD /d 0 /f
The agent picks it up within seconds; no restart is needed. Group Policy can deliver the same value (Group Policy). The Cloud sync line on the Setup page shows which value is in force.
Then plug in the bridge.
You should see: from the command above, nothing at all: /qn installs silently, and the prompt comes back when it is done (add /l*v %TEMP%\crayonic-msi.log to the command for a log). A double-click shows a progress bar that closes by itself. Either way, the Windows service Crayonic Agent is then running (services.msc).
Until you pin, the agent updates itself
With nothing pinned, the agent installs the newest STABLE build by itself: it checks as soon as the service starts and then every minute. It never installs an older build, so 1.0.692 stays while STABLE holds older ones. Step 4 pins it.
What cloud sync off means
With cloud sync off, the agent sends nothing to CDM: no events, no heartbeat, no crash reports, and no connection to CDM's messaging service, so CDM cannot send it commands. Its settings come only from this PC and from Group Policy. Agent and bridge firmware updates still come from release.crayonic.io. Events recorded while cloud sync is off are never uploaded later.
2. Open Crayonic - Agent Settings
Open the Start menu, type Agent Settings, open Crayonic - Agent Settings and accept the administrator prompt. (The other Start menu entry, Crayonic - Show Enrollment Code, is for CDM.)
You should see: the window opens on the Setup page. On the left is a dark sidebar with the pages; the agent's version and the PC's name are at its foot. The Setup page lists one line for each thing a badge sign-in depends on, marked OK, FIX, CHECK or INFO. Above them, the red Set up this PC button says what is left to do.
No Start menu entry? From an administrator Command Prompt run "C:\Program Files\CrayonicAgent\CrayonicAgentService.exe" --settings --gui.
3. Choose the sign-in method
Next to Sign-in method:, choose Smartcard (PIV certificate) or Entra FIDO (which one?). The window has already picked one for this PC: Entra FIDO on a PC that is Entra joined and not in a domain, smartcard otherwise. Choosing only changes what the page checks; nothing is saved yet.
4. Press Set up this PC
Press Set up this PC. It asks one question that lists, in order, everything it will do, and does only what is still needed:
- Remove the old Crayonic credential provider, if the PC has one (details).
- Apply the sign-in preset for your method and save it on this PC (details).
- Pin updates to the versions installed now (details).
The notes under Before applying are normal on a PC that CDM does not manage. The first says that the agent takes over the sign-in screen's registry values; the second that the bridge disconnects from USB for a moment while it switches mode. Because the question carries notes, No is the default button: click Yes with the mouse. Pressing Enter cancels without changing anything.
While the old provider is removed, a line with a progress bar at the bottom of the window shows how far it is (up to a minute or two). Then the preset and the pins are saved in one go, and a message lists what was done:
- Windows does not need a restart. Carry on.
- Restart Windows to finish removing the old provider. Some of its files were in use; Windows deletes them at the next start. Restart now, or before the first badge sign-in.
You should see: after about ten seconds the bridge has switched mode. Press Refresh at the bottom: every line reads OK or INFO, and Set up this PC is gone because nothing is left to do.
If a line still reads FIX or CHECK, its text says why, and a Fix button sits on its right where one press can fix it. Lines without a button need something outside the window: see Troubleshooting.
5. Check the bridge and the badges
Open Devices in the sidebar. It shows what the agent sees, refreshed every three seconds while the page is open:
- The bridge: its serial number, mode and versions (
fwfirmware,blbootloader,hwhardware). serves the sign-in screen marks the bridge the sign-in uses. - Under it, its smart card reader (smartcard mode only) and the badge connected to it.
- Nearby badges: every badge the bridge hears, with its signal strength and why it does or does not have a tile on the sign-in screen:
- on the sign-in screen: it has a tile;
- below rssi: too far away, weaker than -60 dBm;
- arrival pending: it has only just appeared; its tile follows in a moment;
- stale: not heard recently;
- over cap: more badges are near than the sign-in screen has tiles;
- unnamed hidden: hidden because it has no name yet;
- excluded local: this PC's own bridge or USB badge.
The Pair the selected badge with this PC button and the Pairing page are for badges with encrypted-link firmware, which is not released yet. Leave them alone.
6. Sign in with the badge
- Lock the PC (Windows key + L) or sign out. The sign-in screen shows a tile for each badge near the PC.
- The user holds their badge close to the bridge and picks its Crayonic tile. The sign-in starts by itself.
- The user confirms on the badge if it asks, and Windows signs them in.
Smartcard: the first sign-in on a PC takes a few seconds while Windows reads the badge's certificate; later ones are faster. A tile shows a made-up name until the agent has read that badge's certificate once while someone is signed in, and the user's name after that.
Entra FIDO: users pick the Crayonic tile, not Windows' own Security key tile: both use the PC's single FIDO sign-in, and while one runs the other fails as busy. A tile shows a made-up name until that badge has signed in on the PC once.
A badge plugged into the PC by USB (for charging, say) gets its own tile, Connected by USB, which never starts by itself; pick it to sign in over the cable.
What Set up this PC does
Set up this PC runs the three buttons below it in order, behind one question. You can also press them one at a time, or press Fix on a line, which runs the same button for that line. Each asks its own question first.
Remove the old credential provider
PCs that once had an earlier Crayonic logon tile still carry the old credential provider. The window names it by its file: CP1 (CrayonicCredentialProvider.dll) or CP2 (CrayonicCredentialProvider2.dll), and lists the Crayonic Credential Provider MSI separately if it is installed. The old provider and the agent's own (CP3) would both pick up the same badge and cancel each other's sign-in, so the old one has to go. A red banner at the top of the window says when a PC has one.
Remove the old provider (or Remove it in the banner, or Fix on the Old credential provider line):
- uninstalls the old MSI;
- unregisters the old provider;
- stops and deletes its services (
CrayonicBridge, andCrayonic Smartcard Removal Policywhere present); - deletes its files from
System32, at the next restart if they are in use.
It never touches the agent, CP3 or the settings under HKLM\SOFTWARE\Crayonic. The question lists exactly what it found. Progress shows at the bottom of the window, and the full log in Last operation on the Install updates page; the uninstaller's own log is %ProgramData%\CrayonicAgent\legacy_cp\uninstall_<ProductCode>.log.
When files were in use, the Old credential provider line and the banner say Restart Windows to finish removing the old provider, and offer no button: pressing again would only schedule the same deletes. After Set up this PC, its final message says so too; the message after a separate Remove (or Fix) only says the removal is done, so read the line. The old provider is already unregistered, so it does nothing until the restart.
A line that reads CHECK Not registered, but its files are still in System32 is harmless; Fix (or Delete the left-over files) removes them.
The sign-in preset
Apply the smartcard sign-in preset (or Apply the Entra FIDO sign-in preset) sets everything its sign-in needs at once:
- turns on the Crayonic credential provider (CP3) with the chosen sign-in method;
- starts the sign-in as soon as the user's badge connects, without a second click;
- names the sign-in tiles from the badge itself: from its certificate (smartcard), or from its sign-in once it has signed in on the PC (Entra FIDO);
- switches the bridge to the interface the method uses: the smart card reader for smartcard, FIDO for Entra FIDO. The bridge runs one or the other;
- sets the distances, the same for both methods: a tile appears for a badge whose signal is at least -60 dBm and stays until it drops below -70 dBm; the bridge connects a badge only when it is held close (-40 dBm) and keeps it until the link is lost.
It saves them on the PC itself (HKLM\SOFTWARE\Crayonic\Agent), so they survive restarts and work without CDM. Anything else saved on the PC is kept. Both presets set the same settings, so applying one after the other leaves nothing of the first behind. The Reference lists every value.
The bridge restarts its USB connection to switch interface. Within about ten seconds its smart card reader, Crayonic KeyVault 0, appears (smartcard), or its FIDO interface comes back (Entra FIDO). Press Refresh.
If Group Policy, or Apply until restart, already sets the sign-in method or the bridge mode to something else, the preset cannot win over it. The window then says so instead of half-applying the preset: Set up this PC stops before it changes anything, and the line names who keeps the value (Troubleshooting).
Pin the updates
With nothing set, the agent installs every newer STABLE build by itself. In production a new release should reach your PCs only after you have tried it on a few. Pin updates to the installed versions therefore saves two update policies on the PC, one for the agent and one for the bridge firmware.
For each of the two it asks the release server which channel lists the installed version, STABLE first, then BETA, then ALPHA:
- Pinned (the version is listed): Agent: pinned to 1.0.692 on the STABLE channel. The PC stays on that version, and the pin names the channel where the next version will be looked for when you raise it.
- Held (no such channel lists it): Agent: held at 1.0.692. The PC stays on that version too, and never reports an error. This happens to a DEV build (DEV keeps only its newest build, so it is never a pin channel), when the release server cannot be reached, and for the bridge firmware when two bridges on the PC run different versions.
Either way nothing updates by itself and nothing is ever downgraded. The difference matters only later: to roll out a new version on a held PC, you pin it to that version with its channel instead of raising a pin (Raise a pin later).
Plug the bridge in before you pin: without one, only the agent is pinned. One firmware policy covers every bridge on the PC, so a bridge plugged in later with older firmware is updated to the pinned version.
The window does not offer a pin where it would be wrong:
- CDM sets the update policy on this PC. Pin the versions in CDM instead.
- Cloud sync is on and CDM's settings have not arrived yet (a fresh install with the MSI's default). Once they arrive, a pin saved here would outrank CDM's update policy without CDM showing it. On a PC that CDM will never manage, turn cloud sync off first (step 1).
- Group Policy sets the update mode. Pin in the Group Policy document (Group Policy).
In these cases the Updates line keeps its CHECK with the reason, has no Fix button, and Set up this PC leaves the pin out. Pressed by hand, Pin updates warns and defaults to No.
Updates and bridge firmware
The Install updates page installs bridge firmware and agent builds by hand. A pin only stops automatic updates, so this works on a pinned PC too.
What the page shows
The page has one card per device: one for each bridge plugged in, then one for the agent. Each card names the device, shows the installed version in an Installed label and, for a bridge, its firmware line and hardware (nRF5 firmware line (1.x), hardware 200).
When the page opens, the window checks each device against the STABLE, BETA and ALPHA channels and recommends an update only from those, never from DEV. DEV is asked only about a device that runs a build none of them lists, so that its card can say whether a newer DEV build exists. Each card says what it found:
| The card says | What it means |
|---|---|
| 1.4.98 is available on ALPHA, a pre-release channel. The newest on STABLE is 1.4.62., and a button Install 1.4.98 | The newest version on those channels that is newer than the installed one. When several channels list it, the card names the most conservative one. A bridge is offered only firmware of its own line, built for its hardware, and never a build marked not recommended. |
| Up to date: 1.0.692 is the newest release for this agent. (in green) | Nothing newer on STABLE, BETA or ALPHA. There is no button. |
| This agent runs 1.0.692, which STABLE, BETA and ALPHA do not list (a DEV build). | The device runs a DEV build. The card adds Nothing newer is on any channel, or names a newer DEV build and points to Choose another version. It never recommends a DEV build. |
| Could not check for updates: the release server could not be reached. Check this PC's internet or proxy access. | The agent got no answer from release.crayonic.io (Before you start). Try again asks again; Show the error shows the agent's full message. When every card fails for the same reason, the page says it once, above the cards. |
| The installed version of this bridge cannot be read | Nothing is recommended. Pick a version under Choose another version. |
The button that installs the recommended update is red only for a STABLE release with no pin or hold in the way. For a pre-release (ALPHA or BETA), and wherever a pin or hold note shows, it is an outlined button. For a pre-release the text also says so and names the newest version on STABLE. Bridge firmware comes from ALPHA (below), so a bridge's card always offers it this way: that is expected, install it.
When the PC's updates are pinned or held, a grey note under the offer says what installing it means for the policy, and the confirmation question repeats it. For example: This machine's bridge firmware is pinned to 1.4.92 on the Updates page. Installing 1.4.98 moves this bridge off the pin; the pin stays, so a bridge plugged in later still gets 1.4.92. For the agent: Installing … here does not change the pin. The note names where the policy is set: on the Updates page (saved on this PC, also by Set up this PC), by Group Policy, in CDM or by a session override.
Refresh at the bottom of the window asks the channels again; otherwise the window checks once while it is open. On this page, as on Devices and Status, the bottom bar has only Refresh and Close.
When the update policy names its own channel
An update policy can name a channel of its own instead of STABLE, BETA, ALPHA or DEV: a mirror on your own server, or your Device Manager's release address. It comes from CDM, from Group Policy or from the Updates page (Raise a pin later). The card then asks that channel first, and when it answers, only that channel decides what is offered: 1.4.99 is available from your organisation's update channel (updates.contoso.com, set in Device Manager). The text above the cards says which devices are checked against it.
- When the channel cannot be reached, the card says Could not reach your organisation's update channel (…). STABLE, BETA and ALPHA were checked instead., and never calls the device up to date.
- When this PC refuses the channel's address, the card says why and how to allow it; automatic updates then hold until the policy is fixed. A channel must be
https, onrelease.crayonic.io, on a server listed in the registry valueAgentUpdateHosts(agent) orFirmwareHosts(bridge firmware) underHKLM\SOFTWARE\Crayonic\Agent, or, for the agent, under your Device Manager's own release address.
Which channel holds what
Crayonic publishes builds on four channels. They do not hold the same things:
| Channel | Agent | Bridge firmware (Crayonic Bridge, firmware 1.4) | Use it for |
|---|---|---|---|
| STABLE | Released builds (1.0.634 today; 1.0.692 once promoted) | Old builds only: 1.4.14, 1.4.62 | Agent updates in production |
| BETA | Nothing published (the window says No builds on BETA) | Old builds only: 1.4.11, 1.4.14 | Nothing at the moment |
| ALPHA | Pre-release builds, among them 1.0.692, the build this page describes | Current firmware: 1.4.90, 1.4.92, 1.4.94, 1.4.98 | Bridge firmware updates |
| DEV | Daily builds, only the newest | Development builds 1.4.67-1.4.81, and 3.0.x builds of a different firmware line | Only a build Crayonic names. Never bridge firmware |
Read it like this:
- Bridge firmware comes from ALPHA. The bridge's card finds it there by itself. The STABLE build it names (The newest on STABLE is 1.4.62) is older than the firmware on a current bridge. Under Choose another version, STABLE and BETA list their builds as (older), and when the chosen channel has nothing newer the window says where the newest build for this bridge is, for example Nothing newer on STABLE. Newest for this bridge: 1.4.98 on ALPHA.
- 1.4.81 is marked (not recommended) and is never offered on a card: it is a rebuild of an older version that shows Windows a placeholder instead of its FIDO interface until a badge connects.
- A bridge never changes firmware line. A bridge on 1.4.x is never offered the 3.0.x builds on DEV, and the other way round; the version list says how many builds of the other line it left out, and the window refuses a cross-line install even with Allow an older version ticked. There is no way back from a line change.
- Never tick Allow an older version unless Crayonic asks you to.
Update the bridge firmware
- Open Install updates. The bridge's card offers the newest firmware for it, today 1.4.98 is available on ALPHA. Press Install 1.4.98.
- The question names the bridge, the two versions and the channel, and adds the pin note when the PC is pinned. It defaults to No: click Yes.
The agent downloads the firmware, checks it, restarts the bridge into its bootloader and flashes it, and reports success only once the bridge is back on the new version. The card shows it as it happens: Installing 1.4.98 (ALPHA channel). Do not unplug the bridge until it is done., the current step with a progress bar, and a greyed-out Installing… button. One install runs at a time: meanwhile the other cards' install buttons are greyed out, and a card that has an update on offer says Waiting for the bridge update to finish.
Warning
Do not unplug the bridge while it is flashed. For that minute there is no badge sign-in on the PC.
When it is done, the card says Done: the bridge runs 1.4.98. and checks again. If it fails, the card says Failed: with the reason and a Show details button that opens the log, and its button becomes Try 1.4.98 again.
Afterwards, press Pin updates to the installed versions on the Setup page again so the pin matches the new version. If the firmware is pinned to a newer version than the one you install, the question warns that the agent will flash the bridge back up to the pin at its next check.
A bridge whose bootloader is older than version 4 (bl 3 on Devices) cannot be updated from this page: after you confirm, the card reports Failed: This bridge's bootloader (v3) must be updated first, which only the automatic update does. To let the automatic update do it, open Updates in the sidebar and, on the Bridge firmware card, choose Follow the newest build and set Channel to ALPHA - early builds. Press Save on this machine. The agent checks for bridge firmware once an hour; once Devices shows the new firmware and bl 4 or later, press Pin updates to the installed versions again. Or ask Crayonic.
Update the agent
When STABLE, BETA or ALPHA has a newer agent, the agent's card offers it the same way: press Install with its version and click Yes in the question.
For an agent build the card does not offer, such as a DEV build Crayonic names, use Choose another version on the agent's card (below): set Channel, pick the version from the list and press Install this agent. Only newer versions install: the installer refuses a downgrade.
The agent downloads the installer and checks its signature. The window then says so and closes, the agent stops, the installer runs and the agent starts again on the new version, all within about a minute. Open the window again to check the version, and pin again if the PC is pinned.
Choose another version
Choose another version, under each card, opens the full channel lists:
- Channel: STABLE, BETA, ALPHA or DEV, the policy's own channel when it names one, and Custom.... It opens on the channel the card points to (the recommended update's, the installed release's, or DEV for a DEV build), with that version selected.
- Custom... asks for the web address (
https) of a folder that holds the release database (firmware_database.jsonfor a bridge,installer_database.jsonfor the agent). The address must pass the same rule as an update policy's channel (above): the dialog says why one is refused and which registry value would allow its server. Change address under the list replaces an address that found nothing. Every package is still verified before it is installed. - Version: each version on the chosen channel, marked (newer), (older) or (installed). The list fills itself when the drawer opens and whenever you pick a channel; the line under it says how many versions the channel has.
- Refresh list asks the channel again, for a build published while the window is open.
- Install on the bridge or Install this agent installs the selected version, after the same question as the card's button.
- Allow an older version (bridge only) lets you install firmware older than the bridge runs. Never tick it unless Crayonic asks you to.
Use it for a DEV build Crayonic names, for an older bridge firmware version when Crayonic asks for one, or to look at what a channel holds. Hide other versions folds it away again.
Last operation
At the bottom of the page, Last operation shows the last install, or the old provider's removal, in one line. Show details unfolds its full log. A failed operation opens its log by itself, once.
Raise a pin later
The simplest way, on a pinned or a held PC: install the new version by hand as above, then press Pin updates to the installed versions again.
To let the agent do the install instead, open Updates in the sidebar. It has one card for the bridge firmware and one for the agent. The first line of each says what the PC does now and who decided it, for example Pinned to 1.4.92 on ALPHA - set on this PC, and a label next to the title says where the policy comes from. Each card offers three choices:
- Follow the newest build: install each new build on the channel as soon as it is published;
- Stay on one version: install the version picked in the box next to it, from the channel, and keep it there. The box lists what the chosen channel publishes;
- Never update by itself: keep what is installed now (a held PC shows this one).
Channel picks STABLE, BETA, ALPHA, DEV or Custom address... for a channel of your own, which must pass the same rule as on Install updates (above). To raise a pin, choose Stay on one version, pick the new version and the channel that lists it: STABLE for a released agent (ALPHA for 1.0.692 until it is promoted), ALPHA for the bridge firmware. A held PC is raised the same way. As soon as you change something, the card says what the PC will do after saving, and warns in amber when the chosen channel does not list the version (nothing would install). Reset gives the card back to CDM's policy or the default.
Then press Save on this machine (not Apply until restart, which an agent update undoes). When a card shows an error, the window asks before it saves.
Where CDM or Group Policy sets the policy, the card is read-only and says where to change it (Read-only here - change it in CDM.). For CDM's policy, Set it on this PC instead makes it editable; what you save then overrides CDM on this PC, which CDM does not show.
Rolling out to many PCs
Set up one PC as above, check that badge sign-in works there, then copy its settings to the others.
Export the settings
The preset, the pins and anything else saved on the PC form one settings document. Press Export for Group Policy… at the bottom of the window (on Setup or a settings page: Devices, Install updates and Status have only Refresh and Close there). The dialog shows the document and which sections it carries.
The dialog exports the rows ticked in the window right now, unsaved edits included. Press Save on this machine first if you changed anything by hand.
Choose where the settings land on the other PCs:
- The Group Policy key (
HKLM\SOFTWARE\Policies\Crayonic\Agent, the default). It wins over a PC's own settings and over CDM. The settings window on those PCs cannot save over it; only Apply until restart overrides it, until the agent restarts, which is useful for a test. - The machine's own key (
HKLM\SOFTWARE\Crayonic\Agent), like Save on this machine. Written once, with the.reg, the.ps1or--import, it stays editable on each PC. A Group Policy item for this key rewrites it at every policy refresh, so for Group Policy use the Group Policy key.
Then take it in the form your route needs:
| Form | Use it for |
|---|---|
| Copy as one line | The Value data of a Group Policy registry item (below). Always paste it as one line. |
One line of JSON (.txt) |
The same line, as a file. |
Registry file (.reg) |
reg import <file> /reg:64 as an administrator, or a double-click. For a PC outside a domain, or a disk image. |
Group Policy Preferences item (.xml) |
Paste it into the Group Policy Management Editor instead of typing the item. |
PowerShell that writes the value (.ps1) |
Run as SYSTEM or as an administrator: an Intune platform script, a startup script, or by hand. It writes the value, reads it back, and exits 0 or 1. |
PowerShell that adds the item to a GPO (.ps1) |
Run on a domain controller or a PC with the Group Policy Management tools: .\crayonic-gpo.ps1 -GpoName "Crayonic Agent". If the GPO already has an item for this value it stops; -Replace replaces every such item, hand-made ones included. |
JSON document (.json) |
Keep it, or load it on another PC with --import. |
The export holds settings only: never a credential, and never the agent's connection to CDM.
Group Policy, without CDM
In an Active Directory domain, one Group Policy object (GPO) linked to the organizational unit that holds the PCs can do what the quick start did on one PC.
Install the agent
- Put the MSI and its
_CloudSyncDisabled.mston a share that computer accounts can read, for example\\fileserver\software\Crayonic\. - In the GPO, open Computer Configuration → Policies → Software Settings → Software installation, choose New → Package… and select the MSI by its UNC path, not a mapped drive.
- Choose Advanced, and on the Modifications tab add the MST (by its UNC path). Do this before clicking OK: a transform cannot be added afterwards. Leave the deployment type Assigned.
PCs install the agent at their next startup, not on a background refresh. Run gpupdate /force and restart; with fast logon on, it can take two restarts.
The MST works only on PCs that never had the agent. For the others, add a registry item to the same GPO: HKLM\SOFTWARE\Policies\Crayonic\Agent, value CloudSyncEnabled, REG_DWORD 0.
Deliver the settings
In the same GPO, open Computer Configuration → Preferences → Windows Settings → Registry and choose New → Registry Item:
| Field | Value |
|---|---|
| Action | Update |
| Hive | HKEY_LOCAL_MACHINE |
| Key Path | SOFTWARE\Policies\Crayonic\Agent |
| Value name | EffectiveSettings |
| Value type | REG_SZ |
| Value data | The line from Copy as one line |
Paste one line
The Value data box keeps only the text before the first line break, and the PCs refuse an incomplete document. The exported line is also prepared for Group Policy Preferences, which would otherwise replace %NAME% with environment variables: it carries %, < and > in an escaped form.
Instead of typing the item, you can copy the exported .xml file in Explorer, right-click Registry in the editor and choose Paste, or run the exported GPO script. The export dialog shows the same steps under By hand in Group Policy.
PCs apply the item at their next Group Policy refresh (about every 90 minutes, or at once with gpupdate /force). Within a minute the agent applies the settings; no restart is needed.
Remove the old provider everywhere
Add a computer startup script (Computer Configuration → Policies → Windows Settings → Scripts → Startup). It does what the removal step does, on every PC:
@echo off
set "EXE=%ProgramW6432%\CrayonicAgent\CrayonicAgentService.exe"
if not exist "%EXE%" exit /b 0
"%EXE%" --settings --remove-old-provider >> "%ProgramData%\CrayonicAgent\remove-old-provider.log" 2>&1
exit /b %ERRORLEVEL%
It waits up to five minutes for the agent to start, which is normal at boot (--wait SECONDS changes that). A PC with nothing to remove is done as soon as the agent answers. It exits with:
| Code | Meaning |
|---|---|
0 |
Removed, or there was nothing to remove (the batch form also exits 0 when the agent is not installed). |
3010 |
Removed; the next restart finishes the job. |
1 |
Failed. The script's log says why; the uninstaller's own log is %ProgramData%\CrayonicAgent\legacy_cp\uninstall_<ProductCode>.log. |
2 |
The command line was wrong: nothing ran, and the log shows the usage text. |
3 |
The program could not start; the log has the error. |
The log file exists only because the batch file above writes it; the agent itself writes no such file.
The exe is a Windows (GUI) program: a batch file waits for it and gets its exit code, but PowerShell does not. For a PowerShell startup script or an Intune platform script, start it like this. The path comes from ProgramW6432 because Intune runs scripts in 32-bit PowerShell:
$exe = Join-Path $env:ProgramW6432 'CrayonicAgent\CrayonicAgentService.exe'
$log = Join-Path $env:ProgramData 'CrayonicAgent\remove-old-provider.log'
if (-not (Test-Path -LiteralPath $exe)) { 'Crayonic agent is not installed'; exit 0 }
$p = Start-Process -FilePath $exe -ArgumentList '--settings','--remove-old-provider' -Wait -PassThru -NoNewWindow -ErrorAction Stop
Add-Content -LiteralPath $log -Value ("{0} exit {1}" -f (Get-Date -Format s), $p.ExitCode)
exit $p.ExitCode
This form logs only the exit code. Intune reports every exit code other than 0 as Failed, 3010 included, although 3010 means the removal worked and a restart finishes it.
Keep the updates pinned
The exported document carries the pins (or holds) from the reference PC. To roll out a new version:
-
Edit the versions in the document, naming the channel each version is published on. A channel must be
httpsonrelease.crayonic.io. A site with its own mirror can allow its host on each PC as a local administrator: the registry valueAgentUpdateHosts(agent) orFirmwareHosts(bridge firmware) underHKLM\SOFTWARE\Crayonic\Agent, a comma-separated list of host names."agent_update_policy": {"mode": "pinned", "target_version": "1.0.NNN", "channel_url": "https://release.crayonic.io/Agent/STABLE/"}, "fw_policy": {"mode": "pinned", "target_version": "1.4.NN", "channel_url": "https://release.crayonic.io/Firmware/ALPHA/"}Edit inside the one-line Value data, or edit the
.jsonexport, load it on a test PC with--import, and use Copy as one line there again. -
Deliver it to a pilot first: a second GPO linked to an organizational unit with a few PCs. A GPO linked closer to the PCs applies later and wins. Give it the complete document with only the versions changed: both GPOs write the same single value, so nothing merges between them.
- Once the pilot PCs work, update the main GPO.
A pin never downgrades. {"mode": "hold"} stops automatic updates at whatever each PC runs.
Check that it arrived
On a PC, run gpupdate /force, wait a minute, then from an administrator Command Prompt:
"C:\Program Files\CrayonicAgent\CrayonicAgentService.exe" --settings --terminal-only
- The Group Policy line names the sections the policy sets, for example
agent_update_policy, bridge_settings, credential_provider, fw_policy. - If it reads
REFUSED -, the reason follows. - A
!line under a layer names a setting that was left out (a misspelt key, a distance outside -100..0 dBm, a section of the wrong shape); the rest applies. - The readiness lines are the same as on the Setup page.
gpresult /r /scope computerlists the GPOs the PC received.
The window's Status page shows the same layers. Left-out settings are listed under their layer with the names the settings pages use, for example Bridge > Connect distance: -140 is below -100.
Change or withdraw
To change the settings, paste a new line over the item's Value data.
A refused document is urgent
If the PCs refuse a new document (for example, it was pasted over two lines), it replaces the previous good one, because both are the same value. Agent and bridge updates are held until you fix it, but nothing else of the document applies. On a PC that CDM does not manage, badge sign-in goes away at the agent's next restart.
Removing the document is not a clean way back either: the update pins go with it (the agent then follows the newest STABLE build again), and after the agent's next restart badge sign-in is off while the sign-in screen still expects it. So:
- To switch badge sign-in off, deliver a document with
"credprov_enabled": falsethat keeps the update policies, and leave it in place. - Any replacement document must keep
agent_update_policyandfw_policy, and thecredential_providersection for as long as badge sign-in is wanted. - To retire the item, change its action to Delete and leave it in the GPO. Delete the value only, never the whole key: the same key holds
CloudSyncEnabled.
Remove this item when it is no longer applied on the item's Common tab deletes the value only on PCs that applied the ticked item and only after it stops applying. Wait until every PC has refreshed policy before you delete the item or unlink the GPO.
Without a domain
PCs outside a domain can take the same document:
- the exported
.regfile, withreg import <file> /reg:64as an administrator (without/reg:64, a 32-bit runner such as an Intune Win32 app writes where the agent never looks); - the exported
.ps1, for example as an Intune platform script with Run this script using the logged on credentials set to No; - a
.jsonexport with--import.
Run --remove-old-provider from a script of its own (the PowerShell form above): the exported .ps1 ends with its own exit, so anything appended to it never runs.
Troubleshooting
The Setup page's lines, as they read in the window:
| Line | What to do |
|---|---|
| FIX Old credential provider: Still on this machine | Press Fix or Set up this PC (details). |
| CHECK Old credential provider: Removed. Restart Windows to finish… | Restart Windows. Nothing to press. |
| CHECK Old credential provider: Not registered, but its files are still in System32 | Harmless. Fix removes the files. |
| FIX Credential provider (CP3): Not registered | Reinstall the agent. |
| FIX Credential provider (CP3): Registered but switched off | Delete the value Disabled under HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Authentication\Credential Providers\{D41F8C90-3E6B-4A72-9C15-5B2E7A0D6F31}. |
| FIX Credential provider (CP3): Hidden by the 'Exclude credential providers' policy | Take {D41F8C90-3E6B-4A72-9C15-5B2E7A0D6F31} out of that policy's list, in the GPO that sets it. |
| FIX Badge sign-in: Off / CHECK the sign-in method is … | Press Fix or Set up this PC. |
| FIX Badge sign-in or Bridge mode: Group Policy keeps …, so the … preset cannot change it - change it there | The sign-in method or bridge mode is set in a GPO. Change it in that GPO's document; the window cannot. No Fix button, and Set up this PC stops with the same reason. |
| The same, with 'Apply until restart' keeps … | Settings applied for this session only win until the agent restarts. Restart the Crayonic Agent service, then press Set up this PC again. |
| FIX Bridge: No bridge is plugged in | Plug the bridge in, or try another USB port. If Device Manager shows it as VID_0000 with Code 43, unplug it and plug it back in; a restart of the USB port does not help. |
| FIX Bridge mode | Press Fix. If the bridge stays in the other mode, unplug it and plug it back in. |
| FIX Smart card reader (smartcard) | The reader appears about ten seconds after the bridge switches to smart card mode. Press Refresh. |
| FIX Smart Card service (smartcard): disabled | In services.msc, set Smart Card to Manual or Automatic. If it says missing, the Windows component is gone from this PC; repair Windows. |
| FIX Domain (smartcard) | Join the PC to the domain. A smartcard sign-in does not work in a workgroup. |
| FIX FIDO interface (Entra FIDO) | Windows sees the bridge's FIDO interface about ten seconds after the bridge switches to FIDO mode; press Refresh. If it stays, unplug the bridge and plug it back in. On bridge firmware older than 1.4.76, and on 1.4.81, the line is INFO until a badge connects: update the bridge. |
| FIX Microsoft Entra (Entra FIDO) | Not in a domain: Settings › Accounts › Access work or school › Connect › Join this device to Microsoft Entra ID (signing in from Connect alone only registers the device). In a domain: set up hybrid join and Microsoft Entra Kerberos, or use the smartcard method. dsregcmd /status shows the state. |
| FIX Windows (Entra FIDO) | Update Windows: 1909 or later (2004 when hybrid joined). Not Windows Server. |
| CHECK Badges: None seen yet | Wake a badge with its button and bring it near the bridge. |
| CHECK Updates: In production, pin the versions | Press Fix or Set up this PC (details). |
| CHECK Updates: … - in the Group Policy document, which sets the mode here | Pin in that GPO's document (details). |
| CHECK Updates: … - in CDM … | CDM sets, or will set, the update policy. Pin in CDM, or, on a PC that CDM will never manage, turn cloud sync off. |
| CHECK Updates: held while a settings document … | Fix the document the line names. Until then that update is held. Usual causes: a misspelt key ("Mode"), a pin without target_version, or a document pasted over several lines. |
| INFO Cloud sync: On on a PC CDM will not manage | Turn it off with the reg add command. |
| ? Bridge mode: Not reported yet | The agent has only just started. Wait a few seconds and press Refresh. |
Other problems:
| What you see | What to do |
|---|---|
| Smartcard: the user name or password is incorrect | The domain controller refused the certificate: it is not strongly mapped to the user (KB5014754). Issue certificates with the user's SID extension, or add a mapping such as X509:<I>issuer<SR>serial to the account's altSecurityIdentities. |
| Entra FIDO: the sign-in fails as busy, or hangs | Make sure users pick the Crayonic tile, not Windows' Security key tile. |
| No tile for a badge | Check Devices. below rssi means the badge is too far from the bridge. If it is not listed, wake it with its button. |
| The tile is there but the badge does not connect | Hold the badge close to the bridge: the preset connects only above -40 dBm. |
| Set up this PC asks and nothing happens | You pressed Enter: No is the default when the question carries notes. Click Yes. |
| Install updates: Could not check for updates: the release server could not be reached | The agent service cannot reach release.crayonic.io: allow it through, or set a proxy it uses (Before you start). Then press Try again. Show the error shows the agent's full message. |
| Install updates: the bridge's card offers an ALPHA build, a pre-release channel | Expected: current bridge firmware is published only on ALPHA (channels). Install it. |
| Install updates: the agent's card says a DEV build | The PC runs a development build. Install 1.0.692 from ALPHA instead (step 1), unless Crayonic named that DEV build. |
| Install updates: the install buttons are greyed out; a card with an update on offer says Waiting for … to finish | Another install, or the old provider's removal, is still running. One runs at a time. |
| Install updates: Failed: This bridge's bootloader (v3) must be updated first | The bridge needs the automatic update once (Update the bridge firmware). |
| Install updates: Could not reach your organisation's update channel | The policy names a channel of its own that the agent cannot reach. Check the address in the policy and this PC's access to that server (policy channel). |
| Updates: … is not on STABLE: this PC will not find it there | The version is published on another channel. Pick the channel that lists it, or a version from the list (Raise a pin later). |
REFUSED - is not valid JSON on the Group Policy line |
The document arrived broken, almost always pasted over several lines. Copy it again with Copy as one line, at once (Change or withdraw). |
| A setting in the document has no effect | Run --settings --terminal-only and look for its ! line, or open Status, which lists it under its layer with the reason. |
| Group Policy settings do not arrive | gpresult /r /scope computer must list the GPO. The item's Key Path is SOFTWARE\Policies\Crayonic\Agent, without HKLM\. Allow a minute after gpupdate /force. |
| The startup script exits other than 0 | See the exit codes. Another installation is in progress clears on the next start. |
certutil -scinfo shows the wrong reader |
Over Remote Desktop, Windows shows the readers of your own computer. Check on the PC itself, or with --terminal-only. |
To check a PC remotely, run the window in text mode from an administrator Command Prompt or over SSH (not PowerShell remoting, which shows nothing). It prints the same lines and device list:
"C:\Program Files\CrayonicAgent\CrayonicAgentService.exe" --settings --terminal-only
In an interactive Command Prompt the prompt comes back before the text; the text follows a moment later.
Reference
What the presets set
| Setting | Smartcard | Entra FIDO | Meaning |
|---|---|---|---|
credprov_enabled |
on | on | Show badge tiles on the sign-in screen. |
credprov_logon_method |
smartcard | aad_fido | Sign in with the badge's PIV certificate, or with its passkey for Microsoft Entra ID. |
credprov_aad_fido_logon |
off | on | The older Entra FIDO switch, kept in step for agents that predate the method. |
credprov_auto_start |
on | on | Start the sign-in once the badge connects. |
credprov_auto_connect_on_select |
on | on | Connect the badge when its tile is selected. |
credprov_auto_fido_on_roster_connect |
on | on | Also start the sign-in when a badge connects on its own. |
credprov_name_from_credential |
on | on | Name tiles from what the badge itself presents: its certificate, or its sign-in. |
credprov_fido_nudge |
off | off | Do not restart a bridge function after each connect to wake Windows' own security-key tile. |
credprov_rssi_min |
-60 dBm | -60 dBm | Show a tile only for a badge whose signal is at least this. |
credprov_hysteresis_db |
10 dB | 10 dB | Keep a shown tile until the signal falls 10 dB below that (-70 dBm). |
smartcard_bridge_enabled |
on | off | The bridge's smart card reader (CCID). |
fido_bridge_enabled |
off | on | The bridge's FIDO interface (CTAP-HID). The bridge runs either this or the reader. |
rssi_connect_threshold |
-40 dBm | -40 dBm | The bridge connects a badge only above this: held close. |
rssi_fastconnect_threshold |
-40 dBm | -40 dBm | The same gate for the bridge's fast connect. |
rssi_disconnect_threshold |
0 | 0 | No distance-based disconnect: the bridge keeps the badge until the link is lost. |
All of them are in the credential_provider section, except the last five, which are in bridge_settings.
What "Pin updates" sets
"agent_update_policy": {"mode": "pinned", "target_version": "1.0.692",
"channel_url": "https://release.crayonic.io/Agent/STABLE/"},
"fw_policy": {"mode": "pinned", "target_version": "1.4.92",
"channel_url": "https://release.crayonic.io/Firmware/ALPHA/"}
Or, for a version no STABLE, BETA or ALPHA channel lists, {"mode": "hold"}. The modes:
pinned: install exactly this version from the named channel if it is newer than what runs (STABLE when no channel is named);latest: follow the newest build on the channel;hold: never update automatically.
With nothing set and no CDM, the agent follows latest on STABLE and the bridge firmware is held.
Command line
CrayonicAgentService.exe --settings followed by:
| Option | What it does |
|---|---|
| (nothing) | The window from a Start menu shortcut or Explorer; text when started from a Command Prompt you are sitting in. |
--gui |
Draw the window, even from a Command Prompt. |
--terminal-only |
Print the settings, readiness lines and devices as text. |
--help |
Print the usage. |
--export FILE |
Write this PC's saved settings to FILE (also --export=FILE). The extension picks the form: .json, .txt (one line), .reg, .xml (Group Policy Preferences item), .ps1 (script that writes the value). |
--format NAME |
Name the form instead: json, line, reg, gpp, ps1, or gpo (script that adds the item to a GPO). |
--to policy or --to machine |
Where it lands on the other PCs: the Group Policy key (default) or their own key. |
--from effective |
Export everything in force here, CDM and Group Policy included, not only the saved settings (--from machine, the default). |
--import FILE |
Save a .json document as this PC's own settings, replacing what was saved before. Works with the agent stopped too. |
--remove-old-provider |
Remove CP1/CP2 if installed. Exits 0, 3010, 1, 2 or 3 (meanings). |
--wait SECONDS |
How long to wait for the agent to start: 0 to 3600, default 300. |
--export, --import and --remove-old-provider are for scripts: they never draw a window or ask for elevation, so run them from an elevated prompt. Use one of them at a time; --format, --to and --from go only with --export, and --wait only with --remove-old-provider. A wrong command line prints the usage and exits 2.
Where settings come from
Each source beats the ones before it, setting by setting:
- CDM, when the PC is enrolled and cloud sync is on.
- This machine (
HKLM\SOFTWARE\Crayonic\Agent), written by Save on this machine, Set up this PC, the presets, the pin and--import. - Group Policy (
HKLM\SOFTWARE\Policies\Crayonic\Agent). - This session, written by Apply until restart; it lasts until the agent restarts.
The Status page lists these four layers with the same numbers and names. Clear both drops layers 2 and 4, never Group Policy.
On the settings pages each setting has one control, and a label next to it says where its value comes from: Default, CDM, This PC, Group Policy or This session, and Changed until you save. Changing a value sets it on this PC. Reset gives it back to Group Policy's value, else CDM's, else the default; Undo takes a Reset back. A setting that Group Policy sets says so under it: a value saved on this PC does not take effect while the policy sets it. Older switches and fine-tuning are folded under Show advanced settings at the end of each page, which says how many of them are set. Distances are offered as named places with their signal strength, for example Close - next to the PC (-40 dBm); you can also type a number.
The window's pages
| Page | What it is for |
|---|---|
| Setup | Readiness lines, Set up this PC, the preset and pin buttons. |
| Devices | Bridges, readers and badges the agent sees, refreshed every three seconds. |
| Bridge, Sign-in screen, Cloud, Pairing | Every individual setting, grouped, in plain words. Change one, then Save on this machine. |
| Updates | How the PC updates the bridge firmware and the agent by itself: one card each (Raise a pin later). |
| Install updates | A card for each bridge and for the agent with the update to install, every other version under Choose another version, and the last operation's log. |
| Support switches | A few switches for troubleshooting with Crayonic support, which CDM never sets. They have their own Save support switches button, go straight to this PC's registry and stay until reset. |
| Status | This PC and its bridges, where each setting comes from, and the sign-in screen. Copy diagnostics copies all of it, with the devices this PC sees, as text for Crayonic support; Show raw details unfolds the settings layers as raw text. |
Related
- Crayonic Agent — badge roster, CDM settings, sign-in telemetry and lock-on-disconnect
- Crayonic Credential Provider — how the logon tile behaves. The agent installs it; the standalone download is obsolete
- Crayonic Bridge — brings the badge to the workstation and drives proximity
- Crayonic Device Manager — the same settings, managed centrally for a fleet
- Downloads