Diligence is still under development and incomplete, and some this documentation is wrong. For a more comprehensive but experimental version download the Savory Framework, which was the preview release of Diligence.
Authentication Service
This all-important service manages a few systems, which together allow your site to be "logged into" by individual users.
Usage
Make sure to check out the API documentation for Diligence.Authentication.
Users
Users are maintained in a simple MongoDB collection. You can easily attach settings to any user document, which can have any structure and depth you need.
Passwords are hashed many times and stored with a random salt. This good practice makes sure that even if a hacker were to steal your database and hack into a few accounts, they would not be able to use the results of their work to crack the other passwords.
Users are considered "entities" by the authorization service, such that you can attach permissions to user documents. Users can inherit permissions from groups and from other users.
Though you can maintain the user documents yourself, you can add the registration feature to allow individuals to create their own users.
Sessions
When users do log in, they get a cookie with a session ID, which matches a document in the sessions collection. Thus, every conversation is associated with a session. You can store anything you want in the session document.
The authorization service can check any operation against the conversation's session to make sure it's permitted.
The service comes with a task to make sure to remove sessions that have not been used for a while. It's a good security feature! (People tend to forget to log out, which can be especially dangerous in public places.)
Caching Per User
This very powerful feature uses a cache key patten handler to inject the currently logged in user ID into the cache key. This lets you cache any /web/dynamic/ or /web/fragment/ resource per user, which can do wonders towards helping your site scale. Of course, it does not make sense to cache every dynamic part of a page, but if you can indetify those fragments that look different only for different users then you've achieved a lot.
Authentication Forms
The authentication service comes with a bunch of /web/fragments/ that you can easily drop in to any page. They handle things like logging in, logging out, and showing the currently logged-in user.
Providers
Using Diligence's plug-ins library, the authentication service adds transparent support for 3rd-party authentication providers. Currently supported providers are Facebook, Windows Live, Twitter and OpenID (tested with Google, Yahoo, Myspace, LiveJournal).
Users coming from outside are real users: the first time they log in, a user document is created for them in the collection, and it can join in with settings, permissions, etc. Depending on how your application works, you can treat these users as any other user, or use the authorization service to treat them as "guests" with the ability to do only certain tasks. All 3rd-party users are automatically associated with an authorization group named after their provider. So, you can grant special permissions (or deny permissions) to "facebook."
This useful feature allows your application to be especially welcoming. Studies have shown that typical users think twice when a site requires registration. People either don't want to invest the effort in registering, or are anxious about yet another copy of their personal data being stored in somebody's database.
The Diligence Manual is provided for you under the terms of the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. The complete manual is available for download as a PDF.
