|
1530
|
1 # Access control
|
|
1528
|
2
|
|
|
3 If all your images are free and available to everybody or if your server is not
|
|
|
4 reachable from the internet then congratulations, you can run digilib without
|
|
1530
|
5 authorization: Leave the [digilib-config](digilib-config.html) setting
|
|
1528
|
6
|
|
|
7 use-authorization=false
|
|
|
8
|
|
|
9 and ignore the rest of this chapter.
|
|
|
10
|
|
|
11 But if you have some images that are freely available and others
|
|
1530
|
12 that should be only visible to some users then you need to set
|
|
1528
|
13
|
|
|
14 use-authorization=true
|
|
|
15
|
|
1530
|
16 and configure digilib's authentication and authorization mechanism.
|
|
|
17
|
|
1528
|
18 ## Authentication and authorization
|
|
|
19
|
|
|
20 digilib has different mechanisms for the tasks of *authentication* - establishing
|
|
|
21 the identity of the user requesting the image (more accurately the roles associated to
|
|
|
22 this identity) - and *authorization* - establishing the rules for accessing specific
|
|
|
23 images (the roles required to access the image).
|
|
|
24
|
|
1530
|
25 The authe<b>n</b>tication mechanism is implemented by the digilib.auth.Auth<b>n</b>Ops interface
|
|
1528
|
26 implemented through the class configured in the `digilib-config` parameter
|
|
1530
|
27 `authnops-class` while the authori<b>z</b>ation mechanism is implemented by the
|
|
|
28 digilib.auth.Auth<b>z</b>Ops interface implemented through the class configured in
|
|
1528
|
29 `authzops-class`.
|
|
|
30
|
|
|
31 All authentication and authorization classes are configured through different elements
|
|
1530
|
32 in the XML config file
|
|
1528
|
33
|
|
|
34 digilib-auth.xml
|
|
|
35
|
|
1530
|
36 in the `WEB-INF` directory (the file name can be configured with the `digilib-config`
|
|
|
37 parameter `auth-file`).
|
|
|
38
|
|
|
39 In short: you need to set both `authnops-class` and `authzops-class` in `digilib-config` with
|
|
|
40 two of the classes described below (or implement your own) and create a `digilib-auth.xml` file
|
|
|
41 with the configuration for the chosen implementations.
|
|
1528
|
42
|
|
|
43 ### Authentication: IpAuthnOps
|
|
|
44
|
|
|
45 `digilib.auth.IpAuthnOps` assigns roles based on the IP address of the user requesting the
|
|
|
46 image. This works well for situations where all users of the local network are allowed to
|
|
|
47 access resources. The class reads the tag `digilib-adresses` from `digilib-auth.xml`:
|
|
|
48
|
|
1530
|
49 <digilib-addresses>
|
|
|
50 <address ip="130.92.68" role="eastwood-coll,ptolemaios-geo" />
|
|
|
51 <address ip="130.92.151" role="wtwg" />
|
|
|
52 <address ip="0:0:0:0:0:0:0:1" role="local" />
|
|
|
53 </digilib-addresses>
|
|
1528
|
54
|
|
1530
|
55 A computer with an ip address that matches `ip` is automatically granted all roles under `role`.
|
|
1528
|
56 The ip address is matched from the left (in full quads). Roles under "role" must be separated by comma only (no spaces).
|
|
|
57
|
|
|
58 Caution: If you run your Servlet Container (Tomcat) behind Apache or another reverse proxy
|
|
1530
|
59 then Tomcat only sees the IP address of the proxy server for all connections. You need to
|
|
1528
|
60 configure Tomcat to honor the `X-Forwarded-For` and `X-Forwarded-Proto` headers.
|
|
|
61
|
|
|
62 ### Authentication: IpServletAuthnOps
|
|
|
63
|
|
1530
|
64 `digilib.auth.IpServletAuthnOps` assigns roles based on the IP address of the user requesting
|
|
1528
|
65 the image (see `IpAuthnOps` above) and uses the `ServletRequest.isUserInRole()` function of
|
|
|
66 the Servlet Container if the roles provided by the IP address are not sufficient.
|
|
|
67
|
|
1530
|
68 Using authentication information from the Servlet Container requires that the Servlet Container
|
|
|
69 is configured for authentication. For information about this please refer to the
|
|
|
70 documentation of your Servlet Container.
|
|
1528
|
71
|
|
1530
|
72 For Tomcat 8 there is documentation at
|
|
|
73 (https://tomcat.apache.org/tomcat-8.0-doc/realm-howto.html)[https://tomcat.apache.org/tomcat-8.0-doc/realm-howto.html]
|
|
|
74 Note that you need to configure a `<security-constraint>` in `web.xml` to force the
|
|
|
75 server to ask for a password (there is an old example in `web-additional.xml`).
|
|
|
76
|
|
|
77 ### Authentication: OpenIdAuthnOps
|
|
|
78
|
|
|
79 `digilib.auth.OpenIdAuthnOps` assigns roles based on an [OpenId-Connect](http://openid.net/) token
|
|
|
80 passed with the request. The token can be passed either in the URL parameter `id_token` or as a cookie
|
|
|
81 with the name `id_token` (the name of the cookie can be configured with the `digilib-config`
|
|
|
82 parameter `authn-token-cookie`).
|
|
|
83
|
|
|
84 The class reads the tag `digilib-oauth` from `digilib-auth.xml`:
|
|
|
85
|
|
|
86 <digilib-oauth>
|
|
|
87 <openid issuer="https://id.some.where" clientid="myclient" roles="openid-users" keytype="jwk">
|
|
|
88 {"kty":"RSA","e":"AQAB","kid":"rsa1","alg":"RS256","n":"qt6yOiI_wCoCVlGO0MySsez...Lf9by7TGw"}
|
|
|
89 </openid>
|
|
|
90 </digilib-oauth>
|
|
|
91
|
|
|
92 The `openid` tag defines roles (in `role`, separated by comma only, no spaces)
|
|
|
93 that will be granted to the user that provides a valid token from the given server.
|
|
|
94 The server is identified by the url in `issuer`, the
|
|
|
95 client id in `clientid` and the public key of the server in JWK format as content
|
|
|
96 of the tag. There can be multiple `openid` tags.
|
|
|
97
|
|
|
98 To set up a connection with an OpenId-Connect identity server you usually have to enter the
|
|
|
99 URL of your digilib instance as a redirect URL and the client id that you chose
|
|
|
100 and make sure that the server answers requests with `response_type=id_token`. The public
|
|
|
101 key of the server in JWK format can often be requested from the server by adding `/jwk` to
|
|
|
102 the URL.
|
|
|
103
|
|
|
104 To automatically authenticate with OpenId in the digilib Javascript frontend you can use the
|
|
|
105 digilib plugin `jquery.digilib.oauth.js` and configure it with the URL of the ID server as
|
|
|
106 `authServerUrl` and the client id as `authClientId`. This will give you an extra login button
|
|
|
107 that authenticates the user by redirecting her to the ID server. You can additionally set
|
|
|
108 `authOnErrorMode` to true to automatically authenticate the user whenever the image from
|
|
|
109 the digilib server doesn't load which is usually caused by missing authentication
|
|
|
110 (there is an example in `jquery/digilib-auth.html`).
|
|
|
111
|
|
|
112 ### Authentication: IpOpenIdAuthnOps
|
|
|
113
|
|
|
114 `digilib.auth.IpOpenIdAuthnOps` assigns roles based on the IP address of the user requesting
|
|
|
115 the image (see `IpAuthnOps` above) and uses an OpenId-Connect token passed with the request
|
|
|
116 (see `OpenIdAuthnOps` above) if the roles provided by the IP address are not sufficient.
|
|
|
117
|
|
|
118 ### Authorization: PathAuthzOps
|
|
|
119
|
|
|
120 `digilib.auth.PathAuthzOps` requests roles based on the directory path of the requested image.
|
|
|
121 All images in the given directory and all its subdirectories can be accessed only if the user
|
|
|
122 can provide one of the requested roles.
|
|
|
123
|
|
|
124 The class reads the tag `digilib-paths` from `digilib-auth.xml`:
|
|
|
125
|
|
|
126 <digilib-paths>
|
|
|
127 <path name="histast/eastwood-collection" role="eastwood-coll"/>
|
|
|
128 <path name="documents/nonpublic" role="openid-user,eastwood-coll"/>
|
|
|
129 </digilib-paths>
|
|
|
130
|
|
|
131 A user must supply one of the roles in `role` to access the directory in `name`.
|
|
|
132 Roles in `role` must be separated by comma only (no spaces).
|
|
|
133
|
|
|
134 ### Authorization: MetaAccessAuthzOps
|
|
|
135
|
|
|
136 `digilib.auth.MetaAccessAuthzOps` requests roles using "access" information in the file metadata.
|
|
|
137
|
|
|
138 This requires a `FileMeta` implementation (configured in the `filemeta-class` parameter of
|
|
|
139 `digilib-config`) that provides an `access` key in the metadata returned by `DocuDirent.getMeta().getFileMeta()`
|
|
|
140 like `digilib.meta.IndexMetaFileMeta`.
|
|
|
141
|
|
|
142 The class reads the tag `digilib-access` from `digilib-auth.xml`:
|
|
|
143
|
|
|
144 <digilib-access>
|
|
|
145 <access type="group:mpiwg" role="mpiwg-user"/>
|
|
|
146 <access type="default" role=""/>
|
|
|
147 </digilib-access>
|
|
|
148
|
|
|
149 A user must supply one of the roles in `role` to access any object with a metadata access value
|
|
|
150 matching `type`.
|
|
|
151 Roles in `role` must be separated by comma only (no spaces).
|
|
|
152
|
|
|
153 The access type `default` is special, it applies to all objects without metadata access information.
|
|
|
154
|
|
|
155 `digilib.meta.IndexMetaFileMeta` reads XML files conforming to the
|
|
|
156 ["index.meta" specification](http://intern.mpiwg-berlin.mpg.de/digitalhumanities/mpiwg-metadata-documentation/formate/indexmeta-standard)
|
|
|
157 and extracts image information from the `meta/img` tag and access information from the
|
|
|
158 `meta/access-conditions` tag (see also class `digilib.meta.IndexMetaAuthLoader`).
|
|
|
159
|
