# HG changeset patch
# User robcast
# Date 1473357278 -7200
# Node ID 70e1225fe08cc85d10648c4e1f9767c9b26f4b79
# Parent  b330eafffed6673882fdd4a14df2d8bf52f3b8fd
added auth* documentation.

diff -r b330eafffed6 -r 70e1225fe08c doc/src/site/markdown/auth.md
--- a/doc/src/site/markdown/auth.md	Thu Sep 08 13:56:20 2016 +0200
+++ b/doc/src/site/markdown/auth.md	Thu Sep 08 19:54:38 2016 +0200
@@ -1,19 +1,20 @@
-# digilib image permissions
+# Access control
 
 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. You can leave the [digilib-config](digilib-config.html) setting 
+authorization: Leave the [digilib-config](digilib-config.html) setting 
 
 	use-authorization=false
 
 and ignore the rest of this chapter.
 
 But if you have some images that are freely available and others 
-that should be only visible to some users then you need to configure digilib's
-authentication and authorization mechanism and set
+that should be only visible to some users then you need to set
 
 	use-authorization=true
   
+and configure digilib's authentication and authorization mechanism.
+
 ## Authentication and authorization
 
 digilib has different mechanisms for the tasks of *authentication* - establishing
@@ -21,18 +22,23 @@
 this identity) - and *authorization* - establishing the rules for accessing specific
 images (the roles required to access the image).
 
-The authe**n**tication mechanism is implemented by the digilib.auth.Auth**n**Ops interface
+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 `digilib-config` parameter
-`authnops-class` while the auhtori**z**ation mechanism is implemented by the
-digilib.auth.Auth**z**Ops interface implemented through the class configured in
+`authnops-class` 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
 `authzops-class`.
 
 All authentication and authorization classes are configured through different elements
-in the common config file
+in the XML config file
 
 	digilib-auth.xml
 	
-in the `WEB-INF` directory.
+in the `WEB-INF` directory (the file name can be configured with the `digilib-config`
+parameter `auth-file`).
+
+In short: you need to set both `authnops-class` and `authzops-class` in `digilib-config` with
+two of the classes described below (or implement your own) and create a `digilib-auth.xml` file
+with the configuration for the chosen implementations.
 
 ### Authentication: IpAuthnOps
 
@@ -40,23 +46,114 @@
 image. This works well for situations where all users of the local network are allowed to
 access resources. The class reads the tag `digilib-adresses` from `digilib-auth.xml`:
 
-	<digilib-addresses>
- 	  <address ip="130.92.68" role="eastwood-coll,ptolemaios-geo" />
-	  <address ip="130.92.151" role="wtwg" />
-	  <address ip="0:0:0:0:0:0:0:1" role="local" />
-	</digilib-addresses>
+    <digilib-addresses>
+      <address ip="130.92.68" role="eastwood-coll,ptolemaios-geo" />
+      <address ip="130.92.151" role="wtwg" />
+      <address ip="0:0:0:0:0:0:0:1" role="local" />
+    </digilib-addresses>
 
-A computer with an ip address that matches "ip" is automatically granted all roles under "role".
+A computer with an ip address that matches `ip` is automatically granted all roles under `role`.
 The ip address is matched from the left (in full quads). Roles under "role" must be separated by comma only (no spaces). 
 
 Caution: If you run your Servlet Container (Tomcat) behind Apache or another reverse proxy
-then Tomcat only sees the IP-Address of the Apache server for all connections. You need to
+then Tomcat only sees the IP address of the proxy server for all connections. You need to
 configure Tomcat to honor the `X-Forwarded-For` and `X-Forwarded-Proto` headers.
 
 ### Authentication: IpServletAuthnOps
 
-`digilib.auth.IpServletAuthnOps` assigns roles based on the IP Address of the user requesting
+`digilib.auth.IpServletAuthnOps` assigns roles based on the IP address of the user requesting
 the image (see `IpAuthnOps` above) and uses the `ServletRequest.isUserInRole()` function of 
 the Servlet Container if the roles provided by the IP address are not sufficient.
 
+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.
 
+For Tomcat 8 there is documentation at 
+(https://tomcat.apache.org/tomcat-8.0-doc/realm-howto.html)[https://tomcat.apache.org/tomcat-8.0-doc/realm-howto.html]
+Note that you need to configure a `<security-constraint>` in `web.xml` to force the 
+server to ask for a password (there is an old example in `web-additional.xml`).
+
+### Authentication: OpenIdAuthnOps
+
+`digilib.auth.OpenIdAuthnOps` assigns roles based on an [OpenId-Connect](http://openid.net/) token
+passed with the request. The token can be passed either in the URL parameter `id_token` or as a cookie
+with the name `id_token` (the name of the cookie can be configured with the `digilib-config` 
+parameter `authn-token-cookie`).
+
+The class reads the tag `digilib-oauth` from `digilib-auth.xml`:
+
+    <digilib-oauth>
+      <openid issuer="https://id.some.where" clientid="myclient" roles="openid-users" keytype="jwk">
+        {"kty":"RSA","e":"AQAB","kid":"rsa1","alg":"RS256","n":"qt6yOiI_wCoCVlGO0MySsez...Lf9by7TGw"}   
+      </openid>
+    </digilib-oauth>
+
+The `openid` tag defines roles (in `role`, 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 `issuer`, the
+client id in `clientid` and the public key of the server in JWK format as content 
+of the tag. There can be multiple `openid` tags.
+
+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 `response_type=id_token`. The public
+key of the server in JWK format can often be requested from the server by adding `/jwk` to
+the URL.
+
+To automatically authenticate with OpenId in the digilib Javascript frontend you can use the 
+digilib plugin `jquery.digilib.oauth.js` and configure it with the URL of the ID server as
+`authServerUrl` and the client id as `authClientId`. This will give you an extra login button
+that authenticates the user by redirecting her to the ID server. You can additionally set 
+`authOnErrorMode` to true to automatically authenticate the user whenever the image from 
+the digilib server doesn't load which is usually caused by missing authentication 
+(there is an example in `jquery/digilib-auth.html`).
+
+### Authentication: IpOpenIdAuthnOps
+
+`digilib.auth.IpOpenIdAuthnOps` assigns roles based on the IP address of the user requesting
+the image (see `IpAuthnOps` above) and uses an OpenId-Connect token passed with the request
+(see `OpenIdAuthnOps` above) if the roles provided by the IP address are not sufficient.
+
+### Authorization: PathAuthzOps
+
+`digilib.auth.PathAuthzOps` 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.
+
+The class reads the tag `digilib-paths` from `digilib-auth.xml`:
+
+    <digilib-paths>
+      <path name="histast/eastwood-collection" role="eastwood-coll"/>
+      <path name="documents/nonpublic" role="openid-user,eastwood-coll"/>
+    </digilib-paths>
+
+A user must supply one of the roles in `role` to access the directory in `name`.
+Roles in `role` must be separated by comma only (no spaces).
+
+### Authorization: MetaAccessAuthzOps
+
+`digilib.auth.MetaAccessAuthzOps` requests roles using "access" information in the file metadata.
+ 
+This requires a `FileMeta` implementation (configured in the `filemeta-class` parameter of 
+`digilib-config`) that provides an `access` key in the metadata returned by `DocuDirent.getMeta().getFileMeta()`
+like `digilib.meta.IndexMetaFileMeta`.
+
+The class reads the tag `digilib-access` from `digilib-auth.xml`: 
+
+    <digilib-access>
+      <access type="group:mpiwg" role="mpiwg-user"/>
+      <access type="default" role=""/>
+    </digilib-access>
+
+A user must supply one of the roles in `role` to access any object with a metadata access value 
+matching `type`.
+Roles in `role` must be separated by comma only (no spaces).
+
+The access type `default` is special, it applies to all objects without metadata access information.
+
+`digilib.meta.IndexMetaFileMeta` reads XML files conforming to the 
+["index.meta" specification](http://intern.mpiwg-berlin.mpg.de/digitalhumanities/mpiwg-metadata-documentation/formate/indexmeta-standard)
+and extracts image information from the `meta/img` tag and access information from the 
+`meta/access-conditions` tag (see also class `digilib.meta.IndexMetaAuthLoader`).
+
diff -r b330eafffed6 -r 70e1225fe08c doc/src/site/markdown/digilib-config.md
--- a/doc/src/site/markdown/digilib-config.md	Thu Sep 08 13:56:20 2016 +0200
+++ b/doc/src/site/markdown/digilib-config.md	Thu Sep 08 19:54:38 2016 +0200
@@ -2,12 +2,14 @@
 
 ## digilib-config.xml
 
-The main configuration for digilib is `digilib-config.xml` in the `WEB-INF` 
-directory in the webapp. 
-(If you really need a different location you can define it in the `config-file`
+The main configuration for digilib is the XML file `digilib-config.xml` in the `WEB-INF` 
+directory in the webapp or a Java properties file `digilib.properties` somewhere in the classpath.
+(If you really need a different location for the XML file you can define it in the `config-file`
 init-parameter to the Servlet.)
 
-In the XML-based configuration file you can set several paths and options. 
+In the configuration file you can set lots of paths and options. digilib uses
+default values for all configuration settings that meet most requirements
+so you have to configure only the settings that you want to change.
 
 You have to adjust the **`basedir-list`** parameter to the directories
 where your images are installed. The directory path has to be an absolute 
@@ -31,11 +33,14 @@
 	  <parameter name="basedir-list" value="/docuserver/images" />
 	</digilib-config>
 	
-A more customized configuration may look like this (for a full list of
-configuration options use the source: 
-[1](https://sourceforge.net/p/digilib/code/ci/default/tree/common/src/main/java/digilib/conf/DigilibConfiguration.java) 
-[2](https://sourceforge.net/p/digilib/code/ci/default/tree/servlet/src/main/java/digilib/conf/DigilibServletConfiguration.java)
-[3](https://sourceforge.net/p/digilib/code/ci/default/tree/servlet3/src/main/java/digilib/conf/DigilibServlet3Configuration.java)
+A more customized configuration may look like the following 
+(for another commented example see 
+[digilib-config.xml.template](https://sourceforge.net/p/digilib/code/ci/default/tree/webapp/src/main/webapp/WEB-INF/digilib-config.xml.template),
+for a full list of
+configuration options and their default values use the source:
+[DigilibConfiguration](https://sourceforge.net/p/digilib/code/ci/default/tree/common/src/main/java/digilib/conf/DigilibConfiguration.java),
+[DigilibServletConfiguration](https://sourceforge.net/p/digilib/code/ci/default/tree/servlet/src/main/java/digilib/conf/DigilibServletConfiguration.java),
+[DigilibServlet3Configuration](https://sourceforge.net/p/digilib/code/ci/default/tree/servlet3/src/main/java/digilib/conf/DigilibServlet3Configuration.java)
 ):
 
 	<!-- Digilib servlet config file -->
@@ -69,21 +74,11 @@
 	  <!-- number of waiting requests in queue -->
 	  <parameter name="max-waiting-threads" value="20" />
 	
-	  <!-- Restrict access to authorized users.
-	       User authentication and roles are provided by the servlet container 
-	       (see tomcat-users.xml).
-	       Authorization for resources (directories) is evaluated by the servlet 
-	       (see auth-file). -->
+	  <!-- Restrict access to authorized users -->
 	  <parameter name="use-authorization" value="false"/>
 	
-	  <!-- Location of XML file with authorization requirements. -->
-	  <parameter name="auth-file" value="digilib-auth.xml"/>
-	
-	  <!-- Part of URL to indicate authenticated access to Tomcat. -->
-	  <parameter name="auth-url-path" value="authenticated/"/>
-	
 	  <!-- use mapping of "virtual directories" to real directories on the server -->
-	  <parameter name="use-mapping" value="false"/>
+	  <parameter name="use-mapping" value="true"/>
 	
 	  <!-- location of XML name mapping file -->
 	  <parameter name="mapping-file" value="digilib-map.xml"/>
@@ -96,56 +91,10 @@
 messages by the servlet. Standard images will be used if these
 parameters are not defined.
 
-You can specify the Java toolkit implementation with the `docuimage-class`
-parameter. The `ImageLoaderDocuImage` usually gives best performance
-and works with JDK 1.4 and up.
+If you need authorization set `use-authorization` to true and read the 
+[documentation on authentication and authorization](auth.html).
 
 You can see a summary of your running digilib configuration at the URL 
 [http://localhost:8080/digitallibrary/server/dlConfig.jsp](http://localhost:8080/digitallibrary/server/dlConfig.jsp)
 
-
-## digilib-auth.xml
-
-The digilib access authorization is defined in the file defined by the `auth-file`
-parameter (default: `digilib-auth.xml` in `WEB-INF` ).
-
-The file has two parts `diglib-paths` and `diglib-addresses`. It looks like this:
-
-	<auth-config>
-	
-	  <digilib-paths>
-	    <!-- 
-	      A user must supply one of the roles under "role"
-	      to access the directory "name".
-	      Roles under "role" must be separated by comma only (no spaces).  
-	    -->
-	    <path name="histast/eastwood-collection" role="eastwood-coll" />
-	    <path name="ptolemaios_geo" role="ptolemaios-geo" />
-	  </digilib-paths>
-	
-	  <digilib-addresses>
-	    <!-- 
-	      A computer with an ip address that matches "ip"
-	      is automatically granted all roles under "role".
-	      The ip address is matched from the left (in full quads).
-	      Roles under "role" must be separated by comma only (no spaces). 
-	    -->
-	    <address ip="127" role="local" />
-	    <address ip="130.92.68" role="eastwood-coll,ptolemaios-geo" />
-	    <address ip="130.92.151" role="ALL" />
-	  </digilib-addresses>
-	
-	</auth-config>
-
-`diglib-paths` defines restricted directories and the roles needed
-for access. The roles are defined with the users in `tomcat-users.xml`
-(see above). All subdirectories of the given directories have the same
-restrictions. All directories not listed here (and not subdirectories of listed
-directories) are freely accessible.
-
-`diglib-addresses` defines hosts or networks of computers that are
-automatically authenticated without username and password. Hosts can be assigned
-roles. The special keyword `ALL` authorizes for everything. If the
-role assigned to the computer is not sufficient to access a resource the user
-will be asked for username and password.
         
\ No newline at end of file
diff -r b330eafffed6 -r 70e1225fe08c doc/src/site/markdown/features.md
--- a/doc/src/site/markdown/features.md	Thu Sep 08 13:56:20 2016 +0200
+++ b/doc/src/site/markdown/features.md	Thu Sep 08 19:54:38 2016 +0200
@@ -27,7 +27,11 @@
   JPG, PNG, GIF, JPEG2000, and more depending on Java ImageIO support).
   
 * **IIIF image API**: the digilib server provides [IIIF](http://iiif.io)
-  image API (V1.1) compliant access to your images besides the digilib native server API.
+  image API (V2.0) compliant access to your images besides the digilib native server API.
+  
+* **OpenId Connect authentication**: the digilib server can use authentication
+  information from an [OpenId Connect](http://openid.net/) identity server.
+  See the [authorization](auth.html) documentation.
   
 * **plugins**: there are several Digilib plugins written in Javascript to add functionality to the client side, making use of jQuery features. See the [plugins](plugins.html) documentation.
 
diff -r b330eafffed6 -r 70e1225fe08c doc/src/site/site.xml
--- a/doc/src/site/site.xml	Thu Sep 08 13:56:20 2016 +0200
+++ b/doc/src/site/site.xml	Thu Sep 08 19:54:38 2016 +0200
@@ -35,6 +35,7 @@
       <item name="Configuring digilib" href="digilib-config.html"/>
       <item name="Directory layout" href="image-directories.html"/>
       <item name="Java settings and tuning" href="java-settings.html"/>
+      <item name="Access control" href="auth.html"/>
     </menu>
     <menu name="Development">
       <item name="The digilib Scaler API" href="scaler-api.html"/>
diff -r b330eafffed6 -r 70e1225fe08c servlet/src/main/java/digilib/auth/OpenIdAuthnOps.java
--- a/servlet/src/main/java/digilib/auth/OpenIdAuthnOps.java	Thu Sep 08 13:56:20 2016 +0200
+++ b/servlet/src/main/java/digilib/auth/OpenIdAuthnOps.java	Thu Sep 08 19:54:38 2016 +0200
@@ -76,10 +76,16 @@
 
     protected File configFile;
 
+    /** JwtConsumer to parse the token without validation to extract the issuer */
     protected JwtConsumer firstPassJwtConsumer;
+    
+    /** Map of validating JwtConsumers by issuer (URL) */
     protected Map<String, JwtConsumer> idpJwtConsumers;
+    
+    /** Map of (List of) roles by issuer (URL) */ 
     protected Map<String, List<String>> idpRoles;
 
+    /** Name of the cookie that contains the token */
     protected String tokenCookieName;