/ 
CatalystX-Usul-0.16.1
/ CatalystX::Usul::Users

Name

CatalystX::Usul::Users - User domain model

Version

Describes v0.16.$Rev: 1 $

Synopsis

package CatalystX::Usul::Users::DBIC;

extends CatalystX::Usul::Users;

Description

Implements the base class for user objects. Each subclass that inherits from this should implement the required list of methods

Configuration and Environment

Defines the following attributes

alias_class

A loadable class which defaults to File::MailAlias

aliases

An instance of the alias_class attribute

cache

A hash ref that caches CatalystX::Usul::Response::Users objects

def_passwd

Default password string which defaults *DISABLED*

load_factor

Integer which defaults to 14. Used by Crypt::Eksblowfish::Bcrypt to determine how expensive the key distribution algorithm should be

locale

The language used to localize text, defaults to en_GB

max_login_trys

Maximum number of login attempts before an account is disabled. An integer that defaults to 3

max_pass_hist

Maximum number of previous password to store thereby preventing reuse. An integer that defaults to 10

min_name_len

Minimum combined length of the users first and last names. Used to create the account name. An integer that defaults to 6

passwd_type

Default encryption algorithm to use when encrypting passwords. A string that defaults to Blowfish

profile_class

A loadable class which defaults to CatalystX::Usul::UserProfiles

profiles

An instance of the profile_class

role_cache

A hash ref that caches CatalystX::Usul::Role objects

role_class

A required loadable class which defaults to Class::Null

roles

An instance of the role_class

sessdir

Path to the directory containing the user password history files and the count of failed login attempts. Location of used user passwords and account activation keys

user_pattern

The default pattern used to filter user accounts. A string that defaults to \A [a-zA-Z0-9]+

userid_len

The length of the generated user id, without the prefix. An integer that defaults to 3

Subroutines/Methods

activate_account

Activation is not currently supported by the base user store

authenticate

$user_obj = $self->authenticate( $test_for_expired, $username, $password );

Called by the check_password method in the user response class. If the $test_for_expired flag is true then the accounts password must not have expired or an exception will be thrown. The supplied password is encrypted and compared to the one in storage. Failures are counted and when max_login_trys are exceeded the account is disabled. Errors can be thrown for; unknown user, inactive account, expired password, maximum attempts exceeded and incorrect password

change_password

$self->change_password( $username, $old, $new, $encrypted );

Proxies a call to update_password which must be implemented by the subclass. Requires the user to authenticate

dequeue_activation_file

$username = $self->dequeue_activation_file( $file );

Reads and deletes the supplied activation file. Returns the username

disable_account

$self->disable_account( $user );

Calls update_password in the subclass to set the users encrypted password to *DISABLED* thereby preventing the user from logging in

encrypt_password

$enc_pass = $self->encrypt_password( $force, $username, $old, $new, $encrypted );

Encrypts the new password and returns it. If the encrypted flag is true then new is assumed to be already encrypted and is returned unchanged. The old password is used to authenticate the user unless the force flag is true

find_user

$user_obj = $self->find_user( $username, [ $verbose ] );

This method is required by the Catalyst::Authentication::Store API. It returns a user object (obtained by calling "get_user") even if the user is unknown. If the user is known a list of roles that the user belongs to is also returned. Adds a weakened reference to self so that Catalyst::Authentication can call the check_password method on the response class. If the $verbose flag is true will load additional information about the user, e.g. their .project

get_new_user_id

$user_id = $self->get_new_user_id( $first_name, $last_name, [ $prefix ] );

Implements the algorithm that derives the username from the users first name and last name. The supplied prefix from the user profile is prepended to the generated value. If the prefix contains unique domain information then the generated username will be globally unique to the organisation

get_primary_rid

$role_id = $self->get_primary_rid( $username );

Placeholder methods returns undef. May be overridden in a subclass

get_security_data

$user_security_ref = $self->get_security_data( $username, $password_type );

Returns a hash ref of security data about the requested user.

get_user

$user_obj = $self->get_user( $username, [ $verbose ] );

Returns a user object for the given user id. If the user does not exist then a user object with a name of unknown is returned. If the $verbose flag is true will load additional information about the user, e.g. their .project

get_user_data

$user_data_ref = $self->get_user_data( \%options, $username );

Returns a hash ref of data about the requested user. Includes the fields from "find_user" plus profile data

get_users_by_rid

@user_list = $self->get_users_by_rid( $role_id );

Placeholder methods returns an empty list. May be overridden in a subclass

invalidate_cache

$self->invalidate_cache;

Marks the user and role caches as invalid thereby forcing a reload

invalidate_user_cache

$self->invalidate_user_cache;

Marks the user cache as invalid thereby forcing a reload

is_user

$bool = $self->is_user( $username );

Returns true if the given user exists, false otherwise

list

$user_list = $self->list( [ $pattern ] );

Returns an array ref of all users whose ids match the optional pattern

loc

$localised_text = $self->loc( $key, @args );

Return text localised to a given language

register

$list_of_list_of_localisable_messages = $self->register( $args, $fields );

Create a new self registered user

register_authorisation

@localisable_message = $self->register_authorisation( $fields );

Write the user data fields to disk and await authorisation before creating the new user

set_password

$self->set_password( $username, $new, $encrypted );

Proxies a call to update_password which must be implemented by the subclass. Does not require user authentication

supports

$bool = $self->supports( @spec );

Returns true if the hash returned by our get_features attribute contains all the elements of the required specification

user_attributes

@attribute_list = $self->user_attributes

Class methods returns the list of attributes supported by the CatalystX::Usul::Response::Users response object

validate_password

$bool = $self->validate_password( $username, $password );

Wraps a call to "authenticate" in a try block so that a failure to validate the password returns false rather than throwing an exception

Diagnostics

None

Dependencies

CatalystX::Usul::Constraints
CatalystX::Usul::Response::Users
CatalystX::Usul::Shells
CatalystX::Usul::Moose
Class::Usul::File
Class::Usul::IPC
Crypt::Eksblowfish::Bcrypt
TryCatch

Incompatibilities

There are no known incompatibilities in this module

Bugs and Limitations

There are no known bugs in this module. Please report problems to the address below. Patches are welcome

Author

Peter Flanigan, <Support at RoxSoft.co.uk>

Acknowledgements

Larry Wall - For the Perl programming language

License and Copyright

Copyright (c) 2014 Peter Flanigan. All rights reserved

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic

This program is distributed in the hope that it will be useful, but WITHOUT WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE