]> git.sesse.net Git - itkacl/blob - README
Protect the web interface against CSRF, and the CSRF token against BREACH.
[itkacl] / README
1 README for ITKACL
2 =================
3
4 ITKACL is an authorization system. It is intended to solve the problem where you have
5 an identification system (e.g. UNIX passwd files or LDAP) and an authentication system
6 (e.g. Kerberos) going, but not all valid users are to have access to all systems.
7
8 ITKACL is designed to be lightweight and easily integratable into your own systems.
9 At Studentersamfundet i Trondhjem (the student society of Trondheim), where ITKACL
10 was developed, we use Kerberos+ITKACL to control access to well over fifty different
11 services (most of them web-based).
12
13 Although the master record for your ACLs is a PostgreSQL database, the core library
14 does its checking by querying a precomputed user/service database stored in DNS.
15 This yields a very high degree of infrastructure reuse, enabling very fast
16 lookups, well-tested replication, and secure integrity checking (through DNSSEC).
17 ITKACL scales up to at least thousands of users and hundreds of different ACLs;
18 probably much further.
19
20 The ITKACL distribution is currently a bit raw, since it is extracted from various
21 software packages written more or less independently over the course of ten years.
22 However, ITKACL is not complex or very hard to set up. Included is a web interface
23 for adminstering ACLs, a C library for checking (using libunbound to do the actual
24 DNS lookups and DNSSEC validation), bindings for several languages (Perl, Python,
25 PHP), and authorization modules for Apache and PAM. Everything can be built as
26 Debian packages, or you can go the way of make + make install for each package.
27
28
29 Model
30 =====
31
32 ITKACL is a hierarchical system. If you have access to /web/foo, you also have
33 access to /web/foo/bar (unless there's a negative ACL entry for you on /web/foo/bar).
34 However, access to /web/foo does not give you automatic access to /web.
35
36 Every object (e.g. /web/foo) has a list of ACL entries, saying who will be granted
37 or denied access to the given resource. "Who" means either a username, a UNIX group
38 (fetched through NSS, which often but not always will get information from /etc/group),
39 or the special group "<everyone>", which includes all users ITKACL knows about at
40 sync time.
41
42 Grant is processed before deny, so deny takes precedence within the same list.
43 (The web interface sorts this properly.)
44
45
46 HOWTO
47 =====
48
49 To get started, the first thing you want to do is probably to set up the database
50 and the web interface; see the itkacl-web-1.0 directory. After that, compile the
51 core library from itkacl-2.1, and adjust the example /etc/itkacl.conf.
52 You also want to set up your DNS zone, set up DNS keys for dynamic updating,
53 and run the DNS sync job (also from itkacl-2.1) for the first time. Unless you
54 only speak over secured networks (such as localhost), DNSSEC might be a good idea;
55 there are many HOWTOs online these days if you search for them, and itkacl.conf
56 has a "require-dnssec" directive you can use to force DNSSEC checking.
57
58 After this, you are ready to authorize your services using ITKACL! Here's an example
59 for how to limit access to a web site in Apache using Kerberos and ITKACL:
60
61   AuthType Kerberos
62   KrbAuthRealms SAMFUNDET.NO
63   Krb5Keytab /etc/apache2/krb5/amsit.keytab
64   AuthName "AMSIT, Serveringsgjengen"
65   require itkacl /web/amsit/sg
66
67 Remember SSL, so that the password is not sent in clear text.
68
69 The PAM module can be used like this (together with pam_unix.so, for instance):
70
71   account required pam_itkacl.so realm='/login/itk-workstations'
72
73 The programming interfaces should be pretty self-explanatory. However, do note
74 that the return values are not the same in every language; for instance, since
75 scripting languages typically communicate fatal errors through exceptions,
76 they will typically throw such an exception on an error, instead of just returning
77 -1. Also, since success in e.g. Perl is typically specified using true instead
78 of 0, the return value is different from the C convention.
79
80
81 Copyright and license
82 =====================
83
84 ITKACL is Copyright 2004-2013 Steinar H. Gunderson <sesse@samfundet.no>, and is
85 licensed under the GNU General Public License, version 2. See the included
86 COPYING file for the full license text.