Copyright 2012 Andrei Sambra - firstname.lastname@example.org
What is WebIDauth?
Right now, WebIDauth supports the following functionalities:
- initiates the WebID protocol, by requesting an SSL client from connecting clients
- checks the request for a variable called verbose and verifies if it is set, and if so it displays the contents of the certificate used to connect to the IdP (the request does not have to contain a valid authreqissuer value)
- checks if the SubjectAltName filed contains something else other than the webid uri, and only processes the URI
- checks if the webid profile contains multiple public keys and cycles through them looking for a match
One may check the demo available at https://my-profile.eu/ for instance (which uses WebIDDelegatedAuth to consume WebID and which relies on https://auth.my-profile.eu/, the Identification Provider running WebIDauth.
How it works
To take an example, the web application at http://sp.example.com/ (which could be called Service Provider or SP) could have a "Login" link on their main page to allow users to authenticate using their webids (check http://auth.my-profile.eu/ for an example of such a demo SP). This link points to a server which is running WebIDauth, let's say https://idp.example.com/, and which we will call IdP (Identification Provider) from now on (check https://auth.my-profile.eu/ for a real IdP). A typical link would look something like this:
What happens next is the IdP will demand an SSL certificate from the user's browser. From the certificate it will extract the webid URI, then after fetching the FOAF profile located at that specific URI it will attempt to match the public key of the certificate with the data found in the FOAF profile. Of course, additional verification steps take place during this process.
If the two match, it will then redirect the user back to the page contained in the authreqissuer variable (the Service at http://sp.example.com/), appending several variables. For client compatibility reasons, the variable names are the same with those returbed by foafssl.org, hence the new URL will look like this:
Where the above variables have the following meanings:
$authreqissueris the URL passed by the server in the initial request (https://sp.example.com/index.php in the example).
$webidis the WebID of the user connecting (the URL of the user's FOAF profile).
$timeStampis a time stamp in XML Schema format. This timestamp protects against replay attacks.
$URLSignatureis the signature of the whole URL in bold above (signed with the IdP's private SSL key).
$refereris the address of the IdP, which might be needed to fetch the public key of the IdP's SSL certificate (in this example idp.example.com)
In case of error the service gets redirected to the following URL: $authreqissuer?error=$code
Where $code can be either one of:
nocert:No certificates installed in the client's browser.
certExpired:The certificate has expired
noVerifiedWebId:WebId does not match the certificate.
noWebId:No identity found for existing WebID.
IdPError:Other error(s) in the IdP setup. Please warn the IdP administrator.
PHP, OpenSSL, Apache's mod_ssl
It requires a dedicated Web server whose SSL configuration can be adjusted so that it will initiate the SSL cert request to the connecting clients (see instructions in the example dot.htaccess provided). Note that this may require a global configuration for Web servers like Apache, which will prevent hosting other Web apps on the same server if they don't need WebID authentication to be enabled full time.
- Simply copy the all the contents to your public web directory.
- Rename the dot.htaccess file to .htaccess (or adjust your web server's config in a similar way)
- Make sure Apache's mod_ssl is enabled on your webserver.
- Edit file 'index.php' and replace the $server_key variable to use your server's private key. You may also change the temporary directory to some other location than the default one.
- Save everything and start authenticating users by having them click a link similar to this one: https:///index.php?authreqissuer=
- test different formats of webid profiles