An 'Authentication' hook is called ostensibly to check the user's password. It can do more than that though.
It is called something like:
$dav_principal = AuthenticationHook( $username, $password );
In general it should:
- Accept a username / password
- Confirm that the username / password are correct
- Create (or update) a 'dav_principal' record in our database
- Return the 'dav_principal' record as an object
- Return the boolean 'false' value when authentication fails
It can expect:
- DAViCal Configuration data will be available in $c->authenticate_hook['config'], which might be an array, or whatever is needed.
Bypassing password checks
If you know that the webserver validated the password (e.g. with Kerberos or such), then you can trust the username is correct and fetch the correct user details from your canonical source of such data, constructing a record to return to DAViCal.
Updating a user's details
DAViCal holds a user's details in the database and many queries join against this table, so it is important that the user's details within DAViCal should reflect changes in your canonical source of such data. In order to assist in this there you can:
within your code and you will have access to the
UpdateUserFromExternal($dav_principal) and the
CreateHomeCalendar($username) functions which will hopefully simplify your job. That include also contains an example routine.
Some drivers will allow you to map fields from an authentication source (e.g. LDAP). The fields in DAViCal which may be mapped in this way are as follows:
|'username'||The user's logon name|
|'email'||The user's e-mail address. Used for free-busy lookups when scheduling and for delivering meeting invitations.|
|'user_active'||Whether this user is currently active, and allowed to log in.|
|'modified'||When this user data was last modified.|
|'fullname'||The user's full name|
|'email_ok'||The date on which the user's e-mail address was confirmed correct.|
|'date_format_type'||The letter 'E', 'U' or 'I' for "European (dd/mm/yyyy)", "US (mm/dd/yyyy)" or "International (yyyy-mm-dd)" date formats.|
|'locale'||A locale for this user such as 'es_MX' or 'en_NZ'.|
|'type_id'||1 indicates a person, 2 is a 'bookable resource' such as a car or meeting room, and 3 is a group which will not have calendars by default.|
|'displayname'||A displayname for this principal. Will default to the fullname.|
|'default_privileges'||A 24-bit bitmask of the privileges for this user. See Permissions for more background, though at present you'll have to look at the code for the exact details of which bit is which privilege. This is definitely *not* recommended for the faint at heart! and you're probably better to just stick with the site-wide default_privileges configuration which is an array of permission names, and much easier.|