ad_proc -public auth::require_login {} {
    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 
    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
}

ad_proc -public auth::authenticate {
    {-authority_id ""}
    {-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.    
    
    @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 passowrd The password as the user entered it.
    
}

Peter Marklund

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.
}

ad_proc -public auth::create_user {
    {-username:required}
    {-password:required}
    {-first_names ""}
    {-last_name ""}
    {-email ""}
    {-url ""}
    {-secret_question ""}
    {-secret_answer ""}
} {
    @param authority_id The id of the authority to create the user in. Defaults to
                        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
    if { [empty_string_p $authority_id] } {
        # Pick the first authority that can create users
        set authority_id [db_string first_registering_authority {
            select authority_id
            from auth_authorities
            where register_p = 't'
            and sort_order = (select max(sort_order)
                              from auth_authorities
                              where register_p = 't'
                             )
        } -default ""]
        if { [empty_string_p $authority_id] } {
            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 {
            auth::registration::Register \
                -authority_id $authority_id \
                -username $user_name \
                -password $password \
                -first_names $first_names \
                -last_name $last_name \
                -email $email \
                -url $url \
                -secret_question $secret_question \
                -secret_answer $secret_answer
        }
    }
}

ad_proc -private auth::registration::Register {
    {-authority_id:required}
    {-username:required}
    {-password:required}
    {-first_names ""}
    {-last_name ""}
    {-email ""}
    {-url ""}
    {-secret_question ""}
    {-secret_answer ""}
} {
    Invoke the Register service contract operation for the given authority.
    @authority_id Id of the authority. Defaults to local authority.
    @url Any URL (homepage) associated with the new user
    @secret_question Question to ask on forgotten password
    @secret_answer Answer to forgotten password question
} {
    if { [empty_string_p $authority_id] } {
        set authority_id [auth::authority::local]
    }
    # TODO:
    # Implement parameters
    return [acs_sc::invoke \
                -contract "auth_registration" \
                -impl [auth::authority::get_element -authority_id $authority_id -element "auth_impl_name"] \
                -operation Register \
                -call_args [list [list] \
                                 $username \
                                 $authority_id \
                                 $first_names \
                                 $last_name \
                                 $email \
                                 $url \
                                 $password \
                                 $secret_question \
                                 $secret_answer]]
}

ad_form -name user_add -form {
    {authority_id:integer(hidden)}
    {username:text}
    {email:text}
    {password}
} -on_submit {
    if { [ad_parameter UsernameIsEmail] == 't' } {
       set email $username
    }
    array set auth_info [auth::authenticate \
        -authority_id $authority_id \
        -username $username \
        -password $password]
   # Handle authentication problems
   switch $auth_info(auth_status) {
        ok {
            # Continue below
        }
        bad_password {
        }
        no_account {
        }
        auth_error {
        }
        default {
        }
   }
   # TODO: form builder validation of auth_status
   # Handle account status
   switch $auth_info(account_status) {
       ok {
           # Continue below
       }
       default {
       }
   }
   # TODO: form builder validation of account_status
   # We're logged in
   ad_returnrediredt $return_url
   ad_script_abort
}

array set registratoin_info [auth::register \
    -authority_id $authority_id \
    -username $username \
    -password $password \
    -first_names $first_names \
    -last_name $last_name \
    -email $email \
    -url $url \
    -secret_question $secret_question \
    -secret_answer $secret_answer]
# Handle registration problems
switch $registratoin_info(reg_status) {
    ok {
        # Continue below
    }
    default {
    }
}
# User is registered and logged in
ad_returnrediredt $return_url

ad_proc -public auth::password::get_change_url {
    {-user_id:required}
} {
    Returns the URL to redirect to for changing passwords. If the
    user's authority has a "change_pwd_url" set, it'll return that,
    otherwise it'll return a link to /user/password-update under the
    nearest subsite.
    @param user_id The ID of the user whose password you want to change.
    @return A URL that can be linked to for changing password.
} -
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. 
    
    @param user_id The ID of the user whose password you want to change.
    @return 1 if the user can change password, 0 otherwise.
} {
    # Implementation note:
    # Calls auth::password::CanChangePassword(authority_id) for the user's authority.
}
ad_proc -public auth::password::change {
    {-user_id:required}
    {-old_password:required}
    {-new_password:required}
} {
    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>
       <li> password_status: "ok", "no_account", "old_password_bad",
       "new_password_bad", "error" </li>
       <li> password_message: A human-readable description of what
       went wrong. </li>
    </ul>
} {
    # Implementation note
    # Calls auth::password::ChangePassword(authority_id, username, old_password, new_password) for the user's authority.
}
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 retrive 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.
} {
    # Implementation note
    # Calls auth::password::CanRetrievePassword(authority_id) for the user's authority.
}
ad_proc -public auth::password::retrieve {
    {-user_id:required}
} {
    Retrieve the user's password.
    @param user_id      The ID of the user whose password you want to retrieve.
    @return An array list with the following entries:
    <ul>
       <li> password_status: "ok", "no_account", "not_implemented",
       "error" </li>
       <li> password_message: A human-readable description of what
       went wrong, if password_status is not "ok".  Not set if
       password_status is "ok". </li>
       <li> password: The retrieved password. </li>
    </ul>
} {
    # Implementation note
    # Calls auth::password::RetrievePassword(authority_id, username) for the user's authority.
}
ad_proc -public auth::password::can_reset_p {
    {-authority_id:required}
} {
    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.
} {
    # Implementation note
    # Calls auth::password::CanResetPassword(authority_id) for the user's authority.
}
ad_proc -public auth::password::reset {
    {-user_id:required}
} {
    Reset the user's password, which means setting it to a new
    randomly generated password and informing the user of that new
    password.
    @param user_id      The ID of the user whose password you want to reset.
    @return An array list with the following entries:
    <ul>
       <li> password_status: "ok", "no_account", "not_implemented",
       "error" </li>
       <li> password_message: A human-readable description of what
       went wrong, if password_status is not "ok".  Not set if
       password_status is "ok". </li>
       <li> password: The new, automatically generated password. If no
       password is included in the return array, that means the new
       password has already been sent to the user somehow. If it is
       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.
}

ad_proc -public auth::authority::enable_batch_sync {
  -authority_id
} {
 db_dml toggle_enbaled_p { 
     update some_table
     set    batch_sync_enabled_p = 't'
     where  authority_id = :authority_id
   }
}

ad_proc -public auth::batch_sync_sweeper {} {
   db_foreach select_authorities {
      select authority_id
      from   auth_authorities
      where  active_p = 't'
      and    batch_sync_enabled_p = 't'
   } {
      auth::authority::batch_sync -authority_id $authority_id
   }
}
ad_proc -public auth::authority::batch_sync {
   -authority_id
} {
   set driver [auth::get_driver -authority $authority]
   acs_sc::invoke $driver Synchronize -authority $authority
}

ad_proc -private auth::authentication::Authenticate {
    {-authority_id ""}
    {-username:required}
    {-password:required}
} {
    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 { [empty_string_p $authority_id] } {
        set authority_id [auth::authority::local]
    }
    # TODO:
    # Implement parameters
    return [acs_sc::invoke \
                -contract "auth_authentication" \
                -impl [auth::authority::get_element -authority_id $authority_id -element "auth_impl_name"] \
                -operation Authenticate \
                -call_args [list $username $password [list]]]
}

ad_proc -private auth::local::authentication::Authenticate {
    username
    password
    {parameters {}}
} {
    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 {
       if { [ad_parameter EmailForgottenPasswordP] == 't' } {
            set auth_info(auth_status) "bad_password"
            ... display link...
       } else {
            set auth_info(auth_status) "bad_password"
       } 
        return [array get auth_info]
    }
    # 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]
}

ad_proc -private auth::registration::Register {
    {-authority_id:required}
    {-username:required}
    {-password:required}
    {-first_names ""}
    {-last_name ""}
    {-email ""}
    {-url ""}
    {-secret_question ""}
    {-secret_answer ""}
    {-parameters ""}
} {
    Invoke the Register service contract operation for the given authority.
    
} {
    if { [empty_string_p $authority_id] } {
        set authority_id [auth::authority::local]
    }

    return [acs_sc::invoke \
                -contract "auth_registration" \
                -impl ??? \
                -operation Register \
                -call_args [list ???]]
}

ad_proc -private auth::local::registration::Register {
    parameters
    username
    authority_id
    first_names
    last_name
    email
    url
    password
    secret_question
    secret_answer
} {
    Implements the Register operation of the auth_register
    service contract for the local account implementation.
} {
    array set result {
        creation_status "reg_error"
        creation_message {}
        element_messages {}
        account_status "ok"
        account_message {}
    }
    # TODO: email = username
    # TODO: Add catch
    set user_id [ad_user_new \
                     $email \
                     $first_names \
                     $last_name \
                     $password \
                     $question \
                     $answer \
                     $url \
                     $email_verified_p \
                     $member_state \
                     "" \
                     $username \
                     $authority_id]
    if { !$user_id } {
        set result(creation_status) "fail"
        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)
    # TODO: double-click protection
    # Get whether they requre some sort of approval
    if { [parameter::get -parameter RegistrationRequiresApprovalP -default 0] } {
        set member_state "needs approval"
        set result(account_status) "closed"
        set result(account_message) [_ acs-subsite.lt_Your_registration_is_]
    } else {
        set member_state "approved"
    }
    set notification_address [parameter::get -parameter NewRegistrationEmailAddress -default [ad_system_owner]]
    if { [parameter::get -parameter RegistrationRequiresEmailVerificationP -default 0] } {
        set email_verified_p "f"
        set result(account_status) "closed"
        set result(account_message) "[_ acs-subsite.lt_Registration_informat_1][_ acs-subsite.lt_Please_read_and_follo]"
        set row_id [db_string rowid_for_email {
            select rowid from users where user_id = :user_id
        }]
        # Send email verification email to user
        set confirmation_url "[ad_url]/register/email-confirm?[export_vars { row_id }]"
        with_catch errmsg {
            ns_sendmail \
                $email \
                $notification_address \
                "[_ acs-subsite.lt_Welcome_to_system_nam]" \
                "[_ acs-subsite.lt_To_confirm_your_regis]"
        } {
            ns_returnerror "500" "$errmsg"
            ns_log Warning "Error sending email verification email to $email. Error: $errmsg"
        }
    } else {
        set email_verified_p "t"
    }
    # Send password/confirmail email to user
    if { [parameter::get -parameter RegistrationProvidesRandomPasswordP -default 0] || \
             [parameter::get -parameter EmailRegistrationConfirmationToUserP -default 0] } {
        with_catch errmsg {
            ns_sendmail \
                $email \
                $notification_address \
                "[_ acs-subsite.lt_Welcome_to_system_nam]" \
                "[_ acs-subsite.lt_Thank_you_for_visitin]"
        } {
            ns_returnerror "500" "$errmsg"
            ns_log Warning "Error sending registration confirmation to $email. Error: $errmsg"
        }
    }
    # Notify admin on new registration
    if {[ad_parameter NotifyAdminOfNewRegistrationsP "security" 0]} {
        with_catch errmsg {
            ns_sendmail \
                $notification_address \
                $email \
                "[_ acs-subsite.lt_New_registration_at_s]" \
                "[_ acs-subsite.lt_first_names_last_name]"
        } {
            ns_returnerror "500" "$errmsg"
            ns_log Warning "Error sending admin notification to $notification_address. Error: $errmsg"
        }
    }

    return [array get result]
}

Peter Marklund

Peter Marklund

auth::password::CanResetPassword .Input: driver Output: 1 or 0

auth::password::ResetPassword .Input: username, parameters.Output: successful_p: boolean, password (or blank, if the server sends the user its new password directly), message: To be relayed to the user.

auth::password::CanRetrievePassword .Input: driver Output: 1 or 0

auth::password::RetrievePassword .Input: usernameOutput: retrievable_p: boolean, message: Instruct the user what to do if not.

auth::password::CanChangePassword Input: driverOutput:True or false.

auth::password::ChangePassword Input: username, old_password, new_passwordOutput: new_password

set user_id [ad_conn]
set authority_id [auth::authority -user_id $user_id]
set driver [auth::get_driver -authority $authority]
set retrieve_password_p [auth::password::CanRetrievePassword -driver $driver]
set reset_password_p [auth::password::CanResetPassword -driver $driver]

"If you've forgotten your password, you can ask this server to reset your password and email a new randomly generated password to you ."

# Fetch the username. What proc should we use?
set username [auth::username]
# Reset password
auth::password::ResetPassword -username $username
set subject "[_ acs-subsite.lt_Your_forgotten_passwo]"
# SIMON: how does the password get inserted here?
# Should make use of auth::password::RetrievePassword
set body "[_ acs-subsite.lt_Please_follow_the_fol]"
# Send email
if [catch {ns_sendmail $email $system_owner $subject $body} errmsg] {
    ad_return_error \
        "[_ acs-subsite.Error_sending_mail]" \
        "[_ acs-subsite.lt_Now_were_really_in_tr]
<blockquote>
  <pre>
    $errmsg
  </pre>
</blockquote>
[_ acs-subsite.lt_when_trying_to_send_y]
<blockquote>
  <pre>
[_ acs-subsite.Subject] $subject
$body
  </pre>
</blockquote>
"
    return
}

Original estimate:

Hours spent:

Estimated hours remaining:

Risk:

Current login pages are over HTTP. Just bashing them to be HTTPS has these issues:

Beginning with a human being using a computer, describe how the feature is triggered and what it does. As this story becomes more detailed, move pieces to appropriate parts of the document.

Security, Reliability and robustness.

Parameters:

Original estimate: 8 hours.

Hours spent: 0.25

Estimated hours remaining:

Risk:

set user_id [ad_conn user_id]
set authority [auth::authority -user_id $user_id]
set driver [auth::get_driver -authority $authority]
set change_password_p [auth::password::CanChangePassword -driver $driver]

if {![db_0or1row select_email {}]} {
    db_release_unused_handles
    ad_return_error "[_ acs-subsite.lt_Couldnt_find_user_use]" "[_ acs-subsite.lt_Couldnt_find_user_use_1]"
    return
}
set system_owner [ad_system_owner]
set subject "some other i18n key msg"
set body "some other i18n key msg"
# Send email
if [catch {ns_sendmail $email $system_owner $subject $body} errmsg] {
    ad_return_error \
        "[_ acs-subsite.Error_sending_mail]" \
        "[_ acs-subsite.lt_Now_were_really_in_tr]
<blockquote>
  <pre>
    $errmsg
  </pre>
</blockquote>
[_ acs-subsite.lt_when_trying_to_send_y]
<blockquote>
  <pre>
[_ acs-subsite.Subject] $subject
$body
  </pre>
</blockquote>
"
    return
}

Original estimate:

Hours spent:

Estimated hours remaining:

Risk:

This has already been implemented on oacs-4-6 branch.

Original estimate: 6 hours.

Hours spent:

Estimated hours remaining:

Risk:

We keep a record of which authenticated users have requested pags on the site in the last x minutes (typically about 5), and thus are considered to be currently online. We've already made the changes necessary to security-procs.tcl to do this on an earlier project, but haven't quite finished the work and put it back into the tree.

Original estimate:

Hours spent:

Estimated hours remaining:

Risk:

NOTE: We'll need to keep a pretty close transaction log of any action taken during batch sync, and also offer a mechanism for storing transactions that couldn't be completed for some reason, e.g. email address already taken, etc., email the admin, offer a list of transactions that failed for manual resolution by an admin.

Performance criteria: Nightly batch run should be able to complete within 3 hours with 10,000 users.

We'll want to design an API for an incremental or snapshot run to call, which takes care of all the updating, logging, error handling, emailing admins, etc.

We need examples of how the communication would be done from our clients.

We might need a source/ID column in the users table to identify where they're imported from for doing updates, particularly if importing from multiple sources (or when some users are local.)

None.

This is executed in background thread, typically nightly.

There's also a link from the authority administration page to run the batch synchronization immediately.

The process runs like this:

The design should favor interoperability, reliability and robustness.

NOTE: Do we really want to do this as service contracts? We might be better off getting one implementation running, and only do the service contract when we're certain what it would look like.

TODO: Look at how Blackboard and other systems implements this, specifically how do they get the data out of the other system. Which enterprise servers already support the IMS Enterprise specification?

TODO: Find out if Greenpeace needs an different exchange format from IMS Enterprise, given that they're not in the University business.

Service contract for retrieving the document:

    GetDocument ( 
        type:       0 = snapshot
                    1 = incremental
        since:      date that you want the incremental update since?
        parameters: values of implementation-specific parameters
    ): document as string
        Performs the request necessary to get a document containing
        enterprise information.
    GetParameters (
    ): list of parameters specific to this implementation.
        Parameters would typically be the URL to make a request to.

Service contract for processing the document:

    ProcessDocument ( 
        type:       0 = snapshot
                    1 = incremental
        since:      date that you want the incremental update since?
        document:   the document containing either incremental or snapshot of enterprise data.
        parameters: values of implementation-specific parameters
    ): document as string
        Processes the document and updates the OpenACS users and other tables appropriately.
    GetParameters (
    ): list of parameters specific to this implementation.
        Not sure what parameters would be.

It looks like we'll use the IMS standard for formatting of the doucment, but not so

For features with UI, a map of all pages, showing which pages can call others, which are includeable, etc. For each page, show all UI elements on the page (text blocks, forms, form controls). Include administration functionality.

Here goes:

ad_proc -public auth::authority::new {
      {-authority_id:required}
      {-short_name:required}
      {-pretty_name:required}
      {-sort_order:required}
      {-auth_impl_id:required}
      {-auth_p:required}
      {-pwd_impl_id:required}
      {-forgotten_pwd_url:required}
      {-change_pwd_url:required}
      {-register_impl_id:required}
      {-register_p:required}
      {-register_url:required}
} {
   db_dml new_authority {
      insert into auth_authorities (
        authority_id,
        short_name,
        pretty_name,
        active_p,
        sort_order,
        auth_impl_id,
        auth_p,
        pwd_impl_id,
        forgotten_pwd_url,
        change_pwd_url,
        register_impl_id,
        register_p,
        register_url
      ) values (
        :authority_id,
        :short_name,
        :pretty_name,
        1,
        :sort_order,
        :auth_impl_id,
        :auth_p,
        :pwd_impl_id,
        :forgotten_pwd_url,
        :change_pwd_url,
        :register_impl_id,
        :register_p,
        :register_url
      )
   }
}
ad_proc -public auth::authority::delete {
  {-authority_id:requied}
} {
   db_exec delete_authority {
      delete from auth_authorities 
      where authority_id = :authority_id
   }
}
ad_proc -public auth::authority::edit {
      {-authority_id:required}
      {-short_name:required}
      {-pretty_name:required}
      {-active_p:required}
      {-sort_order:required}
      {-auth_impl_id:required}
      {-auth_p:required}
      {-pwd_impl_id:required}
      {-forgotten_pwd_url:required}
      {-change_pwd_url:required}
      {-register_impl_id:required}
      {-register_p:required}
      {-register_url:required}
} {
   db_exec edit_authority {
      update auth_authorities 
      set    short_name = :short_name,
             pretty_name = :pretty_name,
             active_p = :active_p,
             sort_order = :sort_order,
             auth_impl_id = :auth_impl_id,
             auth_p = :auth_p,
             pwd_impl_id = :pwd_impl_id,
             forgotten_pwd_url = :forgotten_pwd_url,
             change_pwd_url = :change_pwd_url,
             register_impl_id = :register_impl_id,
             register_p = :register_p,
             register_url = :register_url
      where  authority_id = :authority_id
   }
}

Original estimate:

Hours spent:

Estimated hours remaining:

Risk:

When the administrator configures an authority to use a specific service contract implementation, e.g. PAM, that implementation can say which parameters it supports, e.g. Host, Port, Root node, etc.

The administrator will specify values for these parameters as part of configuring the authority.

These parameter values will be passed along to the service contract implementation when its methods get called.

Flexibility, usability.

We're considering whether to implement a very simple solution a' la current package parameters, or a general configuration solution as outlined in the Configurator Spec .

Simple solution: A table with key/value pairs attached to the auth_authorities table.

Original estimate, simple solution: 8 hours

Original estimate, complex solution: 50 hours

Hours spent:

Estimated hours remaining:

Risk:

Describe how any functionality to be replaced works.

Beginning with a human being using a computer, describe how the feature is triggered and what it does. As this story becomes more detailed, move pieces to appropriate parts of the document.

Which one or two of the following are emphasised in this design?

For a feature with a public API, write the stub for each procedure, showing all parameters, a preliminary description of instructions, and expected return.

For a feature without a public API, describe how the feature is invoked.

Include admin-configurable parameters.

For features with UI, a map of all pages, showing which pages can call others, which are includeable, etc. For each page, show all UI elements on the page (text blocks, forms, form controls). Include administration functionality.

Describe key algorithms, including pseudo-code.

Describe data model changes.

What error codes or error conditions could result? How are they handled?

Describe in pseudo-code how upgrade will be implemented.

Original estimate:

Hours spent:

Estimated hours remaining:

Risk: