Skip to content

Cookbook: On-Premises Active Directory Integration

This cookbook takes an on-premises Active Directory domain from password sign-in to people signing in to Windows with a logon certificate on a Crayonic wallet. It lists what to check first, what to change on your domain controllers and certificate authority, how to issue and map each certificate, and how to prove that each part works before you roll it out.

For: Active Directory and PKI administrators. You need: a test domain or a pilot OU, one test user, one enrolment workstation, one test Windows machine and one Crayonic wallet of each model you plan to deploy.

Where this fits

The wallet acts as a PIV smart card, and Windows signs the user in with a standard Kerberos smart card logon. No Crayonic server and no Microsoft Entra ID are needed. For passkey sign-in with Entra ID, see the Entra ID cookbook.

Screenshots and checks

The Crayonic Enterprise Setup PDF has screenshots of the template and PIV Manager dialogs. It dates from 2023 and does not cover strong certificate mapping, so where the two differ, follow this cookbook. The Microsoft steps were checked against Microsoft's documentation on 1 November 2026.

Choose your setup

Make these three decisions first. They decide which steps you can skip.

Decision Options Go to
How does the wallet reach the machine? USB or NFC, with Windows' own smart card tile. Needs no Crayonic software on the machine. Step 7
A Crayonic Bridge, so people sign in by bringing the wallet to the machine. Adds the Bridge and the Crayonic Agent on each machine. Step 8
Will people still be able to use a password? Yes: the wallet is an extra way to sign in. No: enforce smart card sign-in per account or per machine. Step 10
Do you also need an encryption certificate on the wallet? No: this cookbook issues the logon certificate only. Yes: add the optional Data Encryption template from section 2.1.3 of the PDF. Keep it separate, because one template cannot serve both purposes. Step 4

The checklist

Keep this list open as you work. Each line links to its step.

Before you change anything

On the domain controllers and the certificate authority

For each wallet

On Windows

Before you roll out

1. Check the prerequisites

Accounts and rights

Task Account you need
Create templates, publish them on the CA, change the NTAuth store Member of Enterprise Admins
Request certificates and provision wallets A certificate issuer: a member of the group you create in step 4
Add a mapping to a user's account Write access to the user's altSecurityIdentities attribute, for example a delegated group or Domain Admins
Test sign-in A standard user with a test certificate

Servers and machines

Requirement Details
Active Directory Active Directory Domain Services, with current Windows updates on all domain controllers
Certificate authority Active Directory Certificate Services with an Enterprise issuing CA, or another CA that meets Microsoft's requirements for non-Microsoft CAs. This cookbook assumes an Enterprise CA. Do not install a production CA on a domain controller
Machines Windows 10 or 11, joined to the domain. A workgroup machine cannot use this sign-in, because a smart card logon is a Kerberos logon
Smart Card service The Windows Smart Card service must not be disabled. No Crayonic smart card driver is needed: Windows uses its built-in PIV support
Enrolment workstation Windows 10 or later, joined to the domain, with Crayonic PIV Manager installed, plus the Remote Server Administration Tools if you map certificates from this machine

Wallets

Update the firmware with the Crayonic Firmware Manager or the files on the Downloads page. Then enrol a fingerprint on the wallet if you want people to unlock it with one. The PIN is set in step 5.

An emergency account and a pilot group

  • Keep at least one emergency administrator account that signs in with a password, and exclude it from everything in step 10. It is your way back in if a policy or a certificate problem locks people out.
  • Create a pilot group and a pilot OU with your test user and test machine. Apply the policies in this cookbook there first.

2. Give every domain controller a KDC certificate

Each domain controller that authenticates smart card users needs its own certificate. The client checks this certificate during every smart card logon. Microsoft recommends the Kerberos Authentication template, because certificates from the older Domain Controller and Domain Controller Authentication templates do not include the KDC Authentication EKU.

Check that the template is published

An Enterprise CA publishes Kerberos Authentication by default. On the CA, open certsrv.msc and look under Certificate Templates. If it is missing, right-click Certificate Templates, select New > Certificate Template to Issue and select it.

The built-in template uses older cryptography. If you want RSA 2048 and SHA256 on your domain controller certificates, follow Microsoft's steps to duplicate it, and have the new template supersede the older domain controller templates.

Let the domain controllers enrol

Turn on certificate auto-enrollment for the domain controllers, in a Group Policy object linked to the Domain Controllers OU:

  1. Go to Computer Configuration > Windows Settings > Security Settings > Public Key Policies.
  2. Open Certificate Services Client - Auto-Enrollment and set Configuration Model to Enabled.
  3. Select Renew expired certificates, update pending certificates, and remove revoked certificates and Update certificates that use certificate templates.
  4. On each domain controller, run gpupdate /force and allow a few minutes.

Check the result

On each domain controller, open certlm.msc, go to Personal > Certificates and confirm that a certificate from your CA lists KDC Authentication under Intended Purposes. Then check all domain controllers from one place:

certutil -dcinfo verify

3. Prepare the certificate authority

Check the NTAuth store and trust

The domain controller accepts a smart card logon only if the CA that issued the certificate is in the forest's NTAuth store. An Enterprise CA is added to it automatically when it is installed. Check it:

certutil -enterprise -store NTAUTH

Your issuing CA must be listed. If it is not, or if your CA is not an Enterprise CA, add it from a file holding the CA's certificate, as an Enterprise Admin:

certutil -dspublish -f issuing-ca.cer NTAuthCA

Domain controllers and machines must also trust the root CA that the issuing CA chains to. With an Enterprise CA this happens through Active Directory. With another CA, distribute the root through a Group Policy object, under Public Key Policies > Trusted Root Certification Authorities.

The NTAuth change reaches machines with the next Group Policy refresh. Run gpupdate /force on your test machine to get it at once.

Publish the CRL over HTTP

If the revocation check fails on the domain controller or on the client, the logon is denied. A CRL that cannot be downloaded, an out-of-date CRL and an "unknown" status all count as failures.

  1. In certsrv.msc, open the CA's Properties, go to the Extensions tab and select CRL Distribution Point (CDP).
  2. Make sure there is an HTTP location with Include in the CDP extension of issued certificates selected.
  3. If you added or changed a location, restart the CA. Only certificates issued from then on carry the new location, so reissue the domain controller certificates if they do not have it.
  4. Make sure a web server serves that URL, and that new CRLs reach it. To publish a new CRL on the CA, run certutil -crl.

After you issue your first certificate in step 5, check from a test machine that the chain and the CRL can be reached:

certutil -urlfetch -verify alice.cer

Check how the CA handles requests

Open the CA's Properties:

  1. On the Policy Module tab, select Properties and confirm that Follow the settings in the certificate template, if applicable is selected.
  2. On the Security tab, confirm that the group of certificate issuers you create in step 4, or Authenticated Users, has Request Certificates.

4. Create the logon certificate template

Create the template

  1. Open certtmpl.msc, right-click Smartcard Logon and select Duplicate Template.
  2. Use the settings below. The template name cannot be changed after you save it.
  3. In certsrv.msc, right-click Certificate Templates, select New > Certificate Template to Issue and select the new template.
Tab Setting Value
Compatibility Certification Authority Windows Server 2012 or later
Certificate recipient Windows 8 / Windows Server 2012 or later
General Template display name Crayonic Smartcard Logon
Template name CrayonicSmartcardLogon
Validity period 1 year
Renewal period 6 weeks
Publish certificate in Active Directory Off
Request Handling Purpose Signature and smartcard logon
Renew with the same key Off
When the subject is enrolled Prompt the user during enrollment
Cryptography Provider Category Key Storage Provider
Algorithm name RSA
Minimum key size 2048
Providers Requests must use one of the following providers: Microsoft Smart Card Key Storage Provider
Request hash SHA256
Subject Name Supply in the request
Issuance Requirements CA certificate manager approval See Limit who can enrol
Extensions Application Policies Client Authentication and Smart Card Logon
Basic Constraints Enabled and critical; the subject is an end entity
Key Usage Digital signature; critical
Issuance Policies Optional. Add one only if your organization uses assurance policies

Limit who can enrol

This template can issue a certificate for any user

With Supply in the request, whoever requests the certificate decides whose name goes in it, and that includes a domain administrator. Microsoft flags this combination as a common and dangerous misconfiguration (ESC1) when ordinary users can enrol. Treat the certificate issuers like any other highly privileged administrators.

  1. Create a global security group, for example Crayonic Certificate Issuers, with as few members as possible. Use dedicated accounts for its members, and sign in with them only on the enrolment workstation.

  2. On the template's Security tab, select Advanced and set these permissions:

    Principal Permissions
    Crayonic Certificate Issuers Read, Enroll
    Domain Admins, Enterprise Admins Read, Write. No Enroll or Autoenroll
    Authenticated Users Read only

  3. Turn on auditing on the CA, so that every issued certificate is logged, and check Issued Certificates regularly for certificates you do not recognize.

  4. For more protection, use one or both of Microsoft's other mitigations:
    • Turn on CA certificate manager approval, so that a second person approves each certificate. Test this with PIV Manager first: this cookbook's steps assume the certificate is issued at once.
    • Remove the template from Certificate Templates on the CA between provisioning batches. A template that is not published cannot be requested.

5. Provision the wallet

Do this once for each wallet, on the enrolment workstation, signed in as a certificate issuer.

Initialize the wallet

  1. Connect the wallet by USB and start Crayonic PIV Manager. If the wallet is not detected and the Crayonic Agent runs on this machine, stop the Agent first.
  2. A new wallet opens the Device Initialization dialog. To change the secrets on a wallet that is already initialized, select Manage device PINs.

  3. Set the three secrets:

    Secret Who knows it How to set it
    PIN The user Numeric. The user unlocks the wallet with it
    PUK IT support Random and unique to the wallet. It unblocks a blocked PIN
    Management key Certificate issuers only Select Use a separate key, then Randomize. It controls which certificates can be written to the wallet

  4. Store the PUK and the management key in your secrets manager, against the wallet's serial number.

Issue the certificate

  1. Select Certificates. On the Authentication tab, select Generate new key....

  2. Fill in the dialog. The private key is generated on the wallet and never leaves it.

    Field Value
    Algorithm RSA (2048 bits)
    Output Request a certificate from a Windows CA
    Certificate Template CrayonicSmartcardLogon
    Subject The domain components and the user, for example /DC=com/DC=contoso/CN=alice. Include the DC parts: without them, domain resolution can fail
    User Principal Name (UPN) The user's UPN in Active Directory, for example alice@contoso.com. Check that it matches the account's userPrincipalName

  3. Enter the PIN and the management key when asked, and select your CA. Generating the key can take up to 30 seconds.

  4. When the certificate appears on the tab, select Export certificate... and save it, for example as alice.cer. You need it for the next step.

Check the wallet

With the wallet connected, read the certificate back:

certutil -silent -scinfo

The output must show your CA as the issuer, the template and the subject, with no chain or revocation errors.

6. Map the certificate to the user

Every certificate from this template needs a mapping

Since Microsoft's September 2025 updates, domain controllers enforce strong certificate mapping and the setting that relaxed it is no longer supported. A certificate must carry the user's SID extension or be strongly mapped to the account. The CA adds the SID extension only to certificates from online templates, which build the subject from Active Directory. This template takes the subject from the request, so plan to map each certificate yourself. Without a mapping, the logon fails.

Add the mapping to the user's altSecurityIdentities attribute. Microsoft recommends the issuer and serial number form:

X509:<I>DC=com,DC=contoso,CN=CONTOSO-DC-CA<SR>1200000000AC11000000002B

The issuer is written in reverse order. The serial number is reversed byte by byte: a serial of 2B0000000011AC0000000012 becomes 1200000000AC11000000002B. Use one of these two ways to get it right.

With Active Directory Users and Computers, for one or two users

  1. Open dsa.msc and select View > Advanced Features.
  2. Right-click the user and select Name Mappings.
  3. On the X.509 Certificates tab, select Add and choose alice.cer.

With PowerShell, for scripted rollouts

This needs the Active Directory PowerShell module:

$cert = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new('C:\certs\alice.cer')
$issuer = $cert.Issuer -split ',\s*(?=[A-Za-z0-9.]+=)'
[array]::Reverse($issuer)
$serial = ($cert.GetSerialNumber() | ForEach-Object { $_.ToString('X2') }) -join ''
$mapping = 'X509:<I>' + ($issuer -join ',') + '<SR>' + $serial
$mapping
Set-ADUser -Identity alice -Add @{ altSecurityIdentities = $mapping }

Check the mapping

Get-ADUser -Identity alice -Properties altSecurityIdentities | Select-Object -ExpandProperty altSecurityIdentities

The value must start with X509:<I> and contain <SR>. The forms X509:<I>...<S>..., X509:<S>... and X509:<RFC822>... are weak mappings, and the domain controller rejects them.

A mapping belongs to one certificate

When a wallet gets a new certificate, the serial number changes, so add a new mapping and remove the old one. See Operate.

7. Test sign-in over USB

Test this first, before you add a Bridge, because it uses only Windows and the wallet.

  1. On the test machine, sign out and connect the wallet by USB.
  2. Windows shows a smart card tile with the user's UPN. Under Sign-in options, select the smart card icon if it is not already selected.
  3. Sign in one of these two ways:
    • Enter the PIN and press Enter.
    • Unlock the wallet with its PIN or a fingerprint first, then leave the field empty and press Enter.

Prove it was a certificate logon

On the domain controller, open the Security log and find event 4768 for the user. Pre-Authentication Type must be 16, and Certificate Information must show your CA and the certificate's serial number.

If the logon fails

Check the domain controller's System log for Kdcsvc events first. See Troubleshooting.

8. Add the Crayonic Bridge and Agent (optional)

With a Bridge, people sign in by bringing their wallet to the machine and do not type a PIN on the screen. Follow Badge Sign-in Setup for the full steps, with Smartcard (PIV certificate) as the sign-in method:

  1. Install the Agent, which includes the Crayonic Credential Provider, and plug in the Bridge.
  2. Remove the old credential provider, if a machine has one.
  3. Apply the smartcard sign-in preset. The Bridge restarts as a smart card reader, and within about ten seconds Crayonic KeyVault 0 appears as a reader.
  4. Pin the updates, and check the Bridge and the wallets.
  5. Roll out to more machines with Group Policy. You do not need Crayonic Device Manager for this.

Isolated networks

The Agent downloads updates from release.crayonic.io. On a network without internet access, pin the updates and distribute the installers yourself.

9. Lock the session when the wallet leaves

Which setting locks the machine depends on how the user signed in.

Signed in with What locks the machine What to do
The Crayonic tile, through a Bridge The Crayonic Agent. Windows' own removal policy does not lock for a wallet on a Bridge, because the Bridge's reader never reports the card removed Leave When the signed-in badge is removed on Lock the computer. See Walk-away lock
Windows' smart card tile, over USB or NFC Windows' smart card removal policy Set the policy and the service below

For Windows' removal policy, in a Group Policy object:

  1. Go to Computer Configuration > Windows Settings > Security Settings > Local Policies > Security Options.
  2. Set Interactive logon: Smart card removal behavior to Lock Workstation. The default is No Action.
  3. Set the Smart Card Removal Policy service to Automatic. The policy has no effect unless the service is running.

Acceptance tests

Run these on the test machine with the test user. Do not roll out until all of them pass.

# Test Expected result
1 Sign in with the wallet over USB Desktop appears. Event 4768 on the domain controller shows pre-authentication type 16
2 Sign in with the wallet at the Bridge (if used) The tile shows the user's name, and the sign-in completes with no PIN on the screen
3 Lock the machine and unlock it with the wallet The session resumes
4 Remove the wallet or walk away The machine locks
5 Enter a wrong PIN The sign-in is refused. Stop before five wrong attempts, which block the PIN
6 Try a wallet whose certificate has no mapping The logon is refused, and event 39 appears on the domain controller
7 Revoke a test certificate, publish the CRL and try it The logon is refused. Allow for domain controllers using a cached CRL until its next update
8 Remote Desktop from the test machine to a domain server, with smart cards selected under Local Resources The session opens after the wallet unlocks
9 Sign in with the emergency account It still works
10 Disconnect the test machine from the network and sign in with the wallet as a user who signed in before Windows uses cached credentials. Decide whether this meets your policy

10. Enforce smart card sign-in (optional)

There are two settings. They are independent, and you can use either one or both. Roll them out to the pilot first.

Per account: the user must use a smart card, on any machine

In dsa.msc, open the user's properties, go to the Account tab and select Smart card is required for interactive logon.

This replaces the user's password

Windows replaces the account's password with a random value, so applications that ask for the user's password stop working. Check which applications your pilot users rely on before you turn this on. Clearing the option does not bring back the old password, so an administrator has to set a new one.

Per machine: everyone must use a smart card on this machine

In a Group Policy object, under Computer Configuration > Windows Settings > Security Settings > Local Policies > Security Options, set Interactive logon: Require smart card to Enabled. A local account managed by Windows LAPS is exempt.

Test this with the Crayonic tile

If you sign in through a Bridge, test this policy on a pilot machine with the Crayonic tile before you roll it out. Keep a way back in, for example through Windows LAPS. Note that the policy applies to everyone on the machine, including the emergency account from step 1, so exclude the machines that account needs.

Operate

A wallet is lost or stolen

  1. Remove the certificate's mapping from the user's account. Once this replicates, the domain controller has no mapping to accept the certificate. It does not wait for a CRL to expire.
  2. In certsrv.msc, under Issued Certificates, revoke the certificate with the reason Key Compromise.
  3. Publish a new CRL: certutil -crl.
  4. If the user had Smart card is required for interactive logon, give them a replacement wallet, or clear the option and set a temporary password.
Set-ADUser -Identity alice -Remove @{ altSecurityIdentities = 'X509:<I>DC=com,DC=contoso,CN=CONTOSO-DC-CA<SR>1200000000AC11000000002B' }

A certificate is about to expire

Issue a new one as in step 5. It replaces the old certificate in the slot. Then, in this order: add the new mapping, confirm that the user can sign in, remove the old mapping and revoke the old certificate. There is no automatic renewal in this setup, so track expiry dates. With the 1 year validity above, start at least 6 weeks ahead.

The user forgets the PIN

The PIN is blocked after 5 wrong attempts. IT support unblocks it with the PUK in PIV Manager, under Manage device PINs. If the PIN is known, the user can change it in the wallet's menu, or by pressing Ctrl+Alt+Del and selecting Change a password. Windows rejects simple PINs such as 1234 there.

A wallet moves to another user

  1. Reset the wallet from its menu: RESETS > RESET PIV. This deletes its certificates and restores the default PIN, PUK and management key.
  2. Revoke its certificates, publish a new CRL and remove the mapping from the old user's account.
  3. Provision the wallet for the new user from step 5.

The domain controller certificate expires

Auto-enrollment renews it. Check certutil -dcinfo verify as part of your regular monitoring, because an expired certificate stops smart card logons on that domain controller.

Limits

  • Domain-joined Windows only. This cookbook covers Windows machines joined to the domain. For the other platforms that read the PIV certificate, see the compatibility tables on the Badge and KeyVault pages.
  • USB, NFC or Bridge. Windows reaches the certificate over USB, NFC or through a Crayonic Bridge. NFC needs an NFC reader on the machine. A PIV logon does not work directly over Bluetooth without a Bridge.
  • RSA keys. This cookbook uses RSA 2048. An ECC certificate also needs the policy Allow ECC certificates to be used for logon and authentication, and Microsoft notes that an offline ECDSA logon needs an associated ECDH key.
  • No Crayonic Credential Manager. CCM is a console for Microsoft Entra ID environments, so it is not part of this setup. Certificates are issued with PIV Manager, one wallet at a time.
  • Offline sign-in. With no domain controller in reach, Windows signs in with cached credentials and does not check the certificate. It works only for a user who has signed in on that machine before.

Troubleshooting

Symptom Cause and fix
The user name or password is incorrect with a correct PIN, or Kdcsvc event 39 on the domain controller The certificate has no strong mapping. Add one (step 6) and allow for replication
Kdcsvc event 41 The SID in the certificate does not match the account, so the certificate was issued to a different user. Issue a new one
The system could not log you on. Your credentials could not be verified Check, in this order: the domain controller has a certificate with the KDC Authentication EKU (step 2); the issuing CA is in NTAuth (step 3); the UPN in the certificate matches the account
The smartcard certificate used for authentication was not trusted Revocation or trust failed. Run certutil -urlfetch -verify alice.cer on the machine and on the domain controller. Check that the CRL is online and not past its next update (step 3)
No smart card tile, or no certificate on the tile Run certutil -silent -scinfo. Check that the certificate is in the Authentication slot, has not expired, and has the Smart Card Logon EKU and Digital signature key usage
CA rejected the CSR in PIV Manager Check the template name you typed, that the template is published on the CA and that you are a member of the issuers group
Write to slot failed in PIV Manager The management key you entered does not match the wallet's
PIV Manager does not detect the wallet Connect it by USB and stop the Crayonic Agent if it holds the wallet
Tile from the Bridge: Another Badge took the reader Another wallet took the Bridge during the sign-in. Try again, holding the wallet close
The machine does not lock when the wallet leaves Check how the user signed in (step 9). A sign-in with Windows' own tiles is not watched by the Agent
Remote Desktop from a machine outside the domain shows an authentication error Use Remote Credential Guard, or disable Network Level Authentication on the target server. The first is the better choice, because disabling NLA weakens the server's protection

Sources

Microsoft

Crayonic