Setup guide

Set up OneSigner, step by step

From installer to your first signature: install the Windows service, activate your license, get your USB token recognised, create signing profiles and sign from a watched folder, the web portal or your CI/CD pipeline. Tick each step off as you go — your progress is remembered on this device.

Guide published · last reviewed by the One Sign engineering team.

1 Create your account and download OneSigner

Sign in to onesign.sg, collect your licence key and download the installer package.

  1. Go to /portal/download and sign in — register with an email address or use Sign in with Google. An account is required before the download becomes available.
  2. Download the OneSigner Service + GUI package. This single installer contains both the background signing service and the configuration app.
  3. Open My Licenses in the portal. A free 30-day trial key is issued to every new account — you can also request one at /portal/trial. Keep this page open; you will paste the key into the app in step 3.

Note: OneSigner signs PDF documents (PDF Signing) and software (Code Signing) using the certificate stored on your USB token. It can sign locally on the machine where it is installed, or remotely through the web portal and the command line.

2 Install OneSigner

Run the installer with administrator rights and install to the default folder.

  1. Find OneSigner-Setup.exe in your Downloads folder, right-click it and choose Run as administrator.
  2. If Windows shows the Windows protected your PC popup, click More info, then Run anyway. If the popup does not appear, skip this.
  3. In the setup window, keep the default install folder C:\OneSigner\app, then click Next and Install.
  4. Wait while the progress bar completes — do not click anything. Setup moves on by itself; click Next to continue.
  5. When setup reports that installation has finished, click Finish.
Windows Explorer context menu on OneSigner-Setup.exe with Run as administrator highlighted
Figure 2.1: Right-click the installer and choose Run as administrator.
Windows SmartScreen dialog reading Windows protected your PC with the More info link
Figure 2.2: If this window appears, click More info and then Run anyway to continue.
OneSigner setup wizard welcome page
Figure 2.2b: The OneSigner setup wizard opens.
Setup page showing the destination folder C:\OneSigner\app
Figure 2.3: Keep the default folder C:\OneSigner\app, then click Next and Install.
Setup progress bar during installation
Figure 2.4: Do not click anything — wait for the progress bar to finish.
Setup completion page with the Finish button
Figure 2.5: When setup reports completion, click Finish.

3 Activate your licence key

Paste the key from your portal account into the app to complete activation.

  1. Sign in to onesign.sg with the account you created and open My Licenses.
  2. Copy your licence key.
  3. Open the OneSigner app on your machine and go to the License tab.
  4. Paste the key into the License Key box and click Save License Settings.
My Licenses page in the OneSign portal showing the licence key to copy
Figure 3.1: Sign in to the portal and copy the key from My Licenses.
License tab of the OneSigner app with the key pasted into the License Key field
Figure 3.2: Paste the key into the License tab and click Save License Settings.

4 Install your USB token driver

Windows must recognise the USB token before OneSigner can use the certificate stored on it.

  1. Install the driver supplied by your token vendor on the same machine where OneSigner is installed.
  2. Plug the USB token in and confirm the vendor's own management app detects it.

Note: This guide covers SafeNet and YubiKey because those are the tokens we use. Other brands work the same way — install that vendor's driver instead. See the Knowledge Base if your device is not listed here.

SafeNet

  1. Download and install the SafeNet Authentication Client for Windows from your certificate provider.
  2. Plug the token in and open SafeNet Authentication Client to check that the device and its certificate are listed.
  3. In OneSigner, open the SigningEngine tab and click the refresh button on the Certificate row to pick up the token.
SafeNet Authentication Client window listing the connected token and its certificate
Figure 4.1: The SafeNet client has detected the USB token.
SigningEngine tab in OneSigner with the refresh button next to the Certificate field
Figure 4.2: On the SigningEngine tab, click the refresh button on the Certificate row to detect the USB token.

YubiKey

  1. Download and install YubiKey Manager and the YubiKey Smart Card minidriver that match your version of Windows.
  2. Plug the key in and open YubiKey Manager to confirm it is detected.
  3. Back in OneSigner, refresh the Certificate list and check that the YubiKey certificate appears.
YubiKey Manager showing the connected device and its serial number
Figure 4.3: YubiKey Manager has detected the USB token.
OneSigner Certificate field listing the certificate stored on the YubiKey
Figure 4.4: The Certificate field shows the correct YubiKey certificate.

5 Configure the service on the General tab

Set the port, API token and watched folders, then confirm the service is running.

  1. Open the OneSigner Service app and go to the General tab.
  2. Set Port to 9440.
  3. Click Generate next to API Token to create a token.
  4. Set Upload Folder to C:\OneSigner\unsigned.
  5. Set Signed Folder to C:\OneSigner\signed.
  6. Click Save Settings, then click Restart.
  7. Open a browser and go to localhost:9440. If the OneSigner sign-in page appears, the service is running correctly.
General tab of OneSigner showing port, API token and folder settings
Figure 5.1: Settings on the General tab.
Browser at localhost:9440 showing the OneSigner sign-in page
Figure 5.2: Check that OneSigner is running by opening localhost:9440.

Note: SigningEngine is where you create the profiles used for signing. OneSigner supports three profile types: PDF Signing for PDF documents, Code Signing for software (.exe, .dll, .msi, .cab, .sys and similar), and AKV Proxy for remote code signing over HTTPS with OneSignTool. Every time you create or edit a profile you must return to the General tab and click Restart to apply the change.

6 Create a PDF signing profile

Define which certificate signs your PDFs, where the signature is placed and which folders are watched.

  1. Go to the SigningEngine tab and click + under Profiles.
  2. Under Profile Info, set ID to profile_pdf, Name to PDF Signing, Tenant to Not linked and Type to PDF Signing.
  3. Set Source Folder to C:\OneSigner\unsigned and Signed Folder to C:\OneSigner\signed.
  4. Under Signature Config, choose the certificate in Certificate — with the USB token plugged in, the matching certificates are listed.
  5. Enter the token credentials in Token PIN / Token Password.
  6. Set Position — either a fixed signature position, or automatic placement after a chosen piece of text.
  7. Click Save to store the profile.
  8. Go to the General tab and click Restart to apply it.
SigningEngine tab with a PDF Signing profile filled in
Figure 6.1: A completed PDF Signing profile.
General tab with the Restart button highlighted
Figure 6.2: Go to the General tab and click Restart to apply the profile.

Note: The credential field is labelled either Token PIN or Token Password, depending on the token and certificate OneSigner detects. Enter whichever credential your token uses.

7 Create a code signing profile

Set up Authenticode signing for executables and installers using signtool and your token. New to EV code signing? Start with the requirements guide.

  1. Go to the SigningEngine tab and click + under Profiles.
  2. Under Profile Info, set ID to profile_codesign, Name to Code Signing, Tenant to Not linked and Type to Code Signing.
  3. Set Source Folder to C:\OneSigner\unsigned and Signed Folder to C:\OneSigner\signed.
  4. Under Code Signing (signtool), select the token certificate in Certificate and enter the Token PIN / Token Password.
  5. Set SignTool Path to C:\OneSigner\signtool.exe. If you do not have the tool yet, download it first and point the field at the downloaded file.
  6. Set Position — fixed or automatic.
  7. Set Timestamp URL to the timestamping service of the CA that issued your token certificate — check the Issued by field of the certificate.
  8. Click Save, then go to the General tab and click Restart.

Note: Timestamp URLs change from time to time. To be sure, search the CA's own site for "<CA name> signtool code sign timestamp URL". Common values (SHA-256 recommended): DigiCert http://timestamp.digicert.com; Sectigo / Comodo http://timestamp.sectigo.com; GlobalSign http://timestamp.globalsign.com/tsa/r6advanced1; SSL.com http://ts.ssl.com; Microsoft Trusted Signing http://timestamp.acs.microsoft.com.

SigningEngine tab with a Code Signing profile filled in, including the SignTool path and timestamp URL
Figure 7.1: A completed Code Signing profile.
General tab with the Restart button highlighted
Figure 7.2: Go to the General tab and click Restart to apply the profile.

Note: As with PDF profiles, the credential field is labelled Token PIN or Token Password depending on the token and certificate detected.

8 Set up the Azure Key Vault proxy profile (optional)

Add an AKV Proxy profile so build machines can code-sign remotely over HTTPS with OneSignTool.

  1. Go to the SigningEngine tab and click + under Profiles.
  2. Under Profile Info, set ID to profile_akvproxy, Name to AKV Proxy, Tenant to Not linked and Type to AKV Proxy.
  3. Set Source Folder to C:\OneSigner\unsigned and Signed Folder to C:\OneSigner\signed.
  4. Under Azure Key Vault Proxy, fill in Cert Name (-kvc). Any name works; using the certificate's CN keeps it recognisable. To find it, press Win + R, run certmgr.msc, locate the certificate of the token you have plugged in, open Details > Subject, then copy the CN value into the field.
  5. Select the token certificate in Certificate and enter the Token PIN / Token Password.
  6. Set Sign Method to auto.
  7. Set Timestamp URL to the timestamping service of the CA that issued your certificate.
  8. Click Save, then go to the General tab and click Restart.
Certificate details dialog in certmgr.msc showing the Subject field and its CN value
Figure 8.1: Cert Name (-kvc) can be anything; here the certificate's CN is used.
SigningEngine tab with an AKV Proxy profile filled in
Figure 8.2: A completed AKV Proxy profile.
General tab with the Restart button highlighted
Figure 8.3: Go to the General tab and click Restart to apply the profile.

Note: The credential field is labelled Token PIN or Token Password depending on the token and certificate detected.

9 Publish a public domain with the managed tunnel (optional)

Give your OneSigner machine a public HTTPS address so you can sign from anywhere.

  1. Sign in to the OneSign website, open My Licenses and click Custom domain.
  2. Create the public domain you want and set the port. Once it is created, copy the URL and the Tunnel token.
  3. In the OneSigner app on your machine, open the Custom Domain tab. Tick Enable Custom Domain and download Cloudflare when prompted.
  4. Paste the URL and the tunnel token into their fields, then click Save Tunnel Setting.
  5. Go to the General tab and click Restart to finish.
  6. Open the new public domain in a browser. If the OneSigner sign-in page loads, the tunnel is working.
Custom domain page in the OneSign portal with the domain and port creation form
Figure 9.1: Create the public domain in the portal.
Portal showing the generated tunnel URL and tunnel token ready to copy
Figure 9.2: Copy the URL and the Tunnel token.
Custom Domain tab in OneSigner with the URL and tunnel token pasted in
Figure 9.3: Paste the URL and tunnel token into the app, then click Save Tunnel Setting.
General tab with the Restart button highlighted
Figure 9.4: Go to the General tab and click Restart to apply the tunnel settings.

10 Test PDF signing locally with the watched folder

Fine-tune the signature position with a test sign, then sign for real by dropping files into the watched folder.

Note: Local signing needs either Ghostscript or BulkSigner installed on the machine — one of the two is enough. Without either, signing fails with the error shown below.

Error message shown when neither Ghostscript nor BulkSigner is installed
Figure 10.1: The error you see when neither Ghostscript nor BulkSigner is installed.

Check the signature position with a test sign

  1. Go to the SigningEngine tab, select profile-pdf under Profiles, then click the … button to add the PDF you want to test with.
  2. Under Signature Config, adjust Position and Page — the X and Y coordinates decide where the signature lands. Then go to General and click Restart to apply the change.
  3. Click Test Sign.
  4. Open the test-signed folder — it sits alongside your test PDF — and open the signed sample.
  5. Repeat the previous three steps, adjusting the position each time, until the signature sits exactly where you want it.
SigningEngine tab with a test PDF loaded and the position and page coordinates being adjusted
Figure 10.2: Add a test PDF and adjust the signature position.
test-signed folder in Explorer containing the signed sample PDF
Figure 10.3: Open the sample in the test-signed folder and check the signature position; repeat until it is right.

Sign for real

  1. Open the OneSigner app and check on the General tab that Status reads Running. If it is not running, click Start.
  2. Copy the files you want to sign into C:\OneSigner\unsigned. Files are signed automatically as soon as they land in the folder.
  3. Wait a moment, then open C:\OneSigner\signed. Signed files move from unsigned to signed — open one and confirm the signature is present.
General tab showing Status Running
Figure 10.4: On the General tab, make sure Status is Running.
Explorer window showing a file being pasted into C:\OneSigner\unsigned
Figure 10.5: Copy the file you want to sign into C:\OneSigner\unsigned.
Explorer window showing the signed file in C:\OneSigner\signed
Figure 10.6: Once signed, the file moves from unsigned to signed — open it to confirm the signature.

11 Sign remotely from the web portal

Upload documents from any machine and sign them with the token plugged into your OneSigner host.

  1. On the machine with the USB token, open OneSigner and check on the General tab that Status is Running. If not, click Start.
  2. From another machine, open a browser and go to your public domain — for example https://tunnel.onesigner.com.
  3. Sign in. The default username and password are both admin.
  4. Click the Sign Documents menu.
  5. Choose the profile to use in Signing profile — PDF signing or code signing.
  6. Click Choose files and upload one or more files.
  7. Enter the USB token PIN in Signing Pin.
  8. Click Sign Documents. Each file reports Success, or Error with the reason if it fails.
  9. Open Signed files to download the signed documents.

Note: Change the default password the first time you sign in — either in the portal, or in the OneSigner app on the License tab under Portal Admin, by entering a new password and clicking Reset Admin Password.

Note: An admin can create accounts for colleagues under Management so they can sign online too. Each user signs with the signing PIN they were given.

OneSigner portal sign-in page opened at the public tunnel domain
Figure 11.1: Open the public domain in a browser and sign in.
Sign Documents page with a profile selected, files uploaded and the signing PIN entered
Figure 11.2: In Sign Documents, pick a profile, upload the files, enter the token PIN and click Sign Documents.
Signed files page listing successfully signed documents with download links
Figure 11.3: After signing, download the results from Signed files.
Downloaded PDF opened in a viewer showing the applied digital signature
Figure 11.4: The downloaded PDF carries the signature.

Sign myself — hand-drawn signatures with Visual Signing

  1. Open the Sign myself menu and follow the setup instructions numbered 1 to 5 on that page.
  2. In Visual Signing, add the PDF you want to sign.
  3. Open the Draw tab and draw your signature in the white area below it.
  4. Click Place signature on PDF to preview where the signature will sit.
  5. Click Sign & Download to sign the file and save it.
Sign myself page in the portal showing the numbered setup instructions
Figure 11.5: To sign by hand, open Sign myself and follow setup steps 1 to 5.
Visual Signing view with the Draw tab open and a signature drawn on the canvas
Figure 11.6: In Visual Signing, draw on the Draw tab, click Place signature on PDF to preview, then Sign & Download.
Downloaded PDF showing the hand-drawn signature in place
Figure 11.7: The downloaded PDF contains the signature.

Note: The screenshots above use Firefox. If you sign by hand in Chrome, you must enable Apps on device for the site.

Chrome site settings with the Apps on device permission enabled
Figure 11.8: Hand signing in Chrome requires Apps on device to be enabled.

12 Sign from the command line

Code-sign directly on the OneSigner machine, or remotely from a build machine using a generated AKV package.

Option 1 — sign directly with the CLI

  1. Open Command Prompt as administrator.
  2. Run the command in this form:
"C:\OneSigner\app\OneSignerService.exe" --codesign /sha1 <Thumbprint> /pin <Token-Password> /fd sha256 /tr <Timestamp URL> /td sha256 "path to the file you want to sign"
  1. Press Enter and wait for the result.

Note: OneSigner can build this command for you — open the app and copy the suggested CLI command, which already contains your certificate thumbprint and timestamp URL.

OneSigner app showing the suggested CLI command ready to copy
Figure 12.1: Copy the suggested CLI command from OneSigner.
Command prompt output showing a successful code signing run
Figure 12.2: A successful direct signing run from the CLI.

Option 2 — sign remotely with an AKV package

  1. On the OneSigner machine, go to the SigningEngine tab, type a name under Partner codes and click + Create.
  2. Click the entry you just created, then click Build .zip to download the package.
  3. Extract the package on the machine that will sign, and copy the file you want to sign into the extracted folder.
  4. Open Command Prompt as administrator, cd into the extracted folder and run sign.cmd with the path of the file to sign. For example:
cd C:\Users\Si\Desktop\OneSignTool-test
sign.cmd 7z2602-x64.exe
SigningEngine tab showing a partner code entry and the Build .zip button
Figure 12.3: Create the partner code and build the AKV package.
Extracted AKV package folder containing sign.cmd and the file to be signed
Figure 12.4: The extracted package, with the file to sign copied in.
Command prompt output showing a successful remote signing run via the AKV package
Figure 12.5: Remote signing completed successfully via the AKV package.

13 Give your team accounts and anchor the signature to text

Place the signature below a chosen piece of text and let colleagues sign with their own portal accounts.

  1. In the OneSigner app, open the signing profile and set the signature to be placed below the text you enter.
  2. Click Save, then go to the General tab and click Restart to apply the change.
  3. In the portal, create accounts for your colleagues under Management and give each of them a signing PIN.
  4. Ask them to sign in to the portal and sign a document from Sign Documents. The signature lands under the text you anchored it to.
Signing profile configured to place the signature below a specified text string
Figure 13.1: Set the signature to be placed below the text entered, then click Save and Restart.
Portal showing a successful signing run performed by a user account created by the admin
Figure 13.2: A document signed successfully by a user account created by the admin.

Note: What a token can sign depends on the certificate it holds — a YubiKey provisioned for document signing only will sign PDFs, not code. See the Knowledge Base if you are unsure which certificate you have.

All done — what next?

Your tokens now sign for everyone: browse the Knowledge Base for the REST API reference, multi-tenant setup and troubleshooting, or buy a license when your trial ends. Stuck on a step? Talk to us — we answer setup questions directly.