HAM: Simplified, Powerful Authorization for Complex FileMaker Apps

Charles Delfs, June 4, 2021, dotFMP Berlin 2021

Managing complex user authorizations in FileMaker apps is often a daunting task. With multiple user types, permissions, and plan tiers, it’s easy for developers to get lost in a maze of scripts, conditions, and configuration settings. HAM, or the Headless Authorization Module, was designed to address these challenges, enabling developers to manage user privileges in an elegant, scalable way.

Menu

1. Introduction
2. Understanding Authorization vs. Authentication
3. HAM’s Core Concepts
4. Structuring Privileges with HAM
5. Why Use HAM?
6. How to Set Up HAM in Your FileMaker App
7. Exploring HAM Configurations
8. Using Inheritance in HAM
9. Advanced HAM Features: Sum and Eval Options
10. Examples and Real-World Scenarios
11. Best Practices for HAM Implementation
12. Integrating HAM with Third-Party Systems
13. Contributing to HAM
14. Key Takeaways

Introduction

To top

Charles Delfs from Delfs Engineering introduced HAM during the 2021 dotFMP Conference, showcasing how it can revolutionize authorization management in FileMaker. HAM provides a structured yet flexible approach to handling user privileges, making it particularly useful for SaaS products and multi-tenant environments where different users have distinct levels of access.

Understanding Authorization vs. Authentication

To top

Before diving into HAM, it’s crucial to understand the difference between authorization and authentication:

• Authentication answers the question, “Who are you?” through login credentials.
• Authorization answers, “What are you allowed to do?” by defining specific actions a user can perform. HAM focuses exclusively on this aspect.

HAM’s Core Concepts

To top

HAM is a headless module, meaning it doesn’t include a user interface. It operates in the background, managing privileges and permissions through JSON objects. This flexibility means that HAM can be adapted to various scenarios without needing a specific UI, making it ideal for complex, data-driven environments.

Structuring Privileges with HAM

To top

HAM uses a non-opinionated, JSON-based model to define user privileges, allowing you to:

• Track Permissions: Define what users can and cannot do at a granular level.
• Override Permissions: Customize access for specific users without altering the primary privilege structure.
• Utilize Recursion: Inherit permissions from parent roles, reducing redundancy in setup.

JSON Example: Privilege Hierarchies

The following JSON snippet defines a basic structure for three user roles—basicUser, manager, and admin:

{
  "basicUser": {
       "addUsers": false,
       "editUsers": false,
       "editOwnDetails": true,
       "widgetsAllowed": 1
  },
  "manager": {
       "inherit": ["basicUser"],
       "editUsers": true,
       "widgetsAllowed": 3
  },
  "admin": {
       "inherit": ["manager"],
       "addUsers": true
  }
}

Each user role can inherit privileges from others. This example uses inherit to cascade permissions, meaning that manager inherits all permissions from basicUser but gains additional ones, like editUsers.

Why Use HAM?

To top

Managing authorizations directly within FileMaker can be cumbersome, especially when dealing with multiple privilege levels or complex nested permissions. HAM offers several benefits:

• Scalability: It can manage permissions across many users and plan tiers without performance issues.
• Flexibility: HAM adapts to a variety of use cases, from simple CRUD (Create, Read, Update, Delete) operations to complex role-based access.
• Integratability: Easily integrates with external systems or APIs, enabling you to share privilege configurations across platforms.

How to Set Up HAM in Your FileMaker App

To top

Setting up HAM involves defining user privileges and configuring them within FileMaker. This setup typically includes:

1. Define Privileges in a JSON object within a preferences table or similar configuration space.
2. Assign User Roles by linking them to privilege groups defined in the JSON structure.
3. Run Initialization Scripts during user login to set up the current session’s privileges based on role and overrides.

Key Custom Functions in HAM

HAM relies on three core custom functions:

1. HAM_Config: Initializes the user session, setting up privileges.
2. HAM_CheckPriv: Checks if a user has a specific privilege.
3. HAM_Utils: Supports additional tasks like debugging and error handling.

Exploring HAM Configurations

To top

HAM offers various configuration options:

• evaluateNow: Determines whether eval privileges should be calculated at initialization.
• storeGlobal: Specifies whether global variables should store privilege data, impacting security and performance.
• encryptionKey: Adds encryption for sensitive data, making HAM suitable for secure applications.

Using Inheritance in HAM

To top

Inheritance is a powerful feature of HAM that minimizes redundancy:

• Cascading Inheritance: Users inherit permissions from multiple roles, specified in an ordered array within inherit. The last role in the array takes precedence.
• Recursive Inheritance: Ensures permissions are layered correctly, allowing complex permission hierarchies without extensive manual configuration.

Example

In the following JSON, manager inherits from both basicUser and an additional role extraRole:

"manager": {
  "inherit": ["basicUser", "extraRole"],
  "editUsers": true
}

The manager role now has all permissions of both basicUser and extraRole.

Advanced HAM Features: Sum and Eval Options

To top

HAM supports advanced configuration with _sum and _eval for numerical aggregation and conditional checks:

• _sum: Adds values across roles. For example, summing widgetCount from multiple roles.
• _eval: Dynamically evaluates permissions. Example: "editRooms_eval": "Get ( DayOfWeek ) = 2" This allows editing rooms only on Mondays.

Examples and Real-World Scenarios

To top

HAM’s flexibility makes it suitable for a variety of scenarios. Here’s how you might use HAM for user authorization in a SaaS app:

• SaaS Plan Management: Define plans (e.g., Gold, Silver, Bronze) with privileges like maxProjects or prioritySupport.
• Role-Based Access: Assign roles to team members and manage permissions for each role within a multi-tenant application.
• User Overrides: Allow individual users to have special permissions that deviate from the standard roles, such as temporary access to a restricted feature.

Best Practices for HAM Implementation

To top

When implementing HAM, follow these best practices to ensure your setup remains maintainable and secure:

1. Semantic Naming: Use clear, descriptive names for privileges. For example, use canViewReports instead of view to avoid confusion.
2. Minimize Hardcoding: By using HAM’s flexible JSON structures, you can avoid hardcoding privilege checks throughout your scripts.
3. Avoid Deep Nesting: While HAM can handle complex nesting, try to keep inheritance simple to avoid performance impacts and reduce debugging complexity.

Integrating HAM with Third-Party Systems

To top

HAM can seamlessly integrate with other systems, such as web apps or external APIs. To do this:

1. Export HAM Configurations: Pass JSON objects containing user privileges to the external system.
2. Leverage HAM in Web Apps: Since HAM generates JSON, it’s compatible with most modern web frameworks, allowing you to enforce the same set of permissions across multiple platforms.
3. Use for API Authorization: HAM can define access scopes for API endpoints, ensuring that only authorized users can make specific requests.

Contributing to HAM

To top

HAM is open-source and maintained on GitHub, where contributions are welcome:

• Submit Pull Requests: If you find a bug or want to add a feature, submit a pull request with your changes.
• Report Issues: File an issue if you encounter problems or have suggestions for improvement.
• Write Tests: Test any new features or bug fixes to ensure they don’t introduce errors.

Key Takeaways

To top

HAM brings a fresh approach to managing user authorizations in FileMaker, blending simplicity with flexibility. Its JSON-based structure allows for easy adaptation to different use cases, from simple role management to complex SaaS environments. With HAM, you can centralize privilege management, reduce redundancy, and ensure your FileMaker apps are both powerful and easy to maintain.

Whether you’re managing a single FileMaker app or a complex, multi-platform SaaS product, HAM offers a scalable solution that can grow with your needs.

https://github.com/DelfsEngineering/FM-HAM