NAME
Concierge::Auth::Base - Base class / contract for Concierge::Auth backends
VERSION
v0.5.2
SYNOPSIS
# This is a base class - do not use directly
# Backend implementations inherit from this class:
package Concierge::Auth::MyBackend;
use parent 'Concierge::Auth::Base';
sub authenticate {
my ($self, $user_id, $credential) = @_;
# Implementation...
}
# Implement other required methods...DESCRIPTION
Concierge::Auth::Base defines the interface that every Concierge::Auth backend must implement, regardless of how it stores or verifies identity. Backend implementations (Concierge::Auth::Pwd for the built-in password-file backend, or alternatives such as an LDAP-backed backend) inherit from this class and must implement the five methods below.
The contract is deliberately expressed at the level of the domain operations Concierge itself needs to perform -- "add a user," "change credentials," "is this ID known," "authenticate" -- rather than at the level of any one backend's natural storage primitives. The built-in password-file backend, for example, satisfies this contract internally using its own file-locking, hashing, and response-formatting helpers, but those are private implementation detail of that backend and are not part of this contract. A backend with a fundamentally different storage/verification model (e.g. an LDAP directory) satisfies the same five methods however fits its model, without needing anything resembling those primitives at all.
Concierge::Auth backends are intentionally independent of Concierge::Users and of the main Concierge orchestrator. No method in this contract receives a Concierge or Users handle, and no conforming backend should reach into either. Concierge is responsible for composing calls to Auth and Users as separate steps; a backend that needs data from outside its own store should receive it as an argument to the relevant method, not via a persistent back-reference.
Users typically do not interact with this class directly - they use Concierge::Auth (or a Concierge desk) which manages the configured backend object internally.
The Generators Guarantee
Concierge also relies on its configured authentication class's object to generate identifiers for other uses not connected to authentication. For example, applications might not authenticate visitors or guests (see admit_visitor/checkin_guest in Concierge) -- they are simply assigned a generated identifier for cookie/session purposes, with no credential involved at all. That capability (gen_uuid, gen_random_id, gen_random_token, gen_random_string, gen_word_phrase) is therefore independent of the five-method contract above.
Unlike the five required methods, this guarantee is satisfied with a working default rather than a die-stub: Concierge::Auth::Base itself implements each of these methods by delegating to the plain functions of the same name in Concierge::Auth::Generators. Every backend that inherits from this class -- including Concierge::Auth::Pwd -- gets them for free and does not need to implement or compose anything to satisfy this guarantee. A backend is still free to override any one (or all) of these methods with its own logic (for example, an LDAP backend that wants directory-issued identifiers instead of locally-generated ones); Perl's normal method resolution means an override in the subclass simply takes precedence over the default here.
REQUIRED METHODS
Backend implementations must implement the following methods.
new
my $backend = Concierge::Auth::MyBackend->new(%args);Constructor. %args is backend-specific (e.g. a password-file path for Concierge::Auth::Pwd, or a directory URI/bind DN for an LDAP backend).
authenticate
my $result = $backend->authenticate($user_id, $credential);Verifies that $credential is valid for $user_id. This is a pure credential check with no side effects -- session creation and any other orchestration remain the responsibility of Concierge.
Must return:
{ success => 1 }Or on failure:
{ success => 0, message => "Error description" }is_id_known
my $result = $backend->is_id_known($user_id);Checks whether $user_id is a known identity to this backend's authority (e.g. present in the password file, or resolvable in the LDAP directory). This answers "known to the credential authority," not "known to the application" -- Concierge composes this with Concierge::Users separately if it needs the broader answer.
Must return:
{ success => 1, known => 1|0 }enroll
my $result = $backend->enroll($user_id, $credential, \%opts);Establishes $user_id as a known identity with the given credential. %opts is backend-specific and optional. For a backend where identities are provisioned externally (e.g. LDAP accounts managed by directory admins), this may mean confirming the ID already exists in the external authority rather than creating anything locally; the status key distinguishes the two cases so Concierge can decide whether any additional orchestration (e.g. also creating a Users profile record) is needed.
Must return:
{ success => 1, user_id => $user_id, status => 'created' }
# or, for backends where enrollment is external:
{ success => 1, user_id => $user_id, status => 'already_known' }Or on failure:
{ success => 0, message => "Error description" }change_credentials
my $result = $backend->change_credentials($user_id, $new_credential);Replaces the credential on file for an existing $user_id. Fails if the ID is not known to this backend.
Must return:
{ success => 1, user_id => $user_id }Or on failure:
{ success => 0, message => "Error description" }revoke
my $result = $backend->revoke($user_id);Removes $user_id as a known identity from this backend. Symmetric with "enroll". For backends where identities are provisioned externally, this may mean severing the local association rather than deleting anything in the external authority; the same status convention as "enroll" may be used to distinguish these cases if useful to callers.
Must return:
{ success => 1, user_id => $user_id }Or on failure:
{ success => 0, message => "Error description" }GENERATOR METHODS
Backend implementations inherit working defaults for the following methods and are not required to override them -- see "The Generators Guarantee" above. Each delegates to the identically-named function in Concierge::Auth::Generators and preserves its wantarray (value)/(value, message) dual-return convention, which is distinct from the { success => ... } hashref convention used by the five required methods above.
gen_uuid, gen_random_id, gen_random_token, gen_random_string, gen_word_phrase
See the identically-named functions in Concierge::Auth::Generators for each one's signature and behavior.
gen_token
Deprecated alias for gen_random_token.
gen_crypt_token
Deprecated alias for gen_random_token.
See Concierge::Auth::Generators for the parameters and return value of each.
SEE ALSO
Concierge::Auth::Pwd - built-in password-file backend implementation
Concierge::Auth::Generators - functional interface this class's default generator methods delegate to
Concierge::Auth - Auth manager / facade
Concierge::Sessions::Base - the analogous contract for session storage backends, which this module is modeled on
Concierge - main orchestrator; see its EXTENSIBILITY section for the component substitution pattern
AUTHOR
Bruce Van Allen <bva@cruzio.com>
LICENSE
Artistic License 2.0