Index: openacs-4/packages/acs-core-docs/www/xml/kernel/ext-auth-design.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/ext-auth-design.xml,v diff -u -r1.13.2.2 -r1.13.2.3 --- openacs-4/packages/acs-core-docs/www/xml/kernel/ext-auth-design.xml 9 Aug 2019 20:04:23 -0000 1.13.2.2 +++ openacs-4/packages/acs-core-docs/www/xml/kernel/ext-auth-design.xml 17 Dec 2019 16:37:50 -0000 1.13.2.3 @@ -11,42 +11,42 @@ EXT-AUTH-1: Authentication and Account Status API (4 hours) - by + by Peter Marklund - + Current Design Procedures to support this feature have already been written by Lars. We are using the existing procedure ad_user_login and are deprecating ad_maybe_redirect_for_registration and making it invoke - auth::require_login. + auth::require_login. Execution Story The auth::authenticate procedure will be called by the login page and the auth::require_login procedure at the beginning of any - application pages that require login. + application pages that require login. Tradeoffs: - For this feature reliability and testing are the prime concerns. + For this feature reliability and testing are the prime concerns. External Design - The authtentication API has the following public methods: + The authtentication API has the following public methods: ad_proc -public auth::require_login {} { - If the current session is not authenticated, redirect to the + If the current session is not authenticated, redirect to the login page, and aborts the current page script. Otherwise, returns the user_id of the user logged in. - Use this in a page script to ensure that only registered and authenticated + Use this in a page script to ensure that only registered and authenticated users can execute the page, for example for posting to a forum. @return user_id of user, if the user is logged in. Otherwise will issue an ad_script_abort. @see ad_script_abort @@ -60,13 +60,13 @@ {-username:required} {-password:required} } { - Try to authenticate and login the user forever by validating the username/password combination, - and return authentication and account status codes. - + Try to authenticate and login the user forever by validating the username/password combination, + and return authentication and account status codes. + @param authority_id The ID of the authority to ask to verify the user. Defaults to local authority. @param username Authority specific username of the user. @param password The password as the user entered it. - + } @@ -79,7 +79,7 @@ Procedure auth::authenticate - Need to stub ns_sendmail? + Need to stub ns_sendmail? Test auth_status not "ok" for: @@ -96,7 +96,7 @@ - + Test account_status "closed" for @@ -106,7 +106,7 @@ - + Error handling (requires stubbing the Authenticate service contract): @@ -130,18 +130,18 @@ - + Page Flow - None + None Data Model - None + None TODO @@ -163,7 +163,7 @@ </itemizedlist> </sect3> </sect2> - + <sect2> <sect2info> <title>EXT-AUTH-3: Account Creation API (5 hours) @@ -174,17 +174,17 @@ <title>EXT-AUTH-3: Account Creation API (5 hours) - by + by Peter Marklund - + Current API -ad_proc ad_user_new {email first_names last_name password password_question password_answer +ad_proc ad_user_new {email first_names last_name password password_question password_answer {url ""} {email_verified_p "t"} {member_state "approved"} {user_id ""} } { Creates a new user in the system. The user_id can be specified as an argument to enable double click protection. If this procedure succeeds, returns the new user_id. Otherwise, returns 0. @@ -221,7 +221,7 @@ the authority with lowest sort_order that has register_p set to true. } { set authorities_list [list] - + # Always register the user locally lappend authorities_list [auth::authority::local] # Default authority_id if none was provided @@ -238,9 +238,9 @@ } -default ""] if { $authority_id eq "" } { error "No authority_id provided and could not find an authority that can create users" - } + } lappend authorities_list $authority_id - } + } # Register the user both with the local authority and the external one db_transaction { foreach authority_id $authorities_list { @@ -325,12 +325,12 @@ acs-subsite/www/register/user-new.tcl. Again, all logic is in the pages. - + External Design - We will have to rewrite the following pages: + We will have to rewrite the following pages: User login: /register/index @@ -357,7 +357,7 @@ The code to handle the login process in /register/index.tcl would -look like this: +look like this: ad_form -name user_add -form { {authority_id:integer(hidden)} @@ -436,7 +436,7 @@ user-login.tcl. If user not registered (i.e. $auth_info(account_status) eq "no_account" ), - user is redirected to user-register.tcl. + user is redirected to user-register.tcl. Error Handling @@ -446,7 +446,7 @@ <literal>auth::authenticate </literal> - Returns the array element auth_status, which can either be: + Returns the array element auth_status, which can either be: ok: login was successful, continue @@ -475,7 +475,7 @@ - Also account_status is returned, which can either be: + Also account_status is returned, which can either be: ok: login was successful, continue @@ -498,7 +498,7 @@ auth::register - Returns the array element reg_status, which can either be: + Returns the array element reg_status, which can either be: ok: Registration was successful, continue @@ -560,7 +560,7 @@ - + Execution Story User login scenario: @@ -625,13 +625,13 @@ Otherwise, no "Change my password" link. - + The change password page will call the Password Management API to change the password. - + @@ -657,9 +657,9 @@ ad_proc -public auth::password::can_change_p { {-user_id:required} } { - Returns whether the given user change password. - This depends on the user's authority and the configuration of that authority. - + Returns whether the given user change password. + This depends on the user's authority and the configuration of that authority. + @param user_id The ID of the user whose password you want to change. @return 1 if the user can change password, 0 otherwise. } { @@ -674,7 +674,7 @@ Change the user's password. @param user_id The ID of the user whose password you want to change. @param old_password The current password of that user. This is required for security purposes. - + @param new_password The desired new password of the user. @return An array list with the following entries: <ul> @@ -689,20 +689,20 @@ } ad_proc -public auth::password::get_forgotten_url { {-authority_id:required} -} { +} { Returns the URL to redirect to for forgotten passwords. If the user's authority has a "forgotten_pwd_url" set, it'll return that, otherwise it'll return a link to /register/email-password under the nearest subsite. - + @param authority_id The ID of the authority that the user is trying to log into. @return A URL that can be linked to when the user has forgotten his/her password. } - ad_proc -public auth::password::can_retrieve_p { {-authority_id:required} } { - Returns whether the given authority can retrieve forgotten passwords. - + Returns whether the given authority can retrieve forgotten passwords. + @param authority_id The ID of the authority that the user is trying to log into. @return 1 if the authority allows retrieving passwords, 0 otherwise. } { @@ -730,8 +730,8 @@ ad_proc -public auth::password::can_reset_p { {-authority_id:required} } { - Returns whether the given authority can reset forgotten passwords. - + Returns whether the given authority can reset forgotten passwords. + @param authority_id The ID of the authority that the user is trying to log into. @return 1 if the authority allows resetting passwords, 0 otherwise. } { @@ -758,7 +758,7 @@ returned, it means that caller is responsible for informing the user of his/her new password.</li> </ul> -} { +} { # Implementation note # Calls auth::password::ResetPassword(authority_id, username) for the user's authority. } @@ -809,7 +809,7 @@ - + #29, service contract for password mgmt, will have to change as implied by the return values of this API. @@ -850,7 +850,7 @@ - + EXT-AUTH @@ -932,27 +932,27 @@ through all enabled and batch-enabled authorities and calls <literal>auth::authority::batch_sync -authority_id integer -</literal>. +</literal>. </sect4> </sect3> <sect3> <title>Internal Design - Administration + Administration ad_proc -public auth::authority::enable_batch_sync { -authority_id } { - db_dml toggle_enbaled_p { + db_dml toggle_enbaled_p { update some_table set batch_sync_enabled_p = 't' where authority_id = :authority_id } } - Scheduled proc: + Scheduled proc: ad_proc -public auth::batch_sync_sweeper {} { db_foreach select_authorities { @@ -998,7 +998,7 @@ calls auth::authentication::Authenticate which invokes - the service contract implementation for the authority. Returns: + the service contract implementation for the authority. Returns: auth_status: "ok", "bad_password", "no_account", @@ -1036,7 +1036,7 @@ Invoke the Authenticate service contract operation for the given authority. @param username Username of the user. @param password The password as the user entered it. - + @param authority_id The ID of the authority to ask to verify the user. Leave blank for local authority. } { if { $authority_id eq "" } { @@ -1059,26 +1059,26 @@ password {parameters {}} } { - Implements the Authenticate operation of the auth_authentication + Implements the Authenticate operation of the auth_authentication service contract for the local account implementation. } { array set auth_info [list] # TODO: username = email parameter ... set username [string tolower $username] - + set authority_id [auth::authority::local] set account_exists_p [db_0or1row select_user_info { select user_id from cc_users where username = :username and authority_id = :authority_id - }] - + }] + if { !$account_exists_p } { set auth_info(auth_status) "no_account" return [array get auth_info] } - + if { [ad_check_password $user_id $password] } { set auth_info(auth_status) "ok" } else { @@ -1087,10 +1087,10 @@ ... display link... } else { set auth_info(auth_status) "bad_password" - } + } return [array get auth_info] } - # We set 'external' account status to 'ok', because the + # We set 'external' account status to 'ok', because the # local account status will be checked anyways set auth_info(account_status) ok return [array get auth_info] @@ -1121,7 +1121,7 @@ External Design auth::registration::Register - returns: + returns: creation_status @@ -1162,7 +1162,7 @@ {-parameters ""} } { Invoke the Register service contract operation for the given authority. - + } { if { $authority_id eq "" } { set authority_id [auth::authority::local] @@ -1219,7 +1219,7 @@ set result(creation_message) "We experienced an error while trying to register an account for you." return [array get result] } - + # Creation succeeded set result(creation_status) "ok" # TODO: validate data (see user-new-2.tcl) @@ -1446,16 +1446,16 @@ EXT-AUTH-16: Authentication Service Contract (1 hour) - by + by Peter Marklund - + Already done by Lars. We should ocument which messages can/should be HTML and which should be plain text and in general try to - document expected values of return variables more clearly. - by + document expected values of return variables more clearly. + by Peter Marklund @@ -1467,14 +1467,14 @@ EXT-AUTH-17: Account Creation Service Contract (1 hour) - by + by Peter Marklund - + Already done by Lars. Todo: improve documentation of return values. - by + by Peter Marklund @@ -1486,16 +1486,16 @@ EXT-AUTH-18: Authority Configuration Data Model (2 hours) - by + by Peter Marklund - + The table auth_authorities already exists in acs-kernel for Oracle. We need to create the table for PostgreSQL and provide upgrade scripts. Rename column auth_p authenticate_p for readability and - clarity? Change column name active_p to enabled_p. + clarity? Change column name active_p to enabled_p. TODO: new column: help_contact_text with contact information (phone, email, etc.) to be displayed as a last resort when people are having problems with an authority. @@ -1509,9 +1509,9 @@ constraint auth_authority_short_name_un unique, pretty_name varchar2(4000), - active_p char(1) default 't' + active_p char(1) default 't' constraint auth_authority_active_p_nn - not null + not null constraint auth_authority_active_p_ck check (active_p in ('t','f')), sort_order integer not null, @@ -1555,7 +1555,7 @@ Password recovery is currently handled by /register/email-password.tcl, email-password-2.tcl and - email-password-3.tcl. All logic is placed in the pages. + email-password-3.tcl. All logic is placed in the pages. Execution Story @@ -1627,7 +1627,7 @@ </para> The logic of bad-password will be moved into /register/index as part of ad_form, but the logic should look like something along the - lines of: + lines of: <programlisting> set user_id [ad_conn] set authority_id [auth::authority -user_id $user_id] @@ -1636,14 +1636,14 @@ set reset_password_p [auth::password::CanResetPassword -driver $driver] </programlisting> If $retrieve_password_p and $reset_password_p is true, this text - will be displayed: + will be displayed: <para>"If you've forgotten your password, you can <ulink url="email-password?user_id=blahblah">ask this server to reset your password and email a new randomly generated password to you </ulink>." </para> - And email-password, should look something like this: + And email-password, should look something like this: <programlisting> # Fetch the username. What proc should we use? set username [auth::username] @@ -1674,7 +1674,7 @@ return } </programlisting> - We'll want to add a check for CanChangePassword in /pvt/home. + We'll want to add a check for CanChangePassword in /pvt/home. </sect3> <sect3> <title>Estimate @@ -1798,7 +1798,7 @@ <sect3 id="execution_stor"> <title>Execution story - User: + User: User visits /pvt/home @@ -1821,7 +1821,7 @@ - Admin: + Admin: () @@ -1841,7 +1841,7 @@ If $change_password_p is true, we'll display the "Change my password" link on /pvt/home. update-password would look something - like this: + like this: if {![db_0or1row select_email {}]} { db_release_unused_handles @@ -1949,7 +1949,7 @@ Execution Story A page showing who has requested a page during the last 5 minutes. - Could be integrated with a chat or instant messaging service. + Could be integrated with a chat or instant messaging service. Internal Design @@ -1961,7 +1961,7 @@ project, but haven't quite finished the work and put it back into the tree. </para> - Lars? + Lars? </sect3> <sect3> <title>Estimate @@ -2033,7 +2033,7 @@ <orderedlist> <listitem> <para>OpenACS retrieves a document from the enterprise server -containing user information. Example mechanisms: +containing user information. Example mechanisms: <itemizedlist> <listitem> <para>A file is delivered to an agreed-on location in the file @@ -2103,7 +2103,7 @@ <para>Service contract for retrieving the document: </para> <programlisting> - GetDocument ( + GetDocument ( type: 0 = snapshot 1 = incremental since: date that you want the incremental update since? @@ -2119,7 +2119,7 @@ <para>Service contract for processing the document: </para> <programlisting> - ProcessDocument ( + ProcessDocument ( type: 0 = snapshot 1 = incremental since: date that you want the incremental update since? @@ -2173,18 +2173,18 @@ <sect3> <title>Internal Design - Describe key algorithms, including pseudo-code. + Describe key algorithms, including pseudo-code. Data Model - Describe data model changes. + Describe data model changes. Error Handling What error codes or error conditions could result? How are they - handled? + handled? Upgrade @@ -2197,14 +2197,14 @@ <title>EXT-AUTH-29: Password Management Service Contract (1 hour) - by + by Peter Marklund - + Already done by Lars. Todo: improve documentation of return values. - by + by Peter Marklund @@ -2219,7 +2219,7 @@ External Design - We'll want an API that lets us + We'll want an API that lets us add authorities: auth::authority::new @@ -2234,7 +2234,7 @@ - authorities. + authorities. Here goes: @@ -2292,7 +2292,7 @@ {-authority_id:required} } { db_exec delete_authority { - delete from auth_authorities + delete from auth_authorities where authority_id = :authority_id } } @@ -2312,7 +2312,7 @@ {-register_url:required} } { db_exec edit_authority { - update auth_authorities + update auth_authorities set short_name = :short_name, pretty_name = :pretty_name, active_p = :active_p, @@ -2350,15 +2350,15 @@ EXT-AUTH-31: External Authentication Datamodel (2 hours) - by + by Peter Marklund - + The columns authority_id and username have been added to the users table for Oracle. We need to add them for PostgreSQL and provide - upgrade scripts. + upgrade scripts. create table users ( user_id not null @@ -2368,8 +2368,8 @@ authority_id integer constraint users_auth_authorities_fk references auth_authorities(authority_id), - username varchar2(100) - constraint users_username_nn + username varchar2(100) + constraint users_username_nn not null, screen_name varchar2(100) constraint users_screen_name_un @@ -2398,7 +2398,7 @@ - by + by Peter Marklund @@ -2470,13 +2470,13 @@ OACS-COL-1: Automate install and self-test (5 hours) - by + by Peter Marklund - - I need to make sure the install scripts work. I then need to: + + I need to make sure the install scripts work. I then need to: Schedule nightly recreation @@ -2492,14 +2492,14 @@ - by + by Peter Marklund - + EXT AUTH #x: Title of feature @@ -2623,7 +2623,7 @@ </para> <para>Risk: </para> - + </sect3> </sect2> </sect1>