1Plack::Middleware::AuthU:s:eWrebCIoDn(t3r)ibuted Perl DoPcluamcekn:t:aMtiidodnleware::Auth::WebID(3)
2
3
4

NAME

6       Plack::Middleware::Auth::WebID - authentication middleware for WebID
7

SYNOPSIS

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

DESCRIPTION

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

CONFIGURATION

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

SERVER SUPPORT

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

BUGS

129       Please report any bugs to
130       <http://rt.cpan.org/Dist/Display.html?Queue=Web-ID>.
131

SEE ALSO

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

AUTHOR

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

DISCLAIMER OF WARRANTIES

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.36.0                      2023-01-20 Plack::Middleware::Auth::WebID(3)
Impressum