Mercurial > hg > digilib

comparison doc/src/site/markdown/auth.md @ 1530:70e1225fe08c

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
added auth* documentation.
author robcast
date Thu, 08 Sep 2016 19:54:38 +0200
parents 08d64f3d1f76
children
comparison
equal deleted inserted replaced
1529:b330eafffed6 1530:70e1225fe08c
1 # digilib image permissions 1 # Access control
2 2
3 If all your images are free and available to everybody or if your server is not 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 4 reachable from the internet then congratulations, you can run digilib without
5 authorization. You can leave the [digilib-config](digilib-config.html) setting 5 authorization: Leave the [digilib-config](digilib-config.html) setting
6 6
7 use-authorization=false 7 use-authorization=false
8 8
9 and ignore the rest of this chapter. 9 and ignore the rest of this chapter.
10 10
11 But if you have some images that are freely available and others 11 But if you have some images that are freely available and others
12 that should be only visible to some users then you need to configure digilib's 12 that should be only visible to some users then you need to set
13 authentication and authorization mechanism and set
14 13
15 use-authorization=true 14 use-authorization=true
16 15
16 and configure digilib's authentication and authorization mechanism.
17
17 ## Authentication and authorization 18 ## Authentication and authorization
18 19
19 digilib has different mechanisms for the tasks of *authentication* - establishing 20 digilib has different mechanisms for the tasks of *authentication* - establishing
20 the identity of the user requesting the image (more accurately the roles associated to 21 the identity of the user requesting the image (more accurately the roles associated to
21 this identity) - and *authorization* - establishing the rules for accessing specific 22 this identity) - and *authorization* - establishing the rules for accessing specific
22 images (the roles required to access the image). 23 images (the roles required to access the image).
23 24
24 The authe**n**tication mechanism is implemented by the digilib.auth.Auth**n**Ops interface 25 The authe<b>n</b>tication mechanism is implemented by the digilib.auth.Auth<b>n</b>Ops interface
25 implemented through the class configured in the `digilib-config` parameter 26 implemented through the class configured in the `digilib-config` parameter
26 `authnops-class` while the auhtori**z**ation mechanism is implemented by the 27 `authnops-class` while the authori<b>z</b>ation mechanism is implemented by the
27 digilib.auth.Auth**z**Ops interface implemented through the class configured in 28 digilib.auth.Auth<b>z</b>Ops interface implemented through the class configured in
28 `authzops-class`. 29 `authzops-class`.
29 30
30 All authentication and authorization classes are configured through different elements 31 All authentication and authorization classes are configured through different elements
31 in the common config file 32 in the XML config file
32 33
33 digilib-auth.xml 34 digilib-auth.xml
34 35
35 in the `WEB-INF` directory. 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.
36 42
37 ### Authentication: IpAuthnOps 43 ### Authentication: IpAuthnOps
38 44
39 `digilib.auth.IpAuthnOps` assigns roles based on the IP address of the user requesting the 45 `digilib.auth.IpAuthnOps` assigns roles based on the IP address of the user requesting the
40 image. This works well for situations where all users of the local network are allowed to 46 image. This works well for situations where all users of the local network are allowed to
41 access resources. The class reads the tag `digilib-adresses` from `digilib-auth.xml`: 47 access resources. The class reads the tag `digilib-adresses` from `digilib-auth.xml`:
42 48
43 <digilib-addresses> 49 <digilib-addresses>
44 <address ip="130.92.68" role="eastwood-coll,ptolemaios-geo" /> 50 <address ip="130.92.68" role="eastwood-coll,ptolemaios-geo" />
45 <address ip="130.92.151" role="wtwg" /> 51 <address ip="130.92.151" role="wtwg" />
46 <address ip="0:0:0:0:0:0:0:1" role="local" /> 52 <address ip="0:0:0:0:0:0:0:1" role="local" />
47 </digilib-addresses> 53 </digilib-addresses>
48 54
49 A computer with an ip address that matches "ip" is automatically granted all roles under "role". 55 A computer with an ip address that matches `ip` is automatically granted all roles under `role`.
50 The ip address is matched from the left (in full quads). Roles under "role" must be separated by comma only (no spaces). 56 The ip address is matched from the left (in full quads). Roles under "role" must be separated by comma only (no spaces).
51 57
52 Caution: If you run your Servlet Container (Tomcat) behind Apache or another reverse proxy 58 Caution: If you run your Servlet Container (Tomcat) behind Apache or another reverse proxy
53 then Tomcat only sees the IP-Address of the Apache server for all connections. You need to 59 then Tomcat only sees the IP address of the proxy server for all connections. You need to
54 configure Tomcat to honor the `X-Forwarded-For` and `X-Forwarded-Proto` headers. 60 configure Tomcat to honor the `X-Forwarded-For` and `X-Forwarded-Proto` headers.
55 61
56 ### Authentication: IpServletAuthnOps 62 ### Authentication: IpServletAuthnOps
57 63
58 `digilib.auth.IpServletAuthnOps` assigns roles based on the IP Address of the user requesting 64 `digilib.auth.IpServletAuthnOps` assigns roles based on the IP address of the user requesting
59 the image (see `IpAuthnOps` above) and uses the `ServletRequest.isUserInRole()` function of 65 the image (see `IpAuthnOps` above) and uses the `ServletRequest.isUserInRole()` function of
60 the Servlet Container if the roles provided by the IP address are not sufficient. 66 the Servlet Container if the roles provided by the IP address are not sufficient.
61 67
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.
62 71
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