Changes between Version 12 and Version 13 of SimpleAttach

10/30/17 21:31:36 (8 months ago)



  • SimpleAttach

    v12 v13  
    23= Simplified registration/download process =
    4 This document proposes changes to the process by which volunteers
    5 download BOINC and attach to projects.
     5This document describes a new process by which volunteers
     6download BOINC and attach to projects or account managers.
    7 == Current attach process ==
     8The current download/attach process has two problems:
    9 Suppose a first-time volunteer wants to participate in a BOINC project
    10 that uses the standard PHP code for its front page.
    11 The steps are:
     10 * There are too many clicks.
     11 * Much of the GUI is in the Manager.
    13  1. Visit the project web site (say, via a link in a news story).
    14  1. Click on "Download" on the project site, taking you to the BOINC download page.
    15  1. Click on "Download BOINC" or "Download BOINC + VBox".
    16  1. When the download is done, click on the installer.
    17  1. Click on "defaults" in the installer.
    18  1. The Manager runs and brings up the Attach wizard.  Click on Add Project.
    19  1. Find the project in the project list (hopefully you still remember its name).
    20    Note: if the project is new and is not in the list,
    21    you need to go back to its web site, find the URL,
    22    and copy/paste it into the wizard.
    23    New volunteers are unlikely to figure this out.
    24  1. Click on New User.
    25  1. Enter email address and password.
     13The new process eliminates clicks and shifts most of the GUI to the web,
     14which lets us use things like OpenAuth and Recaptcha,
     15and which provides a more unified experience.
    27 For existing volunteers (i.e. already running BOINC on this computer) the steps are:
     17Note: this process only works for "vetted" projects and AMs,
     18i.e. those that appear on the BOINC web site.
     19Making it work for arbitrary projects would decrease security.
    29  1. Visit project web site; figure out what to do next
    30    (the standard front page doesn't say).
    31  1. Open the BOINC Manager.
    32  1. Open Attach wizard.
    33  1. Click on Add Project.
    34  1. Find project in list or enter URL.
    35  1. Click on Existing User.
    36  1. Enter password (email should be pre-populated from previous attach).
    38 Problems with this design:
    40  * In each case there are many steps, and we lose a fraction of volunteers at each step.
    41  * For non-listed projects, users have to type or copy/paste a URL.  Bad.
    42  * If the project requires !VirtualBox, the user should be required to download BOINC+VBox.
    43  * The scheme applies to non-Android computers.
    44   For Android users the process is similar,
    45   except that BOINC must be downloaded from the Google or Amazon app store.
    46   The standard project front page says nothing about Android.
    48 This document describes a new scheme that addresses these problems.
    50 == Proposed attach process ==
     21== New download/attach process ==
    5223=== Front page ===
    54 The project front page has a "Join" button, linked to a "registration" page.
     25The project or AM front page has a Join button, linked to a "registration" page.
    5627=== Registration page ===
    58 The registration page shows two forms side by side:
     29If the user is already logged in on this project,
     30the page redirects to the Download page.
     31Otherwise, the page has two forms:
    5932 * Create account (for users new to this project)
    6033 * Log in (for existing users)
    61 Submission of either form goes to the Download page (below).
    63 If the user is already logged in on this project,
    64 the page redirects to Download page.
     34Submission of either form goes to the Download page.
    6636=== Download page ===
    68 This page tells the user what software they need to install,
    69 and lets them either download it or confirm that it's already installed.
    71 ==== Android case ====
    73 Show:
    74  * '''[Download BOINC]''' (link to Google or Amazon app store)
    75  * '''Open BOINC, select Add Project, and choose (project name)'''
    77 Note: we can improve this, but it will take changes to the Android GUI.
    79 ==== Non-Android case ====
    81 A project's config file can specify whether it needs VBox,
    82 and whether it has a min client version.
    83 The Download page says something like:
     38This page says something like:
    8540 * To participate in X, your computer must have BOINC (and VBox) installed.
    86  * If these are already installed, [click here]
    87  * [Download BOINC (and VBox)].
     41 * If these are already installed, [click here].
     42   This links to a page with instructions for adding project via the Manager.
     43 * Buttons to download BOINC and BOINC+VBox.
     44   These show the download size, platform name, and version,
     45   like the download page on the BOINC web site.
    89 The "click here" link goes to a page that:
     47=== Manager ===
    91  * Sends some cookies (see below)
    92  * Tells the user to open the Manager and choose Add Project.
    94 The Download link does to a page that
    95  * Sends some cookies (see below)
    96  * Initiates a download
    97  * Tells the user to double-click on the installer when download is done
     49When the manager is first run,
     50it is attached to the project or account manager,
     51to the user's account.
     52No user interaction with the Manager is needed.
    9954=== User experience ===
    10156In summary, the new-user process is:
    103  1. Visit project web site, click on '''Join".
     58 1. Visit project or account manager web site, click on '''Join".
    10459 1. Enter email/passwd, click OK
    10560 1. Click Download
    10661 1. Click on installer, choose defaults
    107  1. Manager runs, brings up confirmation/welcome dialog
    109 Note the following improvements:
    11064 1. User doesn't leave the project web site (e.g. doesn't land on BOINC web site)
    111  1. User doesn't see list of all projects
     65 1. User doesn't see the list of all projects.
    11367=== What projects must do ===
     69Down the XML version list from
     71Save it as html/user/versions.xml.
     72Update this as new client versions are released.
     74In the home page: put a Join button linking to register.php
    11576Add to config.xml:
    116  * <project_desc>: a few-sentence description of the project.
    117  * <project_inst>: the host institution (optional).
    119 Add to config.xml if needed:
    120  * <min_core_client_version>
    121  * <need_vbox>
     81The project's ID, as shown in
    123 In the home page:
    125  * put a button linking to register.php
     85and optionally:
     87 <min_core_client_version>70803</min_core_client_version>
     88 <need_vbox/>
    12791== Implementation ==
    129 Register page: use existing code for forms
     93When a user is shown the Download page,
     94the server code creates a "login token" - a string of 8 random hex chars.
     95It creates a record in the login_token table,
     96containing the token, the user ID, and the create time.
    131 Download page: extract from config.xml:
    132  * the master URL
    133  * the project name
    134  * the project description
    135  * the project institution
    136  * software requirements
     98The client installer is downloaded indirectly via
     99a script on the BOINC web server (concierge.php).
     100This is passed the project ID, the login token, and the installer filename.
     101It downloads the file, appending to the filename the project ID and login token.
    138 These first 4 items are passed as URL args to a script on the BOINC web server (concierge.php).
    139 Also passed:
    140  * the user name
    141  * the user authenticator
    142  * whether a download is required
    143  * whether VBox is needed
     103When the BOINC installer is launched, it writes the installer filename to
     104a file "installer_filename.txt" in the BOINC data directory.
    145 === The concierge.php script ===
    147 The concierge.php script looks at the master URL to see if the project is in BOINC's list.
    149 It sends the following cookies (from the domain):
    151  '''attach_known''':: 1 if the project is known to BOINC
    152  '''attach_master_url''':: the master URL
    153  '''attach_project_name''':: the project name
    154  '''attach_project_desc''':: the project description
    155  '''attach_project_inst''':: the project institution
    156  '''attach_user_name''':: the user name
    157  '''attach_auth''':: the user authenticator
    159 These cookies are sent with a 24-hour expiration time.
    161 If the "download" arg is set,
    162 the script looks at the user agent string to find the computer's platform,
    163 and gets the URL of the current BOINC installer for that platform.
    164 (If VBox is needed, it uses the BOINC+Vbox installer).
    165 It then redirects to the URL of the installer file.
    166 On current browsers this doesn't change the web page
    167 (which is still the project's main page);
    168 it starts a download of the BOINC installer,
    169 which is displayed in the status bar or elsewhere.
    171 If there is no installer for the computer's platform,
    172 it goes to the BOINC "Download all" page.
    174 === Cookieless Installs ===
    176 For unsupported browsers or projects with custom installers, the required information will be passed as
    177 part of the filename of the package downloaded from the server.
    179 When the BOINC installer is launched, it'll detect the required information and add/update project_init.xml which
    180 in turn will be consumed via the client software on startup.
    182 Package name parameters are as follows:
    184  '''amu''':: the master URL
    185  '''an''':: the project name
    186  '''aa''':: the user authenticator
    187  '''asc''':: the setup cookie
    189 Usage Rules:
    191  * Each parameter is broken up into name/value pairs
    192  * Each name/value pair is separated by an underscore
    193  * Each value is base64 encoded
    195 Example package name (Windows):
    196 {{{
    197 boinc_setup_amu_aHR0cDovL3NldGlhdGhvbWUuYmVya2VsZXkuZWR1Lw==_aa_ODU0NjVfZWEwYWJkNjc4NDc2MjllMWFlOWVkM2I4YWRmZmZmZmY=.exe
    198 }}}
    200 Example package name (Mac):
    201 {{{
    203 }}}
    205 Note: Using the setup cookie is more desirable than storing the authenticator as part of the
    206 executable name.  Setup cookies are created by the project server and expire after a given
    207 period of time.  During the manager's attach process, it'll use the lookup account RPC to
    208 convert the setup cookie into the user's weak authenticator.
    210 === Manager ===
    212 When the manager starts up, or the Add Project command is given,
    213 it looks for the '''attach_master_url''' cookie from
    214 the domain.
    215 If this is present, it puts up the Attach Wizard,
    216 at a confirmation page that shows
    217  * the project name, description, and institution
    218  * the user name
    219  * whether the project is known to BOINC
    221 == Anonymous registration ==
    223 The join process can be further simplified if we eliminate the
    224 email address and password associated with accounts.
    225 This might be selected by the project (using a config flag)
    226 or by the volunteer (by an "anonymous" checkbox in the Register page).
    228 In each case, the Register page would create an account
    229 with random strings for email address and password.
    231 We may want to add the following features:
    232  * Let volunteers with anonymous accounts log in to the project web site
    233    via links in the Manager.
    234  * Let anonymous accounts be made non-anonymous (i.e. given an
    235    email address, name, and password).
     106When the client startup it, it looks for this file.
     107If found, does a "lookup account token" RPC to the project,
     108obtaining the user name and a weak authenticator.
     109It attaches to the project using this authenticator.
    237111== Unsupported platforms ==
    239 One issue not addressed by this proposal:
    240 what if the computer is of a type for which the project has no apps?
     113What if the computer is of a type for which the project has no apps?
    241114The user should learn this immediately.
    242115E.g. viewed from an Android device,
    245118'''This project is not able to use Android devices.
    246119Please visit this site from a Windows, Mac, or Linux computer.'''
     121==== Android case ====
     123This doesn't work for Android.
     124Instead, show:
     125 * '''[Download BOINC]''' (link to Google or Amazon app store)
     126 * '''Open BOINC, select Add Project, and choose (project name)'''