Planning Suite: plan, organize, organise, schedule, rota, roster, event management

Authentication System Documentation

This document details the Planning Suite Authentication System, detailing how users are registered and authenticated, and how they can be deleted. Some of it is targetted at site administrators, discussing database management topics, but it also includes some frequently asked questions for the rest of us.

Contents

The Shared Schema

The information stored by an organization about individuals can be split into two categories:

  • User specific information: Information about the individual, irrespective of the organization they belong to. This could include their name, email address, password, address, telephone number.
  • Organization specific information: Information about the individual's relationship with the organization, like when they joined, their membership status, relevant skills or certifications.

In Planning Suite we store these two classes of information in two separate database schemas. The user specific information is stored in a "Shared Schema", shared by all organizations that use planning suite, and then the organization specific information is stored in the site specific information. For Kirkwall Baptist Church, the site specific information is stored in the "kbc" schema.

This gives the following benefits:

  • If a user changes their email address, or another shared attribute, then all organizations benefit.
  • Organizations can use several instances of Planning Suite to manage their data rather than having to store it all in one instance. Perhaps on for each office or unit.
  • Login between sites is simplified as they all use the same password

User Names

User Names at Planning Suite perform a number of functions:

  • Login Key: User Names can be used along with the password to login to the site.
  • User reference: When uniquely referencing a user within the realm of the site, perhaps to assign a user to a duty or a group, we use the usernames.
  • Email Alias: Should the site be making use of the email alias functionality, then the user will have an alias of [UserName]@maildomain

Ordinarily usernames will follow the [FirstName].[LastName] pattern, but there might be exceptions to this such as office, webmaster or president. Many organizations might want to have their own users with usernames of office or president, or perhaps there might be two different John Smiths, both of whom want a username of John.Smith. To solve this UserNames are only meaningful within the context of a site; that is to say they are not stored in the Shared Schema, rather they are stored in the site specific schema.

Users can also have multiple usernames. This is helpful for those whose names have abbreviations; Phil/Philip, Mike/Michael, Jenny/Jennifer. Or perhaps when someone gets married and changes their name. By permitting a user to have multiple usernames they can simultaneously hold several different mail aliases at the same time, thus helping meet Planning Suite's goal of easing communication between the members of your organization.

Login

User login is an extremely important process, with lots of possible points of failure which can easily become a significant support burden. For this reason, Planning Suite accepts an extremely wide variety of login details to authenticate the user. You can login using any of the following:

  • User Name: (Preferred) ie John.Smith
  • Email address: ie John.Smith@example.com
  • Email Alias: ie John.Smith@example.planningsuite.com
  • Email Alias from a different site: John.T.Smith@otherexample.planningsuite.com
  • Unrecognized unqiue User Name: Paul.Smith, not currently an example.planningsuite.com user so there isn't currently a Paul.Smith user, but the only Paul Smith in the Shared Schema.

The login procedure is shown in the diagram on the right. Firstly we examine the user token to decide whether or not it represents an email address, or just a username.

If it is an email address, then we will look to see if the domain is one of the domains that Planning Suite is managing. If it is, then the local part of the email address is likely to be a username in the context of that organization, so we connect to the schema for the relevant organization, and test the username from there. If it isn't then we can use the email address to look for a matching shared user.

When testing the username, we look to see if the username is currently registered as a valid username for the site. If so the user has been located, and the password can be tested. If not then we split the username at the "." and consider the first part to be the First Name and the second part to be the Last Name and go looking for a matching shared user.

When looking for a shared user we will either have an Email Address, or a First/Last Name. Where there are several users that share an Email Address, or a First/Last Name, we use the supplied password to disambiguate between any potential duplicates. If we can't find a matching shared user, then the user is sent to the registration form to register and create a new account.

If we do manage to find a shared user, then we will allocate a username for the shared user. First off we will try FirstName.LastName, and if that is already taken we will add numbers to the username until we have a unique username in the context of the site they have logged into. This means a user logging in as John.Smith@site1.planningsuite.com might end up with a username of John4.Smith within the context of site2.planningsuite.com.

Note if a shared user is allocated a username as part of the login process, they will not be automatically added to the Users.Group. They will have to specifically ask to do this after logging in, at which point they will understand that by doing so, they will grant the organization access to their email address.

Registration

The registration process will firstly make sure that the combination of First Name, Last Name and Email address is unique, then create a user in the Shared Schema. A username will then be allocated to the user and they will be added to Users.Groups granting the organization's administrators access to their email address.

If a matching shared user already exists, then either we will try to provide an appropriate error message to the user. We might point them to the password reminder form, direct them to the fact that the user aleady exists and need not be created, or inform the active administrator that the shared.user exists but they can't be added to Users.Groups without their explicit permission. This final restriction might seem peculiar, but it prevents someone who knows the FirstName/LastName/Email for someone important at an organization from adding the user to their organization for which they are an administrator, and then changing their password.

A new shared user will also not be created if the First Name/Last Name are already taken by an existing planning suite user, or if the Email address is already taken. Administrators can get round this restriction, but mostly these actions are done by users who have forgotten their login details, and think registering for a new account would be easier than re-locating their login details. Registering duplicate accounts is undesirable, as the new account won't be connected to their information and groups.

Deletion

Once a Planning Suite user has been created, it can only be deleted completely by the Planning Suite staff. The user can be removed from all the groups of a specific site, and address book information can be deleted, but given the user might also be affiliated with another Planning Suite site their account can't be categorically deleted. Once the user has been removed from Users.Groups for your site, you won't be able to add them back without logging in as that user, so be careful to do this action only after you are sure you have no further need for the user. You may find users will remove themselves from the Users.Group to indicate that they have no further need for your organization's services.

Freqeunt Problems

Forgotten user names

If you have forgotten your username, it is usually of the form FirstName.LastName. If that still doesn't work you can try entering your email address.

Forgotten passwords

If you have forgotten your password, enter your username, and click the "Remind Me" button beside the Password box. Your password should then be emailed to you.

Web Services

The Auth Gui inherits from CPage, and provides the following actions:

If you you may gain access to additional actions.

Action ContentType Description
PasswordReminderAjaxJsonRequest an email reminder of a user's password
LogoutAjaxJsonKill the user's session
LoginAjaxJsonValidate the supplied password and create an authenticated user session
RegistrationHtmlShow the registration form
HelpHtmlShow the normal login page but immediately request help
Registration CompleteHtmlShow static registration complete message
RegisterAjaxJsonRegister the new user