.. installation.rst

===============
Install the App 
===============

Once you have :ref:`downloaded <ykauth-download>` the Yubico Authenticator app, follow the installation instructions listed here for your chosen platform.

macOS 
=====

Yubico Authenticator installation on macOS is slightly different for :ref:`direct downloads <installation-mac-direct>` vs. :ref:`Mac App Store <installation-mac-app-store>`. However, both methods require you to :ref:`enable input monitoring <installation-input-monitoring>` and :ref:`screen recording <installation-screen-recording>` after installation.

.. _installation-mac-direct:

Installation via direct download 
--------------------------------

If you :ref:`downloaded the .dmg file from the Yubico website <ykauth-download>`, do the following:

#. Double-click on the `yubico-authenticator-<version>.dmg` file. 

#. Drag the Yubico Authenticator icon to the Applications folder when prompted.

    .. image:: /images/mac-direct-install.jpg
       :width: 450

#. :ref:`Enable input monitoring <installation-input-monitoring>` and :ref:`screen recording <installation-screen-recording>`.

.. _installation-mac-app-store:

Installation via the Mac App Store 
----------------------------------

If you want to :ref:`install the app via the Mac App Store <ykauth-download-mac>`, do the following:

#. On the Yubico Authenticator page in the Mac App Store, click **Get**. Once the app has been downloaded, the blue **Get** button will change to a green **Install** button. 

#. Click the **Install** button. Enter your Apple ID and password when prompted. 

    .. image:: /images/mac-store-install.jpg
       :width: 500

#. :ref:`Enable input monitoring <installation-input-monitoring>` and :ref:`screen recording <installation-screen-recording>`

.. _installation-input-monitoring:

Enable input monitoring 
-----------------------

Before you can use the :ref:`Slots <yubico-otp>` feature of Yubico Authenticator, you must enable input monitoring. These special permissions are required because the YubiKey's Yubico OTP application, which you interact with via **Slots**, communicates with your Mac as if it were an external keyboard.

To enable input monitoring, do the following:

#. Open the Yubico Authenticator app and insert a YubiKey into your Mac. 

#. Click on **Slots**. 

#. A **Keystroke Receiving** window should pop up. Click on **Open System Settings**.

    .. image:: /images/keystroke-receiving.jpg
       :width: 400

#. This will take you to your **Input Monitoring** settings. Flip the toggle next to **Yubico Authenticator** to the "on" position. 

    .. image:: /images/input-monitoring.jpg
       :width: 450

#. If the Yubico Authenticator app is still open, another window will pop up prompting you to restart the app to apply the new settings. Click **Quit & Reopen**.

    .. image:: /images/quit-and-reopen.jpg
       :width: 225

.. note:: If you are not automatically prompted to change your input monitoring settings when opening the app for the first time, you can still do this manually by going to **System Settings** > **Privacy & Security** > **Input Monitoring**. Click the + icon, select the Yubico Authenticator app in the window that appears, and click **Open**. 

.. _installation-screen-recording:

Enable screen recording 
-----------------------

Before you can add new :ref:`OATH accounts <oath>` via QR code, you must enable screen recording. You will be prompted to do this the first time you attempt a QR scan, but you can also set these permissions manually by doing the following:

#. On your macOS device, go to **System Settings** > **Privacy & Security** > **Screen & System Audio Recording**.

#. If you do not see Yubico Authenticator on the list yet, add it by clicking the plus symbol, selecting the app, and clicking **Open**.

#. Set the toggle next to Yubico Authenticator to the "on" position.

    .. image:: /images/installation-screen-recording.jpg
       :width: 450

.. _ykauth-desktop-windows-label:

Windows 
=======

If you :ref:`downloaded the .msi file from the Yubico website <ykauth-download>`, double-click the `yubico-authenticator-<version>-win64.msi` file and follow the prompts to complete installation.

Alternatively, you can install Yubico Authenticator for Windows via the :ref:`Microsoft Apps Store <ykauth-download-windows>`.

Linux 
=====

Once you have :ref:`downloaded the tar.gz file from the Yubico website <ykauth-download>`, extract the folder where the app has permissions to run. 

Enable pcscd 
------------

Before you can use the :ref:`Accounts <oath>` (OATH) and :Ref:`Certificates <piv-certficates>` (PIV) features of Yubico Authenticator, you must enable pcscd, which allows communication over the CCID interface. 

To enable and start pcscd on most Linux systems, run:

.. code-block:: 

    sudo systemctl enable --now pcscd

To check if pcscd is running, enter:

.. code-block:: 

    systemctl status pcscd

To check if pcscd is enabled, enter:

.. code-block:: text

    systemctl is-enabled pcscd

QR scanning
-----------

For Linux machines running the `Wayland <https://wayland.freedesktop.org/>`_ graphical environment, the QR scanning feature (used when adding a new :ref:`OATH account <oath>`) requires either the `gnome-screenshot <https://help.gnome.org/users/gnome-help/stable/screen-shot-record.html.en>`_ tool (when running the Gnome desktop environment) or the `Spectacle <https://apps.kde.org/spectacle/>`_ tool (when running the KDE desktop environment).

Running the app 
---------------

To run the Yubico Authenticator for Linux app, change your path to wherever the executable is located and enter ``./authenticator``.

Alternatively, you can create a shortcut for Yubico Authenticator in the app launcher by running the `desktop_integration.sh script <https://github.com/Yubico/yubioath-flutter/blob/main/resources/linux/desktop_integration.sh>`_, which is included in the tarball. 

Installing older versions of Yubico Authenticator for Linux 
-----------------------------------------------------------

To install an older version of Yubico Authenticator for Linux (5.1 and previous), follow the instructions on the `Support site <https://support.yubico.com/hc/en-us/articles/360016649039-Installing-Yubico-Software-on-Linux#01H30DFPTR4TYSEA38X13HY4YQ>`_.

Android 
=======

To install Yubico Authenticator for Android, go to the Yubico Authenticator page in the :ref:`Google Play Store <ykauth-download-android>` and click **Install**.

.. image:: /images/android-install.jpg
    :width: 400

USB permissions
---------------

When you open the app and connect a new YubiKey to your Android device over USB, you may be prompted to allow the app to communicate with the key over the USB interface. The USB device name for the key is often listed as "YubiKey OTP+FIDO+CCID". Click **OK**.

.. image:: /images/android-open-app.jpg
    :width: 400

Installation via direct download 
--------------------------------

You may also :ref:`download the .apk file directly <ykauth-download>`. To install, click on the .apk file and follow the prompts. Your device may request permission to install apps downloaded from your browser.

iOS and iPadOS
==============

To install Yubico Authenticator for iOS/iPadOS, go to the Yubico Authenticator page in the :ref:`App Store <ykauth-download-ios>` and click **Get**. Authenticate with your Apple account information when prompted. Once downloaded, click **Open** to open the Yubico Authenticator app.

.. image:: /images/download-ios.jpg
    :width: 400

Developers 
==========

For developers wishing to build and package the Yubico Authenticator app from source, please see the GitHub documentation for your desired platform:

- `Desktop and Android <https://github.com/Yubico/yubioath-flutter/blob/main/doc/Development.adoc>`_
- `iOS/iPadOS <https://github.com/Yubico/yubioath-ios/blob/main/README.md>`_