Skip to main content

Integration Guide for Windows desktop login (On-prem Ad)

  • Updated

Introduction

This guide provides information on how to set up passwordless Windows Desktop Login (WDL) for on-prem Active Directory domain joined devices. It covers:

  • Installation & configuration of the Beyond Identity Domain Connector (aka BI AD Connector or BI AD Agent) on the Active Directory Domain Controller for key synchronization.
  • Configuration of the Okta AD Agent to work with the Beyond Identity cloud for key synchronization.
  • Setting up the Active Directory to use Key Trust based authentication for Beyond Identity Credentials Provider.
  • Installation and configuration of the Beyond Identity Desktop Login Authenticator app.

 

Prerequisites

Beyond Identity Web SSO:

  • The Beyond Identity Web SSO must be already configured and working.
  • You must have super admin privileges to the Beyond Identity Admin Console.

 

Active Directory Side:

  • You must have Enterprise Admin privileges on your AD Domain Controller(s).
  • AD Domain Controller(s) must be running on Windows Server 2016 or later version (AD Schema Version: Windows Server 2016 or later schema).
  • The minimum required domain functional and forest functional levels for deployment is Windows Server 2008 R2. (Server Manager > Domains and Trust > Right-Click on the Root Domain > Properties)
  • AD Domain Controller must have following components:
    • Active Directory Domain Services
    • Active Directory Certificate Services (Required for Server Certificate issuance and publishing 3rd party CA issued certificates) 
  • Kerberos Domain Controller (KDC) certificate must be deployed on the AD Domain Controller(s)
  • DNS Services must be running.
  • If you are using a non-Microsoft SSO and have already configured your SSO with your Active Directory:
  • The SSO AD Agent (e. g. Okta AD Agent) must be installed.
  • The service account used by the SSO AD Agent must be a member of the following groups:
    • Domain Users
    • Key Admin
    • Enterprise Key Admin
    • Administrators
  • If SSO AD Agent is not available or if you are using Microsoft SSO, we will install Beyond Identity Domain Connector as part of the WDL installation. You can install it on the AD Domain Controller itself or any domain joined server running Windows 2016 or later.
  • You must have the ability to create and push GPO policies. If your GPO replication takes a long time, then you can execute steps outlined in section 3 and 4.1 and ensure that correct GPO policies are applied, ahead of time, so we can proceed with the installation and testing without waiting for it.

 

Client Side:

  • You need to have physical access or a console session to the machine to enroll and use WDL. Enrollment or using WDL over an RDP session is not supported.
  • Device must have joined the AD domain.
  • Device must be running Windows 10 (Build 1703 or later) or Windows 11 (Must be a Pro or Enterprise License).
  • Device must have Trusted Platform Module (TPM) 2.0 installed.
  • Device must have Root & Intermediate certificates for Domain Controller deployed.
  • Device may have a built-in or pluggable fingerprint reader (Optional).
  • Device must have Beyond Identity Authenticator app installed and enrolled in the Beyond Identity Web SSO. We will replace the app with the Beyond Identity Desktop Login Authenticator App.



Beyond Identity Domain Connector Installation & Configuration

The steps from this section are NOT required if the SSO AD Agent, e. g. Okta AD Agent, is deployed in your environment. In that case, skip to the next section.

 

  1. Create (or use an existing) service account (e. g. biservice) and make it a member of the following groups:
    1. Domain Users
    2. Key Admin
    3. Enterprise Key Admin
    4. Administrators
  2. On the server where the Domain Connector is installed, ensure that the service account used has sufficient privileges to install system services.
  3. Run gpedit.msc
  4. Navigate to  Computer Configuration > Windows Settings > Security Settings > Local Policies > User Rights Assignment.
  5. In the details pane, double-click on “Log on as a service”.
  6. Click on “Add User or Group” and add the service account to the list of accounts. Once you have selected the user, click “OK”.
  7. Click “OK” and close the policy editor.

  8. Login to Beyond Identity Admin Console and click on Integrations from the menu.
    1. On the Settings page, Desktop Login Tab.
    2. On the “Beyond Identity AD Connector” item click on the arrow to “Install this service”.
    3. Click on “Generate Key” and record the newly generated key for use in the next step.

  1. Download the Beyond Identity Domain Connector on a domain joined server from here.
  2. Install the Beyond Identity Domain connector and enter the below values:
    1. Access Key: <Use Key generated in a previous step>
    2. Domain: Comma separated domain values (e. g. beyondadfs.com)
    3. Username: service account name used to run the Beyond Identity Service (e. g. biservice@beyondadfs.com)
    4. Password: <Service-Account-Password>

  1. Once the installation is complete, make sure the service “Beyond Identity Domain Connector” is running.

 

Okta Configuration for Beyond Identity WDL

If you completed the steps from the previous section, skip this section. The steps in this section are required only when the Okta AD Agent is deployed in your environment. 

Verify Okta AD Agent Deployment

  • It is assumed that you have the Okta AD Agent already installed and configured. If not, follow the Active Directory Integration Prerequisites page when installing the Okta AD agent and configuring the integration.
  • The Okta tenant should have “Attribute Level Mastering” and “Allow both profile mastering and push” features enabled. These features are enabled only for the non-developer (production) accounts. Please, see Appendix in the Beyond Identity Okta Integration guide for an example of the ticket to be opened with Okta to enable these features.
  • The Okta service account should be a member of the Domain Administrators AD Group. 
  • The Okta service account needs to be able to modify the attribute msDS-KeyCredentialLink in AD. This is usually accomplished by adding the Okta service account to the Key Admins Group in AD.

Okta Tenant Configuration

Ensure that the Okta tenant is set up for creating and updating user attributes by making following changes:

  1. Sign into the Okta portal as an administrator.
  2. In the main Okta menu, select “Directory”.
  3. In the “Directory” drop-down menu, select “Directory Integrations” and Select “Active Directory”. 
  4. On the directory page, go to “Provisioning” tab and click on “To App” to configure provisioning from Okta to Active Directory. Make following changes on this page as shown in the diagram.
    1. Click on the Edit button for the “Provisioning to App”.
    2. Create Users: <Leave-Original-Value>
    3. Update User Attributes: Enable
    4. Deactivate Users: <Leave-Original-Value>
    5. Sync Password: <Leave-Original-Value>
    6. Click on Save.

 

Okta Custom Attributes Configuration

In the following steps, we will create a custom attribute required for the desktop login, master the attribute in Okta and map it back to the AD Attribute. We will also generate the Okta API token used for updating the desktop login attribute.

 

  1. Sign into the Okta portal as an administrator.
  2. In the main Okta menu, select “Directory”.
  3. In the “Directory” drop-down menu, select “Profile Editor”.
  4. Find your Active Directory profile and select the “Edit Profile” action.

  5. Under the user profile editor, you will see an action to “Add Attribute”.
  6. Click on “Add Attribute” and pick “msDS-KeyCredentialLink” from the schema as shown in the image.

  7. Create a custom profile attribute in the Okta user (default) profile. Navigate to Directories > Profile Editor and click on the Okta User (default) profile.

  8. Click on “Add Attribute”. Select fields as shown below:
    1. Data Type: String array
    2. Display Name: Beyond Identity Desktop Login Credentials
    3. Variable Name: byndidDesktopLoginCredentials
    4. Description: Beyond Identity Desktop Login Credentials
    5. Attribute required: Not Checked
    6. Click Save. See image below for reference:

  1. Update the Profile master for the recently added attribute by performing the following steps.
    1. Click on edit button for “byndidDesktopLoginCredentials” attribute in the Okta profile.
    2. For “Source Priority” field select “Inherit from Okta” from the pull-down menu. If you are not seeing the “Master Priority” field, then create a ticket as explained in the Appendix in the Beyond Identity Okta integration guide.
    3. Click on Save Attribute. Please, see image below for reference.
    4. Note that Okta will refer to this attribute with an underscore: msDS_KeyCredentialLink. This will be automatically remapped as necessary.

  1. Update Attribute Level Mapping between Okta and Active Directory for the recently added attribute by performing the following steps.
    1. Select Directory > Profile Editor > Active Directory >Directories> Mappings.
    2. Switch to the Okta User to Directory tab. 
    3. Click on the pull-down button for “byndidDesktopLoginCredentials” attribute in Okta profile and map user. byndidDesktopLoginCredentials to msDS_KeyCredentialLink.
    4. Ensure the mapping should be set to “Apply mapping on user create and update” for the user.byndidDesktopLoginCredentials attribute mapping as shown in the image.
  1. Generate a new Okta API token for the desktop login attribute update by vising Security > API page from the main Okta menu.
    1. Click on the Tokens tab.
    2. Click on Create Token.
    3. Provide name for the Token, e. g. “Beyond Identity Desktop Login service”.
    4. New Token will be generated. Write down the token value and use it in the following step.

 

Beyond Identity Admin Console Configuration

  1. Login to the Beyond Identity Admin Console.
  2. Click on the Integrations tab and then click on the “OKTA” tab.
  3. Click on the edit option for “Okta Desktop Login”.

 

AD Server-Side Config

Create a Group for Desktop Login

In the following steps, we will create a group and assign users to participate in Beyond Identity desktop login service.

  1. Sign into AD DC as Domain Administrator.
  2. Launch “Server Manager” management console.
  3. Click on “Tools” and then on the pull-down menu, click on “Active Directory Users and Computers”.
  4. Right click on “Users” > “New” > “Group”, create a group named “Beyond Identity Users”.
  5. Then add appropriate users to this group.

 

 

  1. GPO Configuration to Enable Biometrics

In the following steps, we will create a new custom policy for the computers / devices participating in Beyond Identity Desktop Login Service. We will assign this to “Beyond Identity Users” group.

  1. Sign into AD DC as Domain Administrator.
  2. Launch “Server Manager” management console.
  3. Click on “Tools” and then on the pull-down menu, click on “Group Policy Management”.

 

 

  1. Double-click on “Domains”, then right-click on the appropriate AD domain name and click “Create a GPO in this domain and Link it here…”.

 

  1. Enter the Name as “Beyond Identity GPO”, then click “OK”.

 



  1. From the left navigation menu, right-click on “Beyond Identity GPO” and click “Edit”.
  2. Navigate to Computer Configuration > Policies > Administrative Templates > Windows Component > Biometrics section, and enable the following policies:
    1. “Allow the use of biometrics”
    2. “Allow users to log on using biometrics”
    3. “Allow domain users to log on using biometrics”.

 

 

  1. Navigate to Computer Configuration > Policy > Administrative Templates > Windows Component > Windows Hello for Business section, and enable the following policy:
    1. “Use Biometrics”

         

  1. Navigate to Computer Configuration > Policy > Administrative Templates > System > Logon, and enable the following policy:
    1. “Turn On Convenience PIN Sign in”

 

 

  1. Follow the steps below to apply the GPO Policy to “Beyond Identity Users” Group:
    1. Under Group Policy Management, navigate to Group Policy Objects.
    2. Double-click on “Beyond Identity GPO”.
    3. Click on the “Scope” tab.
    4. Under Security Filtering, Add the “Beyond Identity Users” group.

  1. Click to the “Delegation” tab, then click on “Advanced”.

 

 

  1. Click on “Authenticated Users” group and click on “Allow” permissions for “Read”. 

 

  1. Click on “Beyond Identity Users” group and click on “Allow” permissions for “Read”, “Create all child objects”, “Delete all child objects” “Apply group policy” and click “Apply”. 

  1. Under Group Policy Management, double-click on your primary domain and click on the “Linked Group Objects” tab. 
  2. Make sure the newly created “Beyond Identity GPO” has the link order 1. 

 

 

  1. Client-side Config

    1. Apply the GPO Policy

  1. On a Domain joined Windows device, make sure you are logged in as a domain user and have administrator rights for the local machine.
  2. Apply the GPO by running the gpupdate /force command via the Windows PowerShell in Admin mode or simply rebooting your machine. 
  3. Verify whether the GPO is applied by issuing the gpresult /r /v command via Windows PowerShell in Administrator mode. 

  1. Install Beyond Identity Desktop Login 

  1. On a Domain joined Windows device, make sure you are logged in as a domain user and have administrator rights for the local machine.
  2. Using a browser go to https://app.byndid.com/desktop-login/downloads and download MSI labeled “Desktop Login for Windows”.
  3. Ensure “Beyond Identity Service” service is running on the client before moving to the next step.

 

  1. User Enrollment Process

  1. Run the below command in windows command prompt or powershell and make sure the following parameters match.
    1. dsregcmd /status
      1. Device State
  • AzureAdJoined: NO
  • DomainJoined: YES
  • EnterpriseJoined: NO
  1. Device Details
  •   TpmProtected: YES
  •   DeviceAuthStatus: SUCCESS
  1. SSO State
  • AzureAdPrt: NO

 

  1. Open the Beyond Identity Authenticator app.
  2. Select the Profile already enrolled in Web SSO and click on “Enroll in desktop login”.
  3. Enter your domain password to start enrolling in Beyond Identity’s Windows Desktop Login service.

 

  1. Create a PIN that will be used for passwordless login. Minimum length is 8 characters. Hit ENTER once you have entered the PIN.

 

 

  1. Confirm the PIN added in the previous step.
  2. Optionally, enroll fingerprints for biometric login and then click “Finish Setup”.

 

 

  1. Wait until a confirmation dialog displays. You are now enrolled in Windows Desktop Login.

 

  1. User Login Process

  1. Log out or lock local screen.
  2. Choose the Beyond Identity login option.

  1. When prompted, use a fingerprint or enter a PIN to complete login.

Appendix A: Troubleshooting

  1. Understand the Customer Environment:

  • Domain Joined Machine
  • Key Provisioning: Using BI AD Domain Connector or Okta AD Agent
  • Desktop Login using Key Trust based authentication over Kerberos
  • AD for desktop login, On-Premise Application authentication using Kerberos

 

  1. Match the certificate in AD for Kerberos

Issued Certificate on the client: (User Certificate Store > Personal > Certificates)

 

  1. Event Viewer Logs in AD:

 

  1. Datadog logs for Beyond Identity Domain Connector

Look for these messages in DataDog under your tenant-id at the time of enrollment. This ensures that BI cloud has written the public key into the msDSkeycredential attribute of the user via the BI connector api service.

 

  1. Datadog logs for Okta AD Agent

Look for these messages in Datadog under your tenant-id at the time of enrollment. This ensures that BI cloud has written the public key into the msDSkeycredential attribute of the user via the Okta desktop login service. You can execute the below query.

https://app.datadoghq.com/logs?query=service%3Aokta-desktop-login%20cluster_name%3Aproduction-eks&cols=service%2C%40request_id%2C%40context.tenant_id&index=main&messageDisplay=inline&stream_sort=desc&from_ts=1638374443081&to_ts=1638979243081&live=true

 

  1. Datadog logs for BI Domain Connector

Look for these messages in Datadog under you tenant-id at the time of enrollment. This ensures that BI cloud has written the public key into the msDSkeycredential attribute of the user via the BI Domain Connector api service.

 

 

  1. Verifying the public key the on server & client

In the Active Directory, navigate to Tools > Users and Domains and look for your user. Check the Attribute Editor to ensure msDS-KeyCredentialLink is populated with the correct public key value. You can optionally use Apache Directory Studio to view this as well. (Note: The Attribute Editor is not visible by default. You need to enable Active Directory Users and Computers > View > Advanced features

  • You can also execute the below command via windows PowerShell on the AD to get the keys.

          get-aduser beth.test -Properties msDS-KeyCredentialLink 

  • Verify the key is the same for on the client machine under the authenticator logs located under:

%appdata% Roaming\BeyondIdentity\logs\authenticator

DL Enrollment: Publishing Certificate Handle:Ashwin-Test; UPN: ashish.bhatia@beyondadfs.com; domain: beyondadfs.com; enrollKey: B:828:0002000020000138143C6D1AEEB00B5FA2454D1F6AC54BE25AA6D34F2056F49FAA767CE4220B1D200002D48A01D5990B6BD0AAD9252AB7D6B6FA18179B15A3BECBFAD86735624E36F2411B0103525341310008000003000000000100000000000000000000010001C3F491CA2739F9A55FD5F91B409F7978BB426456B49F16A29DE36A6B4C5223139743420D792610A5E09E851A8590DACC340913918A847F27EA241D3668C319DA81452AA534C1F1C7D1440BB9296C3FDEBFC7F9CBA05B99C5EB79E28779EC73043108B51C52AA7655BB935C2D0434F045C8425E39DC7CAC805273166CFF7CBE67F881A2B95DFBD279E76C8D592C1EB327A55A22DD26310F36242A2938FE18E738EA5B2EF5E297A744CD354C2F788A1D4F397A892B6037DB97B8DE78DC3CDBCE2121EF39909E70501AB4D0C6BF845B1624289D4942EA6B71825F5DC08236B469B5972784792247EBE3E0E17A1D91158B8F318D2AE27D3DC91BBB84F45C55B35A7B0100040101000500100006D43B53E2AFDDAB468D1F0B61BFB0C976020007010008000864A4B12246ECD70108000964A4B12246ECD701:CN=Ashish Bhatia,CN=Users,DC=beyondadfs,DC=com; url: https://api.byndid.com

 

  1. Client Log Location

 

  1. Authenticator Logs:
  • c:\Users\<user>\AppData\Roaming\BeyondIdentity\logs\authenticator\authenticator<date>.log

 

  1. Credential provider Logs:
  • c:\ProgramData\BeyondIdentity\logs\credProvider\credProvider<date>.log

 

  1. Desktop Login service Logs:
  • c:\ProgramData\BeyondIdentity\logs\service\service<date>.log

 

  1. Server Log Location

  • log ( Windows Server Running BI AD Domain Connector: C:\Program Files\DomainConnector\log – BI AD Domain Connector Logs)
  • Okta AD Agent logs (C:\Program Files (x86)\Okta\Okta RADIUS Agent\current\logs)

 

  1. Trust Relationship

If at any time you get the message "The trust relationship between this workstation and the primary domain failed", it can be fixed by entering the information into a Powershell window running under Admin mode:

$credential = Get-Credential

Reset-ComputerMachinePassword -Credential $credential

 

Appendix B: Important Debug commands

  1. Command to check schema version
  • Get-ADObject (Get-ADRootDSE).schemaNamingContext -Property objectVersion

Windows Server 2016 objectVersion value: 87

 

  1. Command to see current user and their domain or groups
    • whoami (to check current user’s name and domain)
    • whoami /groups (to check current user’s groups)

 

  1. Updated GPO policy on a client:
    • gpupdate /force

 

  1. Check resultant set of policies (RSoP) on a windows client: (Run command as an Administrator)
    • gpresult /r /v (/r for summary and /v for verbose)

 

  1. Command to view policy on a local machine.
    • gpedit.msc

 

  1. Command to view the resultant set of policy on a local machine. Running this command after gpupdate will prove that local policies are updated.
    • rsop.msc

 

  1. Device Joined Status check, release device, join device
    • dsregcmd  /status (to check the status of the device, PRT, WHFB enrollment etc…)
    • dsregcmd /leave /debug (to unjoin device from Azure AD)
    • dsregcmd /join /debug (to join device to Azure AD using CLI)

 

  1. Command to check NGC keys in Active Directory:
    • Get-ADObject -LDAPFilter '(msDS-KeyCredentialLink=*)' -Properties msDS-KeyCredentialLink | Select-Object -ExpandProperty msDS-KeyCredentialLink |  Get-ADKeyCredential

 

  1. Command to check specific User’s key in AD
    • get-aduser ashwin.test -Properties msDS-KeyCredentialLink

 

  1. Command to reset specific user’s key in AD
  • Set-ADUser -Identity <UserIdentity> -Clear 'ms-DS-KeyCredentialslink'

 

  1. Command to query for keys in Azure Active Directory:
    • Get-AzureADWHfBKeys -Logging -Report -Tenant contoso.com -All

 

  1. Command to query for keys in Active Directory:
    • Get-ADWHfBKeys -Logging -Report -Domain contoso

 

  1. Command to initiate delta sync from AD Connect
    • Start-ADSyncSyncCycle -PolicyType Delta

 

  1. Command to list Kerberos Ticket and purge Kerberos tickers
    • klist 
    • klist purge

 

  1. Command to delete WHFB Keys:
    • certutil -DeleteHelloContainer
    • logoff

 

  1. Enable running PowerShell script on a client machine
    • Set-ExecutionPolicy unrestricted | remotesigned

 

  1. Debug Beyond Identity Issues Please look at the following log files.
    • Authenticator: %appdata%\BeyondIdentity\logs\authenticator
    • Service: C:\ProgramData\BeyondIdentity\logs\service
    • Credential Provider: c:\ProgramData\BeyondIdentity\Logs\credprovider

 

  1. Important PowerShell modules:
    • AzureAd
    • ActiveDirectory
    • whfbtools
    • MSAL.PS
    • ADSync

 

  1. To debug issues with Desktop login keys getting overwritten in the AD use the steps described in following Microsoft articles to delete the orphaned keys:

https://support.microsoft.com/en-us/topic/using-whfbtools-powershell-module-for-cleaning-up-orphaned-windows-hello-for-business-keys-779d1f3f-bb2d-c495-0f6b-9aeb940eeafb

This issue happens if the device was hybrid joined and the key was written in AAD and AD and then later on device is joined with AD only then the keys will periodically get overwritten from AAD to AD because the AAD is not aware of user unenrolling from WHFB.

 

  1. If an enterprise does not have ADCS and certificates are generated using Standalone CA or third party Public CA then root, intermediate and domain controller certificates need to be published and imported into NTAuth Store using following commands. 
  • certutil -viewstore -enterprise NTAuth (To view content of NTAuth Store)
  • certutil -dspublish -f ca_name.cer NTAuthCA (Publish CA certificate into the NTAuth Store / Active Directory)
  • certutil -dspublish -f sub_ca_name.cer SubCA (Publish Sub CA certificate to DS CA Object)
  • certutil -enterprise -addstore NTAuth issuing_ca_name.cer (Import CA certificate into ENterprise NTAuth Store, This is required only in some scenarios)

 

  1. Domain Controller Certificate requirements:

Source: https://learn.microsoft.com/en-us/windows/security/identity-protection/hello-for-business/hello-hybrid-cert-trust-validate-pki

The certificates issued to the domain controllers must meet the following requirements:

  • The Certificate Revocation List (CRL) distribution point extension must point to a valid CRL, or an Authority Information Access (AIA) extension that points to an Online Certificate Status Protocol (OCSP) responder
  • Optionally, the certificate Subject section could contain the directory path of the server object (the distinguished name)
  • The certificate Key Usage section must contain Digital Signature and Key Encipherment
  • Optionally, the certificate Basic Constraints section should contain: [Subject Type=End Entity, Path Length Constraint=None]
  • The certificate extended key usage section must contain Client Authentication (1.3.6.1.5.5.7.3.2), Server Authentication (1.3.6.1.5.5.7.3.1), and KDC Authentication (1.3.6.1.5.2.3.5), and Smart Card Authentication
  • The certificate Subject Alternative Name section must contain the Domain Name System (DNS) name
  • The certificate template must have an extension that has the value DomainController, encoded as a BMPstring. If you are using Windows Server Enterprise Certificate Authority, this extension is already included in the domain controller certificate template
  • The domain controller certificate must be installed in the local computer's certificate store
  1. In case Windows Desktop Login fails to authenticate the user with the error message (status 0xc00000bb) then it has been tracked back to issue with Domain Controller server certificate not being valid. Performing the following tasks may resolve this issue.
  • Delete Old certificate on each DC in the domain.
  • Publish revocation list from CA as explained in following article.
  • Issue new certificate for each DC in the domain.

 

  1. Commands to list and remove previously configured smart cards.
  • wmic path win32_PnPEntity where "ClassGuid like '{50DD5230-BA8A-11D1-BF5D-0000F805F530}'" get DeviceID,Name,Status
  • tpmvscmgr destroy /instance ROOT\SMARTCARDREADER\0000



  1. Steps to unenroll users from Beyond Identity Desktop Login Service.
  • Exit Beyond Identity Authenticator (File > Exit)
  • Delete Cache Data folder on Windows Machine from C:\ProgramData\BeyondIdentity folder.
  • Issue the above two commands for deleting previously created smart cards.

 

  1. In case Beyond Identity Passwordless desktop login does not work when the machine is not joined to the domain by direct line of sight (on the same network or via VPN), please ensure the following registry key is set to appropriate value to allow cached credentials.
  • HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\Winlogon\ >= 10
  • Further details in the following article: 

https://docs.microsoft.com/en-us/troubleshoot/windows-server/user-profiles-and-logon/cached-domain-logon-information

 



Related articles

Comments

0 comments

Please sign in to leave a comment.