Access rights and user access rights

Overview

This document aims to explain the main differences between two key concepts in the Salto Nebula access control API: access rights and user access rights. It details how the access right service is used to define general access permissions and their associations with access points or access point groups, and how methods within the user service are used to assign these predefined access rights to specific users.

It also aims to clarify the difference between schedules and effective schedules.

Access rights vs user access rights

The access right service and the user access right methods in the user service manage different aspects of access control:

1. Access right service

   • This service is responsible for defining and managing access rights as standalone entities.
   • An access right (for example, salto.nebula.accessright.v1.AccessRight) defines a set of permissions, typically including schedules that dictate when access is valid.
   • It also manages how these general access rights are associated with access points or access point groups:
     • AccessRightAccessPoint: Associates an access right to a specific access point.
     • AccessRightAccessPointGroup: Associates an access right to a group of access points.
   • Essentially, this service defines what the access permissions are and where they generally apply.

2. User access right methods

   • User access right methods (for example, CreateUserAccessRight, UpdateUserAccessRight) are responsible for assigning an existing access right to a specific user.
   • A user access right (for example, salto.nebula.user.v1.UserAccessRight) creates an association between a user and an access right (which was defined using the access right service).
   • When assigning an access right to a user, you can:
     • Specify schedules that are particular to that user's access right. These can only be more restrictive than the schedules on the access right itself.
     • Define activate_time and expire_time for that specific user's grant of the access right. Typically this is useful in environments where reservations or bookings are needed.
     • View effective_schedules, which are the computed final schedules for the user based on the general access right and any user-specific overrides.
   • Essentially, these methods control who gets which predefined access permission, along with any user-specific conditions or overrides for that assignment.

In summary:

• Access right service: Defines the general rules and permissions (the "what" and "where").
• User access right methods (in user service): Assigns those general rules to specific users (the "who") and allows for user-specific refinements to those assignments.

Effective schedules

This section explains the main differences between schedules and effective_schedules and how they relate to access rights.

1. Schedules on an access right

   • When you create an access right (for example, salto.nebula.accessright.v1.AccessRight), you can define a set of schedules for it.
   • These schedules represent the general validity periods for that access right. For example, an access right "Office hours access" might have schedules like "Monday to Friday, 9 AM to 5 PM."
   • This is the baseline schedule for anyone that this access right is assigned to.

2. Schedules on a user access right

   • When you assign an existing access right to a specific user (creating a salto.nebula.user.v1.UserAccessRight object), you have the option to specify another set of schedules directly on this user access right association.
   • These user-specific schedules, if set, can only be more restrictive than the schedules defined on the parent access right itself.
   • For example, if the parent "Office hours access" is Mon-Fri 9 AM-5 PM, you could assign it to "User A" with a user-specific schedule of "Mon-Fri 1 PM-5 PM" (more restrictive). You could not set it to "Mon-Fri 8 AM-6 PM" (less restrictive).
   • If you don't provide user-specific schedules here, the schedules from the parent access right are implicitly considered.

3. Effective schedules on a user access right

   • This field represents the final, computed schedules that actually apply to the user for that particular access right.
   • The system calculates the effective_schedules by taking into account:
     • The general schedules from the parent access right.
     • Any more restrictive schedules defined directly on the user access right association.
   • The effective_schedules are essentially the intersection or the most restrictive combination of these two sets of schedules.
   • If "Office hours access" (parent) is Mon-Fri 9 AM-5 PM, and "User A's" user access right has specific schedules of Mon-Fri 1 PM-3 PM, then the effective_schedules for "User A" for this access right will be Mon-Fri 1 PM-3 PM.
   • If "User A's" user access right had no specific schedules defined, then the effective_schedules would be the same as the parent access right's schedules (Mon-Fri 9 AM-5 PM).

In summary:

• AccessRight.schedules: The general, baseline schedule for an access permission.
• UserAccessRight.schedules: An optional, user-specific override that can only further restrict the baseline schedule.
• UserAccessRight.effective_schedules: The actual, calculated times the user can use the access right, resulting from the combination of the general schedule and any user-specific restrictions. This is what the system ultimately uses to grant or deny access at a given time.