Set up OneSigner, step by step

▶ Watch it done once

Six minutes and 39 seconds, from the installer to a signature Adobe Reader accepts. Recorded on a clean machine, with narration and captions — every step below also has its own clip.

0 Before you start

Three things decide whether the rest of this guide goes smoothly.

Mark step 0 complete

1 Download and verify OneSigner

Always check the installer before you run it. It takes ten seconds.

1. Open Command Prompt or PowerShell in the folder you want the installer in and run this one line. It always fetches the latest release, no account needed:

powershell -ExecutionPolicy Bypass -NoProfile -Command "curl.exe -L --fail -o OneSigner-Setup.exe ((Invoke-RestMethod https://onesign.sg/portal/api/latest-version.php).url)"

Prefer the browser? Download it from onesign.sg/portal/trial.

2. Verify the signature, then note the hash and the size:

powershell -ExecutionPolicy Bypass -NoProfile -Command "Get-AuthenticodeSignature .\OneSigner-Setup.exe | Format-List Status; (Get-AuthenticodeSignature .\OneSigner-Setup.exe).SignerCertificate | Format-List Subject,Issuer; Get-FileHash .\OneSigner-Setup.exe | Format-List Hash; (Get-Item .\OneSigner-Setup.exe).Length"

Keep the SHA-256 and the size with your change record: they identify exactly which release you installed.

Mark step 1 complete

2 Install

A standard wizard. Accept the licence, confirm the folder, install.

For unattended rollout the installer accepts /VERYSILENT /SUPPRESSMSGBOXES /NORESTART.

Mark step 2 complete

3 Activate your licence

Every tab stays disabled until OneSigner is licensed.

1. On first launch you get Activate OneSigner → Start your free 30-day trial.
2. Enter your work email, full name, company and country, then click Email me a code.
3. Take the 6-digit code from the email (subject Verify your email — OneSigner). It is valid for 30 minutes.
4. Enter it and click Activate. Already bought? Use I already have a license key instead.

Confirm the service agrees:

(Invoke-WebRequest http://localhost:9440/ -UseBasicParsing).Content
# "license":{"status":"Valid","message":"License valid until ..."}

Mark step 3 complete

4 Install the driver for your token

Identify the token first, then install only the middleware that matches it.

Get-PnpDevice -PresentOnly | Where-Object { $_.Class -match 'SmartCard|USB' } |
  Select-Object FriendlyName, InstanceId
certutil -scinfo -silent     # shows the reader name and the card ATR

Then restart the smart-card stack and confirm the certificate reaches the Windows store:

Restart-Service SCardSvr -Force
Restart-Service CertPropSvc -Force

Get-ChildItem Cert:\CurrentUser\My | Select-Object Subject, Issuer, HasPrivateKey

Mark step 4 complete

5 Configure the service — General tab

Port, API token and the folders the watcher uses.

1. Leave Port at 9440 unless it clashes with something.
2. Click Generate next to API Token if you will use the REST API.
3. Confirm Upload Folder and Signed Folder.
4. Click Save Settings.

Mark step 5 complete

6 Create a PDF signing profile

Which certificate signs, where the signature lands, and which folders are watched.

1. SigningEngine tab → + under Profiles.
2. ID e.g. profile_pdf, Name anything readable, Type PDF Signing.
3. Source folder C:\OneSigner\unsigned, Signed folder C:\OneSigner\signed.
4. Certificate — pick your token certificate from the dropdown.
5. Token PIN — the token's PIN.
6. Position — Fixed position (page/X/Y), or Find by text to anchor the signature to a phrase, with Match page and Sign at.
7. Timestamp — your CA's TSA, e.g. http://timestamp.sectigo.com.
8. Tick LTV.
9. Save, then Save All, and tick Signing Engine → Enabled.

$cfg = 'C:\OneSigner\app\appsettings.json'
icacls $cfg /inheritance:r
icacls $cfg /grant 'SYSTEM:(R)' 'BUILTIN\Administrators:(F)'

Mark step 6 complete

7 Test sign, then verify properly

Do not trust a green tick in one application. Check the file itself.

1. On the right of the SigningEngine tab set Sample PDF and click Test Sign.
2. Open the signed file in Adobe Reader. The banner must read “Signed and all signatures are valid.”
3. Then confirm the structure independently:

$t = [Text.Encoding]::GetEncoding(28591).GetString([IO.File]::ReadAllBytes("signed.pdf"))
[regex]::Match($t,'/SubFilter\s*/([A-Za-z0-9\.]+)').Groups[1].Value   # ETSI.CAdES.detached
([regex]::Matches($t,'/DSS')).Count                                   # 1  -> LTV data present
([regex]::Matches($t,'/OCSPs')).Count                                 # 1  -> OCSP embedded

Mark step 7 complete

8 Sign automatically with a watched folder

The simplest production pattern: drop a file in, collect it signed.

Copy-Item .\invoice.pdf C:\OneSigner\unsigned\
Start-Sleep -Seconds 25
Get-ChildItem C:\OneSigner\signed

With the default 20-second poll the signed file appears in about ten seconds. The source file is consumed.

Mark step 8 complete

9 Sign from the web portal

For people, rather than for systems.

1. Open http://localhost:9440/portal and sign in.
2. Pick the signing profile, drag PDFs in, click Sign Documents.
3. Results appear under Signed files, and every operation is kept in Recent Signing History.
4. Sign myself adds hand-drawn visual signatures; Management → Logs is the audit trail.

Mark step 9 complete

10 Sign over the REST API

One call in, a signed PDF back.

curl -X POST "http://localhost:9440/api/upload?download=true" \
     -H "Authorization: Bearer <TENANT_TOKEN>" \
     -F "file=@contract.pdf" \
     -o contract-signed.pdf

Mark step 10 complete

11 Code signing and the command line

For installers, executables and CI/CD.

1. Create a second profile with Type = Code Signing and select the code-signing certificate.
2. Sign locally with OneSignTool.exe in C:\OneSigner\app\.
3. For remote or build-agent signing use the AKV Proxy profile and OneSignTool -kvu <server URL> -kva <partner code> -kvc <CertName>.

Mark step 11 complete

12 Publish a public HTTPS address

Needed for the portal, partner packages and remote signing. No open ports required.

1. Web Server tab → Download cloudflared (one-time, ~52 MB).
2. Sign in at onesign.sg/portal/login → My Licenses → Custom Domain.
3. Choose your subdomain and the local port (must match the port in step 5), then create it.
4. Copy the tunnel token back into Tunnel Token, tick Enable Cloudflare Tunnel, set Public URL, save, and restart the service.

Mark step 12 complete

13 Teams, tenants and branding

Separate who signs what, and make the portal look like yours.

1. Tenants tab → + Add for each business unit or customer: its own token and folders.
2. Link a signing profile to the tenant, or its uploads will be stored but never signed.
3. Give each person their own portal account at /portal/admin.
4. Portal → Settings → Branding sets the name, logo, colour, support email and email footer.

Mark step 13 complete

? Troubleshooting

✓ All done — what next?

• Restrict NTFS permissions on C:\OneSigner\app\appsettings.json — it carries the settings and credentials for every profile.
• Back up that file; it is your whole configuration.
• Set a calendar reminder for your certificate's expiry date.
• Confirm the admin token and the portal password are both values you chose yourself.

Questions: support@onesign.sg · Hotline +65 3107 1270