Authorisation
The Authorisation component is an essential part Factory+, as it ensures that access to resources is controlled and restricted based on the permissions assigned to various principals or actors in the architecture. Access Control Lists (ACLs) are used to manage these permissions and provide a flexible way to define and manage access control policies.
ACS Authorisation Component
Overview
The Factory+ Authorisation component can be broken down into the following elements:
- Principals: Principals are the entities (users, services, or applications) that interact with the architecture and request access to its resources. Each principal is identified using a unique ID, referred to as a UUID (Universally Unique Identifier) that conforms to RFC4122. The Identity component is responsible for managing the principals.
- Access Control Lists (ACLs): ACLs are data structures that specify the access permissions for resources in the architecture. Each entry in an ACL defines a particular action that a principal is allowed or denied to perform on a specific resource. ACLs use UUIDs to reference both the principals and the resources.
- Resource Management: The resources in the architecture are managed by different components, and each component is responsible for defining its own ACLs. This allows for a decentralised approach to access control, where each component can define its own rules based on its unique requirements.
- Access Control Enforcement: When a principal attempts to access a resource, the Authorisation component checks the corresponding ACLs to determine if the action is allowed. If the principal's UUID is found in the ACL with the appropriate permissions, access is granted; otherwise, access is denied.
Linking Identity
The Authorisation component in Factory+ plays a crucial role in managing the relationship between internal Principal UUIDs and Identities. The Authorisation component maintains a mapping table that links each Principal UUID to its corresponding Kerberos principal, ensuring that access control requests from authenticated entities can be resolved. With the Principal UUID and the associated ACL information, the Authorisation component can evaluate the user's permissions on the requested resources, ensuring that only authorised actions are allowed.
Access Control Entries (ACEs)
An Access Control Entry (ACE) is a fundamental building block of the Factory+ Authorisation component. It defines the relationship between three key elements: a principal, a permission, and a target:
- Principal UUID: The principal is an entity (user, service, or application) that requests access to a resource. It is represented by a UUID, which uniquely identifies the principal within the architecture.
- Permission UUID: The permission specifies the type of action that the principal is allowed to perform on the target resource. It is also represented by a UUID, which helps to maintain a consistent and standardised set of permissions across the architecture.
- Target UUID: The target is the resource that the principal is trying to access. It is represented by a UUID to ensure that each resource in the architecture can be uniquely identified and referenced.
The semantics of an ACE can be summarised as:
"This Principal UUID has this Permission UUID on this Target UUID."
The access control component checks the ACEs in the ACL to determine if a principal is authorised to perform a particular action on a target resource. If a matching ACE is found in the ACL, the principal is granted access; otherwise, access is denied.
Deny-by-default
In Factory+, the Authorisation component uses allow-only ACEs and follows a deny-by-default permission model. This approach ensures that access to resources is denied unless explicitly granted by an ACE, providing a higher level of security.
The Permission and Target UUIDs in the ACEs are interpreted and enforced by the individual services that make use of the access control system. Each service defines the semantics of these UUIDs based on its own requirements and resource management policies.
Wildcard UUID
The null UUID (00000000-0000-0000-0000-000000000000) is conventionally used as a wildcard target, with two possible interpretations:
- This permission on all targets: When the null UUID is used as the target in an ACE, it signifies that the specified permission applies to all resources managed by the service. This allows the principal to perform the specified action on any target within the service's domain.
- This permission needs no target: In some cases, a permission may not require a specific target to be associated with it. When the null UUID is used as the target, it signifies that the permission itself is sufficient to grant the principal access to the service, without needing to specify any particular resource.
Permission Groups
In Factory+, the use of groups in access control management is a practical way to reduce duplication and simplify the maintenance of ACLs. Groups can be utilised for any of the three UUIDs (Principal, Permission, or Target), allowing for more efficient access control policies. The Authorisation component is responsible for managing groups, as they must be defined and available before other services can be successfully contacted.
Groups can contain other groups, allowing for a hierarchical structure that simplifies access control management. Nested groups are expanded recursively, meaning that all members of a group (including those in nested groups) are considered when evaluating access control policies.
HTTP Interface
Authentication
All requests must supply HTTP authentication; the following mechanisms are supported:
| Mechanism | Authentication info required |
|---|---|
| Negotiate | A Kerberos GSSAPI token. |
| Basic | Username and password for a password-based Kerberos principal. |
| Bearer | A token from the /token endpoint. |
Specification
Well-Known UUIDs
These well-known UUIDs are part of the core framework and all MUST to be registered with the Configuration Store component under the appropriate classes.
Identity
Permission Groups
This group must be set up to contain all the permissions UUIDs below.
Permissions
This permission allows a component to read the ACLs it needs to read. The target of the permission should be the permission group the service application will request from the Authorisation Component.
This permission grants the right to look up the Kerberos principal corresponding to the target, which also represents a principal.
To search for a principal by Kerberos principal name this must be granted as a wildcard.
This must always be granted as a wildcard. This is intended only for administrators.
The target of this permission should be either the UUID of the permission that can be managed, or the wildcard.
If this is not granted as a wildcard then the only endpoint that can be used is POST /authz/ace.
The target of this permission is the group which can be edited. This permission also implicitly grants the right to create the group in the Authorisation Component, as groups exist when and only when they have members.
The target of this permission is the UUID of another principal, or the wildcard. This grants permission to add, change or remove the Kerberos principal mapping.
Class Definitions
These classes are defined by the Authorisation component and provide functionality to the Factory+ framework.
Principals
UUIDs under these classes are typically used in the princpal slot of an ACE, though sometimes they may be used as target representing, for example, the Sparkplug Node address associated with the account.
UUIDs under this class represent particular component instances running on particular Factory+ deployments. They are used to grant the component instance permissions appropriate to its role.
Where a component has a Sparkplug interface, the component account UUID also serves as the component instance's Device UUID.
Permissions
UUIDs of this class are used in the permission field of ACL entries. They represent particular permissions that can be granted to accounts as
needed. The meaning of any individual permission UUID is defined by the component that implements that permission.
Groups
These UUIDs are hardcoded into components, and each one represents the set of permissions that the component needs to query. As part of bootstrapping a component, it is necessary to ensure that the permission group is set up appropriately and contains the permissions documented in the service specification.
UUIDs of this class represent groups of permissions. The group UUID will be used in the permission field of an ACE, and grants all permissions in that group on the given targets.
These UUIDs represent groups of accounts which need to be granted permissions in common. These appear in the princpal field of an ACE.