annotate doc/src/site/markdown/auth.md @ 1528:08d64f3d1f76

beginning of auth documentation.
author robcast
date Thu, 08 Sep 2016 13:53:42 +0200
parents
children 70e1225fe08c
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1528
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
1 # digilib image permissions
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
2
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
3 If all your images are free and available to everybody or if your server is not
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
4 reachable from the internet then congratulations, you can run digilib without
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
5 authorization. You can leave the [digilib-config](digilib-config.html) setting
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
6
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
7 use-authorization=false
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
8
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
9 and ignore the rest of this chapter.
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
10
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
11 But if you have some images that are freely available and others
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
12 that should be only visible to some users then you need to configure digilib's
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
13 authentication and authorization mechanism and set
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
14
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
15 use-authorization=true
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
16
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
17 ## Authentication and authorization
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
18
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
19 digilib has different mechanisms for the tasks of *authentication* - establishing
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
20 the identity of the user requesting the image (more accurately the roles associated to
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
21 this identity) - and *authorization* - establishing the rules for accessing specific
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
22 images (the roles required to access the image).
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
23
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
24 The authe**n**tication mechanism is implemented by the digilib.auth.Auth**n**Ops interface
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
25 implemented through the class configured in the `digilib-config` parameter
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
26 `authnops-class` while the auhtori**z**ation mechanism is implemented by the
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
27 digilib.auth.Auth**z**Ops interface implemented through the class configured in
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
28 `authzops-class`.
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
29
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
30 All authentication and authorization classes are configured through different elements
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
31 in the common config file
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
32
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
33 digilib-auth.xml
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
34
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
35 in the `WEB-INF` directory.
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
36
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
37 ### Authentication: IpAuthnOps
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
38
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
39 `digilib.auth.IpAuthnOps` assigns roles based on the IP address of the user requesting the
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
40 image. This works well for situations where all users of the local network are allowed to
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
41 access resources. The class reads the tag `digilib-adresses` from `digilib-auth.xml`:
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
42
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
43 <digilib-addresses>
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
44 <address ip="130.92.68" role="eastwood-coll,ptolemaios-geo" />
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
45 <address ip="130.92.151" role="wtwg" />
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
46 <address ip="0:0:0:0:0:0:0:1" role="local" />
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
47 </digilib-addresses>
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
48
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
49 A computer with an ip address that matches "ip" is automatically granted all roles under "role".
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
50 The ip address is matched from the left (in full quads). Roles under "role" must be separated by comma only (no spaces).
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
51
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
52 Caution: If you run your Servlet Container (Tomcat) behind Apache or another reverse proxy
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
53 then Tomcat only sees the IP-Address of the Apache server for all connections. You need to
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
54 configure Tomcat to honor the `X-Forwarded-For` and `X-Forwarded-Proto` headers.
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
55
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
56 ### Authentication: IpServletAuthnOps
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
57
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
58 `digilib.auth.IpServletAuthnOps` assigns roles based on the IP Address of the user requesting
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
59 the image (see `IpAuthnOps` above) and uses the `ServletRequest.isUserInRole()` function of
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
60 the Servlet Container if the roles provided by the IP address are not sufficient.
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
61
08d64f3d1f76 beginning of auth documentation.
robcast
parents:
diff changeset
62