Introduction

V-Key Smart Authenticator (VSA): MFA for Windows Logon improves security and streamlines user authentication by leveraging multi-factor authentication (MFA) and advanced mobile-based authentication methods. It provides secure, seamless login experience across various Windows platforms and Windows Server environments using V-Key Smart Authenticator(VSA) App. It integrates push notifications and One-Time Password (OTP) authentication powered by the VSA authenticator.

Purpose

This document's purpose is to describe the features of the V-Key Smart Authenticator: MFA for Windows Logon and provide detailed instructions for installing it on your Windows machine.

Audience

This document is primarily intended for the Windows users who want to integrate V-Key Smart Authenticator: MFA for Windows Logon into their machines.

Objectives

The main objective of the V-Key Smart Authenticator MFA for Windows Logon is to integrate a PKI-based authentication system with secure push notifications and One-Time Password (OTP) verification, powered by the V-Key Smart Authenticator. This approach aims to enhance security within the Windows environment of the organization without sacrificing usability.

Specific Objectives:

• PKI Integration with Push Notifications: Implement PKI-based authentication that leverages secure push notifications through the V-Key Smart Authenticator to allow users to approve or deny logon requests on their mobile devices, ensuring certificate-backed authentication and added convenience.

• OTP Logon: Provide One-Time Password (OTP) functionality via the V-Key Smart Authenticator to offer an additional secure login method, complementing the PKI-based approach.

• Integration with Enterprise Infrastructure: Ensure seamless integration with Active Directory and other enterprise identity management systems to support domain-based authentication across the organization.

Features

This section outlines the features offered by V-Key Smart Authenticator: MFA for Windows Logon.

1. User Type Detection: While using the Windows Logon, the system distinguishes between domain and non-domain users to tailor the authentication process.

Domain Users: For domain-joined machines, authentication will integrate with Active Directory (AD) using PKI. OTP will be available as a fallback for users who face issues with certificate-based authentication.

Non-Domain Users (Workgroup): For workgroup machines or local users, the logon process will rely on local account validation. PKI and OTP authentication will still be supported, even in the absence of Active Directory.

2. Remote Desktop Protocol (RDP) Support

The custom logon solution must support Remote Desktop Protocol (RDP), particularly for Windows Servers, where remote access is frequently required:

RDP for Windows Servers: The credential provider will support both PKI and OTP-based authentication during RDP sessions. Users connecting remotely will authenticate using the V-Key Smart Authenticator, ensuring secure access to Windows Server environments.Multi-factor authentication (MFA) via PKI and OTP will be enforced for all RDP logon sessions, enhancing remote access security.

3. Authentication Methods

The logon solution will leverage two primary authentication methods:

PKI (Primary): The main authentication method will be Public Key Infrastructure (PKI). Users will authenticate with digital certificates stored in the V-Key Smart Authenticator, ensuring a secure, certificate-backed logon.

OTP (Fallback): In cases where PKI-based authentication is not available or fails, users will log in using a time-based One-Time Password (OTP) generated by the V-Key Smart Authenticator. This provides a secure, alternative authentication method.

4. Backup Options via V-Key Smart Authenticator

To ensure continuous access in case of issues with the primary authentication method, the V-Key Smart Authenticator app itself provides a backup:

V-Key Smart Authenticator Backup: Users will be able to generate backup One-Time Passwords (OTPs) directly via the V-Key Smart Authenticator app if the primary PKI authentication method fails or cannot be used. This ensures that even without additional hardware tokens or devices, users will have a secure backup method available.

5. Offline Access (No Internet Access)

During unavailability of internet access (e.g., network outages or remote environments), push notifications will not function, as they require server communication. In these cases, OTP authentication via the V-Key Smart Authenticator will ensure users can still log in securely.

Offline Logon via OTP: When the system detects no internet access, the credential provider will automatically switch to OTP-based authentication. Users will generate a time-based OTP from the V-Key Smart Authenticator and manually enter it into the logon screen. The OTP will be validated locally, allowing users to log in without needing an internet connection.

Scenarios for Offline Access: Offline logon is critical for environments with restricted network access, such as secure facilities or maintainance operations, or during network outages. By using OTP for offline access, users maintain secure access without requiring an active internet connection.

Supported Platforms

The V-Key Windows logon customization is designed to be compatible with the following operating system platforms.

1. Operating Systems

• Windows 10 (Pro)
• Windows Server 2016

2. Processor Architectures

• x64 (64-bit) architecture for all supported platforms

3. Virtual Environments

• VMware Workstation/ESXi
• Azure Virtual Machines (Windows)

4. Dependencies

• Microsoft .NET Framework 4.8 or higher
• V-Key Smart Authenticator client (latest version)
• Windows SDK
• Active Directory Integration (optional)

Configurations on IDM portal

Identity Management (IDM) portal needs to be configured to set up VSA: MFA for Windows Logon. Before that, following prerequisites need to be carried out.

Prerequisites

1. Log in to the IDM Portal with the admin account.
2. Setup a Directory & its Users. Refer Directory Configuration from Appendix section for the guidance.
3. Configure Token Packs. Refer Taken Pack Configuration from Appendix section on how to configure token packs.

Steps to Configure

Follow below steps to set up Windows Logon on IDM Portal.

Step 1: Create an HTTPS Connector

• Navigate to Connector → HTTPS → Select to create HTTPS connector.

• Assign suitable name for HTTPS Connector and Save it.

Step 2: Create HTTPS Service & Assign to the Token Pack

• Navigate to Services → Create → Select Windows Logon Authentication under HTTPS
• Select the Subscription containing the Token Pack that you have configured as prerequisites.
• Select the Token Pack
• Input suitable name for the Windows Logon Service
• Select the Directory with the users that you have configured as a prerequisite
• Select the HTTPS Connector created in Step 1
• Save the HTTPS Windows Logon Service

After creating WinLogon service successfully, select to generate OTP secret for the users

Step 3: Service Verification

• Verify that the Windows Logon (WinLogon) service is created & assigned to the Token Pack successfully

• Navigate to Token Packs → Select to edit the Token Pack used by WinLogon service → Scroll to check the created WinLogon service in the list. Verify that the service is running.

Step 4: Directory Verification

• Verify the directory which was setup for Token Pack
• From the edit Token Pack page, observe the Primary Directory → Check the corresponding directory which is used to enable Win Logon service

Step 5: Activate user with VSA

• Install (V-Key Smart Authenticator) VSA app on mobile device
• On VSA app, activate the user from the Token Pack using Token Pack QR Code or Activation Code
• This successfully completes WinLogon service configuration on IDM Portal and VSA App.

Set up Windows Agent

After configuring the IDM Portal, your Windows machine needs to be set up with V-Key Smart Authenticator (VSA): MFA for Windows Logon (Windows Agent).

Note: To ensure the new installer functions correctly, please follow the steps below to remove specific existing components. Failure to do so may result in the installer not working as expected:

Uninstall the following:

• V-Key Credential Provider
• V-Key Agent Bundle Package

Uninstall the existing versions of the following:

• Windows SDK AddOn
• Windows Software Development Kit
• Visual Studio Build Tools

Note: Please manually uninstall the previous version if applicable. Starting from Windows Agent 1.0.3, the installer should be able to update the Windows Logon Agent to the new version without requiring users to uninstall and reinstall all dependency components.

1. Open IDM Portal and created WinLogon connector. Copy the Client ID & API Key from this page.

2. Run VSA Windows Logon installer with the Administrator permission.

3. Agree to the Term of use & Privacy policy and click Install.

4. Let the setup progress & download necessary components if needed (Visual Studio Build Tools & Windows Development Kits)

5. Now set up V-Key Credential Provider.

• Paste the Client ID and API Key (copied from step 1) from IDM portal (HTTPS connector details session)
• Check or uncheck the Remember Windows User Password option. If checked, only the first time login with push authentication requires to input password. If unchecked, every time login with push authentication requires to input password.

6. Once the installation is finished, log out of the account and check to see if the V-Key WinLogon service appears.

7. Following two batch scripts are distributed with release package to enable or disable default Windows Logon.

• enable_default_login.bat: Batch script to enable the default sign-on option and keep the V-Key sign-on option. This works as a troubleshooting and fallback mechanism in case push not working as expected.
• disable_default_login.bat: Batch script to disable the default window logon and keep the V-Key sign-on option . After troubleshooting, the customer can run this script in order to enforce user with MFA.

Authenticate Login Requests

1. Once V-Key Logon Service appears on the login screen, select push authentication option, then click Send push notification to V-Key app.

On VSA app with activated user, you will see the push authentication request.

After login request on VSA, if first time login gets successful, there will be a prompt message for offline OTP generated.

2. From login screen on Windows, select OTP login from Sign-in options.

Get the OTP from VSA & input into OTP field on Windows login.

After inserting valid OTP in the time window, the login should be successful without any issue.

Uninstall Windows Agent

Open app manager from system & select to completely uninstall below two apps.

• V-Key Agent Bundle Package Install
• V-Key Credential Provider

After that check, the V-Key Windows Logon option is not shown for login anymore.

Error Codes

Category	Error Code	Description
General Errors	1001	Invalid request format
	1002	Internal server error
	1003	Configuration error
Push Authentication Errors	2003	User rejected authentication request
	2004	Timeout waiting for user response
OTP Verification Errors	3000	Invalid OTP format
	3001	Incorrect OTP entered
	3002	OTP attempts limit exceeded
User Management Errors	4000	User not found
Network & Connectivity Errors	5001	Unable to connect to authentication server
	5002	SSL/TLS handshake failure

Appendix

Directory Configuration

1. Log in to the IDM Portal with the admin account
Navigate to Directories page & select Create



Select directory type as V-Key AD



2. Input suitable name for directory & Click Save. Save the Directory successfully.
3. Select to edit created directory to create users under the directory. You may create users manually or import through a .csv file.
Select Add User for manual entry of users.



4. Input all required fields and save User successfully.
5. Check the mailbox of created user to make sure that new account receives an email from V-OS Cloud.
At V-Key AD directory page, select to test configuration. Input login credentials of created account & test.



6. You may also import users from csv file for batch upload. Click Import CSV button.
Download ‘Import-Template.csv' file



Fill the users’s information into the csv file



7. Upload csv file then import it
8. Check the users are imported with user source as CSV Import
9. You may import batch users using Azure AD. For that you should have Azure AD admin account and required setup for Azure AD
10. Click on the Import Azure button
11. Then continue by clicking on the Authorize button.
Submit Azure admin credential to login



After successful authorization, users are selected to migrate. Select the users then click ‘Import’ button and observe the process complete.



12. After import, check the imported users with the User Source as Azure AD.

Note: You may use other Directory types from the option to set up Directory such as Local AD or Open AD.

Token Pack Configuration

The token pack is a unique profile used by V-OS Cloud IDM to identify organizations and environments that V-OS Cloud connecting to. It is based on the connectors and services you configured through V-OS Cloud Dashboard.

The token pack is presented in a form of a QR code and keeps information like ID, name, logo, theme, and configuration information that help the V-Key app identifies the organization that the app users belong to while onboarding to V-OS Cloud services. This code is generated from V-OS Cloud Dashboard and sent to app users for service onboarding. This code is necessary for app users to activate accounts. To use the QR code, app users use the V-Key Smart Authenticator (VSA) app (available in app stores) to scan this code to activate his/her account.

To create and configure a token pack, do the following steps:

1. Log in to the V-OS Cloud Dashboard with an admin account.
2. Click Token Packs on the left sidebar.

3. Click the "pencil" icon of the pre-generated token pack from the list.

   

4. Assign a Name to the token pack for easy identification, e.g., Service Token Pack. This can be any name.

   

5. Click the icon field and assign an icon to the token pack, if desired.

6. Select the Primary Directory and Theme to be assigned to the token pack from the respective dropdown.

   Note: The Primary Directory is the directory used for authenticating users of the V-Key app. It can be the same or different directory configured in the service instance. The Theme is the theme that you wish to apply to your V-Key app when this token pack is used. You can configure different themes for different token packs.

7. Pick the desired Service that you want to enable in the token pack.

   Note: A token pack can contain the services for multiple services. If you are intending to have multiple services under the same token pack, select the service accordingly by toggling the "power plug" icon.

8. Click Save to create the token pack.

Frequently Asked Questions (FAQs)

How to troubleshoot if OTP flow for Windows Logon fails?

1. If the OTP Seeds are not provisioned, OTP login fails. Please check that OTP seeds are generated under Services in IDM Dashboard.

2. If the Windows logon with OTP flow fails due to OTP mismatch, please check if there are any duplicate accounts in the Windows Logon Services(IDM Dashboard). If duplicate account exists, please cleanup account and delete all:

• Select the created WinLogon service
• Select all existing accounts with OTP secrets & delete all
• Generate all OTP secrets again

3. The OTP auto provisioning is only applicable for new active PKI account. If old VSA version already has an OTP secret on IDM, then upgrade to new VSA version,.

4. If the OTP option still won't show, need to provision OTP account manually.

Note: For queries related to using IDM portal, please check below link.

https://cloud.v-key.com/docs/intro/faq