.. _integration:

Integration examples
--------------------

.. _otp_apache:

OTP Authentication with an Apache web server
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

There are two possible RADIUS authentication modules for Apache. ``mod_auth_radius`` is packed
with the FreeRADIUS server. ``mod_auth_xradius`` can be downloaded from http://outoforder.cc.

Previous versions of ``mod_auth_radius`` had the problem to not work with OTPs, but this is now fixed in
the current version.

This describes the use with ``mod_auth_xradius``.

.. note:: If you do not want to use RADIUS, you can also use the module ``mod_authn_linotp``, which is available on
          GitHub.

Download
........

Go to http://www.outoforder.cc/projects and download ``apr_memcache`` and ``mod_auth_xradius``.
You will also need to install ``apache2-prefork-dev`` , ``apache2-utils`` , ``libmemcache-dev and libapreq2-
dev`` [#xradius]_

.. [#xradius] These are Debian package names. On other distributions the names may vary.

Compile
.......
First you need to compile ``apr_memcache``. The authentication module uses the memcache client to
talk to the memcached daemon.

In the ``apr_memcache`` source directory a::

   ./configure prefix=/usr
   make && make install

should do.

Now you can compile ``mod_auth_xradius``::

   ./configure --with-apxs=/usr/bin/apxs2
   make && make install


Configuration
.............

Now you need to assure, that the memcached daemon is started at system boot time. There are
different ways depending on your distribution.

Your Apache configuration might look like this::

   LoadModule auth_xradius_module /usr/lib/apache2/modules/mod_auth_xradius.so
   AuthXRadiusCache memcache "127.0.0.1:11211"
   ## 10h Timeout in seconds.
   AuthXRadiusCacheTimeout 36000
   <VirtualHost *>
     ServerName secret-site3
     ServerAdmin webmaster@localhost
     DocumentRoot /var/www/secure
     <Directory /var/www/secure/>
        Options Indexes FollowSymLinks MultiViews
        AllowOverride None
        Order allow,deny
        allow from all
        AuthType Basic
        require valid-user
        AuthBasicProvider xradius
        AuthName "Please enter your username and OTP-Password and OTP-PIN"
        AuthXRadiusAddServer "localhost:1812" "testing123"
        AuthXRadiusTimeout 7
        AuthXRadiusRetries 2
     </Directory>
     ErrorLog /var/log/apache2/error.log
     LogLevel debug
     CustomLog /var/log/apache2/access.log combined
     ServerSignature On
   </VirtualHost>

Firewall integration
~~~~~~~~~~~~~~~~~~~~

One common scenario is to use one time passwords for remote access via SSL VPNs. In case of
the Astaro Security Gateway it could look like this.

Within Users → Authentication → Servers you need to add your LinOTP host. (see :ref:`figure_astaro1`)


.. _figure_astaro1:
.. figure:: ../images/astaro1.png
   :width: 100%

   *Configure Astaro Security Gateway. Add LinOTP host.*

Choose “RADIUS” for the new server and enter the shared secret that was configured on the
RADIUS server on your LinOTP machine. (see :ref:`figure_astaro2`)

.. _figure_astaro2:
.. figure:: ../images/astaro2.png
   :width: 100%

   *Configure Astaro Security Gateway. Enter RADIUS shared secret.*

You may now test your setup by entering a valid username and its corresponding OTP PIN and
OTP value.


.. _figure_astaro3:
.. figure:: ../images/astaro3.png
   :width: 100%

   *Configure Astaro Security Gateway. Test your setup.*

You are now ready to use this setup to bind the authentication to the users. (see :ref:`figure_astaro3`)

.. note:: With the FreeRADIUS module of LinOTP 2.2 mschapv2 is not supported.
   Thus OTP can only be used for SSL VPN but not for PPTP.


.. index:: RSA, Migration

Authentication with third party OTP solutions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you need to authenticate users with existing tokens, that are not supported by LinOTP you can setup
the FreeRADIUS server to decide, if a user is authenticated against LinOTP or the other solution like
RSA SecurID(R) or other unsupported token systems.

A common scenario is to have the FreeRADIUS server check, if a user is a member of a certain
LDAP [#ldapad]_ group.

.. [#ldapad] Of course, this also works for Active Directory.

By putting users in certain LDAP groups, you can define which backend system should authenticate the user:

If the user is either a member of this group you could have the request handled by LinOTP. If the
user is not a member of this group the authentication
request can be forwarded to another RADIUS server.

In the below example we will use the reverse logic and forward the authentication request to
another 3rd party RADIUS server, *if* the user is a member of this group.

Configure FreeRADIUS LDAP
.........................
First you need to define the LDAP connection of your FreeRADIUS server.

Edit the file ``/etc/freeradius/modules/ldap`` like this::

   ldap instance1 {
        #
        #  Note that this needs to match the name in the LDAP
        #  server certificate, if you're using ldaps.
        server = "172.16.200.61"
        # The DN of the user you are using to authenticate
        identity = "cn=admin,ou=linotp,dc=linotp-test,dc=local"
        password = your_password
        # BaseDN to search the users
        basedn = "ou=linotp2,dc=linotp-test,dc=local"
        filter = "(sAMAccountName=%{%{Stripped-User-Name}:-%{User-Name}})"
        #  How many connections to keep open to the LDAP server.
        #  This saves time over opening a new LDAP socket for
        #  every authentication request.
        ldap_connections_number = 5
        # seconds to wait for LDAP query to finish. default: 20
        timeout = 4
        #  seconds LDAP server has to process the query (server-side
        #  time limit). default: 20
        #
        #  LDAP_OPT_TIMELIMIT is set to this value.
        timelimit = 3
        #
        #  seconds to wait for response of the server. (network
        #   failures) default: 10
        #
        #  LDAP_OPT_NETWORK_TIMEOUT is set to this value.
        net_timeout = 1
        tls {
                start_tls = no
        }
        dictionary_mapping = ${confdir}/ldap.attrmap
        edir_account_policy_check = no
        groupmembership_filter = "(&(objectClass=group)(member=%{control:Ldap-UserDn}))"
   }

You can define many different ldap instances by repeating the ``ldap`` block multiple times.

Configure FreeRADIUS proxy
..........................

In a RADIUS sense the third party server is a RADIUS proxy. Thus we need to define such a proxy in the
file ``/etc/freeradius/proxy.conf``::

   realm FARWARDSERVER {
      	authhost = 3rd.party.server:1812
     	accthost = 3rd.party.server:1813
     	secret   = radius-secret
   }

LinOTP's FreeRADIUS needs to be configured as a RADIUS client on the 3rd party server.
The 3rd party server and the RADIUS secret need to be configured in the above config file.

Configure proxy decision
........................
Finally we need to configure the decision in which case the request is handled by LinOTP and in which case the
request will be handled by the 3rd party server. This is done by adapting the ``authorize`` section
in ``/etc/freeradius/sites-enabled/linotp``::

   authorize {
      [...]
      #
      # put the ldap instance here
      #
      instance1

      if ( instance1-Ldap-Group == "cn=3rdpartyusers,ou=linotp,dc=linotp-test,dc=local" ) {
        update control {
            Proxy-To-Realm = "FORWARDSERVER"
        }
      }
   }

Then all users that are member of the group **3rdpartyusers** will be forwarded to the 3rd party servers and
all other users will be authenticated by LinOTP.

If you need to define more complex conditions take a look at the FreeRADIUS unlang [#unlang]_.

.. [#unlang] http://freeradius.org/radiusd/man/unlang.html


.. include:: freeradius_groups_clients.rst
.. include:: map_client_realm.rst
.. include:: freeradius_ntdomain.rst


LinOTP and MIT Kerberos
~~~~~~~~~~~~~~~~~~~~~~~

.. index:: MIT Kerberos, Single Sign On, Kerberos

.. warning:: This example does not give you an introduction to Kerberos. Unless you have
   a certain knowledge of Kerberos and MIT Kerberos, you should not read this.
   Providing any basic introduction to Kerberos is out of the scope of
   this documentation. As a starting point you should read the Kerberos
   documentation  http://web.mit.edu/kerberos/krb5-devel/doc/ "For Users" and "For Administrators".

Starting with version 1.12 MIT Kerberos comes with support for OTPoverRADIUS. By the time
of writing 1.12 was not released, yet, so you need to get the sources from github::

   git clone https://github.com/krb5/krb5
   apt-get install libcurl4-openssl-dev
   apt-get install autoconf automake make yacc
   autoreconf -i
   util/reconf
   ./configure
   make all

To verify, if your Kerberos was compiled with OTP support, check for the following files::

   ./lib/krb5/krb/preauth_otp.so
   ./plugins/preauth/otp/otp_state.so

After that, install the Kerberos system::

   make install

You need to create a krb config file ``/etc/krb5.conf`` like this::

   [libdefaults]
      default_realm = TEST.KEYIDENTITY.DE

   [realms]
      TEST.KEYIDENTITY.DE = {
      kdc = kerberos
      admin_server = kerberos
     }

   [logging]
      kdc = FILE:/var/log/krb5kdc.log
      admin_server = FILE:/var/log/kadmin.log
      default = FILE:/var/log/krb5lib.log

and a kdc config file ``/usr/local/var/krb5kdc/kdc.conf``::

   [kdcdefaults]
      kdc_ports = 750,88

   [realms]
      TEST.KEYIDENTITY.DE = {
         database_name = /usr/local/var/krb5kdc/principal
         acl_file = /usr/local/var/krb5kdc/kadm5.acl
         key_stash_file = /usr/local/var/krb5kdc/.k5.TEST.KEYIDENTITY.DE
         kdc_ports = 750,88
         max_life = 10h 0m 0s
         max_renewable_life = 7d 0h 0m 0s
   }

Run::

   kdb5_util create -r TEST.KEYIDENTITY.DE -s

Create the administrator::

   # kadmin.local
   Authenticating as principal root/admin@TEST.KEYIDENTITY.DE with password.
   kadmin.local:  addprinc admin/admin@TEST.KEYIDENTITY.DE
   WARNING: no policy specified for admin/admin@TEST.KEYIDENTITY.DE; defaulting to no policy
   Enter password for principal "admin/admin@TEST.KEYIDENTITY.DE":
   Re-enter password for principal "admin/admin@TEST.KEYIDENTITY.DE":
   Principal "admin/admin@TEST.KEYIDENTITY.DE" created.
   kadmin.local:  quit

Start the daemons::

   /usr/local/sbin/krb5kdc
   /usr/local/sbin/kadmind


With the kadmin-tool you need to configure pre authentication for those users, who should use OTP::

   modify_pricipal +requires_preauth otpuser

Setting up OTP with Kerberos
............................

Basic information can be found at the MIT Kerbers Wiki [#kerberoswiki]_.

.. [#kerberoswiki] http://k5wiki.kerberos.org/wiki/Projects/OTPOverRADIUS

To enable OTP for a user you need to set an OTP-string in kadmin::

   set_string otpuser otp [{}]

If you set the otp-string to ``[{}]`` then the default OTP configuration will be used.
The default OTP configuration can be set up in the config file
``/usr/local/var/krb5kdc/kdc.conf``::

   [otp]
      DEFAULT = {
         server = your-lintop-server:1812
         secret = your-radius-secret
         strip_realm = true
   }

Setting up FAST
...............

.. index:: Anonymous PKINIT, FAST

As the OTP value is wired to the KDC, we need to setup FAST [#fast]_. For this
the client needs a ticket to encrypt the tunnel.

For this every ticket on the client could be used.
For convenience and as it plays nice with
``pam_krb5``, we set up anonymous PKINIT.
In anonymous PKINIT only the KDC will get a server certificate. The clients and
users do not need a certificate, which makes the certificate handling not
very complex.

You need to create a user ``WELLKNOWN/ANONYMOUS`` create a CA and the KDC
certificate and
change ``/etc/krb5.conf`` on the KDC and on the clients::

   [realms]
      TEST.KEYIDENTITY.DE = {
      kdc = kerberos
      admin_server = kerberos
      pkinit_anchors = FILE:/root/CA/cacert.pem
   }

On the KDC you also need to provide the private key and thus configure
``/usr/local/var/krb5kdc/kdc.conf`` like this::

   [kdcdefaults]
   kdc_ports = 750,88
   pkinit_identity = FILE:/root/CA/kdc.pem,/root/CA/kdckey.pem
   pkinit_anchors = FILE:/root/CA/cacert.pem


Please refer to [#anonymousPKINIT]_ for setting up anonymous PKINIT.

.. [#fast] Flexible Authentication Secure Tunneling
.. [#anonymousPKINIT]  http://web.mit.edu/kerberos/krb5-latest/doc/admin/pkinit.html#anonymous-pkinit

.. include:: deny_access.rst
.. include:: ldaps.rst