.. md_auto_install.rst .. _md-auto-install-label: ======================= Automated Installation ======================= This section provides configuration requirements and guidance for deploying YKMD in an enterprise environment. The steps provided allow YKMD to be pushed out to all workstations from a central repository, without requiring administrative rights on the local workstation. There are two ways to automate installing YKMD: Method 1 Auto-install using a Startup Script. This is recommended for most environments. Create a startup script that can be pushed out via Group Policy Object (GPO). This automatically installs YKMD on ALL devices in the computer object OU that the GPO is linked to. Method 2 End user install using Device Manager. This is recommended when YKMD needs to be available to a large number of users but only installed on an as-needed basis: Create a registry entry on all client workstations with a GPO setting allowing standard users to update the inbox drivers to YKMD, without requiring an admin to physically touch or access the machine for the install. This way, the users can insert the YubiKey, launch the Device Manager, and automatically update the smart card driver to the latest version of YKMD. .. Note:: The version number shown below (4.6.3.252) is only an example. The actual number changes as downloads are updated. .. _md-group-policy-install-label: Installing via Group Policy Object ==================================== For large deployments, YKMD can be centrally installed via Group Policy Objects. By leveraging a PowerShell script for the necessary commands and a shared network drive accessible from every client station to distribute the YKMD files, an Administrator can automate the installation. When creating an installation script, an Administrator needs to ensure they define registry entries for the PUK Policy, the Touch Policy and the Debug Log Policy, as well as installing the INF file directly. Preparing the Deployment Environment ===================================== The process for deploying the YKMD ``.cab`` file requires every endpoint to be connected to the enterprise GPO domain and to have access to a shared directory. For machines where this is not an option, such as those on isolated networks, YKMD needs to be installed manually. .. _md-driver-store-label: Creating the Driver Store ========================== The first step to deploying YKMD is creating a network shared directory for the YKMD ``.cab`` file. If you already have a network share for driver software, we recommend using the existing location. If not, you need to create a shared network folder, which is accessible with read and execute permissions for all users. For this example, we create a new folder in the ``Z:\`` drive. 1. Open File Explorer and browse to ``Z:\``. 2. Create a new folder, such as: **SoftwareShare**. For example: .. figure:: /graphics/share_drive_create.png :align: center :width: 50% 3. Inside this folder, create another folder, for example named **YKMD**. You can build this file structure per your standard naming convention. 4. Ensure the read, write, execute permissions on the folder are set as follows: * Read / Execute for **Everyone** or **Authenticated Users** * Read / Write / Execute for **Administrators** .. figure:: /graphics/share-properties-tab.png :align: center :width: 75% *Share network path.* .. figure:: /graphics/share-security-setting-all.png :align: center :width: 75% *Authenticated users permissions settings* .. figure:: /graphics/share-security-setting-admin.png :align: center :width: 75% *Administrators permission settings* Method 1 - Auto-Install via Startup Script =========================================== This process creates a PowerShell script for installing YKMD. This script is run with elevated permissions via GPO. It deploys YKMD upon startup, and continues to do so until the GPO object is disabled or removed. Create the Minidriver Zip File ------------------------------- The PowerShell script deploys YKMD to the client machines as a zip file. Download the latest version of the YKMD and add it to a zip file named ``YKMD.zip``. Create the PowerShell Script ----------------------------- The PowerShell script used for the install script connects an endpoint to the shared network folder created previously. See :ref:`md-driver-store-label`. 1. Copy the YKMD components to a local directory on the machine and install YKMD. 2. Create a PowerShell script with all the following items. a. Define the environmental variables at the start of the script. b. Copy the ``YKMD.zip`` to a shared folder which users have read permissions to replace the server with name of server that hosts the ``YKMD.zip``. ``$server="Server"`` c. Replace ``folder_name`` with name of shared folder on the network. ``$shared_folder = "shared"`` d. Set ``temp`` folder location. ``$temp = "$env:windir\temp"`` e. Add ``file_name``. The version number, ``4.6.3.252``, is an example. The actual number changes as downloads are updated. ``$YKMD = "YubiKey-Minidriver-4.6.3.252.cab.sha256"`` f. Add driver path. ``$DriverPath = "$env:windir\System32\DriverStore\FileRepository"`` g. Replace ``folder_name`` with folder name of destination. ``$destination = "YKMD"`` h. Set full path. ``$fullpath = $temp+"\"+$destination`` i. Add logging actions and create folder for logging and troubleshooting data. ``$logdir = "$temp\logs";`` ``$logfile = "yubikey.log"`` ``$logfullpath = $logdir+"\"+$logfile;`` j. Create folder to save logs. ``New-Item $logdir -ItemType Directory -force;`` k. Start recording logs. This doesn't work if the script is run remotely. ``Start-Transcript -Path $logfullpath -force;`` l. Download YKMD from the shared folder and install. ``copy-item "\\$server\$shared_folder\YKMD.zip" -Destination $temp -force;`` m. Extract the contents of the zip folder. ``Expand-Archive -Path "$temp\YKMD.zip" -DestinationPath $fullpath -force;`` n. Extract the contents of the ``.cab`` file. ``cmd.exe /c expand $fullpath\$YKMD -F:* $fullpath | Out-Null`` o. Install the ``.inf`` driver. ``Get-ChildItem $fullpath -Recurse -Filter "*inf" | ForEach-Object { PNPUtil.exe /add-driver $_.FullName /install }`` p. Import the registry keys. ``rundll32.exe setupapi.dll,InstallHinfSection Yubico64_61_Install 132 $fullpath\YKMD.inf`` q. Remove the comment ``#`` from next line to create the device node or leave the comment to let Windows handle creating the device node when the YubiKey is inserted. ``#cmd.exe /c DrvInst.exe "5" "2" "$DriverPath\YKMD.inf_amd64_24989c5c4b9230ad\YKMD.inf" "0" "4e6904753" "0000000000000238" "WinSta0\Default"`` r. Enable the Smart Card Service. ``Get-Service -Name "Scardsvr" | Set-Service -StartupType Automatic`` s. Stop logging. ``Stop-Transcript`` 3. Save this PowerShell script (``.ps1``) on the Windows Server for deployment. Configure the GPO ------------------ After the installation PowerShell script file is created, create the Group Policy Object to run the script. To do this, create a new GPO and link it to the location of the computer objects which require YubiKey Minidriver. 1. Click **Start > Run > gpmc.msc**. 2. Navigate to your domain and locate the OU for the computer objects. 3. Right-click and select **Create a GPO in this domain and Link it here**. 4. Create a descriptive name for this GPO, such as: **YKMD Deploy**. Example: .. figure:: /graphics/gpo-naming.png :align: center :width: 100% Edit YKMD Deploy GPO --------------------- 1. Right-click the new YKMD Deploy GPO and select **Edit**. 2. Expand **Computer Configuration > Policies > Windows Settings > Scripts (Startup/Shutdown)**. 3. Right-click **Startup** and select **Properties**. a. Select **Add** then **Browse**. b. Using another file explorer window, browse to your startup script (``.ps1``), then copy and paste the file into the **File name** field. .. figure:: /graphics/gpo-network-properties.png :align: center :width: 100% c. Select the file, then select **Open**. d. With the script in the **Script Name** field, select **OK**. .. figure:: /graphics/gpo-add-script.png :align: center :width: 100% 4. Select **OK** once more to complete the GPO configuration. Method 2 - Standard User Install (Manual Update) ================================================= This process configures endpoints to make YKMD available to install when the standard user is ready. This does not install YKMD until the user requests it via the Device Manager. Preparing YKMD for Distribution ------------------------------- 1. Download YKMD from the Yubico Support site. a. See `Windows Smart Card Applications and Tools `_ b. Scroll down the page to **YubiKey Smart Card Minidriver (Windows)**. c. Download the latest release of the YubiKey Minidriver. 2. Extract the downloaded contents: .. figure:: /graphics/extract-cab-file.png :align: center :width: 100% a. Browse to your downloads directory. b. Double click the YKMD ``.cab`` file to open and view the contents. c. Select **All**. d. Right-click > **Extract**. e. Select either a local directory or extract directly to the fileshare created in previously. See :ref:`md-driver-store-label`. .. _md-config-gpo-label: Configure the GPO ------------------ Confirm that the file share is configured and accessible to all client workstations, and that YKMD is extracted to that directory. Once this is accomplished, proceed to configure the GPO. The Group Policy Object handles two things: * Making the client workstations aware of the location of YKMD. This is accomplished via an updated Registry setting. * Allowing standard users to install YKMD without requiring admin privileges. This is accomplished via whitelisting the GUID of YKMD. .. _md-create-gpo-label: Create a new GPO ~~~~~~~~~~~~~~~~~ In the location of the computer objects that require YKMD, create a new GPO and link it. 1. Click **Start > Run > gpmc.msc**. 2. Navigate to your Domain and locate the OU for the computer objects. 3. Right-click and select **Create a GPO in this domain and Link it here**. 4. Create a descriptive name for this GPO, such as: **YKMD Deploy**. For example: .. figure:: /graphics/gpo-deploy-file.png :align: center :width: 100% 5. Edit this GPO to complete the configuration. Complete the steps in the following sections. Client Registry Setting ------------------------ Update device path ~~~~~~~~~~~~~~~~~~~ Update the existing **Device Path** registry setting to reference the newly created driver store. 1. Right-click the new YKMD Deploy GPO and select **Edit**. 2. Expand **Computer Configuration > Preferences > Windows Settings > Registry**. 3. Right-click **Registry** and select **New > Registry Wizard**. .. figure:: /graphics/new-registry-wizard.png :align: center :width: 100% .. _md-create-registry-label: Create new Registry ~~~~~~~~~~~~~~~~~~~ The Registry wizard walks you through creating the new Registry setting for your client machines. 1. When the registry browser comes up, browse to **Another Computer** or use the **Local Computer** since this registry setting should be the same on both. For this example, we are using **Local Computer**. 2. Select **Local Computer**, then click **Next**. 3. Browse to: **HKLM > Software > Microsoft > Windows > CurrentVersion**. 4. From the **CurrentVersion** panel, in the bottom window, scroll down and select **DevicePath**. For example: .. figure:: /graphics/new-registry-setting.png :align: center :width: 100% 5. Click **Finish**. Update New Registry ~~~~~~~~~~~~~~~~~~~ Update this new Registry value to append the newly created file share to its search locations. You can append any number of fileshare locations, just separate them with a semicolon. 1. Select the **Registry Wizard Values** created in :ref:`md-create-registry-label` and rename it to something more descriptive. For example, **YKMD Deploy**. 2. Fully expand the new registry value. 3. Double-click the **Device Path** so you can edit the contents. .. figure:: /graphics/new-registry-update.png :align: center :width: 100% 4. Update the last field, **Value Data**. To update, add the following to the existing value: ``;\\\\`` Note the semicolon at the beginning of the string. For example: ``%SystemRoot%\inf;\\\SoftwareShare\YKMD`` The final value should resemble the following: .. figure:: /graphics/new-registry-value-data-field.png :align: center :width: 100% 5. Click **Apply**. Then click **OK** to save your settings. Whitelisting the YKMD GUID ----------------------------------------- This step allows a silent install that does not require the user to elevate to an admin account. .. _md-locate-guid-label: Locate the GUID of YKMD ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1. Browse to the extracted contents of the YKMD ``.cab`` file. 2. Select the file ``YKMD.inf``, right-click and open with a text editor. 3. Find the line ``ClassGuid=``. For example: .. figure:: /graphics/locate-guid.png :align: center :width: 100% 4. Copy and paste the full content of that line after the ``=``. For example: ``ClassGuid={990A2BD7-E738-46c7-B26F-1CF8FB9F1391}`` The GUID: ``{990A2BD7-E738-46c7-B26F-1CF8FB9F1391}`` brackets included, is what we are whitelisting. Enable and Configure Group Policy ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Enable and configure the Group Policy with the updated GUID value: 1. Select the Group Policy **YKMD Deploy** created earlier. See :ref:`md-config-gpo-label`. 2. Browse to: **HKLM > Policies > System > Driver Installation**. 3. Select **Allow non-administrators to install drivers for these device setup classes**. 4. Right-click, and select **Edit**. a. Select **Enabled**. b. Under Options on the bottom left, select **Show**. c. Add the GUID Value from :ref:`md-locate-guid-label` into the next open line. If you have not used this before, this is the first line. For example: .. figure:: /graphics/gpo-enable.png :align: center :width: 100% d. Select **OK > Apply > OK**. Completing the Installation ============================ Confirm the following installation steps are completed. 1. Creation of a network file share to host and distribute YKMD. 2. Download and extraction of YKMD. 3. GPO created and applied to the computer objects which require YKMD. 4. GPO configured based on Method 1 or Method 2 below: Method 1 Push the PowerShell script file to auto-install YKMD. Method 2 a. Client-side registry update. b. Whitelist of YKMD GUID for installation by non-admin users. .. Important:: If any of the above is not completed, review the instructions in this chapter, before proceeding. Issue a Group Policy Update ---------------------------- This can be issued as soon as Method 1 or Method 2 tasks are completed. **The version numbers shown are examples**. The actual number changes as YKMD is updated. 1. Refresh the Group Policy for all clients and publish the new changes. From the command line, issue the command: ``gpupdate /force`` For example: .. figure:: /graphics/gpo-force-update-command.png :align: center :width: 80% 2. If the client computer does not have YKMD installed: Method 1 The end-user must reboot their computer. YKMD is installed during the next reboot. Method 2 The end-user updates YKMD through the Device Manager. a. Launch the **Device Manager**. b. Select YKMD. c. Select **Update > Search automatically for updated driver software**. 3. Confirm YKMD is successfully installed. Open **Device Manager**. .. figure:: /graphics/ykmd-successful-install.png :align: center :width: 100%