Changes between Version 10 and Version 11 of SPIDocs


Ignore:
Timestamp:
Sep 16, 2014 10:55:57 AM (8 years ago)
Author:
faber
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • SPIDocs

    v10 v11  
    8888A 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.
    8989
    90 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:
     90Profiles 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:
    9191
    9292||= Metadata =||= Meaning =||
     
    186186=== Users ===
    187187
    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 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.
    189 
    190 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.
    191 
    192 The simplest way to log in through the SPI is to call the `requestChallenge` operation on the `Users` service.
     188A 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.
     189
     190==== Authentication ====
     191
     192In 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.
     193
     194The 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.
     195
     196Once 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.
     197
     198The 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.
     199
     200If 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.
     201
     202In 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.
     203
     204Some 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.
     205
     206Additionally, a user can always get the server's certificate to check or add to a trusted servers file using `getServerCertificate` from the `ApiInfo` service.
     207
     208Applications will have to carry out these challenges before doing anything else and can choose to log users out as well.
     209
     210==== Profile Management ====
     211
     212The `Users` [wiki:SPIDocs#Services] supports the operations described in the [wiki:SPIDocs#Profiles profiles] description to allow applications to manipulate user profiles.
     213
     214==== Notifications ====
     215
     216Many 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].
     217
     218''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:
     219
     220||= Flag Name =||= Meaning =||
     221|| Urgent || The message is more important than most messages ||
     222|| Read || The user has read this message ||
     223
     224Flags are specified when a notification is sent and can be set by the receiver as well.
     225