Authentication Providers
Table of contents
Starting with Hayes, DekiWiki can be integrated with an external user directory, such as an LDAP server, an Drupal server, or a proprietary user management system. This allows users to sign into the wiki application without the need to create a local account first. Instead, DekiWiki will interact with the external user directory and generate a new account based on defined policies.
Multiple external authentication providers -- or simply providers -- can peacefully co-exist at the same time. This enables DekiWiki to seamlessly integrate with existing systems and provide headroom for future extensibility. Adding a new provider is as simple as entering its name and URI, DekiWiki takes care of the rest.
A provider is responsible for the following tasks:
- authenticating a user
- listing the user's group memberships
- listing all available groups
For systems without a notion of groups -- such as Drupal -- the provider must still return at least one group, be it as simple as "default".
LDAP and Active Directory: DekiWiki includes an LDAP provider for integration with OpenLdap and ActiveDirectory servers. It's a good example for creating new providers.
The following section describe how DekiWiki interacts with an external user directory.
REST Interface
As with the rest of the Deki API, the provider interface uses a RESTful design. REST provides many advantages over SOAP, which is another popular web-services standard. In REST, services rely almost exclusively on the well established HTTP standard. Content doesn't need to be encapsulated and described by XML documents with complicated schemas. Instead, REST specifications are so simple, they are shown by example. For a quick introduction to REST, read REST for the Rest of Us.
Credentials
Depending on the provider, it may be required to pass in an authentication/authorization token. For the purpose of these examples, we'll rely on basic HTTP authentication, which looks as follows:
Authorization: Basic bWF4bTpwYXNzd29yZA==
Authentication
The authentication request determines if a user has a valid username/password combination. This request is accomplished by using one of the standard HTTP authentication modes, such as basic authentication.
Authentication request:
GET /path/to/service/authenticate HTTP/1.1 Authorization: Basic bWF4bTpwYXNzd29yZA== Host: yourhost.com
Successful authentication response:
The provider responds with status code 200 (ok) upon successful authentication while also returning the requestor's user info.
HTTP/1.1 200 OK Date: Tue, 27 Mar 2007 00:13:58 GMT Content-Type: application/xml; charset=utf-8 Content-Length: 771 <user name="maxm"> <email>maximm@mindtouch.com</email> <groups> <group name="wikieditors"/> <group name="wikiadmins"/> <group name="Users"/> <group name="Administrators"/> </groups> </user>
Failed authentication response:
If the username/password combination was not recognized, the provider responds with status code 401 (unauthorized).
HTTP/1.1 401 Unauthorized Date: Mon, 26 Mar 2007 23:43:10 GMT
User Lookup
When a user successfully authenticates, DekiWiki retrieves additional information about the user to create an internal user record. The internal record is only used for tracking the user's activities and not for authentication.
User info request:
GET /path/to/service/users/maxm HTTP/1.1 Host: yourhost.com Authorization: Basic bWF4bTpwYXNzd29yZA=
Successful user info response:
The provider responds with status code 200 (ok) and a non-empty <user> document. The <user> document must contain the 'name' attribute, which will be used to create the user record, an <email> element, and a <groups> element.
HTTP/1.1 200 OK Date: Tue, 27 Mar 2007 00:13:58 GMT Content-Type: application/xml; charset=utf-8 Content-Length: 771 <user name="maxm"> <email>maximm@mindtouch.com</email> <groups> <group name="wikieditors"/> <group name="wikiadmins"/> <group name="Users"/> <group name="Administrators"/> </groups> </user>
Not found user info response:
The provider responds with status code 404 (Not found). Note that the response body can be anything and does not need to match the one shown below.
HTTP/1.1 404 Not Found Date: Tue, 27 Mar 2007 19:56:34 GMT Content-Length: 119 Content-Type: text/html; charset=iso-8859-1 <html><head><title>Not Found (404)</title></head><body><h1>Not Found (404)</h1><br />User 'waldo' not found</body></html>
All Groups
The DekiWiki group management screen can retrieve information about groups from a provider, making it easier for administrators to add group access policies.
All groups request:
GET /path/to/service/groups HTTP/1.1 Host: yourserver Authorization: Basic bWF4bTpwYXNzd29yZA==
All groups response:
The provider responds with status code 200 (ok) and a <groups> document.
HTTP/1.1 200 OK Date: Tue, 27 Mar 2007 00:29:15 GMT Content-Type: application/xml; charset=utf-8 Content-Length: 123 <groups> <group name="wikireaders" /> <group name="wikiadmins" /> <group name="wikieditors" /> </groups>
Group Lookup
The DekiWiki group management screen can confirm that an administrator entered a valid group.
Group info request:
GET /path/to/service/groups/wikieditors HTTP/1.1 Host: yourhost.com Authorization: Basic bWF4bTpwYXNzd29yZA==
Group found response:
The provider responds with status code 200 (ok) and a <group> document.
HTTP/1.1 200 OK Date: Tue, 27 Mar 2007 00:21:35 GMT Content-Type: application/xml; charset=utf-8 Content-Length: 308 <group name="wikieditors" />
Group not found response:
The provider responds with status code 404 (not found). Note that the response body can be anything and does not need to match the one shown below.
HTTP/1.1 404 Not Found
Date: Tue, 27 Mar 2007 20:02:42 GMT
Content-Length: 120
Content-Type: text/html; charset=iso-8859-1
<html>
<head>
<title>Not Found (404)</title>
</head>
<body>
<h1>Not Found (404)</h1>
<br />Group 'waldo' not found
</body>
</html>
Testing and Installing your new provider
After you've written and deployed your authentication provider script somewhere that Deki Wiki can get to via a URI, you simply need to tell tell Deki Wiki about it. Login to your wiki as an admin and go into control panel -> service management. You'll want to add a remote service with the type authentication. The URI can be any HTTP uri that points to the service methods for example http://myhost/path/to/service.
Type a description that users will see from the login page. Make sure it's enabled and optionally set it as the default. Save the service.
Logout and try to log in as the service. Any username/password that validates with your remote auth service gets created locally and will continue to be authenticated against the service.
Troubleshooting and common issues
- Check the logs of your remote service as well as Deki Wiki's (in bin/logs)
- Use an http sniffer to see whats getting sent
- Get help at the technical forum @ http://forums.opengarden.org and stop by the irc channel: irc.freenode.net #opengarden
PHP script that creates a cookie to authenticate on dekiwiki :
/* ------- Cookie's creation for Deki Wiki ------- */
require_once "HTTP/Request.php";
/* Request a value for the user's cookie */
$url = "http://website.com/@api/deki/users/authenticate/";
$req =& new HTTP_Request($url);
$req->setBasicAuth($login, $password);
$response = $req->sendRequest();
if (!PEAR::isError($response)) {
$output=$req->getResponseBody();
/* Authentication proccess : if the response contains 401 authentication failed, the user is not registered */
if(strpos($output,"authentication")==0 && strpos($output,"401")==0)
{
$cookie_deki=$req->getResponseCookies();
setcookie("authtoken",str_replace("\"","",$cookie_deki[0]['value']),time()+3600, '/')
}
else
{
$error = ERROR_DEKIWIKI_WRONG_CREDENTIALS;
}
}
else {
$response->getMessage();
$error = ERROR_WEB_SERVICE;
} edited 09:52, 2 Apr 2008