Use the user registration requirement pattern to specify how new users are registered (set up in the system), with emphasis on capturing those details by which a user can later be authenticated (log in).

Users are special. They are people, and they drive the bulk of what happens in a typical commercial system, so it's critical to know who each user is—to a greater or lesser degree of confidence depending on what we let them do. User registration, then, is more important than just another data maintenance activity. The primary aim of user registration is to record enough information to facilitate user authentication (login); everything else is secondary, though there could be quite a lot else to record.

Letting a user perform their own registration is the most convenient way, but anything they enter must be regarded as suspect (untrusted). They could supply false details (such as lying about their age), or they could enter details about someone else (which is, in some circumstances, a form of identify fraud). Alternatively, a user could be registered by a person who's already trusted, which is usually done when that person is in a position to attest to the prospective user's identity (such as if they're physically present). This is inherently much more dependable, so use it whenever it's practical (for example, for registering new employees). There is scope for more complex registration processes: to have some details entered by the user and some by someone else, or to check the veracity of certain information supplied by the user (against electoral rolls, credit reference agencies, the telephone directory, and such). This might sound invasive, but it depends on the nature of your system, the type of user, and how much faith you need in the accuracy of what the user tells you about their identity. These steps can raise the trustworthiness of the information in question, but they involve extra effort—both in operation and in development.

A user registration requirement should contain:

Extra registration steps usually involve interacting with external systems (such as a credit reference agency) or manual activities (such as examining a faxed copy of an identity document). A commonly-used step is to send an email to the user's email address and ask for a response; this merely proves that this person receives the mail sent to that address. Describe whatever you need in your case.

Even one class of users could have more than one level of registration. You might have rudimentary registration for basic access, but ask for more (and check more thoroughly) if a user wants to do more (that is, to be trusted more). A user's access privileges can thus be affected by which stage a non-trivial registration process has reached.

A user registration requirement can be accompanied by various kinds of extra requirements, most of which relate to the ongoing protection and maintenance of information initially provided at user registration. Consider which of the following areas you feel warrant requirements. Each area is discussed further in its own subsection that follows:

Any of these things that affect users should be documented, so they can read what they're supposed to do. The documentation requirement pattern has an example requirement for a security procedures manual.

Password Format Settling on criteria for an acceptable password involves making compromises. The best balance depends on the nature of your environment: how frequently users log in (and thus how likely they are to forget their password and need to write it down), the potential damage if a password is discovered, how likely an interested party is to discover a password that's written down, and so on. It can make sense to have separate rules for different classes of users: one for employees who use a system all day, every day, and another for visitors to a Web site. Making passwords convoluted makes them harder to guess, but also much harder to remember—and thus makes it much more likely that users will write them down. (Long passwords aren't necessarily unmemorable, though: a password made up of several words can be hard to crack, especially when accompanied by deviant spelling and with an unusual symbol or two thrown in.) Many apparently sensible steps that look like they improve security can actually have the opposite effect, especially when taken to extremes. Specify whatever password criteria you wish, but don't go overboard.

For good measure, you could ask for a utility to hunt for poorly-chosen passwords:

Changing Password Users should be able to change their password whenever they want—for example, if they suspect that it's been compromised (because someone else might have discovered it). But unless you specify a requirement to this effect, the system is acceptable if delivered without a change password function. You might also want to force users to change their password from time to time or to restrict what they can change it to (such as not allowing the same value every time). The situation by which a user forgetting their password eventually leads to the password being changed is discussed in the user authentication requirement pattern's Extra Requirements section.

User De-Registration For each function that creates users, there needs to be at least one function that removes them. Normally it should be possible to de-register them in the same manner as they were registered—which means that if a user can self-register, they can de-register on their own initiative; and if a user is added by someone else, then someone else must be able to de-register them. It might be worth writing a separate de-registration requirement for each relevant class of user, as in the following two examples:

User Data Protection We return to the theme of users being special, this time not because they drive the system, but because they are people who are sensitive about what is known about them and about how information about them is used (and not abused). A well-specified system (and a responsibly-run business) will provide reasonable protection for user information, but that might not be enough. You need to worry about data protection and privacy laws that make further demands. These vary considerably around the world, so don't assume that what's acceptable where you live is good enough everywhere. Europe is generally stricter than the rest of the world, for instance.

Data protection is a large topic in its own right, deserving of more than this backwater subsection. But there isn't space in this book to do it justice, so we'll confine ourselves to suggestions on how to tackle this subject, list a few general guidelines, and give a few example requirements.

Here's a basic high-level process for specifying data protection requirements:

Some of the key data protection provisions are:

A system that's built sensibly shouldn't have difficulty complying with these provisions. Don't regard this list as complete, though. Here are example requirements covering a few of these steps:

Good Security Practices First of all, we want passwords to be handled securely. Requirements can't guarantee this, but you might want to force developers to make some basic precautions, as these two examples do:

Then you might want to outlaw a few bad practices such as loopholes, ways to bypass security precautions, and proliferation of software that asks users to enter secret information (such as their password). There are situations in which developers might be tempted—for honest reasons—to do something that weakens security. A few examples are:

Special Processes for New Users Whenever a user is set up by someone else, we have the pesky problem of how to assign a password that only the new user knows, without the risk of someone else logging in as that new user first. Options include:

The second option doesn't need extra requirements. Here are a couple for the first option:

Day One Considerations More than a few systems have been installed and started up on their first day—only for the project team's pride to be replaced by red faces when it's realized that no one can log in and no one can register a new user. Since it's a one-off occurrence, this might sound like it doesn't deserve a place in the requirements. But solving it might leave an ongoing security flaw, so it's best that everyone be made aware of the potential risk. We don't want a surreptitious utility to be built that can set up new users and then hangs around in the hands of one or two developers or systems administrators. If such a utility is needed, make sure it's known about and kept under strict control. Here's an example requirement to prevent one cause of a bad first day:

The range of topics raised in this requirement pattern makes it clear that there is much to think about. The best advice is simply to take user registration seriously and not to cut corners. Always handle secret values (such as passwords) securely: at the first opportunity, render them indecipherable, and destroy the clear form.

A user registration function is basically a data entry function and should be tested as such. Test the entry and validation of all values. Test that validation is not performed only on an untrusted client device (a remote user's PC). Test that any values that are intended to be secret (such as passwords) are treated as such, and cannot be viewed using the system (such as via inquiries or reports or obtained from logs or from querying the database).

Testing that a user registration process is secure cannot be done solely by using the system. It's a specialized activity (as discussed in the user authentication requirement pattern).

Use the user authentication requirement pattern to specify that a person must make their identity known to the system before they can access anything non-public or anything for which they cannot remain anonymous (in short, anything for which they must log in).

Authentication is the process by which a registered user declares who they are and proves this assertion to the system's satisfaction. This requirement pattern says little on the subject beyond what is of interest to requirements; it doesn't worry about the considerable challenges of implementing a secure system. The most widespread form of authentication in commercial systems is just asking the user to enter their user ID and password, and that's what this requirement pattern concentrates on. The common name for user authentication is "logging in." (This book prefers logging in to logging on—on the basis that entering a system is a better metaphor than climbing atop it. Let's also point out that, as a verb, to "log in" is two words: "to log someone in" sounds fine, and is only possible if there is a gap in which to squeeze "someone.")

There are three accepted ways to check that a person is who they claim to be: something they know (such as a password), something they have (such as an ID card), and something they are (using a part of their body that can be distinguished from that of everyone else—such as a finger or an eye). Depending on how secure you want your authentication process to be, you can ask for more than one (a password and an ID card and a fingerprint, if you insist). There are various factors that affect what's best in a particular situation, including:

Authentication can be regarded as creating a user session, which grants the user access until the session ends. This might sound like an implementation contrivance, but it's not—and it makes some aspects easier to discuss (especially a few of the extra requirements that follow). It appears a good idea to prevent a user from having more than one session at the same time, but it can be problematic, due to technical unreliability (especially with communications). A user is liable to get frustrated if they "return" after a failure, attempt to log in, and are refused because they already have a session (which they cannot use). On the other hand, letting a user have many active sessions can cause problems, too. If you allow a user to have more than one session simultaneously, a history of their actions only makes sense if you show each session separately. One option is for logging in to terminate all previous sessions—but there are circumstances where that's awkward, too (for example, if a user is active and someone who has purloined their password then logs in).

A user authentication requirement should contain:

Don't simply copy any of the requirements given here or in the Extra Requirements section. None of them suits all situations.

Observe that the first example doesn't mention any particular authentication mechanism.

A user authentication requirement looks straightforward and self-contained, but there are various related matters you can specify in extra requirements, mostly to limit the misuse of user accounts. These include the following (each of which is covered in its own subsection that follows—except accessibility, which is covered in the accessibility requirement pattern in Chapter 8).

Forgotten Password Handling We must be able to get a user back on track when they forget their password, for which occasion, we need another way for them to prove their identity. This is straightforward enough in an environment where the user is known personally to someone who can vouch for their identity (such as colleagues in an office): a trusted user can run a function into which the hapless user can enter a new password.

In the absence of a trusted second person who can verify a user's identity (for instance, when a customer wishes to use our Web site), we're likely to be forced to resort to more dubious means. A common stratagem is to ask the user for additional "secret" information when they register—either a "secret phrase" or one or more questions along with their answers. (Registration can suggest questions: what was the name of you first pet? The make of your first car?) This typically results in values that are easier to guess than a password, and often not secret at all. In recognition of this, it's best not to depend solely on this "secret" information to identify the user. Two extra steps are as follows. First, to ask the user to speak on the telephone to an operator, who can bring to bear their personal judgment about whether the user is genuine (and ask extra questions). Second, test whether this person is able to receive communications sent to the user (which can use any of the user's contact details—such as their home address or telephone number, but most often their email address, because it's quick and the sending of an email can be automated). Both these steps are weak from a security standpoint.

Whenever you're thinking about involving an operator in the forgotten password process, consider the potential operational cost, especially if the number of users is large. For systems that don't handle forgotten passwords automatically, this is one of the most numerous types of calls to help desks.

User De-Authentication (Logging Out) Give users the opportunity to log out explicitly, so they can prevent someone else from slipping into their seat after they've gone and performing actions in their guise. Do this even in environments where users rarely log out. For example, visitors usually leave a Web site simply by moving on to another one, or by exiting their browser—but someone in an Internet café won't want a complete stranger to be able to carry on where they left off. Logging out has the effect of ending the user's session. If you allow a user to have multiple sessions simultaneously, you must decide whether logging out applies to all of them or just to the one in which the logout was performed (both of which have their down sides)—or you could let the user choose.

Ending User Sessions It's good practice to limit the duration of a user session, to force a user to prove it's really them from time to time. Without such a limit, a user could log in once and continue to use the system indefinitely. When a session is about to end, ask the user to establish their identity again, and don't permit them to continue to use the system until they do so. If possible, do this in a natural break in what the user is doing (at the end of a transaction, say): be polite. It also helps to let the user know that we're doing this for their own security. The duration of a session should be somewhat longer than users are typically continuously active, so we might set it at twelve hours for an employee, or three hours for a Web site customer. Logging out also ends a user session (as described in the previous subsection). If you can reliably discern that a user is leaving, you can end their session; this depends on the technology being used.

Notice that the first preceding example carefully sidesteps the question of whether it extends the existing user session or creates a new one. Developers might have strong views on the subject, but it's solely a matter for them: it doesn't concern the requirements, so steer clear of it here.

Next, it's useful for an operator to be able to peremptorily terminate a selected user session: without it, you'd be hamstrung in halting a user who's discovered performing nefarious activities. Taking this one small step further gives us the ability to terminate all active user sessions (or all sessions for a particular class of users—such as all customers), which can be useful if we want to shut the system down. Oh, and remember not to terminate the killer operator's own session!

If we can give a user advance notice that their session will end shortly, it's polite to do so. For example, if their session is nearing its time-out time, we could notify them, so they can log out and log in again with minimal inconvenience.

Absent User Protection If an active user suddenly stops doing anything, it could be because they've walked off and left their machine all alone. A Web site customer who simply goes to another site (or shuts down their browser) without logging out can leave an open session. In these situations, we don't want someone else to be able to wander up (metaphorically in the case of an Internet attacker) and, as far as the system's concerned, impersonate the original user. If you want to prevent this, you can either write a requirement that expresses this intent, or write one for a specific way to prevent it—the commonest being an inactivity time-out, after which we ask the user to type in their password upon their return before they are allowed to proceed. We can then take this one stage further and let the user tell the system they're leaving their machine temporarily: that is, effectively to trigger the inactivity time-out immediately.

One awkward feature of locking a session can be (depending on the technology used) that it prevents anyone else from using the machine—which can be irritating. One way around this is to allow someone else to break the lock (though not to take over the original user's session, nor to see what they were doing). A further refinement is to let a user locking their session to say whether they're prepared to let it be broken.

Helping Users Spot Breaches A system cannot tell the difference between a legitimate user and someone else who's discovered their user ID and password, so a system can never detect a security breach of this kind. But if we tell the user a little about their last session (typically, the time they last logged in), they're in a position to judge whether someone else has been impersonating them in the meantime. Here's a requirement for the commonest way:

If we help users detect misuse of their account, we should provide them with a way to tell us about it. You might think existing means of communication suffice, but it can be worth doing a little more. Here's one suggestion:

Think about what an operator should do when notified of a suspected breach of this kind. Have you specified requirements for tools that enable them to investigate (such as to view user sessions—discussed shortly)? Bear in mind that false alarms will probably greatly outnumber genuine misuses.

Blocking Users By "blocking" a user, we mean preventing them from logging in to the system. There several situations in which we might want to block a user, including:

If user accounts can become blocked, we need a way to unblock them. A useful related function is the ability to prevent all users (or a whole class of users—such as all customers) from logging in. This can be invoked prior to shutting down the system, to avoid frustrating users by kicking them out soon after they log in.

Viewing User Sessions User sessions contain valuable information—both about what's currently happening in the system and about which users accessed the system when. It's wasteful to simply discard or ignore this potential treasure. So store it, and let it be exploited. It might help identify a breach of security (after the fact), if nothing else.

Requirements related to user authentication merely specify necessary features; they don't worry about the complexities, of which there are many—too many to relate here.

Coding a login function is almost as easy as a "Hello World" program. But doing it securely is considerably more difficult. Take into account all the good practices described in this requirement pattern, even if they're not formally required. Turn the password entered by the user into an undecipherable form as soon as possible, and overwrite the clear form in memory.

The testing of user authentication needs to be performed at two very different levels:

Ask for features that will assist testing. These include a way to view details about user sessions (especially when they end, so you can test that they time-out properly). To achieve this, we need the beginning and end of every user session to be recorded.

Regardless of how you choose to specify user authorization, there are a few extra topics worth considering:

Presentation and Usability Systems have a natural inclination to appear stupid unless special steps are taken to prevent it. Denying access is one thing; not looking stupid in the process is something else—and one worth treating carefully, because it can save much time, effort, and frustration during the life a system. Don't clog menus with functions that the user isn't authorized to use; don't let them choose values that they're not allowed to, only to slap them in the face if they try.

How much should we tell users about the existence of things to which they're not allowed access? It's naïve to assume they'll not be aware of most of them in one way or another. (It's impractical to produce lots of different sets of user documentation, for instance—though online documentation attached to each function suffers less from this difficulty.) It's counterproductive to hide the existence of some functions, because a user might need to ask someone with extra privileges to do something for them—so they must be aware that other person can do more than they can. Awareness of inaccessible data is a different matter; in a multi-company system, for example, it might be essential to hide other companies completely.

Here are a few example requirements that aim to make access control more friendly in various ways:

Delegating Authority Real businesses are intricate beasts whose managers quite reasonably want to decide who performs what tasks. If managers need a system to offer a particular kind of operational flexibility, it must be expressly built into the system. One kind of operational flexibility involving access control is the ability to delegate authority to someone else, as in this example:

Preventing Loopholes It's possible to implement access control as a thin veneer around a system that, once punctured, leaves the system completely unprotected. It's not the responsibility of requirements to figure out every kind of attack and the provisions needed to guard against it, but we can write requirements that point out potential loopholes we want to guard against, like this one:

Use the specific authorization requirement pattern to specify that a set of users is authorized (or is not authorized) to do or see certain things.

Do not use the specific authorization requirement pattern to specify that user authorization is to be configurable; use the configurable authorization requirement pattern for that.

A specific authorization requirement makes a statement—of any kind—that affects what a certain set of users can see and do. These requirements can vary considerably, but they generally fall into one of the following categories (or possibly more than one—which is most frequently seen in combinations of Categories 2 and 4):

Use this list to help identify what you need: go through each point in turn. Each one can be regarded as an access rule that the organization wishes to apply to the operation of its system. (If you'd like to apply certain rules more widely than just within one system, pull them out into a separate requirements specification—"common requirements"—and then refer to them in the requirements for each system to which they apply, as per the refer-to-requirements requirement pattern.) Recognize the bounds of what the system can realistically restrict access to—and don't waste your time trying to control anything beyond those bounds. That might include hardware, other systems, and third-party software used to implement part of the system. You might be forced to make unpleasant compromises.

A specific authorization requirement needs to convey two things: who and what. The preceding list is of various kinds of what. As for who, express it in whatever terms are appropriate—but be clear. Don't name particular users (people). Mention roles or job titles, if you like, but if you do, define them either within the requirement or elsewhere (as informal material). This is important, because if you don't, readers are apt to interpret them differently. (Someone else's picture of a "systems administrator" might not accord with yours, for example, aside from theirs having green hair and yours purple.) If you're building a system to be used in multiple places, they might be organized very differently; make it as easy as possible for everyone to see how your system would fit their environment.

A specific authorization requirement should contain:

The examples here are presented according to the categories listed in this pattern's Discussion section (along with a few that are combinations of Categories 2 and 4).

Category 1, a universal denial-by-default rule:

Category 2, functions (starting with one you might regard as so obvious that it goes without saying, although a stickler could argue that without it, unrestricted access is acceptable):

Category 3, actions within functions:

Category 4, data:

Categories 2 and 4 combined, both functions and data:

Category 5, limits:

Category 6, time:

Category 7, environment:

Category 8, strength of authentication:

Category 9, transference:

Category 10, operational rules (of which there is a further example in the "Cannot Approve Own Action" section in the approval requirement pattern):

Category 11, blanket bans:

None, beyond those common to both types of user authorization requirement.

Specific authorization requirements can be varied, and the ways to implement them can be equally varied. Deal with each one on its merits. Don't seek a grand mechanism that can solve them all: they might be too diverse.

The biggest decision is whether configurable access control is worth implementing, even if there's no explicit requirement for it. You can't expect a requirements specification to specify every little detail of who's allowed to access what. Judge for yourself how big the gaps are. Maybe there's an unspoken expectation of configurable access control; if so, bring it out into the open and resolve it quickly.

Testing a specific authorization requirement is reasonably straightforward: can that kind of user access whatever it refers to? Are all other kinds of users prevented from accessing it? If a user is able to delegate their authority to another user, test that a delegatee is authorized whenever the delegator is. Change the kind of a user (if that's possible, for example by assigning them a different role), and test that their authorizations change accordingly.

An invaluable tool when testing authorizations is for all rejected authorization requests to be chronicled (logged). When reviewing requirements, check that this feature is included. If not, insist on it.

Use the configurable authorization requirement pattern to specify that the definition of which users can do what is to be configurable (that is, can be changed dynamically).

Do not use the configurable authorization requirement pattern to specify what a set of users is authorized to do or see; use the specific authorization requirement pattern for that.

Configurable authorization control is wonderful: it lets you change who can do what, whenever you like. An employee needs more authority to do their job properly? No problem! A company restructure? Bring it on! At the same time, it's a millstone, with major drawbacks: it's difficult and expensive to implement; it can incur performance penalties; it's time-consuming to set up and subsequently to maintain; ill-considered (or malicious) changes can have major consequences; and it introduces security risks of its own. So ask for access control to be configurable only if it's worth it; even then, keep it as simple as possible and use it only in those areas that justify it. (That is, don't use it everywhere just because it's there.) Also, take care to make clear what's needed and what isn't, so you don't inadvertently end up with an over-fancy solution.

Configurable authorization is most fruitful when used to control access to functions, because in any serious system, the functions are too numerous to fix their access correctly up front, for all time. Configurable authorization to data is rarely called for, because a normal system simply doesn't need the ability to partition data in arbitrary ways; the cases that do occur are usually isolated and best dealt with using specific authorization requirements. (Note that even without requirements for configurable authorization to data, the system might still be implemented with access control at the database level, on tables and SQL procedures and so on. That doesn't concern us here.) Sometimes, though, several sets of access configuration to functions are needed—one for each of a set of data values. For example, a multi-company system might allow permissions to be defined differently for each company within it—such that one user can access one collection of functions for one company and other functions for a different company. This renders configurable authorization more complex to implement and to manage, so avoid it if you can.

Give configurable authorization requirements a high priority, because if you need access control, you can't very well live without it for an extended period until it's delivered in a later phase—and any attempt at an interim solution could be a mess. In any case, its priority must be at least as high as any specific authorization requirements that depend on configurability.

A configurable authorization requirement should contain:

The first two examples spell out the two main "natures" of access control (functions and data). A more common way to express these sentiments might be, "A user shall be able to access only those functions and that information to which they have been granted permission," but that fails to address what information it might apply to, and it hides the enormity of what it's asking for to such an extent that only an eagle-eyed reader would spot it.

A configurable authorization requirement can have the following kinds of extra requirements, in addition to those common to both types of user authorization requirement (each of which is discussed in its own subsection that follows):

Defining User Roles It's most convenient to discuss roles in a reasonably abstract way (because it avoids repetition), which makes sense only if we assume that a user can assume several such roles. A role, then, doesn't necessarily equate to a job description—nor to an "actor" or "class of user." (Roles are likely to be more numerous than any of these other things.) Even if roles are to be configurable, it's useful for the requirements specification to list candidate roles informally; it gives readers a better idea of what we're talking about and can give the configuration a head start.

We need to specify a tool for defining user roles:

If we're defining roles, we could be picky and make sure the software actually uses the roles when deciding what a user is allowed to do:

Authorization Inquiries Why systems act as they do is always shrouded in mystery—invariably far more than necessary. The workings of serious access control can be equally mysterious if it doesn't let you see what's going on. A set of inquiries for this purpose is invaluable. The two most important ways in which authorizations should be viewable are by user (to see what each user can do) and by privilege (to see everyone who can access each thing). The latter can also point out anything to which no one has access, which means parts of the system are lying idle. Here are a couple of basic examples:

The second example leaves open the question of where the information about privileges "known to the system" comes from and how it gets there. The most obvious answer is that it's stored somewhere and there's a way to edit it. If you want to make that explicit, write a requirement to that effect; something like this:

Chronicling Authorization Changes Changes to the configuration of access control can have major consequences, so insist that all changes to access control are chronicled (as per the chronicle requirement pattern in Chapter 7). If a malicious user granted their own access to an extra function, used it, and then revoked access, chronicle entries could be essential in piecing together what happened. Refer to the chronicle requirement pattern for more.

If access control logic is simple and fixed, you can hard-code it. If it's not simple, or if it's liable to change, it's better to build a general, configurable mechanism—regardless of whether the requirements say you should. However, developing an underlying mechanism for access control is difficult and not for the faint-hearted. Apparently sensible and logical approaches can turn out to be a nightmare to manage in practice, because of the sheer quantity of configuration data. If you think a general access control mechanism will be worthwhile, bite the bullet early. Trying to retrofit it later is likely to be unpleasant.

First of all, recognize that you're testing the requirements, not the privileges of whatever roles might have been set up: testing isn't responsible for checking that every user can do what they need to do their job. Having said that, it's always sensible to configure a test system as closely as possible to the live environment—which means defining roles and their privileges as realistically as possible.

When testing access to functions, for each function, test two things: first, that access to the function is controlled; and second, that the correct privilege is checked. This is exceedingly tedious to do manually. It helps if the system lets you observe each authorization check (down to the name of the privilege being checked); then you can see directly whether the correct privilege is used for each function. One way to observe authorization checks is to record them in a chronicle, and there is an example requirement for doing this in the "Chronicling Authorization Changes" subsection of the Extra Requirements section in this pattern.

A simpler test is to create a user role that can do everything, and verify that a user with that role can indeed do everything. Also create a user role that can do nothing, and verify that a user with that role can do nothing but publicly-accessible things.

One difficulty is that the number of privileges could keep growing. You'd have to be inhumanly diligent to insist on trying to test every new one that comes along.

Use the approval requirement pattern to specify that a particular action (or set of actions) must be approved (or, in some circumstances approved) by a second person before it takes place.

Any function in a system can be constructed so as to require approval before it takes effect. We usually think of one person approving an action requested by another, but it is also possible to allow a person to approve actions suggested by the system itself. ("An upgrade is available for the Whizzo Happiness Calculator. Would you like to download it now?" is an example.)

Imagine a bank in which a teller must have any large cash withdrawal approved by a supervisor. This sounds straightforward enough. But what constitutes large? Does it vary from teller to teller: are some more trusted than others? What is meant by supervisor? Can any supervisor approve it, or just the teller's direct superior? If a supervisor performs a withdrawal, must it be approved by another supervisor—and does that mean someone more senior still? Approving an action is invariably significantly trickier than it at first appears (or if you imagine that it will be tricky, you'll be proven right). It's also commonly neglected in both requirements specifications and software.

And when a system has to handle approval of actions, there are further complexities, because every system lacks the common sense possessed by every human being. How do we bring something needing approval to the attention of someone who can approve it? What if more than one person is able to approve it: do we bring it to the attention of all of them? If not, how do we decide which? What if a usual approver is absent? What if someone else wants to perform an action that affects the pending action (for example, if we're waiting for approval to debit a bank account, and another debit to the same account comes along); there are no easy answers to this one. Every little detail must be figured out and specified—and commonly they aren't, resulting in systems that don't behave sensibly and are awkward to use.

The approval of an action is best specified as an extra requirement following that for the function that carries out the action. Approval requirements should answer some or all of the following questions, as appropriate:

This assumes that just a single extra person needs to give their approval. It can be extended to cover two (or even more) people needing to approve. Sometimes this is best done as a "chain" of approvals (one person after another); sometimes they can each approve independently in any order. An example of the latter might be a system that allows the members of a committee to sign off on documents.

These examples demonstrate that while there's a large number of aspects to consider when specifying approval, the end result can be straightforward.

By now it should be clear that the business of approval is tricky and complicated. (That's why you still see bank tellers running around looking for supervisors to approve things, despite banks automating almost everything else in sight. Go and watch them before they end up in a museum.) Properly defining your approval workflow could take a variety of extra requirements, a couple of topics for which are:

Each of these is discussed in its own section that follows.

Cannot Approve Own Action It is unacceptable to allow a user to approve an action that they have performed. Apply this rule to every kind of approval. There is nothing to be gained by not having it: simply let users perform the action without approval being necessary if that's what you want. But it's important to state this restriction explicitly in a requirement—or be prepared for it to be forgotten. Note that an approval step is sometimes used simply to involve a second person, who could be at the same level as the first user (not a supervisor)—hence the elegantly descriptive German term Vieraugen, four eyes. In such a case, both users might have the same permissions, and an explicit restriction of this sort is the only way to prevent one person from both entering and approving. Insisting that a user be unable to approve their own action is an example of an operational rule as per the specific authorization requirement pattern.

Approval Mechanism An approval mechanism lets you see and pick items awaiting approval and go ahead and act on them. The simplest case looks after just a single kind of item (or a small number of fixed kinds).

If your system has more than one or two functions for which approval is needed, it could be worthwhile building or buying (and hence specifying) a general approval mechanism that can manage everything that's awaiting approval, to save duplicating the messy parts. This might include, for example, a function to display all items pending approval by the current user, regardless of what sorts they are. It could incorporate some kind of workflow support, and it could involve an infrastructure deserving of its own requirements specification. You would need to specify requirements for the pieces that make up a general mechanism of this sort. Such requirements could be wide-ranging and complex.

If prompt approval is needed, approvers must have an approval mechanism running all the time (or utilize some kind of notification mechanism). But what if they don't have it running? To work well for prompt response, this function must refresh itself (which is harder with some technologies than others).

Here's an example of a specific approval function:

If more than a couple of types of action need approval (or might in the future), consider building a generalized mechanism for storing any kind of unapproved action. This must be able to store anything that's yet to be approved, for which it needs to be flexible. Depending how sophisticated you want this mechanism to be, it could also provide a means for other functions to find out whether anything of interest to them is awaiting approval. For example, if a large bank account debit is awaiting approval, another function that wishes to know the balance of that account probably needs to take the pending debit into account. Also take care to protect this pending-action store against tampering.

Note that if we build a place to store pending (yet-to-be-approved) actions, this can also be used as the basis for handling timed and co-ordinated changes, as described in the introduction to the Chapter 7 chapter. So if you build a mechanism for one, you have a head start towards the other.

Concentrate on what sorts of things could happen between the action being initiated and its being approved. Has someone already figured out all the extra actions that users could take that could interfere with the action awaiting approval? A workflow (or equivalent) diagram is a particularly helpful form. If not, produce one—and be suspicious that the system might be incomplete. Identify all the possible states an approval request can be in, and the ways it can change state. Figure out all the actions that any of the people involved could take at any stage. Then test these possibilities and verify that the system handles them satisfactorily.