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

       Toby Inkster <tobyink@cpan.org>.

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

       cache
           This may be set to an object that will act as a cache for Web::ID objects.

           Plack::Middleware::Auth::WebID  does  not  care  what  package  you  use for your caching needs. CHI,
           Cache::Cache and Cache should all work. In fact, any package that  provides  a  similar  one-argument
           "get"  and  a  two-argument  "set"  ought  to  work. Which should you use? Well CHI seems to be best,
           however it's Moose-based, so usually too slow for CGI applications. Use Cache::Cache for CGI, and CHI
           otherwise.

           You don't need to set a cache at all, but if  there's  no  cache,  then  reauthentication  (which  is
           computationally  expensive)  happens  for  every  request.  Use of a cache with an expiration time of
           around 15 minutes should significantly speed up the responsiveness  of  a  WebID-secured  site.  (For
           forking  servers  you  probably  want  a  cache that is shared between processes, such as a memcached
           cache.)

       on_unauth
           Coderef that will be called if authentication is not successful. You can use this to  return  a  "403
           Forbidden" page for example, or try an alternative authentication method.

           The  default  coderef  used will simply run the application as normal, but setting "$env->{WEBID}" to
           the empty string.

       webid_class
           Name of an alternative class to use for WebID authentication instead of Web::ID. Note that  any  such
           class would need to provide a compatible "new" constructor.

       certificate_env_key
           The  key  within  $env  where  Plack::Middleware::Auth::WebID  can  find  a  PEM-encoded  client  SSL
           certificate.

           Apache keeps this information in "$env->{'SSL_CLIENT_CERT'}", so it should be no surprise  that  this
           setting defaults to 'SSL_CLIENT_CERT'.

       no_object_please
           Suppresses setting "$env->{WEBID_OBJECT}". "$env->{WEBID}" will still be set as usual.

       This software is copyright (c) 2012 by Toby Inkster.

       This  is  free  software;  you  can  redistribute  it and/or modify it under the same terms as the Perl 5
       programming language system itself.

       Plack::Middleware::Auth::WebID is a WebID handler for Plack.

       If authentication is successful, then the handler sets "$env->{WEBID}" to the user's WebID URI, and sets
       "$env->{WEBID_OBJECT}" to a Web::ID object.

       THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT  ANY  EXPRESS  OR  IMPLIED  WARRANTIES,  INCLUDING,  WITHOUT
       LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.

perl v5.32.1                                       2021-09-11                Plack::Middleware::Auth::WebID(3pm)

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

       Plack, Web::ID, Web::ID::FAQ.

       General        WebID       information:       <http://webid.info/>,       <http://www.w3.org/wiki/WebID>,
       <http://www.w3.org/2005/Incubator/webid/spec/>,
       <http://lists.foaf-project.org/mailman/listinfo/foaf-protocols>.

       Apache             mod_ssl:             Plack::Middleware::Apache2::ModSSL,              Apache2::ModSSL,
       <http://httpd.apache.org/docs/2.0/mod/mod_ssl.html>.

       Gepok: Gepok, Plack::Middleware::GepokX::ModSSL.

       WebID  is an authentication system based on the Semantic Web and HTTPS.  It relies on client certificates
       (but not on certification authorities; self-signed certificates are OK).

       So for this authentication module to work...

       •   You need to be using a server which supports HTTPS.

           Many web PSGI web servers (e.g. HTTP::Server::Simple, Starman, etc) do not support HTTPS natively. In
           some cases these are used with an HTTPS proxy in front of them.

       •   Your HTTPS server needs to request a client certificate from the client.

       •   Your HTTPS server needs to expose the client certificate to Plack via $env.

           If you're using an HTTPS proxy in front of a non-HTTPS web server, then you might need to be creative
           to find a way to forward this information to your backend web server.

       •   The client browser needs to have a WebID-compatible certificate installed.

           Nuff said.

   Apache2(mod_perlandCGI)
       The SSLVerifyClient directive can be used to tell Apache that you want it to request a  certificate  from
       the client.

       Apache  is  able  to deposit the certifcate in an environment variable called SSL_CLIENT_CERT. However by
       default it might not. Check out the SSLOptions directive and enable the "ExportCertData"  option,  or  if
       you're using mod_perl try Plack::Middleware::Apache2::ModSSL.

   Gepok
       Gepok  is  one  of a very small number of PSGI-compatible web servers that supports HTTPS natively. As of
       0.20 it will request client certificates, but you will need to use  Plack::Middleware::GepokX::ModSSL  in
       order to make the certificate available in the PSGI $env hashref.

         use Plack::Builder;

         my $app   = sub { ... };
         my $cache = CHI->new( ... );

         sub unauthenticated
         {
           my ($self, $env) = @_;
           return [
             403,
             [ 'Content-Type' => 'text/plain' ],
             [ '403 Forbidden' ],
           ];
         }

         builder
         {
           enable "Auth::WebID",
               cache     => $cache,
               on_unauth => \&unauthenticated;
           $app;
         };