======================================
Configuring Repository to use Kerberos
======================================


Kerberos is an authentication protocol designed to allow nodes
communicating over an insecure network to verify identity. Repository
can use Kerberos to authenticate users.

The Kerberos protocol uses timestamps to prevent replay attacks on
expired credentials, so the Network Time Protocol (NTP) service must
be set up and working correctly.

Several aspects of Kerberos rely on name service. Your domain name
system (DNS) entries and your hosts must have the correct information.
The ``hostname`` command and the configuration file ``/etc/hostname``
must reflect the fully-qualified domain name (FQDN) of the machine.
The configuration file ``/etc/hosts`` must include an entry with the
FQDN, to allow reverse-DNS lookups to be performed.

To allow clients to authenticate against Anaconda Repository, create a
principal for the service with a private key that identifies the
service. Create a service principal ``HTTP/your.anaconda.repository``, and
create the keytab containing this principal to
``$PREFIX/etc/anaconda-server/http.keytab``:

.. code-block:: bash

   SERVER_NAME=your.anaconda.repository

NOTE: Replace ``your.anaconda.repository`` with your server IP
address or domain name.

.. If you are using FreeIPA:

   .. code-block:: bash

      ipa service-add HTTP/$SERVER_NAME
      ipa-getkeytab -p HTTP/$SERVER_NAME -k /etc/binstar/http.keytab

If you are using MIT Kerberos:

.. code-block:: bash

   kadmin -q "addprinc HTTP/${SERVER_NAME}"
   kadmin -q "ktadd -k $PREFIX/etc/anaconda-server/http.keytab HTTP/${SERVER_NAME}"
   chown anaconda-server:anaconda-server $PREFIX/etc/anaconda-server/http.keytab
   chmod 600 $PREFIX/etc/anaconda-server/http.keytab



If you are using Active Directory:

#. Open Active Directory Users and Computers.

#. Select the Users container.

#. In the **Action** menu, select New, then select User.

#. In the New Object - User dialog, type the user information. In
   this example, we use ``your-anaconda-repository`` as the login.

#. In the next dialog, select the options Password never expires and
   User cannot change password.

#. Right-click on the newly created user, and select Properties.

#. In the Properties dialog, select the **Account** tab, and ensure the
   Do not require Kerberos preauthentication option is selected.

#. Open an Administrative prompt and run:

   .. code-block:: bash

      ktpass -princ HTTP/your.anaconda.repository@YOUR.DOMAIN -out http.keytab -pass "*" -mapUser your-anaconda-user@your-anaconda-server -ptype KRB5_NT_PRINCIPAL

#. Copy the newly created file ``http.keytab`` to
   ``$PREFIX/etc/anaconda-server/http.keytab`` on your Repository
   server.

To enable Kerberos authentication on Repository, add the configuration
options to ``$PREFIX/etc/anaconda-server/config.yaml``:

.. code-block:: yaml

    AUTH_TYPE: KERBEROS
    KRB5_KTNAME: /home/anaconda-server/repo/etc/anaconda-server/http.keytab

For a minimal configuration example see :doc:`kerberos-example`.


.. _kerberos-configuration-options:

Kerberos configuration options
==============================

.. list-table::
   :widths: 20 20 60

   * - AUTH_TYPE
     - string
     - Configures the authentication scheme used for Repository.
       Set to ``KERBEROS`` to enable Kerberos authentication.
       Default: ``NATIVE``.
   * - KRB5_KTNAME
     - string
     - The file path of the keytab containing the service
       principal for Repository. Default: ``/etc/krb5.keytab``.
   * - KRB5_SERVICE_NAME
     - string
     - The service type used to identify the service principal
       for Repository. ``HTTP`` in
       ``HTTP/your.anaconda.repository@YOUR.REALM``. Default:
       ``HTTP``.
   * - KRB5_HOSTNAME
     - string
     - The hostname used to identify the service principal for
       Repository. ``your.anaconda.repository`` in
       ``HTTP/your.anaconda.repository@YOUR.REALM``. Default: the
       hostname of the machine on which Repository is running.
