- Afform provides a portable form system intended for use in core CiviCRM screens.
- CiviCRM includes a standard security model (involving roles, ACLs, entities, hooks, etc). This model is supported by the standard UI and by the API.
- Forms may relate to the standard security model in different ways. In many cases, a form simply abides by the standard model; in others, a form provides a targetted escalation.
The aim of this page is to collect the long-tail of use-cases for the security functionality. This can be used for (a) vetting suitability of design changes and (b) eventually informing E2E tests.
If one wants to leave a question or semi-durable note on this document, try to make it stand out with a
During a waning moon, the `Werewolf` should take human form and `digest()` data. During a waxing moon, the `Werewolf` should take human form and `scoutTerrain()`. > _Question_: But if the moon is waxing gibbous, can the > werewolf do a precursory `prowl()`?
A key variable in describing the security of a form is how it relates to the standard security model -- backend administration forms almost always conform to the standard/baseline security model; public engagement forms almost always require an escalation/exception from the standard model; and self-service forms are in tension (ie sometimes requiring conformance, and sometimes requiring escalation).
Note that this document generally gives more detail/consideration to the latter cases. This is not because they are more or less important - rather, their deviation from the baseline model means that they require greater attention to detail.
Standard backend administration
Description: Suppose one has developed some entity/entities and defined a standard permission model. You wish to quickly create a configuration screen with which a backend user may manage these entities.
The permissions to view the form is integrally tied to the standard permissions of the underlying data. For example, there's no point attempting to render the "OAuth Admin" screen if the user lacks permission
manage OAuth client.
- (BACK-OAUTH) OAuth Admin:
OAuthSysTokenwith a basic CRUD UI and some permissions (e.g.
manage OAuth clientvs
manage OAuth client secrets)
- (BACK-MENTOR) Mentoring hours optimization: You have staff members or volunteers who hold regular office-hours for mentoring people. Each day, they may see 10 mentees. As part of this, the mentor should log some information (e.g. make a note about the mentees' progress/plan in an
Activityand/or update the
Contactinfo). This occurs frequently, so (for efficiency reasons) you want to give the mentor an optimized form that focuses on 8 key fields. The mentor's data-access should still be determined by regular ACLs, and they can still use the rest of the UI to access fuller information.
- (BACK-REG-FREE) Event registration (free): Choose an event. Choose an existing contact or make a new one. Provide/confirm the name and email. Register for the event.
- (BACK-REG-PAY) Event registration (paid): Choose an event. Choose an existing contact or make a new one. Provide/confirm the name, email, and payment information. Register for the event.
(This next example exists somewhere in the grey area between backend administration and self-service - perhaps it's a different category?.)
- (BACK-LIMITED-GROUP) Limited group administration: You have a partially-trusted backend user. You want to allow them to view+edit members of a certain group provided they're limited to certain fields (eg they can view
last_name; they can edit email and communication prefs; but they must not have access to
birth_date). To achieve this, you do not grant access via regular ACLs. Instead, you create a custom screen that exposes only the desired fields for only the desired contacts.
Description: Allow a new, unauthenticated person to fill out some information.
Public forms always represent some kind of special/targeted permission. In general, members of the public cannot create/edit/read/delete
Contact records; but, if using a specific form to add a new record with limited fields, then it may be allowed. This represents an escalation beyond the standard permissioning.
- (PUB-CONTACT) New contact: Add your basic information (first+last name).
- (PUB-NEWS) Newsletter signup: Provide name and email. Add email to a mailing list.
- (PUB-DON) New donation: Provide name, email, and payment information. Process payment and record contribution.
- (PUB-REG-FREE) Event registration (free): Choose an event. Provide name and email. Register for the event.
- (PUB-REG-PAY) Event registration (paid): Choose an event. Provide name, email, and payment information. Register for the event.
- (PUB-MEM) New membership: Choose a membership type. Provide name, email, payment, and membership options.
- (PUB-ACT) Meeting request or Inquiry: Provide name, various contact details, and a topic/request/question for meeting. Request that an agent of the organization (staffer/volunteer) contact you.
- (PUB-CASE) Initiate case: Provide name, various contact details, and a topic/request/question for opening a case. Request that an agent of the organization (staffer/volunteer) facilitate the case.
- (PUB-LIST) Find a member: You operate a professional society. Members of the public who wish to engage with a member may browse the public membership directory.
- (PUB_SURVEY) Anonymous survey: You post a questionnaire for feedback on some business/organizational question.
Description: Make an update or request related to an existing account.
Most examples in "Public engagement" would also be sensible in a "Self-service" context, except with the added requirements of (1) providing the ability to view, update, or link with an existing record and (2) authenticating the identify of the person using the form and
- (SELF-RENEW) Renew membership: For an existing membership, confirm details and provide payment information.
- (SELF-CONTACT) My contact: Provide a form to view+edit personal contact information
- (SELF-RELATIVES) My relatives: Provide a form to view+edit the contact information for oneself and for direct relatives (eg spouse and children)
- (SELF-HOUSEHOLD) My household: Provide a form to view+edit the contact information for a
Household, based on the multi-step relationship (eg
Household member is)==>
- (SELF-ORG) My organization: Provide a form to view+edit the contact information for several related persons/orgs in a multi-step relationship (eg
- (SELF-LIST) Find a member/colleague: You operate a professional society. Confirmed members may lookup information about other confirmed members.
- (SELF-TODO) Add a "To Do" activity: Provide a form create a new activity (
type=Todo) with a subject, details, and date-time. The activity is implicitly assigned to oneself.
Authentication: All of the self-service examples require some kind of authentication/identification for the person using the form. There are variations in how this is done, e.g.
- Username/password (i.e. log into Drupal with a username and password, authenticating as the correlated contact)
- Email with link (i.e. send an email via CiviMail, CiviEvent notification, et al with an authenticated link)
- Access code (i.e. begin a multi-step pageflow; as a step in the process, send a confirmation code over email or SMS - then continue with the flow)
Minimum access/Privilege escalation: Self-service forms are less categorical than backend or public forms, e.g.
- They often involve some kind of targeted escalation beyond the standard model - an admin has selected the fields, therefore it is OK to let the user work with those fields. (In this sense, they are similar to public forms.)
- Within an organization, different people/constituencies may have different self-service abilities.These could be distinguished by some characteristic of the form-user:
- Membership in a group, role, event, etc
- A categorization in a tag, custom-field, etc
- A CMS permission (eg
edit own user)