IX::ARM - easy client calls to the IX Application Rights Manager web service
use IX::ARM; my $arm = new IX::ARM;
ARM.pm uses Frontier::Client, which depends on expat. You may need to install these on your system. It also now requires HTML::Template in order to user $arm->protect() with the IX:: web framework.
ARM.pm provides application rights management (user/group) and external user (non-IX) authentication services over XML-RPC for application developers.
All RPC client calls return the following values from the ARM server response:
$arm->return_code() # 0 for failure or 1 for success
$arm->message() # an English response from the server
authenticate_guest()Verify the username and password of a IX Guest Account user. Given a maximum acceptable password age in days, $arm->password_expired will then return a '0' if the password has been reset recently enough or a '1' if the user should be prompted to reset.
$arm->authenticate_guest($username, $password, $max_password_age);
print "authenticated: " . $arm->authenticated . "\n";
print "password expired: " . $arm->password_expired . "\n";
delete_account()Delete an account and all associated permissions and group memberships. The calling application must have 'may_delete_accounts' permission within ARM itself.
$arm->delete_account($username);
does_user_exist()Check if the user is known in the ARM database.
$arm->does_user_exist($username);
print "user_id: " . $arm->user_id . "\n";
If the username is not found in ARM, $arm->user_id will return an empty string, otherwise it will return the numerical id assigned to that username by ARM.
find_users()Given a search string, returns a list of users from ARM whose first name, last name, or username matches the string.
$arm->find_users($search_string);
print "users found: ";
if ($arm->return_code) {
my $users_ref = $arm->users;
my @users = @$users_ref;
foreach my $user_hash_ref (@users) {
my $first_name = $user_hash_ref->{first_name};
my $last_name = $user_hash_ref->{last_name};
my $username = $user_hash_ref->{username};
}
}
get_permission()Ask ARM if a user has been granted a given permission code for a given application.
$arm->get_permission($application_id, $username, $permission_code);
print "has_permission: " . $arm->has_permission . "\n";
get_contact_info()Retrieve the name and contact information for a user from ARM. Additionally, if provided a $contact_data_prompt_interval in months, $arm->time_to_update() will then return a '0' if the information is considered fresh enough, and a '1' if it is time to prompt the user to update her data.
$arm->get_contact_info($username, $contact_data_prompt_interval);
print "first_name: " . $arm->first_name . "\n";
print "last_name: " . $arm->last_name . "\n";
print "email: " . $arm->email . "\n";
print "phone: " . $arm->phone . "\n";
print "street: " . $arm->street . "\n";
print "city: " . $arm->city . "\n";
print "state: " . $arm->state . "\n";
print "zip: " . $arm->zip . "\n";
print "time_to_update: " . $arm->time_to_update . "\n";
load_perms()Load all permission codes granted to a given user, including those inherited via ARM group membership.
$arm->load_perms($application_id, $username);
# display permissions granted for this app, for this user
my $granted_ref = $arm->granted();
my %granted = %$granted_ref;
print "permission codes granted: ";
while (my ($name, $value) = each %granted) {
print "$name, ";
}
Once this method has been invoked, you can use $arm->protect() (see below) as shorthand to secure sections of your code.
register_account()Create a new user account in ARM, with a password.
$arm->register_account($username, $password);
print "user_id: " . $arm->user_id . "\n";
reset_password()Replace a user's password with a new password.
$arm->reset_password($username, $password);
save_contact_info()Save basic information about a new or returning user.
$arm->save_contact_info(
$first_name,
$last_name,
$email,
$phone,
$street,
$city,
$state,
$zip,
$username,
);
loadDataSource() and setAppToken()Designate the ARM data source you want to connect to, and announce what application is connecting by providing your application token.
Both loadDataSource() and setAppToken() are called during the BEGIN phase of execution, but they may also be invoked at any time by your program to change your ARM environment.
You may provide the ARM data source like this:
IX::ARM::loadDataSource('https://[hostname]/apps/arm_server');
If you do not provide a data source, it will set it to $IX::Conf::x{ARM_service_url} if you are using the IX:: Perl framework.
You may provide the ARM application token for your client application like this:
IX::ARM::setAppToken($your_app_token);
If you do not provide the application token directly, it will attempt to set it to $IX::Conf::x{ARM_app_token} if you are using the IX:: Perl framework.
protect() and permissionDeniedInterface()Use $arm->protect() to secure subroutines quickly. Once load_perms() has been invoked (see above), you can simply provide required the permission code to be checked against the user's %granted table:
$arm->protect('ADMIN');
permissionDeniedInterface() is called to present a denial page if necessary. You may also call permissionDeniedInterface() yourself with a couple acceptable arguments:
IX::ARM::permissionDeniedInterface('denied');
IX::ARM::permissionDeniedInterface('error');
Written and maintained by Marcus Del Greco (marcus@mindmined.com) with technical guidance from Bill Costa.