debian man page for plack::middleware::auth::webid

Plack::Middleware::Auth::WebID(3pm)			User Contributed Perl Documentation		       Plack::Middleware::Auth::WebID(3pm)

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...

       o   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.

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

       o   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.

       o   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.19 it does not request client
       certificates, however there is a fork which provides client certificate support at https://github.com/tobyink/p5-gepok
       <https://github.com/tobyink/p5-gepok>, which will hopefully be merged into the release versions of Gepok at some point in the near future.

       This still doesn't give you the certificate in $env though. I'm working on some Plack middleware to do that. It will be released as
       Plack::Middleware::GepokX::ModSSL in due course.

BUGS
       Please report any bugs to http://rt.cpan.org/Dist/Display.html?Queue=Web-ID <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 <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>.

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.14.2							    2012-05-20				       Plack::Middleware::Auth::WebID(3pm)