Plack:...:WebID(3pm)

📦
version 1.927 · 6 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

✨ Plack::Middleware::Auth::WebID ✨

okay so bestie, this is a Perl module manual page (a 3pm one, from the User Contributed Perl Documentation collection) and it's literally called Plack::Middleware::Auth::WebID — it's the authentication middleware for WebID 🦋. Sit down, grab a strawberry, we're doing this 💅

🌸 NAME 🌸

Plack::Middleware::Auth::WebID — authentication middleware for WebID. that's the whole vibe, no notes 🎀

🦋 SYNOPSIS 🦋

here's the glow-up, copy it exactly bestie:

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. that's it, that's the job 🫶

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. iconic behaviour honestly 😭✨

🎀 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, fr fr. 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. So which one 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. slay, decisions made 💅

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 single 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. no cap 🫡

💜 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'. the way that it just makes sense 🧚

✨ no_object_please

Suppresses setting $env->{WEBID_OBJECT}. $env->{WEBID} will still be set as usual. no thoughts, just the WebID 🔥

👑 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). yes bestie, self-signed is valid here 💅

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 certificate 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. rare HTTPS-native king 👑

💀 BUGS 💀

Please report any bugs to <http://rt.cpan.org/Dist/Display.html?Queue=Web-ID>. do it bestie, they want to know 🙈

🌈 SEE ALSO 🌈

🫶 AUTHOR 🫶

Toby Inkster <tobyink@cpan.org>. thank you toby, genuinely 💜

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

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

like, no promises bestie, that's the whole point 😭

and that's the tea 🍓 — this page is perl v5.32.1, dated 2021-09-11, and yeah the header up top said Plack:...:WebID(3pm) twice because it's from the User Contributed Perl Documentation collection. slay, we're done here 💖✨🦋

📦 where this page comes from