---
name: "Plack::Middleware::Auth::WebID"
section: "3pm"
platform: "linux"
package: "libweb-id-perl"
version: "1.927-3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Plack::Middleware::Auth::WebID"
---

# Plack::Middleware::Auth::WebID(3pm)

authentication middleware for WebID

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