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 @@
-
+
EXT-AUTH-3: Account Creation API (5 hours)
@@ -174,17 +174,17 @@
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 @@
auth::authenticate
- 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
auth::authority::batch_sync -authority_id
integer
-.
+.
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 @@
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:
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]
If $retrieve_password_p and $reset_password_p is true, this text
- will be displayed:
+ will be displayed:
"If you've forgotten your password, you can
ask this server to
reset your password and email a new randomly generated password to
you
."
- And email-password, should look something like this:
+ And email-password, should look something like this:
# Fetch the username. What proc should we use?
set username [auth::username]
@@ -1674,7 +1674,7 @@
return
}
- We'll want to add a check for CanChangePassword in /pvt/home.
+ We'll want to add a check for CanChangePassword in /pvt/home.
Estimate
@@ -1798,7 +1798,7 @@
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.
- Lars?
+ Lars?
Estimate
@@ -2033,7 +2033,7 @@
OpenACS retrieves a document from the enterprise server
-containing user information. Example mechanisms:
+containing user information. Example mechanisms:
A file is delivered to an agreed-on location in the file
@@ -2103,7 +2103,7 @@
Service contract for retrieving the document:
- GetDocument (
+ GetDocument (
type: 0 = snapshot
1 = incremental
since: date that you want the incremental update since?
@@ -2119,7 +2119,7 @@
Service contract for processing the document:
- ProcessDocument (
+ ProcessDocument (
type: 0 = snapshot
1 = incremental
since: date that you want the incremental update since?
@@ -2173,18 +2173,18 @@
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 @@
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 @@
Risk:
-
+