Changes between Version 15 and Version 16 of SPIDocs

Timestamp:

Sep 19, 2014 11:50:27 AM (10 years ago)

Author:

faber

Comment:

--

SPIDocs

@@ -188 +188 @@
 A user represents a researcher using the testbed.  Most operations in the SPI are carried out on behalf of a user.  Users must authenticate themselves to the testbed in order to carry out such operations.  Users own other instances, for example a user owns experiments or projects that they create.  Ownership is both an auditing construct - the testbed can determine which researcher configured which objects - and through policy assigns some rights to carry out operations.  The owner of an experiment has rights outside those specified by the circles the owner belongs to.
 
+Each user has a unique identifier, a textual ''userid''.  Permissions, resources, objects, etcetera are all bound to that userid.  A userid is a text string that uniquely identifies a user.  A userid cannot contain the colon character (:) nor can it conflict with other userids or [wiki:SPIDocs#Projects projectids].
+
+A user creates a namespace for circles, experiments, and libraries.  Instances of each of those abstractions are names as ''namespace'':''name''.  A user with userid `u` can create experiments with names of the form `u:experiment`.  This allows each user to manage their own names without introducing ambiguity when another user creates an experiment with the same name.  Applications are welcome to hide the prefix on such names, except when needed to resolve an ambiguity.  In such a case, teh application may display only the parts of experiment names after the colon to user `u` unless that user also has access to another user's experiment with the same name after the colon.  Such an application might display an experiment list to user `u` that looks like:
+
+||= Experiment Name =||
+|| myworm ||
+|| DDoS ||
+|| bob:mytest1 ||
+|| u:mytest1 ||
+
+Most experiments are unambiguous, but because `u` can see the experiment that user `bob` called `mytest1` and the experiment that `u` called `mytest1`, the application presents the prefixes as well.
+
 ==== Authentication ====
 
-Each user has a unique identifier, a textual ''userid''.  Permissions, resources, objects, etcetera are all bound to that userid.  Authentication is the problem of binding a request to that identity.
+
+Authentication is the problem of binding a request to a userid.
 
 In order for a user to carry out operations on the testbed, the user must log in to the testbed.  When requests are made to the SPI they are made through a secure connection where client and server (that is user and testbed) are identified by an X.509 certificate issued by the testbed.  The login process binds an X.509 certificate used to make a secure connection to a userid in the testbed used to determine rights.  Users are authenticated through a password system.
@@ -270 +283 @@
 
 These are documented below.
+
+=== Projects ===
+
+A Project is an administrative grouping of users that helps to scale testbed administration by allowing trusted users to add others to the testbed.  Intuitively, a project collects users who are working on a particular research project.  A user proposes such a project to the testbed administration.  If the administration approves that project, the proposing user is granted the power to add other users to the project.  Until a user is a member of an approved project, they have minimal rights on the testbed.
+
+To make the distinction above explicit, projects can be in 2 states: ''approved'' and ''unapproved''.  All projects are initially unapproved.  Members of unapproved projects gain no additional rights on the testbed.  Once an administrator approves the project, the members gain broader rights.  Approval is an explicit operation undertaken only in accordance with the testbed's real-world policies.
+
+As users have userids, projects have `projectid`s.  A projectid is a text string that uniquely identifies a project.  It cannot contain a colon, nor can it conflict with either another projectid or userid.
+
+An approved project creates its own namespace for circles, experiments, and libraries in much the same way creating a [wiki:SPIDocs#Users user] does.  Users can be explicitly given the right to create circles, experiments, and libraries in the project's namespace.  The SPI places no meaning on an instance created with a user name prefix rather than a project name prefix, but applications may.
+
+A project also is linked to a [wiki:SPIDocs#Circles circle] named after the project.  A project named `myproject` will have a linked circle `myproject:myproject`.  The system keeps the membership of that circle and the project synchronized.  By assigning rights to that circle, users can assign rights to all project members.
+
+The operations on projects are controlled by the `Projects` [wikiSPIDocs#Services service]. 
+
+When a researcher joins the testbed by [wiki:SPIDocs#CreatingNewUsers creating a user instance], one of the few operations the testbed will allow them to carry out is to propose a project.  The intended workflow is that a researcher comes to the testbed, joins it by creating a user instance and then gains rights by proposing a project that is approved.  Then that user (and other users to which it delegates rights) can administer access under that project.
+
+==== Project Permissions ====
+
+Any member of a project may have one or more of the following permissions that define the operations that user can carry ont on the project itself.  The permissions are:
+
+||= Permission Name =||= Meaning =||
+|| ADD_USER || Request that a user be added to the project or confirm a request by a user to join the project ||
+|| CREATE_CIRCLE ||Create a new circle in the project's namespace (a name prepended by ''projectid'':)||
+|| CREATE_EXPERIMENT ||Create a new experiment in the project's namespace (a name prepended by ''projectid'':) ||
+|| CREATE_LIBRARY || Create a new library in the project's namespace (a name prepended by ''projectid'':) ||
+|| REMOVE_USER || Remove a user from the project.  Any objects they have created in the project's namespace remain ||
+
+
+==== Creating A Project ====
+
+A user creates a project using the `createProject` operation on the `Projects` [wiki:SPIDocs#Services service].  Mechanically, the procedure to create a project is very similar to [wiki:SPIDocs#CreatingNewUsers creating a user].  An application will:
+
+ * User the `getProfileDescription` operation on the `Projects` service to get an empty project profile
+ * Gather data from the user to fill in the project description, including non-optional fields and proper formatting
+ * Call the `createProject` with a project name from the user and that user as the project's owner.  (Administrators can create projects owned by other users).
+
+When `createProject` completes successfully, the project exists but is unapproved.  An administrator can approve it by calling `approveProject` in the `Projects` service once the testbed's real-world criteria are met.  An administrator may also call `removeProject` in the `Projects` service to remove an unapproved project. (`removeProject` also will remove approved projects, potentially removing many users' rights to operate on the testbed.)
+
+==== Adding Users To A Project ====
+
+Users can become members of a project by requesting to join or or by being invited to join. Because joining a project adds a user to the project's circle, that changes the rights of a user, so either of these routes must be endorsed by both the user and someone with relevant permissions in the project.  The difference is only the order in which the endorsements are gathered.
+
+When a user finds a project the would like to join, usually through some out of band mechanism, they call the `joinProject` operation on the `Projects [wiki:SPIDocs#Services service].  This registers the user's intention to join and sends a [wiki:SPIDocs#Notifications notification] to members of the project who have the right to add users to the group.  This notification includes a challenge that is similar in format to the [wiki:SPIDocs#PasswordManagement requestPasswordChange] challenge.  As with that operation, an application can include a URL prefix that will be prepended to the challenge in the notification.
+
+One of the users receiving the notification can then call `joinProjectConfirm` with the challenge and a list of [wiki:SPIDocs#ProjectPermissions permissions] that the user will be assigned.  When that operation completes, the user is a member of the project with the associated rights.  The user calling `joinProjectConfirm` must have the `ADD_USER` right and similarly cannot confer more rights than they have.
+
+When a user with the `ADD_USER` permission wants to invite another user to join the project, the inviting user calls the `addUsers` operation with the projectid, a list of users, proposed permissions, and an a URL prefix that serves the same purpose as the prefix on `joinProject`.  When the operation succeeds, each invited user receives a [wiki:SPIDocs#Notifications notification] containing a challenge (and descriptive text about the project).  If the invited user does wish to join, they call the `addUserConfirm` operation with the challenge.  When that operation succeeds, they are a member of the project.
+