Plugins, Hooks, & External Modules
Developer methods for
Plugins, Hooks, & External Modules
Hook functions
REDCap Developer Tools:
Documentation for Plugins, Hooks, & External Modules
REDCap Version 14.9.1
redcap_custom_verify_username
(REDCap >= 5.8.0)
redcap_custom_verify_username
— Allows custom actions to be performed and (optional) custom messaging to user when someone attempts to grant a user access to a REDCap project on the User Rights page (to be used for external authentication methods only)
Description
array redcap_custom_verify_username ( string $username )
Allows custom actions to be performed and (optional) custom messaging to user when someone attempts to grant a user access to a REDCap project on the User Rights page (to be used for external authentication methods only). If using external authentication (e.g., LDAP, Shibboleth), this function provides the option to verify whether a username is valid in the external authentication system before that username can be granted access to a project on the User Rights page. This function is called when adding a user with custom rights or when assigning a new user to a role. Example use case: If using LDAP authentication, you may have the function connect and bind to your LDAP server and then search your LDAP directory to validate the username so that only valid LDAP users can be given access to the project.
Location of Execution
The function is executed on a project's User Rights page when someone attempts to add a user to the project whenever they click either the 'Add with custom rights' button or 'Assign to role' button.
Parameters
username
The username of the REDCap user when the function gets executed.
The username of the REDCap user when the function gets executed.
Return Values
Your function should return an associative array with two elements: 'status' (either TRUE or FALSE) and 'message' (text that you wish to be displayed on the page). If 'message' is blank/null, then it will do nothing. If a 'message' value is returned, then it will output the text to the page inside a red box. If 'status' is FALSE, then it will display the message and stop processing (i.e., the user will NOT be granted access to the project), but if 'status' is TRUE, then it will display the message but will allow the user to be granted access.
Examples
Example #1:
This example returns an error because the username is NOT valid.
function redcap_custom_verify_username($username) {
...
// Perform logic to verify if username is valid, and determines that it is not.
...
return array('status'=>FALSE, 'message'=>'ERROR: User $username is not a valid username!');
}
Example #2:
This example does not return an error because the username IS valid.
function redcap_custom_verify_username($username) {
...
// Perform logic to verify if username is valid, and determines that it is.
...
return array('status'=>TRUE, 'message'=>'');
}
Example #3:
This example determines that the username IS valid but displays a custom message to the user.
function redcap_custom_verify_username($username) {
...
// Perform logic to verify if username is valid, and determines that it is.
...
return array('status'=>TRUE, 'message'=>'Although this user is valid, please be sure
to [DO WHATEVER] before adding them to the project.');
}
REDCap 14.9.1 - © 2024 Vanderbilt University