NAME

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

SYNOPSIS

         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;
         };

DESCRIPTION

       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.

CONFIGURATION

       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.

SERVER SUPPORT

       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_perl and CGI)
       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.

BUGS

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

SEE ALSO

       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.

AUTHOR

       Toby Inkster <tobyink@cpan.org>.

COPYRIGHT AND LICENCE

       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.

DISCLAIMER OF WARRANTIES

       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)