The Authentication API

The Authentication API enables your own scripts to determine who has what access to your wiki and to validate who they are. It's a powerful and flexible facility that could be used to use your behind-the-firewall LDAP server to administer roles and permissions on your company's PBwiki, or use your campus's single sign-on facility to validate the identities of your wiki's users.

The Process

Currently, the Authentication API is all or nothing. That means that you either wholly switch over your wiki to your server's auth access, or you use PBwiki's. There is no current "either/or" functionality where a user can either log in with PBwiki authentication (such as the wiki-wide password or their PBwiki Identity) or using your mechanism.

You can specify the URL that will be used by your wiki to authenticate a user in the administrative control panel for your wiki under the "API" section, after your wiki has been approved for API use and you've agreed to the API Terms of Service.

From there on out, whenever a user needs to be authenticated (such as trying to make an edit), they will be passed to your URL along with a special token that uniquely designated the login attempt and the site the user was trying to access.

Your service should then determine - through either automated means or by asking the user for their password - the user's identity and access level. Your service should then pass the user back to your PBwiki with a signed authentication token to let us be sure that your service did authorize this user. PBwiki then accords the user the appropriate permissions. Be careful about assigning users "admin" permission, as they can then make serious changes to your wiki, including deleting it and changing the Authentication API URL.

The Details

Let's say you have a wiki called "mywiki.pbwiki.com" and you have your authentication script at "https://www.example.edu/pbwikiAuth.asp". PBwiki will redirect the user desiring authentication to https://www.example.edu/pbwikiAuth.asp?tok=a18b327c8&host=mywiki.pbwiki.com - your script should take note of this token, as it will be needed to validate the user's login attempt. Note that the authentication token is only good for a single login attempt. If you have a multi-step login / authentication process, you could consider giving the user the token and host as a cookie. You should also perform the authentication over HTTPS if at all possible to avoid exposing your user's login and password.

You can then ask the user for their username and password on your system. You should be able to retrieve their email and name as well as their privilege level:

admin (able to administer the wiki, including the ability to delete the wiki)
mod (able to delete files and pages and perform other unrecoverable operations)
write (able to make edits, revert pages, and upload files, but not not make unrecoverable changes)
read (not able to change any aspect of the wiki)

After you've determined the user's identity & access level, your script should compute the authentication token and redirect the user's browser to our authentication return script.

The authentication token is computed by taking the hex representation of a SHA-1 hash of: the URL to which you'll be redirecting the user concatenated with the authentication token we passed to your script concatenated with your API key. Let's suppose you authenticated a user as "John Doe" with email "john@example.edu" and access "write" from IP "1.2.3.4", with a login session that expires October 24, 2006 at midnight GMT. Expiration times are given as integer Unix timestamp values, in this case 1161666000.

All parameters MUST be URI-escaped - if you forget this and use '@' instead of '%40', the authentication will fail.

The URL for the return consists of https://YOURWIKI.pbwiki.com/authReturn.php?name=NAME&email=EMAIL&access=ACCESS&ip=IP&expires=EXPIRES
so in our case this would be:
https://mywiki.pbwiki.com/authReturn.php?name=John%20Doe&email=john%40example.edu&access=write&ip=1.2.3.4&expires=1161666000

After computing the authentication token based on this full URL, "&authTok=AUTHTOK" should be added to the end of the URL and the user should be redirected to this URL.

PBwiki will then process the user's authentication credentials. If they are valid, the user will be bounced back to the front page of their wiki as logged in to the wiki with the name, email, and permissions your API specified.

Sha hash example

We use the php implementation of the sha1 hash algorithm and while that should be standardized, it's good to have an example so you can verify that you'll get the same results we do. The literal string 'hello world' should give the result as shown below:

$hash_res = sha1('hello world');
$expected = '2aae6c35c94fcfb415dbe95f408b9ce91ee846ed';
if($hash_res == $expected) { print "Success"; }

Logout

If you set an optional logout URL, users will be directed there when they click "logout". While you can take any action you'd like on this page, it's recommended that you verify the user wishes to log out of all SSO apps and do so if requested.

Sample Code

<?
$apiKey = "XXXX.....";
$tok = @$_GET['tok'];
$host = @$_GET['host'];
if(!$tok){
  die("no token!");
}

if(!$_GET['done']){
  die("ok to punt you? <a href=/authtest.php?tok=$tok&host=$host&done=1>Yeah.</a>");
}

// okay, let's authenticate you as a reader.
$name = "Joe Dobbson";
$email = "joe@example.org";
$access = "mod";
$ip = $_SERVER['REMOTE_ADDR'];
$sessionExpires = time()+30; // 30 second session!

$retURL = "https://$host/authReturn.php?".
  "name=".urlencode($name)."&".
  "email=".urlencode($email)."&".
  "access=".urlencode($access)."&".
  "ip=".urlencode($ip)."&".
  "expires=".urlencode($sessionExpires);

$authTok = sha1($retURL.$tok.$apiKey);
$retURL .="&authTok=".urlencode($authTok);

header("Location: $retURL");
print "punting you back to $retURL";
?>