Mercurial > hg > digilib

comparison auth.html @ 1640:1ae8b89d3a86

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Creating site for 2.5-SNAPSHOT
author Robert Casties <casties@mpiwg-berlin.mpg.de>
date Tue, 22 Aug 2017 16:38:19 +0000
parents
children 16be3440305b
comparison
equal deleted inserted replaced
-1:000000000000 1640:1ae8b89d3a86
1 <!DOCTYPE html>
2 <!--
3 | Generated by Apache Maven Doxia at 2017-08-22
4 | Rendered using Apache Maven Fluido Skin 1.3.0
5 -->
6 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
7 <head>
8 <meta charset="UTF-8" />
9 <meta name="viewport" content="width=device-width, initial-scale=1.0" />
10 <meta name="Date-Revision-yyyymmdd" content="20170822" />
11 <meta http-equiv="Content-Language" content="en" />
12 <title>digilib - The Digital Image Library &#x2013; Access control</title>
13 <link rel="stylesheet" href="./css/apache-maven-fluido-1.3.0.min.css" />
14 <link rel="stylesheet" href="./css/site.css" />
15 <link rel="stylesheet" href="./css/print.css" media="print" />
16
17
18 <script type="text/javascript" src="./js/apache-maven-fluido-1.3.0.min.js"></script>
19
20
21 </head>
22 <body class="topBarDisabled">
23
24
25
26 <div class="container-fluid">
27 <div id="banner">
28 <div class="pull-left">
29 <a href="./" id="bannerLeft">
30 <h2>digilib - a versatile image viewing environment for the internet</h2>
31 </a>
32 </div>
33 <div class="pull-right"> <a href="./" id="bannerRight">
34 <img src="images/digilib-logo-small.png" />
35 </a>
36 </div>
37 <div class="clear"><hr/></div>
38 </div>
39
40 <div id="breadcrumbs">
41 <ul class="breadcrumb">
42
43
44 <li id="publishDate">Last Published: 2017-08-22</li>
45 <li class="divider">|</li> <li id="projectVersion">Version: 2.5-SNAPSHOT</li>
46
47
48
49
50 </ul>
51 </div>
52
53
54 <div class="row-fluid">
55 <div id="leftColumn" class="span3">
56 <div class="well sidebar-nav">
57
58
59 <ul class="nav nav-list">
60 <li class="nav-header">Overview</li>
61
62 <li>
63
64 <a href="index.html" title="About digilib">
65 <i class="none"></i>
66 About digilib</a>
67 </li>
68
69 <li>
70
71 <a href="features.html" title="digilib features">
72 <i class="none"></i>
73 digilib features</a>
74 </li>
75
76 <li>
77
78 <a href="digilib-short.html" title="How digilib works">
79 <i class="none"></i>
80 How digilib works</a>
81 </li>
82
83 <li>
84
85 <a href="history.html" title="Ancient history">
86 <i class="none"></i>
87 Ancient history</a>
88 </li>
89 <li class="nav-header">Installation</li>
90
91 <li>
92
93 <a href="install-digilib.html" title="Installing digilib">
94 <i class="none"></i>
95 Installing digilib</a>
96 </li>
97
98 <li>
99
100 <a href="build-maven.html" title="Building digilib">
101 <i class="none"></i>
102 Building digilib</a>
103 </li>
104 <li class="nav-header">Configuration</li>
105
106 <li>
107
108 <a href="digilib-config.html" title="Configuring digilib">
109 <i class="none"></i>
110 Configuring digilib</a>
111 </li>
112
113 <li>
114
115 <a href="image-directories.html" title="Directory layout">
116 <i class="none"></i>
117 Directory layout</a>
118 </li>
119
120 <li>
121
122 <a href="java-settings.html" title="Java settings and tuning">
123 <i class="none"></i>
124 Java settings and tuning</a>
125 </li>
126
127 <li class="active">
128
129 <a href="#"><i class="none"></i>Access control</a>
130 </li>
131 <li class="nav-header">Development</li>
132
133 <li>
134
135 <a href="scaler-api.html" title="The digilib Scaler API">
136 <i class="none"></i>
137 The digilib Scaler API</a>
138 </li>
139
140 <li>
141
142 <a href="iiif-api.html" title="The digilib IIIF API">
143 <i class="none"></i>
144 The digilib IIIF API</a>
145 </li>
146
147 <li>
148
149 <a href="client-integration.html" title="Integrating digilib into your page">
150 <i class="none"></i>
151 Integrating digilib into your page</a>
152 </li>
153
154 <li>
155
156 <a href="plugins.html" title="Digilib plugins">
157 <i class="none"></i>
158 Digilib plugins</a>
159 </li>
160 <li class="nav-header">Project Documentation</li>
161
162 <li>
163
164 <a href="project-info.html" title="Project Information">
165 <i class="icon-chevron-right"></i>
166 Project Information</a>
167 </li>
168 </ul>
169
170
171
172 <hr class="divider" />
173
174 <div id="poweredBy">
175 <div class="clear"></div>
176 <div class="clear"></div>
177 <div class="clear"></div>
178 <a href="http://maven.apache.org/" title="Built by Maven" class="builtBy">
179 <img class="builtBy" alt="Built by Maven" src="http://maven.apache.org/images/logos/maven-feather.png" />
180 </a>
181 <a href="http://www.sourceforge.net/" title="Hosted by SourceForge" class="builtBy">
182 <img class="builtBy" alt="Hosted by SourceForge" src="http://upload.wikimedia.org/wikipedia/commons/0/0b/Sourceforge_logo.png" />
183 </a>
184 </div>
185 </div>
186 </div>
187
188
189 <div id="bodyColumn" class="span9" >
190
191 <h1>Access control</h1>
192 <p>If all your images are free and available to everybody or if your server is not reachable from the internet then congratulations, you can run digilib without authorization: Leave the <a href="digilib-config.html">digilib-config</a> setting </p>
193
194 <div class="source">
195 <div class="source">
196 <pre>use-authorization=false
197 </pre></div></div>
198 <p>and ignore the rest of this chapter.</p>
199 <p>But if you have some images that are freely available and others that should be only visible to some users then you need to set</p>
200
201 <div class="source">
202 <div class="source">
203 <pre>use-authorization=true
204 </pre></div></div>
205 <p>and configure digilib&#x2019;s authentication and authorization mechanism.</p>
206 <div class="section">
207 <h2><a name="Authentication_and_authorization"></a>Authentication and authorization</h2>
208 <p>digilib has different mechanisms for the tasks of <i>authentication</i> - establishing the identity of the user requesting the image (more accurately the roles associated to this identity) - and <i>authorization</i> - establishing the rules for accessing specific images (the roles required to access the image).</p>
209 <p>The authe<b>n</b>tication mechanism is implemented by the digilib.auth.Auth<b>n</b>Ops interface implemented through the class configured in the <tt>digilib-config</tt> parameter <tt>authnops-class</tt> while the authori<b>z</b>ation mechanism is implemented by the digilib.auth.Auth<b>z</b>Ops interface implemented through the class configured in <tt>authzops-class</tt>.</p>
210 <p>All authentication and authorization classes are configured through different elements in the XML config file</p>
211
212 <div class="source">
213 <div class="source">
214 <pre>digilib-auth.xml
215 </pre></div></div>
216 <p>in the <tt>WEB-INF</tt> directory (the file name can be configured with the <tt>digilib-config</tt> parameter <tt>auth-file</tt>).</p>
217 <p>In short: you need to set both <tt>authnops-class</tt> and <tt>authzops-class</tt> in <tt>digilib-config</tt> with two of the classes described below (or implement your own) and create a <tt>digilib-auth.xml</tt> file with the configuration for the chosen implementations.</p>
218 <div class="section">
219 <h3><a name="Authentication:_IpAuthnOps"></a>Authentication: IpAuthnOps</h3>
220 <p><tt>digilib.auth.IpAuthnOps</tt> assigns roles based on the IP address of the user requesting the image. This works well for situations where all users of the local network are allowed to access resources. The class reads the tag <tt>digilib-adresses</tt> from <tt>digilib-auth.xml</tt>:</p>
221
222 <div class="source">
223 <div class="source">
224 <pre>&lt;digilib-addresses&gt;
225 &lt;address ip=&quot;130.92.68&quot; role=&quot;eastwood-coll,ptolemaios-geo&quot; /&gt;
226 &lt;address ip=&quot;130.92.151&quot; role=&quot;wtwg&quot; /&gt;
227 &lt;address ip=&quot;0:0:0:0:0:0:0:1&quot; role=&quot;local&quot; /&gt;
228 &lt;/digilib-addresses&gt;
229 </pre></div></div>
230 <p>A computer with an ip address that matches <tt>ip</tt> is automatically granted all roles under <tt>role</tt>. The ip address is matched from the left (in full quads). Roles under &#x201c;role&#x201d; must be separated by comma only (no spaces). </p>
231 <p>Caution: If you run your Servlet Container (Tomcat) behind Apache or another reverse proxy then Tomcat only sees the IP address of the proxy server for all connections. You need to configure Tomcat to honor the <tt>X-Forwarded-For</tt> and <tt>X-Forwarded-Proto</tt> headers.</p></div>
232 <div class="section">
233 <h3><a name="Authentication:_IpServletAuthnOps"></a>Authentication: IpServletAuthnOps</h3>
234 <p><tt>digilib.auth.IpServletAuthnOps</tt> assigns roles based on the IP address of the user requesting the image (see <tt>IpAuthnOps</tt> above) and uses the <tt>ServletRequest.isUserInRole()</tt> function of the Servlet Container if the roles provided by the IP address are not sufficient.</p>
235 <p>Using authentication information from the Servlet Container requires that the Servlet Container is configured for authentication. For information about this please refer to the documentation of your Servlet Container.</p>
236 <p>For Tomcat 8 there is documentation at (<a class="externalLink" href="https://tomcat.apache.org/tomcat-8.0-doc/realm-howto.html)[https://tomcat.apache.org/tomcat-8.0-doc/realm-howto.html">https://tomcat.apache.org/tomcat-8.0-doc/realm-howto.html)[https://tomcat.apache.org/tomcat-8.0-doc/realm-howto.html</a>] Note that you need to configure a <tt>&lt;security-constraint&gt;</tt> in <tt>web.xml</tt> to force the server to ask for a password (there is an old example in <tt>web-additional.xml</tt>).</p></div>
237 <div class="section">
238 <h3><a name="Authentication:_OpenIdAuthnOps"></a>Authentication: OpenIdAuthnOps</h3>
239 <p><tt>digilib.auth.OpenIdAuthnOps</tt> assigns roles based on an <a class="externalLink" href="http://openid.net/">OpenId-Connect</a> token passed with the request. The token can be passed either in the URL parameter <tt>id_token</tt> or as a cookie with the name <tt>id_token</tt> (the name of the cookie can be configured with the <tt>digilib-config</tt> parameter <tt>authn-token-cookie</tt>).</p>
240 <p>The class reads the tag <tt>digilib-oauth</tt> from <tt>digilib-auth.xml</tt>:</p>
241
242 <div class="source">
243 <div class="source">
244 <pre>&lt;digilib-oauth&gt;
245 &lt;openid issuer=&quot;https://id.some.where&quot; clientid=&quot;myclient&quot; roles=&quot;openid-users&quot; keytype=&quot;jwk&quot;&gt;
246 {&quot;kty&quot;:&quot;RSA&quot;,&quot;e&quot;:&quot;AQAB&quot;,&quot;kid&quot;:&quot;rsa1&quot;,&quot;alg&quot;:&quot;RS256&quot;,&quot;n&quot;:&quot;qt6yOiI_wCoCVlGO0MySsez...Lf9by7TGw&quot;}
247 &lt;/openid&gt;
248 &lt;/digilib-oauth&gt;
249 </pre></div></div>
250 <p>The <tt>openid</tt> tag defines roles (in <tt>role</tt>, separated by comma only, no spaces) that will be granted to the user that provides a valid token from the given server. The server is identified by the url in <tt>issuer</tt>, the client id in <tt>clientid</tt> and the public key of the server in JWK format as content of the tag. There can be multiple <tt>openid</tt> tags.</p>
251 <p>To set up a connection with an OpenId-Connect identity server you usually have to enter the URL of your digilib instance as a redirect URL and the client id that you chose and make sure that the server answers requests with <tt>response_type=id_token</tt>. The public key of the server in JWK format can often be requested from the server by adding <tt>/jwk</tt> to the URL.</p>
252 <p>To automatically authenticate with OpenId in the digilib Javascript frontend you can use the digilib plugin <tt>jquery.digilib.oauth.js</tt> and configure it with the URL of the ID server as <tt>authServerUrl</tt> and the client id as <tt>authClientId</tt>. This will give you an extra login button that authenticates the user by redirecting her to the ID server. You can additionally set <tt>authOnErrorMode</tt> to true to automatically authenticate the user whenever the image from the digilib server doesn&#x2019;t load which is usually caused by missing authentication (there is an example in <tt>jquery/digilib-auth.html</tt>).</p></div>
253 <div class="section">
254 <h3><a name="Authentication:_IpOpenIdAuthnOps"></a>Authentication: IpOpenIdAuthnOps</h3>
255 <p><tt>digilib.auth.IpOpenIdAuthnOps</tt> assigns roles based on the IP address of the user requesting the image (see <tt>IpAuthnOps</tt> above) and uses an OpenId-Connect token passed with the request (see <tt>OpenIdAuthnOps</tt> above) if the roles provided by the IP address are not sufficient.</p></div>
256 <div class="section">
257 <h3><a name="Authorization:_PathAuthzOps"></a>Authorization: PathAuthzOps</h3>
258 <p><tt>digilib.auth.PathAuthzOps</tt> requests roles based on the directory path of the requested image. All images in the given directory and all its subdirectories can be accessed only if the user can provide one of the requested roles.</p>
259 <p>The class reads the tag <tt>digilib-paths</tt> from <tt>digilib-auth.xml</tt>:</p>
260
261 <div class="source">
262 <div class="source">
263 <pre>&lt;digilib-paths&gt;
264 &lt;path name=&quot;histast/eastwood-collection&quot; role=&quot;eastwood-coll&quot;/&gt;
265 &lt;path name=&quot;documents/nonpublic&quot; role=&quot;openid-user,eastwood-coll&quot;/&gt;
266 &lt;/digilib-paths&gt;
267 </pre></div></div>
268 <p>A user must supply one of the roles in <tt>role</tt> to access the directory in <tt>name</tt>. Roles in <tt>role</tt> must be separated by comma only (no spaces).</p></div>
269 <div class="section">
270 <h3><a name="Authorization:_MetaAccessAuthzOps"></a>Authorization: MetaAccessAuthzOps</h3>
271 <p><tt>digilib.auth.MetaAccessAuthzOps</tt> requests roles using &#x201c;access&#x201d; information in the file metadata.</p>
272 <p>This requires a <tt>FileMeta</tt> implementation (configured in the <tt>filemeta-class</tt> parameter of <tt>digilib-config</tt>) that provides an <tt>access</tt> key in the metadata returned by <tt>DocuDirent.getMeta().getFileMeta()</tt> like <tt>digilib.meta.IndexMetaFileMeta</tt>.</p>
273 <p>The class reads the tag <tt>digilib-access</tt> from <tt>digilib-auth.xml</tt>: </p>
274
275 <div class="source">
276 <div class="source">
277 <pre>&lt;digilib-access&gt;
278 &lt;access type=&quot;group:mpiwg&quot; role=&quot;mpiwg-user&quot;/&gt;
279 &lt;access type=&quot;default&quot; role=&quot;&quot;/&gt;
280 &lt;/digilib-access&gt;
281 </pre></div></div>
282 <p>A user must supply one of the roles in <tt>role</tt> to access any object with a metadata access value matching <tt>type</tt>. Roles in <tt>role</tt> must be separated by comma only (no spaces).</p>
283 <p>The access type <tt>default</tt> is special, it applies to all objects without metadata access information.</p>
284 <p><tt>digilib.meta.IndexMetaFileMeta</tt> reads XML files conforming to the <a class="externalLink" href="http://intern.mpiwg-berlin.mpg.de/digitalhumanities/mpiwg-metadata-documentation/formate/indexmeta-standard">&#x201c;index.meta&#x201d; specification</a> and extracts image information from the <tt>meta/img</tt> tag and access information from the <tt>meta/access-conditions</tt> tag (see also class <tt>digilib.meta.IndexMetaAuthLoader</tt>).</p></div></div>
285 </div>
286 </div>
287 </div>
288
289 <hr/>
290
291 <footer>
292 <div class="container-fluid">
293 <div class="row span12">Copyright &copy; 2001-2017
294 <a href="http://digilib.sourceforge.net">digilib Community</a>.
295 All Rights Reserved.
296
297 </div>
298
299
300
301 </div>
302 </footer>
303 </body>
304 </html>