Changes between Version 12 and Version 13 of SimpleAttach


Ignore:
Timestamp:
Oct 30, 2017, 9:31:36 PM (7 years ago)
Author:
davea
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • SimpleAttach

    v12 v13  
    11[[PageOutline]]
     2
    23= Simplified registration/download process =
    34
    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.
    67
    7 == Current attach process ==
     8The current download/attach process has two problems:
    89
    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.
    1212
    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.
    2616
    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.
    2820
    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).
    37 
    38 Problems with this design:
    39 
    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.
    47 
    48 This document describes a new scheme that addresses these problems.
    49 
    50 == Proposed attach process ==
     21== New download/attach process ==
    5122
    5223=== Front page ===
    5324
    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.
    5526
    5627=== Registration page ===
    5728
    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).
    62 
    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.
    6535
    6636=== Download page ===
    6737
    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.
    70 
    71 ==== Android case ====
    72 
    73 Show:
    74  * '''[Download BOINC]''' (link to Google or Amazon app store)
    75  * '''Open BOINC, select Add Project, and choose (project name)'''
    76 
    77 Note: we can improve this, but it will take changes to the Android GUI.
    78 
    79 ==== Non-Android case ====
    80 
    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:
    8439
    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.
    8846
    89 The "click here" link goes to a page that:
     47=== Manager ===
    9048
    91  * Sends some cookies (see below)
    92  * Tells the user to open the Manager and choose Add Project.
    93 
    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.
    9853
    9954=== User experience ===
    … …  
    10156In summary, the new-user process is:
    10257
    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
    10862
    109 Note the following improvements:
     63Improvements:
    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.
    11266
    11367=== What projects must do ===
    11468
     69Down the XML version list from
     70http://boinc.berkeley.edu/download_all.php?xml=1.
     71Save it as html/user/versions.xml.
     72Update this as new client versions are released.
     73
     74In the home page: put a Join button linking to register.php
     75
    11576Add to config.xml:
    116  * <project_desc>: a few-sentence description of the project.
    117  * <project_inst>: the host institution (optional).
    11877
    119 Add to config.xml if needed:
    120  * <min_core_client_version>
    121  * <need_vbox>
     78{{{
     79<project_id>N</project_id>
     80}}}
     81The project's ID, as shown in
    12282
    123 In the home page:
     83https://boinc.berkeley.edu/project_list.php
    12484
    125  * put a button linking to register.php
     85and optionally:
     86{{{
     87 <min_core_client_version>70803</min_core_client_version>
     88 <need_vbox/>
     89}}}
    12690
    12791== Implementation ==
    12892
    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.
    13097
    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.
    137102
    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.
    144105
    145 === The concierge.php script ===
    146 
    147 The concierge.php script looks at the master URL to see if the project is in BOINC's list.
    148 
    149 It sends the following cookies (from the boinc.berkeley.edu domain):
    150 
    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
    158 
    159 These cookies are sent with a 24-hour expiration time.
    160 
    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.
    170 
    171 If there is no installer for the computer's platform,
    172 it goes to the BOINC "Download all" page.
    173 
    174 === Cookieless Installs ===
    175 
    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.
    178 
    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.
    181 
    182 Package name parameters are as follows:
    183 
    184  '''amu''':: the master URL
    185  '''an''':: the project name
    186  '''aa''':: the user authenticator
    187  '''asc''':: the setup cookie
    188 
    189 Usage Rules:
    190 
    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
    194 
    195 Example package name (Windows):
    196 {{{
    197 boinc_setup_amu_aHR0cDovL3NldGlhdGhvbWUuYmVya2VsZXkuZWR1Lw==_aa_ODU0NjVfZWEwYWJkNjc4NDc2MjllMWFlOWVkM2I4YWRmZmZmZmY=.exe
    198 }}}
    199 
    200 Example package name (Mac):
    201 {{{
    202 boinc_setup_amu_aHR0cDovL3NldGlhdGhvbWUuYmVya2VsZXkuZWR1Lw==_aa_ODU0NjVfZWEwYWJkNjc4NDc2MjllMWFlOWVkM2I4YWRmZmZmZmY=.zip
    203 }}}
    204 
    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.
    209 
    210 === Manager ===
    211 
    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 boinc.berkeley.edu 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
    220 
    221 == Anonymous registration ==
    222 
    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).
    227 
    228 In each case, the Register page would create an account
    229 with random strings for email address and password.
    230 
    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.
    236110
    237111== Unsupported platforms ==
    238112
    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.'''
     120
     121==== Android case ====
     122
     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)'''