Permission System Documentation
Authentication & User Types
CloudObjects differentiates between access from different types of users:
- Every access to CloudObjects without any authorization is considered anonymous access. It is read-only. Only public objects in public namespaces are available. The directory and co:ObjectAPI/1.0 (without authorization) use anonymous access.
- A developer user corresponds to a person with an individual CloudObjects account. It provides read-only access to all public objects as well as all read and write access to objects in namespaces that the developer owns or is a member of. Access to CloudObjects as a developer is possible through the CLI Tool, the Developer APIs and this website.
- A service user corresponds to a domain and is used by the implementations of objects in the namepace. This is not publicly documented right now. Please contact us if you are interested in building products on top of CloudObjects.
Membership indicates a relationship between a CloudObjects account and a domain. A developer must be a member of a domain in order to configure objects in its namespace.
Domains can be associated with each other. Associations provide a framework for how objects from both namespaces interact with each other.
In every domain association, one side is the consumer and the other is the provider. Associations must be initiated from a provider after consumer and provider have agreed upon the association through an out-of-band mechanism.
To classify the association the consumer is assigned a role - an instance of co:ConsumerRole. There are two predefined roles, co:FullAccess and co:DefaultAccess. Support for custom rules will be added in future.
Providers can manage their consumers through the domain-consumers:list, domain-consumers:add and domain-consumers:remove commands of the CLI Tool whereas consumers can manage their providers through domain-providers:list and domain-providers:remove. The co:DomainRelationsAPI/1.0 is available as well.
CloudObjects defines audiences that encompass a segment of potential consumers, identified by their domains. An audience definition itself is an object of the type co:Audience. CloudObjects defines the audiences co:Public, co:Private and co:ConsumersDefault. Support for custom audiences will be added in future.
If a service accesses CloudObjects, its domain must be in the audience. When a developer accesses CloudObjects, any of the domains that they are a member of must be in the audience.
Audiences are used for object visibility, object usage permissions and triple visibility.
Visibility of an object determines if the audience can see that the object exists and retrieve its description (or a subset of it, depending on triple visibility as explained below) from CloudObjects.
If not further specified, objects have co:Private as their default audience. A different audience can be specified by adding a triple with the property co:isVisibleTo. In order for an object to be listed in the CloudObjects directory its audience must be set to co:Public.
The visibility of this object, however, has implications for the visibility of the entire domain and all objects in its namespace. Objects in a namespace can never have more visibility than the namespace itself, which means that if an object is set to co:Public it will only be visible if the namespace object has a visibility of co:Public, too, otherwise the object's visibility setting will have no effect.
Object Usage Permissions
Object descriptions include references to other objects as predicates or values. Whether an object can reference another object is determined through object usage permissions which are defined through a triple with the co:hasUsagePermittedFor property.
A usage permission is limited by the visibility, which means that an object obviously needs to be visible to the audience that is allowed to use it. Usage permissions default to co:Private just as visibility does.
Even if an object is visible to a user, not all of its triples are necessarily visibility. Triple visibility is based on the property object that is used as the predicate of the triple, because the semantics of a property determine whether the value is confidential or not. Properties that describe sensitive information, such as credentials or internal endpoint URLs, are typically private, while triples used for object documentation (e.g. title, description, API methods) are typically public.
CloudObjects uses some default properties from RDF ontologies from the Semantic Web / Linked Data community which reside outside of CloudObjects and are not identified with COIDs but with URNs or HTTP URIs. These external objects have object visibility, usage permission and triple visibilty set to co:Public, which means their usage is not restricted in any way.