NAME
Concierge::Auth::Base - Base class / contract for Concierge::Auth backends
VERSION
v0.5.0
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 checkID/setPwd/resetPwd/deleteID/checkPwd methods, 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 whatever object ends up as $concierge->{auth} for identifier generation that has nothing to do with authentication: visitors and guests (see admit_visitor/checkin_guest in Concierge) are never authenticated -- 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, and the deprecated aliases gen_token/gen_crypt_token) 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
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