Auth
in package
uses
BaseTraits
Defines object that performs authentication and authorization for REST API Endpoints and obtains details about the authenticating client. This class is intended to be extended by child classes that define specific authentication methods.
Table of Contents
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
- Defines the steps required for users to authenticate wit this authentication method. This method must be overridden by a child Auth class. This method MUST return the username of the authenticating client if auth is successful, and null if it is not. NOTE: This method MUST set $this->username.
- 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 has requested this Auth class for authentication. By default, this method will simply try to authenticate the remote client using the called Auth class. This can also be overridden by child Auth classes to define custom logic to determine if the client is trying to use the called Auth class.
- 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
- Provides additional logic whenever authentication has failed. This is intended to be overridden by a child Auth class when it needs something specific to happen after a client fails to authenticate.
- 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.
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
= []
Sets the OpenAPI securityScheme definition for this Auth class. This value should be the innermost array of the securityScheme and not include the scheme name.
Tags
$username
public
string|null
$username
= null
The username of the authenticated remote client.
$verbose_name
public
string|null
$verbose_name
= null
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()
Defines the steps required for users to authenticate wit this authentication method. This method must be overridden by a child Auth class. This method MUST return the username of the authenticating client if auth is successful, and null if it is not. NOTE: This method MUST set $this->username.
public
_authenticate() : bool
Tags
Return values
bool —Returns true if authentication was successful, returns 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 has requested this Auth class for authentication. By default, this method will simply try to authenticate the remote client using the called Auth class. This can also be overridden by child Auth classes to define custom logic to determine if the client is trying to use the called Auth class.
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()
Provides additional logic whenever authentication has failed. This is intended to be overridden by a child Auth class when it needs something specific to happen after a client fails to authenticate.
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