1Plack::Middleware::AuthU:s:eWrebCIoDn(t3r)ibuted Perl DoPcluamcekn:t:aMtiidodnleware::Auth::WebID(3)
2
3
4
6 Plack::Middleware::Auth::WebID - authentication middleware for WebID
7
9 use Plack::Builder;
10
11 my $app = sub { ... };
12 my $cache = CHI->new( ... );
13
14 sub unauthenticated
15 {
16 my ($self, $env) = @_;
17 return [
18 403,
19 [ 'Content-Type' => 'text/plain' ],
20 [ '403 Forbidden' ],
21 ];
22 }
23
24 builder
25 {
26 enable "Auth::WebID",
27 cache => $cache,
28 on_unauth => \&unauthenticated;
29 $app;
30 };
31
33 Plack::Middleware::Auth::WebID is a WebID handler for Plack.
34
35 If authentication is successful, then the handler sets "$env->{WEBID}"
36 to the user's WebID URI, and sets "$env->{WEBID_OBJECT}" to a Web::ID
37 object.
38
40 cache
41 This may be set to an object that will act as a cache for Web::ID
42 objects.
43
44 Plack::Middleware::Auth::WebID does not care what package you use
45 for your caching needs. CHI, Cache::Cache and Cache should all
46 work. In fact, any package that provides a similar one-argument
47 "get" and a two-argument "set" ought to work. Which should you use?
48 Well CHI seems to be best, however it's Moose-based, so usually too
49 slow for CGI applications. Use Cache::Cache for CGI, and CHI
50 otherwise.
51
52 You don't need to set a cache at all, but if there's no cache, then
53 reauthentication (which is computationally expensive) happens for
54 every request. Use of a cache with an expiration time of around 15
55 minutes should significantly speed up the responsiveness of a
56 WebID-secured site. (For forking servers you probably want a cache
57 that is shared between processes, such as a memcached cache.)
58
59 on_unauth
60 Coderef that will be called if authentication is not successful.
61 You can use this to return a "403 Forbidden" page for example, or
62 try an alternative authentication method.
63
64 The default coderef used will simply run the application as normal,
65 but setting "$env->{WEBID}" to the empty string.
66
67 webid_class
68 Name of an alternative class to use for WebID authentication
69 instead of Web::ID. Note that any such class would need to provide
70 a compatible "new" constructor.
71
72 certificate_env_key
73 The key within $env where Plack::Middleware::Auth::WebID can find a
74 PEM-encoded client SSL certificate.
75
76 Apache keeps this information in "$env->{'SSL_CLIENT_CERT'}", so it
77 should be no surprise that this setting defaults to
78 'SSL_CLIENT_CERT'.
79
80 no_object_please
81 Suppresses setting "$env->{WEBID_OBJECT}". "$env->{WEBID}" will
82 still be set as usual.
83
85 WebID is an authentication system based on the Semantic Web and HTTPS.
86 It relies on client certificates (but not on certification authorities;
87 self-signed certificates are OK).
88
89 So for this authentication module to work...
90
91 · You need to be using a server which supports HTTPS.
92
93 Many web PSGI web servers (e.g. HTTP::Server::Simple, Starman, etc)
94 do not support HTTPS natively. In some cases these are used with an
95 HTTPS proxy in front of them.
96
97 · Your HTTPS server needs to request a client certificate from the
98 client.
99
100 · Your HTTPS server needs to expose the client certificate to Plack
101 via $env.
102
103 If you're using an HTTPS proxy in front of a non-HTTPS web server,
104 then you might need to be creative to find a way to forward this
105 information to your backend web server.
106
107 · The client browser needs to have a WebID-compatible certificate
108 installed.
109
110 Nuff said.
111
112 Apache2 (mod_perl and CGI)
113 The SSLVerifyClient directive can be used to tell Apache that you want
114 it to request a certificate from the client.
115
116 Apache is able to deposit the certifcate in an environment variable
117 called SSL_CLIENT_CERT. However by default it might not. Check out the
118 SSLOptions directive and enable the "ExportCertData" option, or if
119 you're using mod_perl try Plack::Middleware::Apache2::ModSSL.
120
121 Gepok
122 Gepok is one of a very small number of PSGI-compatible web servers that
123 supports HTTPS natively. As of 0.20 it will request client
124 certificates, but you will need to use
125 Plack::Middleware::GepokX::ModSSL in order to make the certificate
126 available in the PSGI $env hashref.
127
129 Please report any bugs to
130 <http://rt.cpan.org/Dist/Display.html?Queue=Web-ID>.
131
133 Plack, Web::ID, Web::ID::FAQ.
134
135 General WebID information: <http://webid.info/>,
136 <http://www.w3.org/wiki/WebID>,
137 <http://www.w3.org/2005/Incubator/webid/spec/>,
138 <http://lists.foaf-project.org/mailman/listinfo/foaf-protocols>.
139
140 Apache mod_ssl: Plack::Middleware::Apache2::ModSSL, Apache2::ModSSL,
141 <http://httpd.apache.org/docs/2.0/mod/mod_ssl.html>.
142
143 Gepok: Gepok, Plack::Middleware::GepokX::ModSSL.
144
146 Toby Inkster <tobyink@cpan.org>.
147
149 This software is copyright (c) 2012 by Toby Inkster.
150
151 This is free software; you can redistribute it and/or modify it under
152 the same terms as the Perl 5 programming language system itself.
153
155 THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
156 WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
157 MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
158
159
160
161perl v5.30.0 2019-07-26 Plack::Middleware::Auth::WebID(3)