• Publicity: Public Only All

password-procs.tcl

Tcl API for password management.

Location:
packages/acs-authentication/tcl/password-procs.tcl
Created:
2003-09-03
Author:
Lars Pind <lars@collaobraid.biz>
CVS Identification:
$Id: password-procs.tcl,v 1.26.2.2 2021/04/08 16:18:58 antoniop Exp $

Procedures in this file

Detailed information

auth::password::can_change_p (public)

 auth::password::can_change_p -user_id user_id

Returns whether we can change the password for the given user. This depends on the user's authority and the configuration of that authority.

Switches:
-user_id (required)
The ID of the user whose password you want to change.
Returns:
1 if the user can change password, 0 otherwise.

Testcases:
auth_password_can_change_reset_retrieve_p

auth::password::can_reset_p (public)

 auth::password::can_reset_p -authority_id authority_id

Returns whether the given authority can reset forgotten passwords.

Switches:
-authority_id (required)
The ID of the authority that the user is trying to log into.
Returns:
1 if the authority allows resetting passwords, 0 otherwise.

Testcases:
auth_password_can_change_reset_retrieve_p

auth::password::can_retrieve_p (public)

 auth::password::can_retrieve_p -authority_id authority_id

Returns whether the given authority can retrieve forgotten passwords.

Switches:
-authority_id (required)
The ID of the authority that the user is trying to log into.
Returns:
1 if the authority allows retrieving passwords, 0 otherwise.

Testcases:
auth_password_can_change_reset_retrieve_p

auth::password::change (public)

 auth::password::change -user_id user_id -old_password old_password \
    -new_password new_password

Change the user's password.

Switches:
-user_id (required)
The ID of the user whose password you want to change.
-old_password (required)
The current password of that user. This is required for security purposes.
-new_password (required)
The desired new password of the user.
Returns:
An array list with the following entries:
  • password_status: "ok", "no_account", "not_supported", "old_password_bad", "new_password_bad", "change_error", "failed_to_connect"
  • password_message: A human-readable description of what went wrong.

Testcases:
auth_password_change, auth_email_on_password_change

auth::password::get_change_url (public)

 auth::password::get_change_url -user_id user_id

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.

Switches:
-user_id (required)
The ID of the user whose password you want to change.
Returns:
A URL that can be linked to for changing password.

Testcases:
auth_password_get_change_url

auth::password::get_forgotten_url (public)

 auth::password::get_forgotten_url [ -authority_id authority_id ] \
    [ -username username ] [ -email email ] [ -remote_only ]

Returns the URL to redirect to for forgotten passwords.

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)
-remote_only (optional, boolean)
If provided, only return any remote URL (not on this server).
Returns:
A URL that can be linked to when the user has forgotten his/her password, or the empty string if none can be found.

Testcases:
auth_password_get_forgotten_url

auth::password::recover_password (public)

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

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

auth::password::reset (public)

 auth::password::reset [ -admin ] -authority_id authority_id \
    -username username

Reset the user's password, which means setting it to a new randomly generated password and inform the user of that new password.

Switches:
-admin (optional, boolean)
Specify this flag if this call represents an admin changing a user's password.
-authority_id (required)
The authority of the user
-username (required)
The username of the user
Returns:
An array list with the following entries:
  • password_status: ok, no_account, not_supported, reset_error, failed_to_connect
  • password_message: A human-readable message to be relayed to the user. May be empty if password_status is ok. May include HTML. Could be empty if password_status is ok.
  • 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.

Testcases:
auth_password_reset

auth::password::retrieve (public)

 auth::password::retrieve -authority_id authority_id -username username

Retrieve the user's password.

Switches:
-authority_id (required)
The ID of the authority that the user is trying to log into.
-username (required)
The username that the user's trying to log in with.
Returns:
An array list with the following entries:
  • password_status: ok, no_account, not_supported, retrieve_error, failed_to_connect
  • password_message: A human-readable message to be relayed to the user. May be empty if password_status is ok. May include HTML.
  • password: The retrieved password.

Testcases:
auth_password_retrieve
[ show source ]