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: Leave the digilib-config 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 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 the identity of the user requesting the image (more accurately the roles associated to this identity) - and authorization - establishing the rules for accessing specific images (the roles required to access the image).
The authentication mechanism is implemented by the digilib.auth.AuthnOps interface implemented through the class configured in the digilib-config
parameter authnops-class
while the authorization mechanism is implemented by the digilib.auth.AuthzOps interface implemented through the class configured in authzops-class
.
All authentication and authorization classes are configured through different elements in the XML config file
digilib-auth.xml
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
digilib.auth.IpAuthnOps
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 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>
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 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 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 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 and extracts image information from the meta/img
tag and access information from the meta/access-conditions
tag (see also class digilib.meta.IndexMetaAuthLoader
).