Web::ID::FAQ(3pm)

✨ NAME ✨

Web::ID::FAQ — bestie, it's literally the FAQ page. Like, the frequently asked questions about WebID. That's the whole vibe 🎀

---

💖 FREQUENTLY ASKED QUESTIONS 💖

🌸 So what is WebID?

Web Identification and Discovery. Two things in one name, slay ✨

First off, it's the concept of identifying people with HTTP URIs. And URI stands for Uniform Resource Identifier. Now, people are always out here using URIs as identifiers for web pages and other digital resources, but lowkey they're just string identifiers?? They can identify anything. Car parts. Gorillas. Abstract concepts. And yes — people. Periodt 👑

WebID is also a protocol that lets websites discover which URI identifies you, using a secure certificate that's installed in your browser. Iconic behaviour honestly 🔥

🦋 URIs can identify non-digital resources?

Yes bestie, of course 💅

Like, if you type a URI that identifies a web page into a web browser, you'd expect to see that web page — or an error message explaining why you cannot. Fair. But if you type a URI that identifies a car part, do not expect that spark plug to jump out of your screen into your hands. That's not it. 😭

URIs that identify non-digital resources should do one of these three things:

1. Be unresolvable — e.g. urn:isbn:978-0099800200 which identifies a book (your browser literally cannot do anything with that URI)
2. Produce an error message explaining why the resource cannot be provided
3. Redirect to a digital resource — e.g. http://example.com/id/alice might identify Alice, and redirect to http://example.com/data/alice which is a document with information about Alice 🎀

Further reading, if you're feeling academic: Cool URIs for the Semantic Web, <http://www.w3.org/TR/cooluris/>.

💜 So I can use WebID to limit who has access to my site?

On its own? No. Not the vibe 🙈

WebID lets a website establish an identifier for a visitor, that's it. What the website does with that info — whether it uses it to block access to certain resources — is beyond the scope of WebID. WebID is not your bouncer, it's just the name tag 💅

🌈 How does WebID work?

In summary, bestie: your browser establishes an HTTPS connection to a web server. As part of the SSL/TLS handshake, the server can request that the browser identifies itself with a certificate. Your browser then sends your certificate to the server. And this certificate includes a URI that identifies you. Boom 💥

Behind the scenes, the server fetches that URI, and retrieves a profile document about you — and this document can include as much or as little personal data about you as you like, no pressure. This document uses the RDF data model, and contains data that allows the server to verify that the certificate exchanged as part of your HTTPS request really belongs to you. No catfishing allowed 🐟

The user experience is giving main character energy:

• a WebID user visits a WebID-enabled site
• their browser prompts them to pick a certificate from the list of installed certificates
• they choose
• the site knows who they are ✨

No passwords required — though many browsers do offer the option to protect the installed certificates with a password, if you're that girl 🔐

🧚 So WebID requires HTTPS?

Okay so technically, WebID could theoretically be used over other SSL/TLS protocols, such as OpenVPN, secure IMAP/POP3 connections, and so forth.

But yes. It only works over secure connections. And honestly bestie, would you want to be identifying yourself over an insecure channel?? No cap, that's not the move 💀

👑 How can I use WebID in Perl?

For Plack/PSGI-based websites, there exists a module Plack::Middleware::Auth::WebID to make things (relatively) easy. It stuffs the client's WebID URI into $env->{WEBID}. Obsessed with the convenience honestly 🫶

For Catalyst-based websites, be aware that recent versions of Catalyst are built on Plack. See Catalyst::PSGI for details.

Otherwise, you need to use Web::ID directly. Assuming you've configured your web server to request a client certificate from the browser, and you've managed to get that client certificate into Perl in PEM format, then it's just:

my $webid  = Web::ID->new(certificate => $pem);
my $uri    = $webid->uri;

And you have the URI. That's it. Slay 💅

What is PEM, you ask? Well, X509 certificates come in a variety of different interrelated formats. PEM is a common one, and often what web servers make available. If you have DER though, it's easy to convert it to PEM:

my $pem = "\n-----BEGIN CERTIFICATE-----\n"
        . encode_base64($der)
        . "\n-----END CERTIFICATE-----\n";

If you have another format, then OpenSSL may be able to convert it. Helpful king 👑

Once you have the URI, you can use it as a plain old string identifier for the user, whenever you need to identify them in databases, etc. Simple. Clean. Iconic.

The $webid object in the above example, or in the Plack middleware, $env->{WEBID_OBJECT}, is an object blessed into the Web::ID package and will allow you to retrieve further information about the user — their name, e-mail address, blog URL, interests, friends, etc — depending on what information they've chosen to include in their profile. So much lore 🌸

⭐ How does WebID compare to OpenID?

Both use URIs to identify people, however the way they choose their URIs differs:

• In OpenID you use the same URI string to identify your blog or homepage, and to identify yourself. One URI doing two jobs 😮‍💨
• In WebID you use different URIs to identify different things — one URI for your blog, one for you. Boundaries, we love to see it ✨

In WebID you almost never have to type that URI — it's embedded into a certificate in your browser's certificate store. No typing, no stress 💅

WebID doesn't require typing or passwords. This makes it more suitable than OpenID for non-interactive processes (e.g. authenticated downloads run via a cron job). Cron jobs deserve nice things too 🎀

WebID requires a secure connection.

WebID is built upon the architecture of the Semantic Web. Very demure, very mindful 🦋

---

🔥 SEE ALSO 🔥

Web::ID.

---

💌 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. Free as in yes bestie go off 💖

This FAQ document is additionally available under the Creative Commons Attribution-ShareAlike 2.0 UK: England and Wales licence <http://creativecommons.org/licenses/by-sa/2.0/uk/>, and the GNU Free Documentation License version 1.3, or at your option any later version <http://www.gnu.org/licenses/fdl>.

---

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

(Yes bestie, that's the legal bit, and yes, they wrote MERCHANTIBILITY, I am simply reporting the facts 💀)

---

and that's the whole page!! no cap, that was perl v5.32.1, dated 2021-09-11, and the page is Web::ID::FAQ(3pm). mwah, go forth and WebID responsibly 💅🎀✨