From 77d3beaa86f3618eb615acd62465e567d26d26f7 Mon Sep 17 00:00:00 2001
From: Frederik Lindenaar <frederik@lindenaar.nl>
Date: Sun, 3 May 2015 17:02:27 +0200
Subject: [PATCH] added documentation and configuration example for FreeRadius;
---
README.md | 110 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
privacyidea.freeradiusmodule | 105 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 215 insertions(+), 0 deletions(-)
create mode 100644 privacyidea.freeradiusmodule
diff --git a/README.md b/README.md
index e69de29..38c282c 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,110 @@
+privacyidea-checkotp
+====================
+
+Shell script implementing the [PrivacyIDEA](http://www.privacyidea.org) OTP (One
+Time Password) check to integrate with [FreeRadius](http://www.freeradius.org)
+in environments where the FreeRadius Perl plugin is not available to use the
+standard check script (e.g. on OS X 10.9).
+
+**Version 1.0**, latest version, documentation and bugtracker available on my
+[GitLab instance](https://gitlab.lindenaar.net/scripts/privacyidea-checkotp)
+
+Copyright (c) 2015 Frederik Lindenaar. free for distribution under the GNU
+License, see [below](#license)
+
+
+Introduction
+------------
+When integrating PrivacyIDEA with the stock OS X Server FreeRadius server, I was
+blocked by the installation not including the `rlm_perl` module. This bash
+(shell) script was created to get around that as it is to be executed using the
+FreeRadius `rlm_exec` module. Please bear in mind that this module suits my
+needs and probably still has a few glitches, though it turned out to be a stable
+solution for my needs. In case you have any comments / questions or issues,
+please raise them through my [GitLab instance](https://gitlab.lindenaar.net/scripts/privacyidea-checkotp) so that all users benefit.
+
+Setup
+-----
+This script will be executed using the FreeRadius `rtl_exec` module, which is
+not the most efficient way to integrate but will suffice for low to medium
+volume use. The script depends on `curl` and `sed` being installed, which is
+the case in most environments.
+
+The setup of this solution consists of the following steps:
+
+ 1. Setup PrivacyIDEA and make sure it is working on its own
+ 2. Install the `privacyidea-checkotp` on your FreeRadius server and make it
+ executable
+ 3. Copy the provided `privacyidea.freeradiusmodule` into the FreeRadius
+ `raddb/modules` directory as `privacyidea`
+ 4. Update `raddb/modules/privacyidea` so that `[WRAPPERSCRIPT_PATH]` points to
+ the script as installed in step #1 and `[PRIVACYIDEA_URL]` is replaced with
+ the base URL of your PrivacyIDEA instance.
+ 5. Check your configuration by running the command configured in
+ `raddb/modules/privacyidea` followed by a username and valid
+ password/OTP/PIN combination (depending on your configuration. To avoid the
+ password being captured in your shell history, use `` `cat` `` instead of
+ the password on the commandline and after entering the command, enter the
+ password/OTP/PIN combination as PrivacyIDEA expects followed by an enter
+ and `CTRL-D`.
+ 6. After successfully testing the base setup, add PrivacyIDEA as authorization
+ and authentication provider with the following steps:
+ 1. Open the virtual host file you want to add PrivacyIDEA authentication to
+ (typically in `raddb/sites-available`)
+ 2. In the section `authorize {`:
+ * disable all authorization modules you do not want to succeed
+ * add the following to the bottom of this section:
+
+ ~~~
+ # Use PrivacyIDEA
+ if(! Service-Type == "Outbound-User") {
+ update control {
+ Auth-Type := PrivacyIDEA
+ }
+ }
+ else {
+ # Service-Type == "Outbound-User"
+ if(NAS-Port-Type == "Virtual" && NAS-Port > 0 ) {
+ update control {
+ Auth-Type := Accept
+ }
+ }
+ }
+ ~~~
+
+ 3. In the section `authenticate {`:
+ * Disable all authentication modules you do not want to succeed
+ * add the following to the top of this section so that PrivacyIDEA
+ authentication is tried first:
+
+ ~~~
+ Auth-Type PrivacyIDEA {
+ privacyidea
+ }
+ ~~~
+
+ 7. Last step is to test the configuration, run FreeRadius as `radiusd -X` and
+ check what happens with an authentication requests reaching the FreeRadius
+ server. Specifc requirements on what needs to happen is dependant on your
+ setup (e.g. I am normally not using any PIN codes for the OTP, but require
+ the user's password followed by the OTP).
+
+Please note that this setups works for plain-text (i.e. non-EAP) authentication
+with FreeRadius, which is what my setup needs. The configuration above does not
+work with EAP authentication, I am still working on that (any hints for that are
+welcome!)
+
+<a name="license">License</a>
+-----------------------------
+This script, documentation and configration examples are free software: you can
+redistribute and/or modify it under the terms of the GNU General Public License
+as published by the Free Software Foundation, either version 3 of the License,
+or (at your option) any later version.
+
+This script, documenatation and configuration examples are distributed in the
+hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied
+warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+General Public License for more details.
+
+You should have received a copy of the GNU General Public License along with
+this program. If not, download it from <http://www.gnu.org/licenses/>.
diff --git a/privacyidea.freeradiusmodule b/privacyidea.freeradiusmodule
new file mode 100644
index 0000000..64f3fdf
--- /dev/null
+++ b/privacyidea.freeradiusmodule
@@ -0,0 +1,105 @@
+#
+# Sample FreeRadius rlm_exec wrapper configuration to perform OTP authentication
+# against privacyidea without rtl_perl module (unavailable on OS X 10.9 Server)
+#
+# Version 1.0, latest version, documentation and bugtracker available at:
+# https://gitlab.lindenaar.net/scripts/privacyidea-checkotp
+#
+# Copyleft (c) 2015 by Frederik Lindenaar
+#
+
+#
+# Return value of the program run determines the result of the exec instance
+# call (See doc/configurable_failover for details) as follows:
+#
+# < 0 : fail the module failed
+# = 0 : ok the module succeeded
+# = 1 : reject the module rejected the user
+# = 2 : fail the module failed
+# = 3 : ok the module succeeded
+# = 4 : handled the module has done everything to handle the request
+# = 5 : invalid the user's configuration entry was invalid
+# = 6 : userlock the user was locked out
+# = 7 : notfound the user was not found
+# = 8 : noop the module did nothing
+# = 9 : updated the module updated information in the request
+# > 9 : fail the module failed
+#
+
+exec privacyidea {
+ #
+ # Wait for the program to finish.
+ #
+ # If we do NOT wait, then the program is "fire and
+ # forget", and any output attributes from it are ignored.
+ #
+ # If we are looking for the program to output
+ # attributes, and want to add those attributes to the
+ # request, then we MUST wait for the program to
+ # finish, and therefore set 'wait=yes'
+ #
+ # allowed values: {no, yes}
+ wait = yes
+
+ #
+ # The name of the program to execute, and it's
+ # arguments. Dynamic translation is done on this
+ # field, so things like the following example will
+ # work.
+ #
+ program = "[WRAPPERSCRIPT_PATH]/privacyidea-checkotp [PRIVACYIDEA_URL]"
+
+ #
+ # The attributes which are placed into the
+ # environment variables for the program.
+ #
+ # Allowed values are:
+ #
+ # request attributes from the request
+ # config attributes from the configuration items list
+ # reply attributes from the reply
+ # proxy-request attributes from the proxy request
+ # proxy-reply attributes from the proxy reply
+ #
+ # Note that some attributes may not exist at some
+ # stages. e.g. There may be no proxy-reply
+ # attributes if this module is used in the
+ # 'authorize' section.
+ #
+ input_pairs = request
+
+ #
+ # Where to place the output attributes (if any) from
+ # the executed program. The values allowed, and the
+ # restrictions as to availability, are the same as
+ # for the input_pairs.
+ #
+ output_pairs =
+
+ #
+ # When to execute the program. If the packet
+ # type does NOT match what's listed here, then
+ # the module does NOT execute the program.
+ #
+ # For a list of allowed packet types, see
+ # the 'dictionary' file, and look for VALUEs
+ # of the Packet-Type attribute.
+ #
+ # By default, the module executes on ANY packet.
+ # Un-comment out the following line to tell the
+ # module to execute only if an Access-Accept is
+ # being sent to the NAS.
+ #
+ packet_type = Access-Request
+
+ #
+ # Should we escape the environment variables?
+ #
+ # If this is set, all the RADIUS attributes
+ # are capitalised and dashes replaced with
+ # underscores. Also, RADIUS values are surrounded
+ # with double-quotes.
+ #
+ # That is to say: User-Name=BobUser => USER_NAME="BobUser"
+ shell_escape = yes
+}
--
libgit2 0.22.2