Changes between Version 10 and Version 11 of SPIDocs

Timestamp:

Sep 16, 2014 10:55:57 AM (10 years ago)

Author:

faber

Comment:

--

SPIDocs

@@ -88 +88 @@
 A profile is a collection of metadata attached to an abstraction instance, primarily to help users and administrators understand what the instance is bing used for.  Users, projects, circles, experiments, and libraries all have profiles attached to them which describe those things.  For example, a user profile includes the researcher's name and an e-mail address.
 
-Profiles are self-describing, so that applications have guidance is what is being presented and how to display it.  Each of the abstractions above has an operation called `getProfileDescription` in its associated [wiki:SPIDOcs#Services service] that returns an array of all the valid fields - called ''attributes'' -  in that abstraction's profile.  Each element of that array - each attribute - includes additional metadata that describes its purpose and presentation:
+Profiles are self-describing, so that applications have guidance is what is being presented and how to display it.  Each of the abstractions above has an operation called `getProfileDescription` in its associated [wiki:SPIDocs#Services service] that returns an array of all the valid fields - called ''attributes'' -  in that abstraction's profile.  Each element of that array - each attribute - includes additional metadata that describes its purpose and presentation:
 
 ||= Metadata =||= Meaning =||
@@ -186 +186 @@
 === Users ===
 
-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 objets - 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.
-
-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.  The login process binds an X.509 certificate used to make a secure connection to a user instance in the testbed used to determine rights.
-
-The simplest way to log in through the SPI is to call the `requestChallenge` operation on the `Users` service.
+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.
+
+==== Authentication ====
+
+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 user instance in the testbed used to determine rights.  Users are authenticated through a password system.
+
+The simplest way to log in through the SPI is to call the `requestChallenge` operation on the `Users` [wiki:SPIDocs#Services service].  The caller specifies the sorts of challenges it can carry out and the server sends the input for such a challenge.  Challenges can include hashing passwords and other mechanisms.  Because the challenge and its response are passed through encrypted channels, we also support a clear challenge.  In a clear challenge the caller submits a password in the clear.  Each challenge is valid for a limited time - 2 minutes - and has a unique identifier so a response is bound to a specific challenge.
+
+Once the caller gets a challenge, it calculates the response and replies to the challenge by calling `challengeResponse` on the `Users` service.  If successful, the user is logged in and can begin carrying out operations.
+
+The login process binds a user to an X.509 certificate, so the certificate and the challenge response need to work together.  There are two ways to do this: if the user has no X.509 certificate from the testbed, the `challengeResponse` request can be made without a client certificate.  In that case, the result of a successful challenge will include a signed certificate and a private key in PEM format that the user can use for future communications.  The key is unencrypted, and it is the responsibility of the client to properly protect it.
+
+If the user has an X.509 certificate - say from a previous successful `challengeResponse` exchange - the user can make the challenge response connection with that certificate, and the certificate/user binding will be complete and no new certificate created.
+
+In either case, connections made with that X.509 client certificate will be treated as from the user until the user logs out using the `logout` operation on the `Users` service, logs in as another user as above, or the login times out in 24 hours.
+
+Some web applications have trouble adding an X.509 certificate on the fly - especially those that run in browsers.  To simplify the development of those applications, there is an operation in the `ApiInfo` service called `getClientCertificate` that returns a certificate issued by the testbed and an unencrypted private key, both in PEM format.  This interface does not require a login and can be accessed through most web browsers, enabling a user to cut and paste the certificate into a local file for use with applications.  The certificate is not logged in.
+
+Additionally, a user can always get the server's certificate to check or add to a trusted servers file using `getServerCertificate` from the `ApiInfo` service.
+
+Applications will have to carry out these challenges before doing anything else and can choose to log users out as well.
+
+==== Profile Management ====
+
+The `Users` [wiki:SPIDocs#Services] supports the operations described in the [wiki:SPIDocs#Profiles profiles] description to allow applications to manipulate user profiles.
+
+==== Notifications ====
+
+Many operations in the SPI require a user to agree with the operation before the operation becomes final.  Users who wish to join a project or a circle request permission from the users who own or administer them.  Administrators who wish to add users to their circles request confirmation from the users.  Basically any operation that expands the rights of users requires the users in question to concur.  In order to let users know when such changes are pending or desired, the SPI supports a system for managing short messages available through the `Users` [wiki:SPIDocs#Services service].
+
+''Notifications'' are these short messages.  A notification consists of a the text of the message a unique identifier for the message, and a set of flags.  The valid flags are:
+
+||= Flag Name =||= Meaning =||
+|| Urgent || The message is more important than most messages ||
+|| Read || The user has read this message ||
+
+Flags are specified when a notification is sent and can be set by the receiver as well.
+