--- 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`).
+