Skip to main content
How to model permissions in Lumos

​
Overview

Modeling permissions in Lumos follows a consistent approach:
  1. Identify Resource Hierarchies
    • If your application has a concept of “resource groups,” “organizations,” or “projects,” these become Resources in Lumos.
    • Each resource has a unique identifier and a human-readable label.
  2. Define Permissions
    • Each type of permission or role is an Permission. For example, “Viewer,” “Editor,” “Billing Admin,” etc.
    • If your application requires scoping permissions to a resource (e.g., a project in your system), you represent that in the resource_id field when returning data from list_entitlements.
  3. Handle Global vs. Scoped Permissions
    • Global: The permission is the same system-wide (no resource context). Return an empty resource_id (or some global identifier) in list_entitlements.
    • Scoped: The permission only applies to a particular resource context (e.g., role in a certain Slack workspace). Return the relevant resource identifier in the list_entitlements response so Lumos knows to associate it with that resource.
  4. Assign/Unassign Permissions
    • Lumos uses assign_entitlement and unassign_entitlement to grant or revoke permissions from a user account in your application.
    • If your system requires additional constraints (like minimum or maximum assignments, or license seat counts), incorporate that logic in your connector’s implementation.
  5. Account and Permission Lifecycle
    • Typically, an account is created or updated (create_account, update_account) with some baseline permissions that are deemed mandatory from an organizational policy.
    • Additional permissions are granted later via assign_entitlement.
    • Permissions are removed via unassign_entitlement, and the account is eventually deactivated (deactivate_account) or deleted (delete_account) as the identity leaves the organization or changes roles.

​
Best Practices for Architects

  1. Keep Permissions Granular
    • Define each permission, license, or group at the appropriate level of granularity so that Lumos can manage them individually. Overly broad permissions can limit the benefits of fine-grained governance.
  2. Use Resource Context Where Applicable
    • If your application’s permissions are resource-scoped, implement list_resources thoroughly. This allows Lumos to accurately represent which permissions belong to which resource.
  3. Handle Lifecycle Events Carefully
    • Decide what “deactivate” vs. “delete” should do in your system. Some organizations prefer to “soft delete” (disable) accounts for compliance reasons. Others allow full deletion.
    • If your system cannot truly delete an account (for data retention reasons), ensure your connector’s delete_account operation is clearly documented.
  4. Leverage Custom Attributes
    • If your application requires special attributes (e.g., a “cost center” or “department code”), add them to list_custom_attributes_schema so that Lumos can track and manage them as part of the user identity.
  5. Follow a Consistent Naming Convention
    • For permissions and resources, use clear, descriptive names that help administrators understand what the permission or container is for.
  6. Performance Considerations
    • If your application has thousands or millions of users or permissions, ensure your connector endpoints (like list_accounts, list_entitlements) implement pagination or incremental synchronization if supported. This keeps synchronization timely and efficient.
  7. Security and Credential Management
    • Encourage the use of secure authentication methods (OAuth 2.0 over user/password or API keys) when possible.
    • Regularly refresh tokens (refresh_access_token) and validate credentials (validate_credentials).

​
Conclusion

By understanding the Lumos object model—identities, accounts, resources, permissions—and how data flows between Lumos and the connected systems, architects and developers can design robust, scalable integrations. Lumos’s read and write capabilities allow for comprehensive synchronization and governance of user accounts and their permissions across a wide variety of applications. When modeling permissions, always map the application’s permissions structure (roles, groups, licenses) as accurately as possible, utilizing resource scoping where needed. This ensures that Lumos administrators can rely on correct data to automate and govern access across the organization.