Nearly all Orchestra operation requires an authorization, which must be provided as an authorization token.
An authorization token is a 128-bit UUID (RFC 4122 [1]) that the server uses to determine that the requestor of an operation has the appropriate permission.
Example authorization token:
90812c16-2857-4f31-b272-bb82f6ecf7b1
Every entity has an authority and a list of authorizations:
- The authority is the authorization token that 'owns' that entity. By default, it is the authorization token with which the entity is created. This authorization is needed to make server related changes to the entity (e.g. delete, create connections, add/remove authorizations from the authorization list...).
- The authorization list contains all the authorization tokens that are allowed to invoke/inquire the entity. The special "VIEW" authorization can be included in the authorization list to give anyone read-only access to invoke/inquire the entity.
Most operations that does not target a specific entity but the server itself, such as creating a new entity, abide by the same logic but using the server entity <0>. The server's authority, called root authority, can do anything. If a server's authority becomes lost, there is no way to recover it via the server API. Authorization tokens authorized on the servers entity <0> can do anything except make changes to the server entity <0>, there they cannot add/remove other authorizations from it.
There also are a few basic server operations that never require any authorization code, such as getting the redirection of an entity (entity_redirection).
The AvesTerra server provides pretty bare-bone mechanisms to handle authorization token, and the avial layer provides abstractions for more convenience and user friendlyness.
¶ Invoke access decision process
Every HGTP command follow the same kind of logic to resolve whether the operation is permitted or not. The 'Invoke' command is a good illustration of that process, as it is the most complex one.
- The authorization token used to make the request is mapped to any token it's instated to. (see Token instation section)
- If the token is the server's authority or in its authorization list, then ARWED is permitted
- If the token is the authority of the entity, then ARWED is permitted
- If the token is in the authorization list of the entity (the Authorizations metadata field), then access is permitted. If the access is restricted (deprecated, shouldn't use), then _RW__ is permitted, otherwise _RWED is permitted
- If the authorization token is mapped to a credential, and that credential is the authority of the entity, then access is authorized and the permission mask is used (see Credential mapping section)
- If the special "view" authorization token is on the entity authorization list, then _R___ is permitted (see Special tokens)
- If the entity authority is null, then access is authorized
Note: This list doesn't include the checks done the oultet on which the remote rendez-vous takes places. It's exhaustive if the entity being invoked is itself an outlet and is self-connected, but if the entity being invoked is connected to an outlet that isn't itself, then there are extra steps that are yet to be discovered.
Operations done on the server such as creating new entity follow a similar logic, except the entity would be <0>. The server's authority or any of its authorization is allowed to create new entities. However only the server's authority is allowed to modify its list of authorizations.
¶ AvesTerra level
The AvesTerra authorization model is designed to be very simple, and it is up to the application layer to determine how to use it (see the Avial/Orchestra level below).
There exist two mechanisms to create token aliases, where a token A is given the same permission as another token B.
¶ Token instation
If a token A is instated to token B, then it gets added to the token instation table held in the server.
erver.
One can see the this instation table by looking at the TOKEN_ATTRIBUTE of the server entity in the avu:
One token can only be instated to one other token. Multiple tokens can be instated to the same token. It's a N:1 mapping.
Whenever an HGTP operation (like an invoke) is performed with token A, the server replaces it with token B. This is the very first operation that happens when a server determines if the provided authorization token is allowed to invoke.
After a token A was instated to token B, if token B isn't mapped to any credential (see Credential mapping section), it gives ARWED permissions access (see Permission mask section) to any entity whose authority is token B, and _RW__ permissions access to any entity whose authorization list contains token B.
Instation only works one level: If token A is instated to token B, and token B is instated to token C, then an invoke with A becomes an invoke with B, not C.
Token instation has precedence over token mapping. If the token A is both instated to token B, and mapped to credential C, then an invoke with A becomes an invoke with B. However if the token B is also mapped to credential D, then an invoke with A will become and invoke with B and be mapped to the credential D.
¶ Credential mapping
If a token A is mapped to token B with permission mask M, then it gets added to the credential mapping table held in the server.
A credential is like a token, except it also holds a permission mask.
One token can be mapped to multiple credentials, and multiple tokens can be mapped to the same credential. It's an N:M mapping.
After a token is mapped to a credential, it access to any entity whose authority is the token of the credential with the permission mask of that credential (see permission mask for more details).
Mapping only works one level: If token A is mapped to token B with permission M, and token B is mapped to token C with permission N, then an invoke with A resolves to the credential of token B with permission M, not token C with permission N.
¶ Permission mask
What an authorization is authorized or not authorized to do is expressed with a permission mask.
A permission mask is a bitfield with 5 bits: Avesterra, Read, Write, Execute, Delete. It is commonly written using the first letter of each field: "ARWED" means everything is allowed, while "_RW__" means only Read and Write is allowed, Avesterra Execute and Delete are disallowed.
One can see the this mapping table by looking at the CREDENTIAL_ATTRIBUTE of the server entity in the avu:
The details of what permission mask does an authorization translate when doing an invoke (and therefore, what authorization mask does the adapter receive) is detailed in the "Invoke access decision process" section above.
Only the Avesterra bit of the permission mask has defined semantic. Someone with Avesterra permission is allowed to modify the metadata of the entity.
The semantic of the Read, Write, Execute and Delete bit of the permission mask is defined by the adapter handling the invoke request.
¶ Restrictions (deprecated)
⚠️ The restriction authorization mechanism remains from early AvesTerra implementations, but I don’t advocate its use as we may want to remove it sometime in the future
Each authorization in the authorization list of an entity has a "restriction" number. That number does not have any predefined semantic, but when an adapter receives a request from a certain authorization it can lookup what its restriction is and have its own interpretation of what that means.
We never used that Restriction system at LEDR, it's unclear how it exactly works in practice.
It seems that if the restriction number is different than 0, then it is given to the adapter in the 'authorization' field. eg a 'restriction' number of '42' will give an authorization token of 00000000-0000-0000-0000-00000000006a (6a is 42 in hexadecimal).
Please someone confirm this information, I havn't verified myself.
¶ Special tokens
- The NULL authorization represents no authorization requirement. If an entity's authority is NULL, then anyone can do anything on it
- The VIEW authorization represents a read-only authorization. If an entity has the VIEW authorization in its authorization list, then anyone can invoke that entity (even with the NO authorization). The adapter will receive a mask of _R___
- The VERIFY authorization is used in the avial compartment adapter when creating new identities and "login in" for the first time
- A public authorization has the first 80 bits set to 0, and they are the only authorization allowed to be sent to an untrusted server (TODO: Check if that is still the case with the new undocumented
pairandunpaircommands) - The NO authorization represents absence of permission to do anything. It also can be displayed (or transmitted over the network as string as)
********-****-****-****-************. It is used when tokens need to be obfuscated. For example when fetching the metadata of an entity with an authorized token (not the authority token), then the authority token and all the authorized tokens are obfuscated and replaced by that NO authorization.
¶ Avial level
The Avial/Orchestra level provides abstractions over authorization tokens to make their management easier: Identities and Compartments.
The Authentication adapter (<15>) manages Identities and Compartments.
Identities and Compartments are both entities:
- An Identity represent a user that will interract with the knowledge space. It could be a human, an application, an organization or anything that may interract with the knowledge space.
- A Compartments represent a collection of entities under the same authority, or a collection of identities with the same "need-to-know" level (todo: clarify)
An entity can only be in a single compartment, meaning the authority of the entity is the authority of the compartment it's in.
¶ Identities
Every identity has a name, a key and a password.
The name seems to not be useful.
The initial identity creation logic provides a way to "validate" the identity with a public/private key pair to be certain that the right user initially sets the password of that identity (see help generate in the avu).
However we usually bypass that process by manually changing the STATE_ATTRIBUTE of the identity to "Good", which is more simple. J Smart used to say this is fine, now apparently it's not anymore.
Once an identity is "validated", the user can get the identity authorization token by sending the key and password to the Authentication adapter.
¶ Obtaining an identity token
¶ Compartments
In order to access a compartment, a client application must first authenticate itself as a legitimate identity with the Authentication Adapter. The identity entity contains the list of the compartments, if any, that they have been authorized to access.
Compartment administrators have two ways to include/exclude an identity from a compartment:
- Grant/Revoke, which relies on token instation
- Issue/Retract, which relies on credential mapping
An identity can be entitled/unentitled to become a compartment administrator (privileged).
¶ Grant/Revoke
If an identity has been granted access to a compartment, it can acess all the entities the compartment is authorized on. The user can get its compartment token from the Authentication adapter. That compartment token represents that identity AS that compartment.
The downside of this approach is that one must choose what compartment they want to perform an action as a member of upon making a request.
To obtain a compartment's authorization token, a client must present the Authentication Adapter with a valid identity authorization token. With this token, the client can then present this token to the Authentication Adapter to request the authorization token for the compartment. The compartment token will only be returned by the Authentication Adapter if the identity token is properly authorized for the compartment.
When interacting with Orchestra, the client soon ends up with a keychain of various tokens that allow them to access various different things, and they are free to perform every action with whichever token makes the most sense. However the client also needs to implement the logic to know what token to use when.
The Issue/Retract approach eleviates the need to juggle with multiple authorization tokens.
¶ Issue/Retract
It's the same logic but with credential mapping.
The limitation is that if we issue a compartment to an identity, we only give the identity access to all the entities the compartment owns (where the compartment token is the authority of the entity). Therefore, we can't have two distinct compartments give identities access to a same entity through credential mapping.
That effectively turns compartments from "set of identity with the same 'need to know' level" to "set of entities with the same authority".
¶ Mixing the two systems
Of course, it's possible for an identity to be granted access to some compartments, and issued access to other comparments.
Though I didn't see any mention of that anywhere, a comparments C1 could be issued access to other compartments, in which case any identity that was granted access to C1 would we issued access to all the other compartments. However identities that were issued access to C1 would not be issued access to other compartments, since credential mapping only works at a depth of 1.
¶ Privileged access
Once an identity has been entitled a compartment, they have privileged access to that compartment and can manage which identities are in that compartment.
¶ Trusted and Foreign servers
AvesTerra is a peer to peer network, when HGTP requests transit over that p2p network, authorization are visible to all hosts participating to the routing of the request.
To protect authorization, they are never forwarded to foreign servers (opposite of trusted)
Actually it's not certain whether the UUID used in AvesTerra are fully conform to RFC 4122. ↩︎