4 _WebIDDelegatedAuth_ is a scaled down version of _libAuthentication_
5 (<https://github.com/melvincarvalho/libAuthentication>).
6 Whereas libAuthentication is a more general purpose PHP support library for the WebID protocol,
7 _WebIDDelegatedAuth_ can only be used to allow Web applications to support WebID authentication by delegating
8 WebID authentication to their prefered third part WebID identification provider.
9 All credit belongs to the initial authors of _libAuthentication_.
11 Further details of the WebID protocol can be obtained at <http://webid.info>
13 If you would like to learn how to get going quickly without diving to much into
14 technical details, then read section 2. and 3.
16 The core classes of _WebIDDelegatedAuth_ are tackled in section 3. and 4.
18 --------------------------------------------------------------------------------
20 2. How to set up "delegated" WebID authentication in a few lines of code
21 ================================================================================
23 There are a few flavours of WebID authentication. The following very simple
24 example shows how to setup a WebID authentication relying on a third party identity
25 provider such as foafssl.org or auth.my-profile.eu.
29 * Publicly available internet site
30 * Apache 2.2 and PHP 5.2.x or higher
32 Checkout and create a script that will be the entry point for your application:
34 git clone https://github.com/WebIDauth/WebIDDelegatedAuth.git
39 require_once('WebIDDelegatedAuth/lib/Authentication.php');
40 $auth = new Authentication_Delegated();
42 if (!$auth->isAuthenticated())
44 echo $auth->authnDiagnostic;
45 echo '<a href="https://foafssl.org/srv/idp?authreqissuer=http://localhost/index.php">Click here to Login</a>';
49 echo 'Your have succesfully logged in.<pre>';
53 Make sure the _"authreqissuer"_ points to YOUR site (to reinvoke the same index.php) and...
56 You just set up you first WebID powered site. Behind the scenes,
57 _WebIDDelegatedAuth_ has an embedded copy of foafssl.org's certificate (in its code) which is used
58 in the authentication process.
61 Note that if you wish to use another delegated identity verification
62 service (for instance 'auth.my-profile.eu'), you may need to change line 4 as :
64 $auth = new Authentication_Delegate(TRUE, NULL, Authentication_URL::parse('https://auth.my-profile.eu'));
66 Then you'd change the login link to :
68 echo '<a href="https://auth.my-profile.eu/auth/?authreqissuer=http://localhost/index.php">Click here to Login</a>';
70 This will ensure that you wish to verify the server's response
71 signature according to the proper certificate, which is also already present in Authentication_X509CertRepo.php
73 Should you want to host your own WebID identity provider (like foafssl.org or auth.my-profile.net), you may check a PHP implementation at https://github.com/WebIDauth/WebIDauth (which is the software used to operate auth.my-profile.net).
75 --------------------------------------------------------------------------------
77 3. Brief overview of _WebIDDelegatedAuth_'s core classes
78 ================================================================================
80 _WebIDDelegatedAuth_ provides the following core classes:
83 Authenticate user by trying the supported authentication methods in a fixed
84 and reasonable sequence
86 * Authentication_Delegated
87 Authenticate via the delegated WebID method using a 3rd party WebID
88 identity provider (foafssl.org and auth.my-profile.eu supported by default)
90 * Authentication_Session
91 Create a session cookie after successful authentication to speed up
92 subsequent authentication attempts
94 A detailed description of the core classes an their usage follows.
96 --------------------------------------------------------------------------------
98 4. Detailed description of _WebIDDelegatedAuth_'s core classes
99 ================================================================================
102 --------------------------------------------------------------------------------
103 This class provides easy access to all supported authentication mechanisms.
104 On instantiation, it performs the following operations:
106 1. Checks if an authentication session cookie is present
107 2. If 1. fails, it tries to authenticate via delegated WebID (see _Authentication\_Delegate_)
108 3. If authentication is successful, it loads the corresponding WebID URI
110 $auth = new Authentication($config) // $config is optional
114 - `$auth->isAuthenticated()` returns true
115 - `$auth->webid` contains the authenticated webid
119 If an error occurs, an explanation can be retrieved by inspecting
120 `$auth->$authnDiagnostic`.
121 If you want to terminate the authenticated session, it is a good idea to call
124 class Authentication_Session
125 --------------------------------------------------------------------------------
127 This class usually won't be instantiated directly. If a given authentication
128 method succeeds, it can optionally persist that information by instantiating
129 _Authentication\_Session_. It stores the authenticated webid and the parsed foaf
130 file in `$_SESSION`. This results in a significant speed up in successive
131 authentication attempts. If you want to create it manually, you can do that as follows:
133 $authSession = new Authentication_Session(1, $webid)
135 where 1 indicates the fact of successful authentication and `$webid` is a URI string.
137 class Authentication_Delegated
138 --------------------------------------------------------------------------------
140 Using the delegated WebID method is probably the easiest way to get you start
141 quickly leveraging this powerful authentication method. It is also the easiest
142 to set up. Refer to Section 2. for an example and make sure you set up the example
143 using a public domain name or a public IP address. I you want find out more details
144 how the identity provider works, see <https://foafssl.org/srv/idp>.
146 You need to instantiate _Authentication\_Delegated_ at a common entry point
147 to your site (e.g. index.php):
149 $auth = new Authentication_Delegated();
151 Most of the input is automatically retrieved from the global php context variables
152 (`$_REQUEST`, `$_SERVER` etc.), so using the default constructor parameters is fine.
156 - `$auth->isAuthenticated()` returns true
157 - `$auth->webid` contains the authenticated webid
159 If not explicitly disabled, on successful authentication an instance of
160 _Authentication\_Session_ will also be created, to speed up further authentication
161 attempts. If that something you don't want to happend, you need to call the constructor
164 $auth = new Authentication_Delegated( false );
168 If an error occurs, an explanation can be retrieved by inspecting `$auth->$authnDiagnostic`.
169 If you want to terminate the authenticated session, it is a good idea to call `$auth->logout`.