auth::password::recover_password (public)

 auth::password::recover_password [ -authority_id authority_id ] \
    [ -username username ] [ -email email ]

Defined in packages/acs-authentication/tcl/password-procs.tcl

Handles forgotten passwords. Attempts to retrieve a password; if not possible, attempts to reset a password. If it succeeds, it emails the user. For all outcomes, it returns a message to be displayed.

Switches:

-authority_id (optional)

The ID of the authority that the user is trying to log into.

-username (optional)

The username that the user's trying to log in with.

-email (optional)

Email can be supplied instead of authority_id and username.

Returns:

Array list with the following entries:

• password_status: ok, no_support, failed_to_connect
• password_message: Human-readable message to be relayed to the user. May contain HTML.

Testcases:

auth_password_recover

Source code:

    if { $username eq "" } {
        if { $email eq "" } {
            set result(password_status) "failed_to_connect"
            if { [auth::UseEmailForLoginP] } {
                set result(password_message) "Email required"
            } else {
                set result(password_message) "Username required"
            }
            return [array get result]
        }
        set user_id [party::get_by_email -email $email]
        if { $user_id eq "" } {
            set result(password_status) "failed_to_connect"
            set result(password_message) "Unknown email"
            return [array get result]
        }
        set user [acs_user::get_user_info -user_id $user_id]
        set authority_id [dict get $user authority_id]
        set username     [dict get $user username]
    } else {
        # Default to local authority
        if { $authority_id eq "" } {
            set authority_id [auth::authority::local]
        }
    }

    set forgotten_url [auth::password::get_forgotten_url  -remote_only  -authority_id $authority_id  -username $username]

    if { $forgotten_url ne "" } {
        ad_returnredirect -allow_complete_url $forgotten_url
        ad_script_abort
    }

    if { [auth::password::can_retrieve_p -authority_id $authority_id] } {
        array set result [auth::password::retrieve  -authority_id $authority_id  -username $username]
    } elseif { [auth::password::can_reset_p -authority_id $authority_id] } {
        array set result [auth::password::reset  -authority_id $authority_id  -username $username]
    } else {
        # Can't reset or retrieve - we give up
        set result(password_status) "not_supported"
        set result(password_message) [_ acs-subsite.sorry_forgotten_pwd]
    }

    return [array get result]

XQL Not present:

Generic, PostgreSQL, Oracle