pfSense-pkg-RESTAPI

JWTAuth extends Auth
in package

Defines an Auth class that allows for JWT authentication against the pfSense REST API.

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
Obtains the submitted JWT from the client and attempts to decode the JWT using this host's server key.
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 = ['type' => 'http', 'scheme' => 'bearer', 'bearerFormat' => 'JWT']

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 = 'JWT'

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 JWT from the client and attempts to decode the JWT using this host's server key.

public _authenticate() : bool
Return values
bool

Returns true if the JWT was successfully decoded, 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
throws
AuthenticationError

When no allowed Auth classes had successful authentication.

throws
ForbiddenError

When authentication was successful for an Auth class, but the client failed to be authorized due to missing privileges.

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
throws
ServerError

When $class_name is not an existing Auth child class in the \RESTAPI\Auth\ namespace

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
returns

String A string containing the submitted bearer token from the client. If a key with the matching $identifier is not found, an empty string will be returned.

Return values
string

get_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
bool

is_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

        
On this page

Search results