Bric::Security - Bricolage Security Guide $LastChangedRevision$ $LastChangedDate: 2006-03-18 01:26:34 +0100 (Sat, 18 Mar 2006) $ This guide describes the security features of Bricolage. These features comprise three parts: authentication, encryption, and authorization. Authentication is the process that allows users to login to Bricolage. Authorization is the process that checks permissions on individual objects before allowing users to access them. And encryption allows users to securely connect to Bricolage. Bricolage's authentication procedure is designed to be simple yet flexible. To login to Bricolage, simply hit any URL on the server. If you have not already logged in, you will be prompted to login. To login, simply enter your username and password, and then click "Login". Note that the username is case-insensitive, while the password is case-sensitive. If you enter the wrong username and/or password, you'll be prompted to login again. Once you have successfully logged in, you may begin using Bricolage. When you are done using Bricolage, you should always log out. While your session will eventually expire, it's always best to logout and quit your browser to prevent others from accessing Bricolage in your name. To logout, simply click the "Logout" button that's available at the top of every Bricolage screen. Once you've logged out, you'll be presented with the login screen again so that you can relogin if you need to. But do be sure to logout to prevent others from using the back button and other clever (and not-so-clever) tricks to view your data.

Authentication Settings
There are a number of system configuration directives that affect user authentication. All System directives are documented in Bric::Admin; however, we'll discuss a few that are relevant to authentication here. First, the "AUTH_ENGINES" directive allows you to select which authentication engines Bricolage should use to authenticate a user attempting to log in. The engines may be specified as a space-delimited list. See Bric::Admin/"Authentication Configuration" in Bric::Admin for complete details. Note that if you include "LDAP" in the list of authentication engines, you must also configure the Bric::Admin/"LDAP Configuration" for your LDAP server. Next, the directives "LOGIN_LENGTH" and "PASSWD_LENGTH" affect the minimum lengths of usernames and passwords, respectively. These lengths are then enforced in the application UI. The more important of these is "PASSWD_LENGTH", since the longer the password, the more difficult it is to crack. Be sure to set this directive to as high as users will bear -- preferably 8 or higher (the default for both "LOGIN_LENGTH" and "PASSWD_LENGTH" is 5). Note that there is no maximum password length. Passwords can be any length and contain any characters. This is because Bricolage passwords are stored in MD5 hashes, rather than the simple "crypt" format used by other applications. Users are thus encouraged to use passphrases rather than simple passwords. Again, you can enforce this to some degree using the "PASSWD_LENGTH" configuration directive. We have set an arbitrary limit of 1024 characters on the password length in the UI, on the simple assumption that no one is going to use an essay for a password. There is no such actual limitation in the API. The maximum login length, on the other hand, is 128 characters. We made it this long to accommodate those environments where email addresses (which are potentially quite long) must serve as logins. We expect that most users would never user more than ten characters. The other two authentication directives, "AUTH_TTL" and "AUTH_SECRET", affect how a user's login session is maintained. "AUTH_TTL" is the length of time, expressed in seconds, that an idle user remains logged in to Bricolage. That is, if a user is logged in, but is idle for longer than the time allowed by "AUTH_TTL", when next the user tries to use Bricolage, he/she will be forced to reauthenticate. This feature helps prevent unauthorized access by people using a computer when a user has neglected to logout. We recommend you set it for some reasonably low period of time -- two hours or less. The default is 8 hours. "AUTH_SECRET" is a random string of characters that is used to encrypt a user's login session in a login cookie. The login session is encrypted to prevent malicious people from figuring out from cookie data how to login to a system. If such a person were to discover the the value of the data stored in "AUTH_SECRET", that precaution would be compromised. We therefore recommend that you change this value periodically -- say every couple of days or once a week. Bricolage can use the industry-standard Secure Socket Layer (SSL) for connection encryption. See Bric::Admin for information about enabling SSL in Bricolage. With SSL enabled, Bricolage automatically uses SSL for all logins and for all user profiles. By doing so, Bricolage assures that users' passwords are never sent over the Internet in the clear. When users login to Bricolage, their passwords are encrypted, and when users and administrators edit User profiles within the application itself, the profiles are edited via SSL so as to ensure that any password changes are also sent via encrypted channels. All other parts of Bricolage use simple HTTP rather than SSL (HTTPS) for sending data to and from the browser. SSL is not preferred in the application in general because encryption incurs a significant performance overhead. A lot of processor time has to go into encrypting and decrypting all data sent to and from the browser when using SSL; and in some Bricolage profiles, that can be a lot of data! There may be times, however, when you wish to use SSL everywhere in Bricolage. Perhaps someone is working on a sensitive story via the Internet, rather than on a LAN, and the story data needs to be encrypted. Or perhaps company policy dictates an emphasis on high levels of security (such as may be the case with patient data in health care), and therefore preventing data from ever being sent in the clear over the Internet. Bricolage makes it a simple process to use SSL for connecting to and using Bricolage at all times. The simplest way to enable an encrypted connection is to check the "Use SSL" checkbox on the login screen. Checking this button causes Bricolage to maintain an SSL connection to the browser even after login. But it's not necessary to use this checkbox. If at any given time you wish to establish an encrypted connection to Bricolage, simply change the address in you browser from "http://" to "https://". That's all you need to do to turn on encryption. Note, however, that if you use this approach and then you edit a user profile, once you have saved the changes to the user profile, Bricolage will return you to a normal, unencrypted connection. This is because Bricolage checks the status of the "Use SSL" checkbox to determine whether or not a user has been using SSL before editing the user profile. Thus the preferred way to establish a secure connection is to check the "Use SSL" checkbox. To return to a normal, unencrypted connection, logout, and then log back in with the "User SSL" checkbox unchecked. And finally, if needs dictate that all users must always use SSL, you can enable the "ALWAYS_USE_SSL" bricolage.conf directive and restart Bricolage. This directive forces Bricolage to always use SSL throughout the entire applications, and thus ensures that all communications (including with the distribution and SOAP servers) are always encrypted. The authorization features of Bricolage comprise two parts: authorization itself and permissions management. The Bricolage authorization system is designed to be relatively simple to use and understand, although its emphasis on groups of objects rather than objects themselves can cause a little consternation until the idea clicks. Here we discuss the philosophy and functionality of authorization in detail, so that you can always return to this document if you're having trouble.

How Authorization Works
In order to keep implementation as straight-forward as possible--and therefore to also save processing time during authorization checking--we designed Bricolage to have only one kind of permission. That permission is best expressed by this sentence: "Grant permission to the members of a group of users to access the members of a group of objects." The advantage of this approach is that all permissions are stored in one place, and therefore can be quickly looked up, thus saving processor time when checking for authorizations. The disadvantage is that one cannot simply grant an individual user permission to an individual object or group. One can, however, create a user group with one member, and an object group with one member, and then grant the single user group permission to access the member of the single object group. So the granularity can still be achieved, but without violating the elegance of the model. In addition to the standard object groups, there are a number of special groups that may contain documents and templates. These are categories, workflows, and desks. To a certain extent, these objects may themselves be thought of as groups, in that they contain other objects. For example, a two stories may be associated with a category. That category may then be considered to be a group of two stories. Likewise, a desk with 4 media documents and 2 stories on it may be thought of as a group of 4 media documents and 2 stories. The upshot of all this semantic gerrymandering is that you can grant permissions to user groups to access the documents and templates in categories, workflows, and on desks. This functionality makes possible highly flexible workflow modeling, so that you can ensure that the right users can access the right content at the right time, in the right place.

Permission Levels
Bricolage supports six permission levels: READ permission allows users to view the contents of objects, but not edit them. EDIT permission allows users to both view and edit the contents of objects and to delete objects, but not create them. RECALL permission allows users to recall documents or templates from the Bricolage library, pulling them into workflows and checking them out for editing. Note that the RECALL permission can only be granted to user groups to access groups of stories, media or templates, since those are the only objects that can be recalled into workflow. CREATE permission allows users to view, edit, delete, and create objects. It also allows them to recall documents or templates from the library. Note that the CREATE permission can only be granted for objects in the "All *" series of groups and to start desks, as an object is automatically a member of its respective "All" group or the start desk, but can't be added to any other group until it has already been created. PUBLISH permission allows users to publish documents and deploy templates. It also allows them to recall, view, edit, delete, and create documents and templates. Note that the RECALL permission can only be granted to user groups to access groups of stories, media or templates, since those are the only objects that can be published or deployed from workflow. And finally, DENY permission prevents users from accessing objects at all. As you can see, the permissions cascade: EDIT assumes READ; RECALL assumes EDIT and READ; CREATE assumes RECALL, EDIT and READ; PUBLISH assumes CREATE, RECALL, EDIT and READ; and DENY overrides all the rest. Naturally, users may have more than one permission granted to access an object due to their membership in multiple groups. Likewise, a particular object may be in more than one object group to which a user group has been granted permission, and there may be different permissions assigned to the different groups. This crossing of permissions requires permission reconciliation. The way multiple permissions are reconciled basically follows the cascading nature of the permissions themselves: the most permissive permission wins. Thus if a user has both READ and EDIT permission to an object, the user will have EDIT access to the object. Likewise, if a user is granted CREATE and RECALL permission, she will have CREATE access to the object. And of course, the user with no permissions at all will have no access to the object at all. The one exception to the "most permissive wins" rule is the DENY permission. Bricolage assumes that if the members of a group have been assigned the DENY permission, then they really should have no access at all, regardless of what other permissions they may have by nature of their memberships in other groups with other permissions. So remember, while in general the most permissive permission wins out, the DENY permission trumps all. The lesson is: use this permission with care.

Permissions Example
So let's look at a few examples. Let us assume that we're working with a system with 3 users, 3 user groups, 2 story groups, and 3 stories. Here's how they're organized: Users All Users Story Admins Evildoers ---------------------------------------------------- Theory x x Mcnibblet x DrEvil x x x User Theory is a member of the "All Users" and "Story Admins" user group. User Mcnibblet is a member of the "All Users" user group. And user DrEvil is a member of the "All Users", "Story Admins", and "Evildoers" user groups. Story All Stories Publish Desk ------------------------------------------------------- Dubbya Celebrates Birthday x Second Matrix Movie Debuts x x Black Hole Destroys Earth x x The first story is a member of the "All Stories" group. The other two stories are members of the "All Stories" group and are on the "Publish Desk", and thus members of its group. Now, let us assign permissions: All Stories Publish Desk --------------------------------------------- All Users READ EDIT --------------------------------------------- Story Admins PUBLISH --------------------------------------------- Evildoers DENY --------------------------------------------- The way Bricolage works with these permissions is that, when a user tries to access a particular object (here a story object), Bricolage finds out what groups the object is in, what user groups have been granted permissions on those groups, and which user groups the user in question is a member of. Then, once it has aggregated all of the permissions that trickle down to the user in question, it decides which one wins, following the criteria outlined above. So let's say that user "Theory" wants to create a new story. Bricolage sees that the new story is in the "All Stories" group, and that the user groups "All Users," "Story Admins," and "Evildoers" have been granted permissions to that group. It turns out that Theory is a member of the "All Users" and "Story Admins" user groups. The permissions granted to these groups to access members of the "All Stories" group are "READ" and "PUBLISH," respectively. Bricolage determines that PUBLISH is the highest-value permission, and so user Theory has that permission, and therefore the ability to create a new story. Another example. Let's say that user "Mcnibblet" wishes to edit the "Dubbya Celebrates Birthday" story. Bricolage determines that this story is a member of only one story group, "All Stories," to which the user groups "All Users," "Story Admins," and "Evildoers" have been granted permissions. Mcnibblet, being the member of only one of these groups, "All Users", has just the one permission: READ. Thus, Mcnibblet has READ permission to the "Dubbya Celebrates Birthday" story, and no other permission. Since Mcnibblet wishes to edit the story, and he does not have EDIT, RECALL, CREATE, or PUBLISH permission, he is prevented from editing the story. Should he choose to view it, however, he'd be able to do so. Now let's look at "DrEvil." This fine user wishes to view the story "Black Hole Destroys Earth," it being that it appeals to his aesthetic tastes. Bricolage determines that this story is a member of the "All Stories" and "Publish Desk" story groups, that all three user groups have been granted permissions to "All Stories," and that "All Users" has been granted permission to "Publish Desk". DrEvil, in turn, is a member of all three groups. Thus, the permissions for DrEvil to access the "Black Hole Destroys Earth" story are READ, PUBLISH, EDIT, and DENY. Comparing these permissions, Bricolage would normally award the most permissive permission, PUBLISH (which encompasses READ, EDIT, RECALL, and CREATE permissions, as well). However, the DENY permission trumps all others. Thus, regardless of DrEvil's membership in the "Story Admins" group, with its PUBLISH permission to access the story, his membership in the "Evildoers" group denies him permission to access the story at all! Here's a breakdown of how all the permissions will manifest for each user trying to access each story. Compare this table with the tables above to figure out how the permissions were determined. Story Theory Mcnibblet DrEvil -------------------------------------------------------- Dubbya Celebrates Birthday PUBLISH READ PUBLISH Second Matrix Movie Debuts PUBLISH EDIT DENY Black Hole Destroys Earth PUBLISH EDIT DENY

The Global Admins Group
One Bricolage user group is special, Global Admins. Members of this group automatically have PUBLISH or CREATE rights to every object in Bricolage, regardless of other group memberships and permissions -- including DENY! In fact, permissions aren't even checked for members of this group - PUBLISH permission is simply always assumed and granted. The name and permissions of the Global Admins group cannot be edited, either - only the membership. Thus membership in this group should be limited to just those users who are responsible for administering the whole of the Bricolage application. Use the other Admin groups to parcel out the rights to Administer particular parts of Bricolage.

Permissions Management
Now that we've explained how the permissions system works, let's examine the interface, and how to use it to configure permissions for your users. All permissions management takes place within group profiles. As you can tell from the above discussion, there are two slightly different kinds of groups, at least as far as permissions management is concerned. The two types are User Groups and Object Groups. All groups in the system are object groups. These are the groups to which user groups are granted permissions. Thus even user groups are object groups, since there need to be permissions granted to manage users, too. So let's browse the interface. Make sure that you're a member of the Global Admins group. Then, in the side navigation bar, select ADMIN -> SYSTEM -> Groups. You will be presented with a list of all the groups in the system. Bricolage ships with only User groups and "All *" groups. If you look at the "Or Pick a Type" select list, you can see that it supports all kinds of object groups. Click "Edit" to edit one of the user groups, say "Distribution Admins" (note that you must have permission to edit groups to do this!). The interface provides fields to edit the name and description of the group, plus a double list manager that allows you to move objects (users, in this case) in and out of the group. The double list manager allows you to assign members to the group. (Note that the attributes of the special "All *" groups are not editable, although their permissions are.) Since we're most interested in permissions management, however, click the "Permissions" button. This interface allows you to edit all of the permissions granted to the the members of the group, plus the permissions granted to other groups to access the members of this group. If you're looking at the "Distribution Admins" group, you'll be presented with a section for managing permissions to grant user group members permission to access the objects in the Distribution Admins group. The "Pick a Permissions Type" select list at the top of the page allows you to access three other permissions sections. (Non-user groups only have the one type of permission interface, for granting permission to groups of users to access the members of the group you're editing.) User Group Permissions are the permissions granted to the members of user groups to access the members of the Distribution Admins group. By default, none are granted, but if you were to click the "READ" radio button for the "Media Producers" row and then click "Save," for example, then all users who are members of the "Media Producers" user group will then have READ access to the users who are members of the Alert Type Managers group. (This is probably not something you want to do!) A note on the interface. By default, Bricolage uses radio buttons to display the permissions. Some may not care for this interface, however (some think it too cluttered), so Bricolage offers an alternative. There is a preference, "Permissions Widget," that can be changed from its default value "Radio Buttons" to the alternative, "Select List." This setting will cause Bricolage to offer select lists for each row of the Permissions page, rather than radio buttons. To change the preference, simply edit the "Permissions Widget" profile in the Preferences Manager. Be sure you have permission to edit preferences, and remember that, unless the "Can be Overridden" checkbox is checked, they are global and will affect how all users see the Permissions interface! Now, select "Object Groups" from the select list. This selection allows you to grant permission to the members of the Distribution Admins group to access the members of other groups. Here you'll see all of the "All *" groups listed (the only groups, aside from start desk groups, for which you can grant CREATE access) as well as all the other groups in the system. You can use the radio buttons or the select list interface to grant the permissions. Note that by default, the Distribution Admins have been granted permission only to CREATE All Destinations and to CREATE All Jobs. The "Workflows" select list option allows you to grant permissions to the members of the current group (Distribution Admins) to access the documents within particular workflows. This feature is useful to allow certain groups of users to access documents only in certain workflows. The "Desks" option allows you to grant permission to the members of the current group (Distribution Admins) to access the documents on particular desks. This feature is useful to allow certain groups of users to access documents only on certain desks. It is also the means by which users can be granted permission to CREATE new documents, by granting the CREATE permission to the relevant start desk, or to RECALL existing documents from the library, by granting the RECALL psermission to the relevant start desk. This view also allows you to grant members of the group permission to PUBLISH documents, by granting the PUBLISH permission to the relevant publish desk. And finally, the "Categories" option allows you to grant permission to the members of the current group (Distribution Admins) to access the documents in a particular category. Again, because category permissions are applied only to documents and templates (the members of the group), you can grant RECALL and PUBLISH permissions. These last four selections will likely be your most used, but they appear only when editing the permissions of user groups. The "User Groups" selection is the only option in the permissions management screen for non-user group profiles. We believe that this section will be most useful when creating a new group, when it makes more sense to associate the group with user groups all at once, rather than edit the user group profiles individually to grant permissions on your new group. Once you click "Save," and return to the group profile, the new permissions settings will have been saved. Click "Save" again to keep any changes made to the group profile name, description, or membership. From this point on, the permissions will be set and all users will be updated. They do not have to login again in order to gain new permissions.

Group Permissions
Our tour of the permissions interface in the last section assumes that you were logged in to Bricolage as a member of the Global Admins group. Things are different for members of other groups. For example, the default "System Admins" group grants its members create access to all of the types of objects in the "System" section of the Bricolage Administration menu (Preferences, Users, Groups, Sites, and Alert Types). So you might think that members of that group can create new groups, add or remove members, and set permissions. This is, in fact, the way Bricolage worked prior to version 1.8.0. However, things could not remain so simple, unfortunately. This is because, under the old approach, a member of the System Admins group had full access to the Global Admins group, meaning that a user could add himself to the Global Admins group. But it doesn't seem like a good idea to allow any user to be able to give himself higher permissions; only another user with those higher permissions should be able to grant them to the first user. So a new approach was implemented. Now a user with EDIT permssion to a group cannot give himself more power than he already has. This was accomplished by following four simple rules: A user cannot edit any group unless he has EDIT permission to the group. This is the same as it has always been. If a user has edit permission to a user group, he cannot add or remove members unless he herself is a member. This prevents him from giving himself or anyone else more permissions than he already has. We have to disallow him from giving greater permissions to someone else, because otherwise that someone else might collude with the user to turn around and give him greater permissions. Not a good idea. If a user has permission to edit a non-user group, he cannot change its membership unless he has permission to EDIT the members of the group. What this means is that he must be a member of a user group that has at least EDIT permission to the members of the non-user group. If a user has edit permission to any group, he cannot change its permissions unless he has permission to access the members of the group. That is, he must be a member of a user group that has at least READ permission to the members of the group he's editing. Furthermore, the permissions he can grant to the group are limited to those he himself has to the members of the group. So if he has READ permission, he can grant only READ or DENY permission. If he has EDIT permission, he can grant READ, EDIT, or DENY. If he has RECALL permission to the members, he can grant READ, EDIT, RECALL, or DENY. If he has CREATE permission to the members, he can grant READ, EDIT, RECALL, CREATE, or DENY. If he has PUBLISH permission to the members, he can grant READ, EDIT, RECALL, CREATE, PUBLISH, or DENY. And, of course, if he has no permission or DENY permission, he can grant no permissions at all. The overarching rule of thumb on which these rules were based is that a user can never grant himself or any other user greater permissions than he himself has, either through group membership or through permission changes. The upshot of all this for you is that, while it's easy to manage permissions as a member of the Global Admins group, it's not so easy for members of other groups. If you want to enable another group of users to administer groups, a member of the Global Admins group must grant the following permissions to that other user group: Ability to EDIT the group itself. Ability to READ, EDIT, or CREATE members of the group (depending on how high a permission you want to allow them to grant to other user groups to access the members of the group). If the group to be managed is a user group, each member of the user group doing the managing must also be a member of the group, so that they can then add and remove other members. This might seem limiting on the surface, but since the overall outcome is to enforce a strong security policy, limiting access is just the point. Good planning is key to a successful security policy, so once you figure out who to allow access to what, you can use the Bricolage security tools to quickly set up a configuration to maintain that policy. Have fun, and stay safe! David Wheeler <david@justatheory.com> Bric