BasicAuth
extends Auth
in package
Defines an Auth class that allows for Basic authentication against the pfSense local user database.
Table of Contents
Constants
- WWW_AUTHENTICATE_HEADER = 'WWW-Authenticate: Basic realm="Login for pfSense REST API"'
Properties
- $client_privileges : array<string|int, mixed>
- $ip_address : string
- $is_authenticated : bool
- $is_authorized : bool
- $required_privileges : array<string|int, mixed>
- $security_scheme : array<string|int, mixed>
- $username : string|null
- $verbose_name : string|null
- $api_settings : array<string|int, mixed>
Methods
- __construct() : mixed
- Creates an Auth object which can be used to authenticate an external client requesting API access.
- _authenticate() : bool
- Obtains the submitted username and password from the client using Basic authentication and performs authentication against the pfSense local user database.
- attempt_multi_auth() : Auth
- Attempts authentication for each allowed Auth class. Authentication AND authorization must pass using at least one of the allowed Auth classes for authentication to be considered successful. In the event that all Auth class methods fail, an error will be thrown detailing the failure.
- authenticate() : bool
- Perform authentication using the current authentication method.
- authorize() : bool
- Checks if the client is authorized to make this request.
- ensure_class_exists() : void
- Throws an error if a given Auth class shortname is not an Auth child class in the \RESTAPI\Auth\ namespace.
- get_auth_key() : string
- Obtains the key with a specified identifier (i.e. bearer) from the client via the authorization header.
- get_class_fqn() : string
- Obtains the fully qualified name of the called class.
- get_class_shortname() : string
- Obtains the shortname of the called class.
- get_classes_in_namespace() : array<string|int, mixed>
- Obtains all classes associated with this class's current namespace.
- is_requested() : bool
- Checks if the remote client is requesting BasicAuth by checking for the necessary headers.
- is_user_enabled() : bool
- Checks if a given username is an existing user that is not disabled
- log_error() : void
- Logs an error to the syslog.
- on_failed_auth() : void
- When basic authentication fails, set the WWW-Authenticate to request basic authentication.
- on_successful_auth() : void
- Provides additional logic whenever authentication is successful. This is intended to be overridden by a child Auth class when it needs something specific to happen after a client successfully authenticates.
- log_authentication() : void
- Logs API authentication according to the current API configuration.
Constants
WWW_AUTHENTICATE_HEADER
public
mixed
WWW_AUTHENTICATE_HEADER
= 'WWW-Authenticate: Basic realm="Login for pfSense REST API"'
Properties
$client_privileges
public
array<string|int, mixed>
$client_privileges
= []
The list of privileges the remote client currently has assigned.
$ip_address
public
string
$ip_address
= ''
The IP address of the remote client.
$is_authenticated
public
bool
$is_authenticated
= false
Indicates whether the remote client is currently authenticated.
$is_authorized
public
bool
$is_authorized
= false
$required_privileges
public
array<string|int, mixed>
$required_privileges
The list of privileges that allow authorization.
$security_scheme
public
array<string|int, mixed>
$security_scheme
= ['type' => 'http', 'scheme' => 'basic']
The OpenAPI security scheme for this Auth class.
$username
public
string|null
$username
= null
The username of the authenticated remote client.
$verbose_name
public
string|null
$verbose_name
= 'Local database'
The human-readable name for this Auth class.
$api_settings
private
array<string|int, mixed>
$api_settings
The current REST API settings config. This contains the settings internal values.
Methods
__construct()
Creates an Auth object which can be used to authenticate an external client requesting API access.
public
__construct([array<string|int, mixed> $required_privileges = [] ]) : mixed
Parameters
- $required_privileges : array<string|int, mixed> = []
-
An array of required pfSense privileges to check during authorization.
_authenticate()
Obtains the submitted username and password from the client using Basic authentication and performs authentication against the pfSense local user database.
public
_authenticate() : bool
Tags
Return values
bool —Returns true if basic auth is successful, return false otherwise
attempt_multi_auth()
Attempts authentication for each allowed Auth class. Authentication AND authorization must pass using at least one of the allowed Auth classes for authentication to be considered successful. In the event that all Auth class methods fail, an error will be thrown detailing the failure.
public
final static attempt_multi_auth([array<string|int, mixed> $auth_classes = [] ][, array<string|int, mixed> $required_privileges = [] ]) : Auth
Parameters
- $auth_classes : array<string|int, mixed> = []
-
Specifies Auth classes that should be included in this multi auth attempt. This must be an array of existing Auth class short names. If no value is assigned, the Auth methods configured in the REST API settings will be assumed.
- $required_privileges : array<string|int, mixed> = []
-
An array of pfSense privileges that are pre-authorized. The client must hold at least one of these privileges to be considered authorized.
Tags
Return values
Auth —The Auth object which succeeded authentication and authorization. This object will contain the details about the authenticated client.
authenticate()
Perform authentication using the current authentication method.
public
final authenticate() : bool
Return values
bool —true if authentication was successful, false if authentication was unsuccessful.
authorize()
Checks if the client is authorized to make this request.
public
authorize() : bool
Return values
bool —true if authorization was successful, false if authorization was unsuccessful.
ensure_class_exists()
Throws an error if a given Auth class shortname is not an Auth child class in the \RESTAPI\Auth\ namespace.
public
static ensure_class_exists(string $class_name) : void
Parameters
- $class_name : string
-
The name of the Auth class to check for.
Tags
get_auth_key()
Obtains the key with a specified identifier (i.e. bearer) from the client via the authorization header.
public
static get_auth_key(string $identifier) : string
Parameters
- $identifier : string
-
The key identifier to look for in the authorization header (i.e. 'bearer', 'apiKey'). Note: This identifier is case-insensitive.
Tags
Return values
stringget_class_fqn()
Obtains the fully qualified name of the called class.
public
get_class_fqn() : string
Return values
string —The FQN for this object's class.
get_class_shortname()
Obtains the shortname of the called class.
public
get_class_shortname() : string
Return values
string —The shortname for this object's class.
get_classes_in_namespace()
Obtains all classes associated with this class's current namespace.
public
get_classes_in_namespace([bool $shortnames = false ]) : array<string|int, mixed>
Parameters
- $shortnames : bool = false
Return values
array<string|int, mixed> —An array of classes currently in this object's namespace
is_requested()
Checks if the remote client is requesting BasicAuth by checking for the necessary headers.
public
is_requested() : bool
Return values
boolis_user_enabled()
Checks if a given username is an existing user that is not disabled
public
static is_user_enabled(string $username) : bool
Parameters
- $username : string
-
The username to check.
Return values
bool —true if the user is disabled, false if it is not.
log_error()
Logs an error to the syslog.
public
static log_error(string $message) : void
Parameters
- $message : string
-
The error message to write to the syslog
on_failed_auth()
When basic authentication fails, set the WWW-Authenticate to request basic authentication.
protected
on_failed_auth() : void
on_successful_auth()
Provides additional logic whenever authentication is successful. This is intended to be overridden by a child Auth class when it needs something specific to happen after a client successfully authenticates.
protected
on_successful_auth() : void
log_authentication()
Logs API authentication according to the current API configuration.
private
log_authentication() : void