Blame view

README.md 5.44 KB
Frederik Lindenaar authored
1
2
3
privacyidea-checkotp
====================
Frederik Lindenaar authored
4
5
6
7
8
Scripts implementing the [PrivacyIDEA](http://www.privacyidea.org) OTP (One
Time Password) check, one implemented as a shell script and the other in python,
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).
Frederik Lindenaar authored
9
Frederik Lindenaar authored
10
**Version 2.0**, latest version, documentation and bugtracker available on my
Frederik Lindenaar authored
11
[GitLab instance](https://gitlab.lindenaar.net/scripts/privacyidea-checkotp)
Frederik Lindenaar authored
12
Frederik Lindenaar authored
13
14
Copyright (c) 2015 - 2016 Frederik Lindenaar. free for distribution under the
GNU License, see [below](#license)
Frederik Lindenaar authored
15
16
17
18


Introduction
------------
Frederik Lindenaar authored
19
20
21
22
23
24
When integrating PrivacyIDEA with the stock OS X Server FreeRadius server, I got
stuck as the OS X Server not including the FreeRadius `rlm_perl` module. At that
time I created the shell-script `privacyidea-checkotp` to get around this using
the available FreeRadius `rlm_exec` module. This solution suited my needs and
may have glitches, though so far it turned out to be a stable solution.
Frederik Lindenaar authored
25
26
27
28
I have reimplemented this script in Python as drop-in replacement for the shell 
script with better error handling and logging / debugging capabilities. The way
to integrate it is the same as the shell script, the only change needed is the
script name.
Frederik Lindenaar authored
29
30

In case you have any comments / questions or issues, please raise them through
Frederik Lindenaar authored
31
32
my [GitLab instance](https://gitlab.lindenaar.net/scripts/privacyidea-checkotp)
so that others benefit.
Frederik Lindenaar authored
33
34
35

Setup
-----
Frederik Lindenaar authored
36
Both scripts will be executed using the FreeRadius `rtl_exec` module, which is
Frederik Lindenaar authored
37
38
39
40
41
42
43
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
Frederik Lindenaar authored
44
45
  2. Install the shell or python version of the script as `privacyidea-checkotp`
     on your FreeRadius server and make it executable
Frederik Lindenaar authored
46
47
48
49
50
51
52
  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
Frederik Lindenaar authored
53
54
55
56
57
58
     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`,
     eg.: ```./privacyidea-checkotp https://server.tld/path username `cat -` ```
Frederik Lindenaar authored
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
  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
Frederik Lindenaar authored
97
     server. Specific requirements on what needs to happen is dependent on your
Frederik Lindenaar authored
98
99
100
101
102
103
104
105
106
107
     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>
-----------------------------
Frederik Lindenaar authored
108
This script, documentation and configuration examples are free software: you can
Frederik Lindenaar authored
109
110
111
112
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.
Frederik Lindenaar authored
113
This script, documentation and configuration examples are distributed in the
Frederik Lindenaar authored
114
115
116
117
118
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
Frederik Lindenaar authored
119
this program.  If not, download it from <http://www.gnu.org/licenses/>.