Product Documentation

This document is an installation guide for the OpenOTP Authentication Package and its Sub-Authentication package (Sub-AP) for Windows. Hence, the installation or configuration of WebADM/OpenOTP, including token registration is not covered in this guide.
For this recipe, you will need to have WebADM/OpenOTP installed and configured. Please, refer to WebADM Installation and Administration guides to do it.

Please read this documentation carefully before installing the Authentication Package on any machines or domain controllers. A poor understanding of the concepts and implications could prevent you from being able to log in to your systems.

Products Overview

RCDevs provides its own Authentication Package (AP) and Sub-Authentication Package (Sub-AP) to manage diverse authentication scenarios in conjunction with the OpenOTP server.
Communications with OpenOTP AP is done through the OpenOTP-CPs provided in the same package.
Communications with OpenOTP Sub-APs installed on Domain controllers can be called by any AP installed on the DCs.
e.g: If the OpenOTP AP and OpenOTP Sub-AP for Kerberos is installed on the DC, the Microsoft AP will be able to call the OpenOTP Sub-AP for specific logon senarios.

Let's have first an overview about AP and Sub-AP components in the next section.

Authentication Package (AP)

Windows authentication packages provide authentication services by implementing package-specific functionality for the LsaLogonUser and LsaCallAuthenticationPackage functions provided by the LSA.

MSV1_0 is an example of a Windows authentication package. The MSV1_0 package accepts a user name and a hashed password, which it looks up in the Security Accounts Manager (SAM) database. Depending on the results of the lookup, the MSV1_0 authentication package accepts or rejects the authentication attempt.

For a list of the support functions the LSA provides for use by Windows authentication packages that require system services, see LSA Functions Called by Authentication Packages.

Windows authentication packages must implement a set of functions that are called by the LSA. For the complete list of functions, see Functions Implemented by Authentication Packages.

There are several authentication packages available in Windows, each serving a specific purpose or supporting different authentication mechanisms. Some of the commonly known authentication packages in Windows include:

  • MSV1_0 AP: Microsoft provides the MSV1_0 authentication package for local machine logons that do not require custom authentication. The Local Security Authority (LSA) calls the MSV1_0 authentication package to process logon data collected by the GINA for the Winlogon logon process. The MSV1_0 package checks the local security accounts manager (SAM) database to determine whether the logon data belongs to a valid security principal and then returns the result of the logon attempt to the LSA.

MSV1_0 also supports domain logons. MSV1_0 processes domain logons using pass-through authentication, as illustrated in the following diagram.

ap

In pass-through authentication, the local instance of MSV1_0 uses the Netlogon service to call the instance of MSV1_0 running on the domain controller. The domain controller's instance of MSV1_0 then checks the SAM database of the domain controller and returns the logon result to the instance of MSV1_0 on the local machine. The local version of MSV1_0 forwards the logon result to the instance of the LSA on the local machine.

If the domain controller is not available, and the LSA contains cached credentials for the user, the local instance of MSV1_0 can authenticate the user using the cached logon data.

The MSV1_0 authentication package also supports subauthentication packages. A subauthentication package is a DLL that can replace part of the authentication and validation criteria used by the MSV1_0 authentication package.

The MSV1_0 authentication package defines a primary credentials key/string value pair. The primary credentials string holds the credentials derived from the data provided at logon time. It includes the user name and both case-sensitive and case-insensitive forms of the user's password.

  • Kerberos SSP/AP: The Kerberos authentication package is used when logging on to a network; local logons are handled by MSV1_0.

When a user logs on using a network account, by default, Kerberos attempts to connect to the Kerberos Key Distribution Center (KDC) on the domain controller and obtain a ticket granting ticket (TGT) by using the logon data supplied by the user.

If a Kerberos KDC is not available, Windows uses MSV1_0 and pass-through authentication as described in MSV1_0 Authentication Package.

The Kerberos authentication package supports version 5, revision 6 of the Kerberos protocol. This protocol is based on Internet RFC 4120. For more information, see the IETF website.

For more information about Kerberos, see Microsoft Kerberos.

These authentication packages play crucial roles in ensuring secure access to resources within the Windows environment, and the choice of package depends on factors such as security requirements, compatibility, and configuration.

source: Microsoft

Sub-Authentication Packages (Sub-AP)

Sub-Authentication Packages (Sub-APs) are components within the Windows authentication architecture that work alongside primary authentication packages to provide additional functionality or support for specialized authentication mechanisms. Sub-APs extend the capabilities of primary authentication packages, allowing for more diverse authentication scenarios.

While primary authentication packages like NTLM and Kerberos handle the core authentication process, sub-authentication packages can augment this process by adding features such as multi-factor authentication (MFA), smart card authentication, or support for third-party authentication methods.

Here are a few examples of sub-authentication packages in the Windows environment:

  • Smart Card Subsystem: This sub-authentication package enables authentication using smart cards, which provide an additional layer of security by requiring users to present a physical card along with a PIN for authentication.

  • Microsoft Passport: Introduced in Windows 10, Microsoft Passport is a sub-authentication package that allows users to authenticate to Windows and certain web services using biometric authentication (such as fingerprint or facial recognition) or a PIN.

  • Third-party Authentication Providers: Windows allows third-party developers to create custom sub-authentication packages to integrate with specialized authentication mechanisms or external identity providers. These providers can include various forms of authentication, such as OAuth, SAML, or proprietary authentication protocols.

Sub-Authentication Packages enhance the flexibility and security of the Windows authentication system by accommodating diverse authentication methods and requirements. They enable organizations to implement robust authentication solutions tailored to their specific needs, including compliance requirements and security best practices.

RCDevs is providing two Sub-Authentication packages part of the MSI installer:

  • MSV1: Add OpenOTP subauthentication to the builtin Microsoft MSV1 authentication package. MSV1 (which is implementing the NTLM protocol) is mostly used for local accounts,
    but can sometimes also be used for domain accounts as a fallback. If you enable this option, an OpenOTP authentication must be performed before
    the MSV1 authentication, or the login will fail. After a successful OpenOTP authentication, any subsequent MSV1 authentication from and for the same user will succeed for the set amount of time configured in Subauthentication grace period setting. You can trigger an OpenOTP authentication by using the OpenOTP Credential Provider, by using the 'Run as' option with any program.

  • Kerberos:
    Add OpenOTP subauthentication to the builtin Microsoft Kerberos authentication package.
    Kerberos is used for domain accounts only, and this option should be enabled on
    the domain controller (it will have no effect on workstations). If you enable this option, an OpenOTP authentication must be performed before the Kerberos authentication, or the login will fail.
    After a successful OpenOTP authentication, any subsequent Kerberos authentication from the same workstation and for the same user will succeed for the set amount of time configured in Subauthentication grace period setting.
    If the workstation cannot reach the DC, no subauthentication will be triggered.
    You can trigger an OpenOTP authentication by using the OpenOTP Credential Provider, by using the 'Run as' option with any program.

If you are using this feature, it is STRONGLY recommended you whitelist some administrative accounts or group as a failsafe prior to some extensive testing in your environment, in the case something goes wrong. Failure to do so could lock you out of your computer or domain controller.

Components part of the MSI

The MSI provided by RCDevs for the OpenOTP Authentication Package product comes with multiple components:

  • Core components (AP): This is the Authentication Package component, which is mandatory in every deployment scenario. That component will be called Remote AP when installed on the domain controllers and local AP when installed on client machines.
  • Password Credential Provider (Password-CP): The Password Credential Provider is the graphical interface prompting users for passwords and second factors (OTP or FIDO).
  • FIDO Credential Provider (FIDO-CP): The FIDO Credential Provider is the passwordless graphical interface prompting users for FIDO authentication. (For local accounts only).
  • OTP Credential Provider (OTP-CP): The OTP Credential Provider is the passwordless graphical interface prompting users for OTP authentication. (For local accounts only).
  • Smartcard Credential Provider (Smartcard-CP): The Smartcard Credential Provider is an extension of the base Microsoft Smartcard Credential Provider, offering support for additional second-factor validations such as OTP and FIDO through integration with the OpenOTP Server. To utilize the OpenOTP Smartcard CP, the necessary configuration for smartcard authentication must be completed within your Windows environment to ensure compatibility with both OpenOTP and Windows. Additionally, it's essential that the certificate on the smartcard is issued by WebADM PKI. WebADM PKI, functioning as a Certificate Authority service, can be set up as a Subordinate Certificate Authority of your Root/Enterprise CA.
  • Credential Provider Filter (CP-Filter): The Credential Provider Filter allows you to enforce OpenOTP CPs as default CPs. Multiple CPs can cohabit on the same machine. For that, you need to configure a whitelist of allowed CPs during installation.
  • MSV1 Sub-Authentication package: Sub-Authentication package handling authentication based on NTLM protocol.
  • Kerberos Sub-Authentication package: Sub-Authentication package handling authentication based on Kerberos.

Deployment scenarios

Active Directory Domain Authentication

In an Active Directory domain scenario, there are a few important things to consider:

  • Only the Password Credential Provider and SmartCard Credential Provider are allowed;
  • The Authentication Package is deployed on Domain Controlers and on all machines who needs to be protected by OpenOTP;
  • In case you are planning to deploy the OpenOTP Sub-Authentication Packages (Kerberos and/or MSV1 for NTLM authentications), in domain scenarios the Sub-Authentication Packages are only deployed on Domain Controlers;
  • The LDAP password is sent to OpenOTP only if the Remote LDAP password check setting is enabled.

AP and Password Credential Provider

Below is a flow overview of the OpenOTP Authentication Package in domain authentication scenario:

ap
  • 1: The OpenOTP Password Credential Provider retrieves username and password information provided by the end-user and forwards it to the locally installed OpenOTP Authentication Package (local AP).
  • 2: The local AP forwards the credentials to the remote AP available on the domain controllers. If the domain controllers cannot be reached, then the local AP directly handles the authentication with OpenOTP, bypassing the remote AP on DCs and using cached credentials for Windows processes.
  • 3: If the AP on the DC is reachable by the client, then the remote AP forwards the request to OpenOTP server(s).
  • 4: OpenOTP manages the authentication request according to the client policy defined for the client AP (AP installed on the Server/Workstation). For example, if the policy is configured for FIDO/OTP authentication, then a FIDO/OTP challenge is forwarded to the local AP, and the user must successfully reply to that challenge. Once the authentication is successfully handled with OpenOTP, we move forward to the next step.
  • 5: At this step, the remote AP on the DC informs the local AP installed on the server/workstation about the authentication result returned by the OpenOTP server.
  • 6: The local AP informs its local Password Credential Provider about the authentication result.
  • 7: The OpenOTP Password Credential Provider then reaches the Microsoft Authentication Package for final validation.

AP, Sub-AP Kerberos/MSV1 and Password Credential Provider

Below is an overview of the flow of the OpenOTP Authentication Package with Sub-AP for Kerberos (or MSV1 for NTLM authentications) in a domain authentication scenario:

ap
  • 1: The OpenOTP Password Credential Provider retrieves username and password information provided by the end-user and forwards it to the locally installed OpenOTP Authentication Package (local AP).
  • 2: The local AP forwards the credentials to the remote AP available on the domain controllers. If the domain controllers cannot be reached, then the local AP directly handles the authentication with OpenOTP, bypassing the remote AP on DCs and using cached credentials for Windows processes.
  • 3: If the AP on the DC is reachable by the client, then the remote AP (on DC) forwards the request to OpenOTP server(s).
  • 4: OpenOTP manages the authentication request according to the client policy defined for the client AP (AP installed on the Server/Workstation). For example, if the policy is configured for FIDO/OTP authentication, then a FIDO/OTP challenge is forwarded to the local AP, and the user must successfully reply to that challenge. Once the authentication is successfully handled with OpenOTP, we move forward to the next step.
  • 5: At this step, the remote AP on the DC informs the local AP installed on the client server/workstation about the authentication result returned by the OpenOTP server.
  • 6: The local AP informs its local Password Credential Provider about the authentication result.
  • 7: The OpenOTP Password Credential Provider then reaches the Microsoft Authentication Package for final validation.
  • 8: During this step, any other authentications utilizing the Microsoft Authentication Package within the configured SubAuthentication grace period will be routed through the OpenOTP Sub-AP. The OpenOTP Sub-AP verifies the authentication state stored in memory by the OpenOTP-AP. If the state is valid (within the configured grace period), the Sub-AP successfully responds to all subsidiary calling applications. However, if the state is expired, two possible scenarios arise:
    • If a Subauthentication Client ID is configured during installation, a new OpenOTP call is initiated by the Sub-AP component. It's important to note that the Sub-AP does not provide any user interface during this process, as it does not pass through the OpenOTP Password Credential Provider. Consequently, to successfully respond to this authentication request, only the Simple Push login method can be utilized by the end-user. Please ensure the SubAuthentication Client Policy is configured accordingly. If an authentication challenge is sent by the OpenOTP backend, the authentication will result in an error.
    • If Subauthentication client ID is NOT configured during the installation, the authentication will simply fail. In such a case, you will need to redo the authentication involving the OpenOTP Password Credential Provider by right-clicking on the desired program and selecting the "Run As" option.

In relation to the OpenOTP Sub-Authentication package and authentication requests originating from Domain Controllers, it's crucial to understand that the OpenOTP Sub-AP does not forward these requests to OpenOTP. Instead, it promptly responds with an access-accept. This behavior is due to a technical limitation within the Sub-AP design. Enforcing authentication from the Domain Controller would otherwise result in an infinite authentication loop.

Important information regarding OpenOTP Kerbero Sub-AP
If the OpenOTP Sub-AP Kerberos is installed on Domain Controllers, all authentications originating from domain computers will trigger an OpenOTP login, even if these computers do not have the OpenOTP AP and CP installed!! Be careful in deployment scenarios.

Local account authentication

In local account authentication scenarios, there are a few important things to consider:

  • The users reference needs to exist on WebADM/OpenOTP side. RCDevs slapd can be used to store these identities.
  • There are two ways to validate and manage account passwords:
    • If the password remains within the Windows scope, you must disable the Remote LDAP Password Check setting during installation. The the password will never be sent to OpenOTP and the setting -LDAP will be sent to OpenOTP API.
    • If the password is managed by WebADM/OpenOTP, you need to enable the Remote LDAP Password Check setting during installation. In this scenario, the local account password is overridden by the LDAP password value validated by OpenOTP during the login process. This ensures that the password is maintained at the WebADM/OpenOTP level. The Client Policies must configured accordingly.
  • All Credential Providers are allowed except the SmartCard-CP, which means Passwordless is only usable with local accounts scenarios.
  • The Authentication Package should be deployed on all machines that need protection by OpenOTP;
  • If you plan to deploy the OpenOTP Sub-Authentication Package (MSV1 for NTLM authentications only, as Kerberos remains for Domain authentication), the Sub-AP MSV1 can be deployed on any machines where it's needed.

AP and Credential Providers (Password, OTP & FIDO)

Below is an overview of the flow of the OpenOTP Authentication Package in local authentication scenario:

ap
  • 1: The OpenOTP Password Credential Provider retrieves username and Password/OTP/FIDO information (according the CP used) provided by the end-user and forwards it to the locally installed OpenOTP Authentication Package (local AP).
    • With the Password-CP, you will be able to do MFA validation (password + OTP or FIDO as second factor);
    • With the FIDO-CP, you will be able to do only FIDO authentication (PasswordLess).
    • With the OTP-CP, you will be able to do only OTP authentication with OTP challenge, Simple-Push or VOICE biometric (PasswordLess).
  • 2: The local AP forwards the credentials to OpenOTP.
  • 3: OpenOTP manages the authentication request according to the client policy defined for the client AP (AP installed on the Server/Workstation). For example, if the policy is configured for FIDO/OTP authentication, then a FIDO/OTP challenge is forwarded to the local AP, displayed by the choosen CP to the end-user, the user must reply to that challenge and OpenOTP will validate the response.
  • 4: Once the authentication is successfully validated by OpenOTP, OpenOTP informs the AP and the AP informs the CP.
  • 5: Finally, the CP contact the AP to ensure the state generated by the AP is valid and then, the user is successfully authenticated.

Notes for PasswordLess CPs (OTP and FIDO):

  • PasswordLess CPs are involving management of LSA_TOKEN_INFORMATION_V2 structure. Have a look on the following Microsoft ressources for more information.
  • When using PasswordLess CPs, to trigger the Simple Push, FIDO2 Challenge or OTP Challenge, the Client Policy used behind must be configured accordingly. For the OTP-CP, you can just provide your username and submit the authentication request to OpenOTP to receive the push login request on your OpenOTP Token application. Same for FIDO challenge.

AP, Sub-AP MSV1 and Password Credential Provider

When the OpenOTP Sub-Authentication MSV1 is enabled, the user password becomes mandatory in the authentication process. This implies that only the OpenOTP Password-CP can be used in that scenario.

Below is an overview of the flow of the OpenOTP Authentication Package in local authentication scenario with Sub-Authentication Package MSV1:

ap
  • 1: The OpenOTP Password Credential Provider retrieves username and password information provided by the end-user and forwards it to the locally installed OpenOTP Authentication Package (local AP).
    • With the Password-CP, you will be able to do MFA validation (password + OTP or FIDO as second factor);
  • 2: The local AP forwards the credentials to OpenOTP.
  • 3: OpenOTP manages the authentication request according to the client policy defined for the client AP (AP installed on the Server/Workstation). For example, if the policy is configured for FIDO/OTP authentication, then a FIDO/OTP challenge is forwarded to the local AP, displayed by the Password-CP to the end-user, the user must reply to that challenge and OpenOTP will validate the response.
  • 4: Once the authentication is successfully validated by OpenOTP, OpenOTP informs the AP and the AP informs the Password-CP.
  • 5: The OpenOTP Password-CP contact the Microsoft MSV1 AP with credentials provided through the Password-CP.
  • 6: The Microsoft MSV1 AP then trigger the OpenOTP MSV1 Sub-AP for final validation. The OpenOTP Sub-AP checks that the state stored in memory is valid and in that case, the authentication result in success. However, if the state is expired, two possible scenarios arise:
    • If a Subauthentication Client ID is configured during installation, a new OpenOTP call is initiated by the Sub-AP component. It's important to note that the Sub-AP does not provide any user interface during this process, as it does not pass through the OpenOTP Password Credential Provider. Consequently, to successfully respond to this authentication request, only the Simple Push login method can be utilized by the end-user. Please ensure the SubAuthentication Client Policy is configured accordingly. If an authentication challenge is sent by the OpenOTP backend, the authentication will result in an error.
    • If Subauthentication client ID is NOT configured during installation, the authentication will simply fail. In such a case, you will need to redo the authentication involving the OpenOTP Password Credential Provider by right-clicking on the desired program and selecting the "Run As" option.

Online and Offline scenarios

RCDevs introduces an Offline Login feature as part of the OpenOTP Authentication Package, compatible with the OpenOTP Token application with Push mode enabled and with FIDO2 keys. To enable this feature, the Offline Login mode setting must be enabled during the AP installation.
Activation of the OpenOTP offline login requires an online login per user and per machine. The first online authentication allow to retreive the offline metadata that will be used by AP and its CPs.

In scenarios involving the deployment of OpenOTP AP in an Active Directory Domain environment, the AP is installed on both the domain controllers and the client machines requiring protection via OpenOTP authentication. RCDevs prioritizes the authority of DCs in authentication processes when they are reachable. Therefore, the local AP installed on client machines (Local AP) consistently attempts to contact the OpenOTP AP installed on the domain controllers (Remote AP) to negotiate authentication.

The authentication request from the local AP will be forwarded to the remote AP, which will then relay the request to the OpenOTP Server. The Client ID of the local AP will be forwarded to the OpenOTP server to apply any Client Policy that may have been defined for that local AP.

These offline metadata are stored in the registry of the local AP. In offline authentication scenarios, where the remote AP and the OpenOTP server(s) cannot be reached by the local AP, the stored offline metadata are utilized.

If the remote AP on the DC is unreachable, the local AP directly attempts to reach the OpenOTP service.
If the OpenOTP service is also unreachable, the offline mode is triggered.

System Requirements for deployments

The OpenOTP Authentication Package runs on x64 Windows platforms starting with Windows 10 and Windows Server from 2019 versions.

Your environment should fulfill the following requirements:

  • x64 Windows 10 or Windows Server 2019 minimum;
  • An instance of WebADM and OpenOTP running in your network or in a cloud;
  • Port TCP 443 and 8443 from APs (local and remote) to OpenOTP server’s accessible.

Preliminary Information

Administrative/elevated permissions are required on any workstation/server to correctly install and/or change the OpenOTP Authentication Package configuration.

To correctly set up the AP, please gather the following information. You will need to enter during the installation process:

  • Components you want to install: at least the Core components and the Password Credential Provider. For production usage the Credential Provider Filter needs to be installed in order to enforce the OpenOTP authentication.
  • The URL(s) of the OpenOTP web-service(s). (mandatory)
  • Local Alias: Domain value sent to OpenOTP SOAP API (usefull for local accounts implementation, not for domain implementation);
  • A client ID (Highly advised)
    • An ID to identify which AP (OpenOTP client) is calling OpenOTP server and to apply a authentication policies. Refer to Client Policy documentation
  • The WebADM certificate authority (CA) file. (Mandatory for offline logins)
  • An OpenOTP client certificate file or an API key (optional if OpenOTP API is not consumed through a reverse proxy)
  • SOAP timeout delay (optional - default value advised)
  • Deploy or not Kerberos/NTLM Sub-Authentication package. Mandatory on DCs to catch all kerberos/NTLM logins and to be processed with OpenOTP. If not needed, then it is optional.
  • Subauthentication grace period if Sub-Auth package is/are installed. By default 10s.
  • Subauthentication client ID. Highly advise if Sub-AP used in order to enforce simple-push login policy.
  • Withelist: An account where authentication will not be passed through OpenOTP (e.g: domain administrator group/account). Highly advised until you validate all scenarios and in order to have a fallback in case you are stuck with your AP setup.

Installation and Configurations

The setup and configuration of the OpenOTP Authentication Package for Windows typically take few minutes.
The installer is the only utility that is needed to set up and to configure the AP and its CPs. The deployment can be done automatically to your clients. This is addressed in another section later in the documentation.

Administrative/elevated permissions are necessary on any workstation to correctly set up and/or change the OpenOTP AP configuration. Please, run Windows PowerShell or command prompt as Administrator. Right click on Windows PowerShell or CMD program, then select Run as Administrator.

First, you have to download the OpenOTP Authentication Package for Windows and copy it on the machine you want to install it.

Installation on Active Directory Domain Controllers (Remote AP) - Mandatory in AD Domain scenario

In an AD Domain scenario, the AP must be installed on all Domain Controllers within your Windows domain. The configuration must be consistent across all domain controllers, with the exception of Client IDs, which may vary to identify specific targets.

Once the package is downloaded, extract files from the archive on your Windows machine(s), run the MSI file with Administrative/elevated permissions and click on Next.

ap

Accept the End-User License Agreement and click on Next.

ap

Now, you have to select which features to install. Core Components (AP) are mandatory in every scenario, along with at least one Credential Provider to establish a connection with the AP. For testing purposes, it's advisable not to enforce the Credential Provider Filter. Enforcing this filter would restrict the usage of OpenOTP AP with its Credential Provider(s) only, without the fallback possibility to other Microsoft login methods. The different Credential Providers and their corresponding usage have been described in section 2.3 of this documentation. Click Next when you are done.

ap

On the first configuration page, you have to configure the following elements:

  • WebADM URL, Server URL, and additional Server URL settings:
  • Loading Text (optional): The text to display during a connection attempt to Webadm. If you are using push login, it could be useful to remind the user here to check his mobile phone.
  • Login Text (optional): you can also define a login text which will be displayed to the user when authenticating.
  • Loading Text(optional) : This is the text displayed during a connection attempt to webadm. If using push login, it could be useful to remind the user here to check his mobile phone.


    Note : Let it empty to keep the default message.
  • Client ID (highly advised): Define here a Client ID referring to a WebADM client policy. It is advised to set a value which is uniquely identifying the origin in the authentication requests. Here I configured AP-AD1 for "Authentication Package Active Directory Domain Controller 1".
ap

Click on Next.

On the second configuration page, you can configure the following elements:

  • Certificate Authority File (optional): this has to be configured if you configured HTTPS in your Server URL during the previous step. This must contains the CA file of your webadm servers. The file will be automatically copied into the installation folder of OpenOTP Windows Credential Provider.
  • API Key or Certificate (optional): if you configured OpenOTP to require an API Key or a Client certificate you can set it with these settings.

The MSI will automatically download the CA certificate on the default WebADM server port if you are using the automatic configuration. You can also obtain it manually by accessing https://your-webadm-ip-address-or-dns-name/cacert URL.

ap

Click on Next.

On the third configuration page, you can configure the following elements:

  • SOAP Timeout (Default to 30) : this is the timeout for connection to the Server URL.
  • Server Selection Policy (Default to Ordered) : If you have more than one webadm server, this is the way the Windows OpenOTP Credential Provider will contact them.
    • Ordered : the first server declared is always preferred;
    • Balanced : the server is chosen randomly for each request;
    • Consistent : the server selection depends on the user ID;
ap

Click on Next.

On the fourth configuration page, you can configure the following elements:

  • Http Proxy Host and Port (optional): This config is for HTTP proxy. If you are running OpenOTP behind an HTTP proxy you need to set the host and the port of the proxy.

  • RDP Client ID (optional). RDP client ID can be used if you want to match a different client policy for RDP and CredUI authentications.

  • Local Alias (optional): when attempting a local login, the domain part of the username will be automatically replaced by the local alias before sending the OpenOTP request.

  • Remote LDAP Password Check: This feature should only be enabled for computers outside of an Active Directory domain. When a computer is part of an AD Domain, the LDAP password is always checked with AD. In scenarios outside of an AD domain, passwords can be maintained either at the Windows level or at the WebADM/OpenOTP level. Enabling this feature indicates that you want to maintain users' passwords at the WebADM/OpenOTP level, and the local password will be overridden after each successful authentication with OpenOTP.

  • Enable Offline Mode Support: Enable this option if you want to use the offline mode of OpenOTP Authentication Package. This will permit you to authenticate to your machine even if OpenOTP service or remote AP installed on the DCs are not reachable. If you entended to use that feature, the setting must be enabled on the remote AP and on the local AP.

  • Auto Create Local Accounts (optional): this option can be enabled when the host is not connected to a Windows domain, and you want the Credential Provider to create user accounts at first login. You can also select local groups to be populated by these auto-created local accounts. The account/password will be created based on the OpenOTP server reponse.

ap

Click on Next.

On the fifth configuration page, you can configure the following elements:

  • Enable MSV1 subauthentication: All NTLM authentications will pass through that subauthentication package which will trigger an OpenOTP authentication.
  • Enable Kerberos subauthentication: All Kerberos authentications will pass through the subauthentication package, triggering an OpenOTP authentication. I choose to install it as I configure my remote AP on my domain controller, intending for all Kerberos authentications to go through the OpenOTP server.
  • Subauthentication grace period (in seconds):Period during which the subauthentication package does not trigger a new OpenOTP authentication request when the authentication is coming from the same user and machine.
  • Subauthentication Client ID: Subauthentication client ID. Highly advise if one of the Sub-AP is used in order to enforce simple-push login policy to be able to approve the login through OpenOTP Token application when the grace subauthentication grace period is expired. If no Client ID is configured, the authentication will fail, requiring you to redo the authentication with OpenOTP-AP using the 'Run As' feature by right-clicking on the desired program.
  • Max hours to bypass MFA: This setting can be used to define for how much time the OpenOTP Windows Credential Provider will not ask for a MFA since the last login.
  • Whitelist: List of user SID separated by ; that won’t be asked for 2FA/MFA to login, skipping any OpenOTP calls. It is highly advised to whitelist an account for testing purposes. Here I whitelisted by default domain administrator account.
  • Protected Principals: List of security principals SID (users and groups) separated by ; which for the OpenOTP call will be enforced. This is basically the opposite of the above whitelist setting, and is only useful if you have whitelisted groups or if you want to enforce OpenOTP authentication for only one/few group(s) or one/few account(s). You can get a user SID by clicking Select Principals button and looking for your user(s) or group(s).
ap

Description of MSV1 Sub-AP:

ap

Description of Kerberos Sub-AP:

ap

Description of Subauthentication Client ID:

ap

On the fifth configuration page, you can configure the following elements:

  • Authentication form (Default to Simple). You have 2 choices:
    • Simple: On the Windows login page, you will have 2 fields in the first step (Username and Password), after pressing login, you will have a second screen with the OTP field. Preferred for better flexibity.
    • Normal: With this option, you will have 3 fields on the login page, one for the Username, one for the LDAP/account password and the last one for the OTP.

The three other settings correspond to the tile images for the different Credential Providers, which will be visible on the login screen.

ap

Click on Next.

On the last page, the following settings can be configured:

  • Credential Provider filter whitelist: If you are installing any of OpenOTP Credential Provider as default, no other providers will be available during login. Use this setting to override this behavior and allow specific credential providers to be used. Please keep in mind that the login process will only be as secure as the least secure of the available credential providers! This is a list of the allowed Credential Providers CLSID separated by ";", a CLSID is of the form {60b7888-ead8-445c-9cfd-0b87f74ea6cd)
    All the CLSID of the registered Credential Providers on your machine can be found in the following registry location:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Authentication\Credential Providers)

This will change depending on your Windows version and if you have installed other third party Credential
Providers.

  • Use the Credential Provider Filter in CREDUI: Only relevant if you installed the Credential Provider Filter. If this is disabled, the filter will be disabled in CREDUI mode, allowing you to use any other credential providers (like the builtin Microsoft password provider) CREDUI is the Microsoft 'popup style' window you can get asking you for credentials, like when trying to run an app using 'Run as', or when launching a remote desktop connection.
ap

Click on Next and then on the next page click Install.

ap

Once the installation is finished, you need to restart your machine for the new configuration to be applied.

ap

Installation on Active Directory Domain computer(s) (local AP) - Mandatory in AD Domain scenario

In an AD Domain scenario, the OpenOTP AP must be installed on all Domain computers you want to enforce OpenOTP authentication within your Windows domain. The configuration is similar to the previous section and settings must be aligned with what has been configured on the remote AP(s) with the exception of Client IDs, which may vary to identify specific targets and the subauthentication packages.

On domain computers that are not domain controllers, it is unnecessary to install and configure the following components and related settings:

  • Subauthentication Kerberos;
  • Subauthentication MSV1;
  • Subauthentication Client ID;
  • Subauthentication grace period.

Refer to the previous section for detailled installation.

Automatic Deployment / Quiet Installation

The MSI installer package is prepared to take all configuration parameters that can be set during local installation for auto-deployment in quiet mode. Hence, you can deploy the setup to any clients and automatically install the Credential Provider without user interaction.

Example of quiet installation with PowerShell:

msiexec /qb /i OpenOTPAuthenticationPackage.msi ADDLOCAL=PasswordCP,FidoCP,OtpCP,SmartcardCP,InstallAsDefault SERVER_URL=https://webadm1.rcdevsdocs.com:8443/openotp/ CA_FILE=C:\ProgramFiles\RCDevs\OpenOTP-AP\ca.crt OFFLINE_MODE=1 CLIENT_ID=AP SUB_CLIENT_ID=SUB-AP

The ADDLOCAL directive can be used with the below parameters:

  • PasswordCP: Password Credential Provider (Working with all scenarios)
  • FidoCP: FIDO Credential Provider (PassworLess with FIDO, working with local accounts scenarios only)
  • OtpCP: OTP Credential Provider (PassworLess with OTP, working with local accounts scenarios only)
  • SmartcardCP: Smartcard Credential Provider (PassworLess with Smartcard based authentication, working with domain accounts scenarios only)
  • InstallAsDefault: Enforce OpenOTP Credential Providers as default Credential Provider.

e.g: In local account scenarios, if you want to provide OTP and FIDO PassworLess Credential Providers and enforce them as default providers, you can do it like:

msiexec /qb /i OpenOTPAuthenticationPackage.msi ADDLOCAL=FidoCP,OtpCP,InstallAsDefault SERVER_URL=https://webadm1.rcdevsdocs.com:8443/openotp/ CA_FILE=C:\ProgramFiles\RCDevs\OpenOTP-AP\ca.crt OFFLINE_MODE=1 CLIENT_ID=AP SUB_CLIENT_ID=SUB-AP

Found below, all configurable parameters for AP installation:

Parameter Value
SERVER_URL URI pointing to one OpenOTP web­‐service.
Example: _https://webadm1.rcdevsdocs.com:8443/openotp/_
Mandatory.
SERVER_URL_2 URI pointing to the second node of your OpenOTP cluster.
Example: _https://webadm2.rcdevsdocs.com:8443/openotp/_
Optional.
LOADING_TEXT The text to display during a connection attempt to Webadm. If you are using push login, it could be useful to remind the user here to check his mobile phone.
Default syntax : "Insert Message".
LOGIN_TEXT A text that is displayed on the Windows login page.
Default (Empty) : "OpenOTP Login".
CLIENT_ID Client ID which is sent to OpenOTP in the login requests.
RDP_CLIENT_ID RDP client ID can be used if you want to match a different client policy for RDP sessions.
SUBAUTH_CLIENT_ID Client ID sent to OpenOTP when a Subauthentication package is involved.
RDP_DEFAULT_ENABLED This option is to force or bypass the MFA check using RDP from the machine when the OpenOTP Windows Credential Provider is installed as the default credential provider. That means when this setting is disabled, you are able to select the default Windows credential provider during an RDP authentication.
  • 0: disabled (Default)
  • 1: enabled.
CA_FILE The file-system path to the WebADM Certificate Authority (CA) file.
Mandatory.
Example: C:\ProgramFiles\RCDevs\OpenOTP-AP\ca.crt
CERT_FILE The file-system path to an OpenOTP client certificate.
Optional.
CERT_PASSWORD The client certificate’s password.
Optional.
API_KEY Allow to provide an API Key value issued from WebADM when client authentication is required in your policies.
Optional.
PROXY_HOST The HTTP or HTTPS URL of your proxy authentication requests must be passed through to reach OpenOTP.
PROXY_PORT Port of the proxy server.
SOAP_TIMEOUT Request timeout when connecting to OpenOTP Authentication Server URL.
The default is 30 seconds (If empty it will be the 30s).
Optional.
LOGIN_METHOD Useful with Password Provider only. There are two login methods available:
  • 0: simple (Default): Only username and password inputs are displayed during login, and if needed a Challenge appears on a next step.
  • 1: Normal: Username, password and OTP inputs are displayed during login.
Simple mode uses the OpenOTP SimpleLogin method where the semantic of the password input is handled by the OpenOTP server and based on the user login policy.
Optional.
SMARTCARD_MFA Only present if you have installed the SmartcardCP feature. If enabled, an additional authentication factor will be required after a successful smartcard login.
SUBAUTH_MSV1 Enable the Subauthentication package for NTLM. Unique value is OpenOTPAuthenticationPackage.
SUBAUTH_KERB Enable the Subauthentication package for Kerberos. Unique value is OpenOTPAuthenticationPackage.
SUBAUTH_GRACE_PERIOD Grace period for subauthentication packages. Value is an interger (10, 20, 30...). Default value is 10s.
BMP_PASSWORD The path of the image on the filesystem for the Password Provider.
Optional.
BMP_OTP The path of the image on the filesystem for the OTP Provider.
Optional.
BMP_FIDO The path of the image on the filesystem displayed for the FIDO Provider.
Optional.
BMP_SMARTCARD The path of the image on the filesystem for the Smartcard Provider.
Optional.
CHECK_LDAP Enable this option if LDAP/Users password should be sent to OpenOTP for validation. If disabled, the -LDAP option is sent to OpenOTP to inform that the password will not be sent and is validated locally.
  • 0: disabled
  • 1: enabled (Default)

Optional.
AUTO_CREATE_ACCOUNT You can enable this option when this host is not connected to the Windows Domain and you want the Credential Provider to create users accounts at first login. The local LDAP password is transparently reset at each login.
  • 0: disabled (Default)
  • 1: enabled
Note: This option is only available if the Remote LDAP Password Check Option is enabled.
AUTO_CREATE_GROUPS Assign local users automatically created to specified group(s). The values are the group names seperated by semi-column (;).
DEBUG_MODE_CP This setting enables or not the debug logs of the AP, Sub-AP and CPs.
  • 0: disabled (Default)
  • 1: Error
  • 2: Warning
  • 3: Infos
  • 4: Debug
DEBUG_LOG_FILE_CP Path where the CPs debug log file will be created. e.g: C:\RCDEVS-LOGS\CP.log
LOCAL_ALIAS You can enable this option when the host is not part of the Windows Domain and you want that the OpenOTP Credential Provider send a static value (e.g: WORKGROUP name) in order to match a WebADM domain. Sometime, the Windows API is returning the hostname which is sent as Domain value in the OpenOTP call. Configure that setting will prevent that behavior.
AUTOCOMPLETE_USERNAME Keep the last logged username on the Windows login screen. Useful for "RunAs Other user" tile.
  • 0: disabled (Default)
  • 1: enabled.
LANGUAGE Language to use for custom strings (end-users messages translations not configurable from WebADM server. It can be translated through custom strings file. Language is the uppercase ISO 639 language code (FR, EN, DE, ZH, LB, ES...). By default, it is using the system installation language.
CP_FILTER_WHITELIST Only relevant if you have selected the InstallAsDefault feature. List of the credential providers CLSID separated by ';' that should still be enabled, overriding the filter. All the CLSID of the registered Credential Providers on your machine can be found in the following registry location : HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Authentication\Credential Providers
FILTER_CREDUI Enforce OpenOTP CPs filters for CredUI scenarios.
OFFLINE_MODE According to this option OpenOTP will permit users to log in when server/network is not reachable, using the OpenOTP Token mobile Application.
  • 0: disabled (Default)
  • 1: enabled
PS: this mode requires at least one online login using push service to fetch its offline information.
PROTECTED_PRINCIPALS List of security principals SID (users and/or groups) separated by ; which for the OpenOTP call will be enforced. This is basically the opposite of the above whitelist setting, and is only useful if you have whitelisted groups
WHITELIST List of user SID separated by ; that won’t be asked for 2FA/MFA to login, skipping any OpenOTP calls.
F2A_BYPASS_TIMER This setting can be used to define for how much time in seconds the OpenOTP Windows Credential Provider will not ask for MFA since the last login, Max : 86400 (24h).
  • Set a positive integer in seconds (e.g. 3600, 7200)
  • 0: disabled (Default)
POLICY Balancing Policy to reach OpenOTP services.
The possible values are 1, 2 or 3.
  • 1: Ordered (Default): The first server is always preferred. When it does not respond, the second server is used.
  • 2: Balanced: The server is chosen randomly for each request. When it does not respond, the other is used.
  • 3: Consistent: The server selection depends on the user ID. A request for one specific user is also always routed to the same server. If it does not respond, the other server is used.

Credential Providers integrated with OpenOTP authentication packages and their scenarios compatibility

Offline scenarios are supported with all Credential Providers as soon as the offline metadata are available on the corresponding host for the corresponding user.

Password Credential Provider

The Password Credential Provider is the CP that supports all authentication methods except for smart card-based login. It can be installed and utilized for all scenarios described in Section 3 of the documentation. If you do not intend to use smartcard based authentication, it is the sole Credential Provider available for use. It supports password, OTP and FIDO-based authentications. In domain scenarios, the LDAP password must always be validated.

Smartcard Credential Provider

The Smartcard Credential Provider is wrapping the builtin Microsoft Smartcard Credential Provider. Therefore, you should check first you are able to log in with the Microsoft builtin smartcard CP before using the Smartcard Credential Provider of OpenOTP.
The Smartcard Credential Provider is working only in Domain joined scnearios.

When you enable the Smartcard CP, at the end of the installation there is an option to enforce additional MFA authentication after the Smartcart authentication. If you want to add an extra-factor like OTP, Push... please enable that option and configure your client policy accordingly.

ap

Certificates issued by Microsoft PKI

You can use certificates generated by Windows, to configure all the Windows PKI infrastructure please refer to the following Microsoft documentation.
Before continuing, make sure you are able to log with the Microsoft Smartcard Credential Provider.

In order to use the Smartcard Credential Provider you will need some additional configuration :

If you look into your user object, you should notice WebADM automatically detected your certificate, but the CA is not trusted.

ap

To resolve this, first you will have to export your CA certificate into a base64 encoded X509 certificate.
This can be done via certlm, Right click > All Tasks > Export. Select the second format option.

ap

Once done, in your WebADM Admin tab, click on Trusted CA Certificates

ap

Click Import CA Certificate, select your file and import it (You can also paste its content with the method 2)

ap
ap

The CA is now trusted and your user object should reflect this

ap

You should now be able to log in with the OpenOTP Authentication Package and the Smartcard Credential Provider.

Certificates issued by WebADM PKI

You can also generate user certificates directly with WebADM and then transfer them on your smartcard. The generated certificate meet by default all the requirements to be used with the Microsoft smartcard logon workflow, so you should not have to override them in a GPO.

On your user object, click on Create certificate, select User usage and fill the information then click Create Cert.

ap
ap

You will then be prompted to download the certificate, do it. Note the password, you will need it to store the private key.
You will now have to store this certificate with its private key on your smartcard. The method to do so depends of your smartcard manufacturer so please consult their technical documentation.

ap

You should now be able to see your newly generated certificate on your user object.

ap

You will now need your WebADM CA certificate. It can be retrieved in your Admin tab, with the Download WebADM CA certificate link or in the Trusted CA Certificates section.

ap

Lastly you will need some additional configuration on Windows side. Please follow those Microsoft configuration instructions, at this point you should only have to do steps 2 and 3.

In summary the WebADM CA certificate should be in the Trusted Root Certification Authorities store of all workstations (this can be automated via a Group Policy) and in the NTAuth store of Active Directory.
This link provides additional information for the latter.

If everything is correctly configured you should now be able to log in with a smartcard with the builtin Microsoft Smartcard Credential Provider. Please make sure this is the case and then you can install the OpenOTP Authentication Package with the Smartcard Credential Provider.

OTP Credential Provider

The OTP Credential Provider can only be installed in local account scenarios. Attempting to use these CP in a domain will result in failure. Instead of requesting the user account password, the only field prompted to the user is the OTP password field. This CP can be utilized for passwordless scenarios. When using the Push login with OpenOTP Token application, you need to provide your username and submit the request with the OTP field empty to trigger the push login request to OpenOTP. With this CP, the -LDAP option is always sent to the OpenOTP Server in case the client/authentication policy is wrongly configured and is requiring LDAP password. In that case, the factor LDAP will be ignored.

FIDO Credential Provider

The FIDO Credential Provider can only be installed in local account scenarios. Attempting to use this CP in a domain will result in failure. Instead of requesting the user account password, the only field prompted to the user is the FIDO password field. This CP can be utilized for passwordless scenarios. To use it, you have to provide your username, leave the password field blank, and submit the authentication request to receive the FIDO challenge generated by the OpenOTP server for the corresponding user. The FIDO key must be plugged into the device before receiving the FIDO2 challenge from the OpenOTP server, else an error will be prompted. With this CP, the -LDAP option is always sent to the OpenOTP Server in case the client/authentication policy is wrongly configured and is requiring LDAP password. In that case, the factor LDAP will be ignored.