Skip to main content

Request Authorization

The auth function in Phlame provides a streamlined approach to handle authentication within web applications and APIs. This function enables developers to authenticate incoming requests based on authorization headers and tokens, with support for optional prefixing and hashing. Let's explore the documentation for the auth function and how it can be used.

note

Due to the importance of autorization, this part of the documentation is highly detailed.

Function Signature:

public static function auth($prefix , $token , $hash , $then , $orelse, $allowfail)

Parameters:

  • $prefix: Optional. A string representing the token prefix. Default is null.
  • $token: Optional. A string representing the authentication token. Default is null.
  • $hash: Optional. A string representing the hashing algorithm to be applied to the authorization header. Default is null.
  • $then: Optional. A callback function to execute when authentication is successful. Default is null.
  • $orelse: Optional. A callback function to execute when authentication fails. Default is null.
  • $allowfail: Optional. A boolean to allow custom orelse code when authentication fails. Default is false. [It does not allow orelse code]

Functionality

The auth function in Phlame offers a comprehensive set of functionalities to handle authentication within web applications and APIs. It begins by retrieving the authorization header from the incoming request and proceeds to check for its presence. In case the authorization header is missing, the function responds with a 401 Unauthorized status code, indicating a lack of authentication credentials. Additionally, the function provides optional support for applying hashing to the authorization header using a specified algorithm, enhancing security measures.

Moreover, developers have the flexibility to specify a prefix for the authentication token, allowing for seamless integration with various authentication schemes. Following this, the function compares the provided token with the authorization header. If they do not match, signifying failed authentication, the function returns a 403 Forbidden status code, restricting access to protected resources.

Furthermore, the auth function supports the execution of callback functions based on the authentication status. If authentication is successful, the then callback is executed, enabling developers to implement custom logic for authorized requests. Conversely, if authentication fails, the orelse callback is triggered, providing developers with the opportunity to handle authentication errors gracefully.

Ultimately, the auth function returns an array containing the authentication status (status) and the authorization header (data). This comprehensive approach to authentication empowers developers to enforce security measures effectively and control access to sensitive resources within their applications.

Example without hashing

Api::auth(
prefix: "Bearer",
token: "authentication_token",
then: function($rout) {
// Custom logic for successful authentication
// Access $rout['data'] to get the authorization header
},
orelse: function($rout) {
// Custom logic for failed authentication
// Access $rout['data'] to get the authorization header
},
allowfail: true
);

info

if you dont want to use prefix, you can just add the prefix to the start of the token directly Example:

Api::auth(
token: "Bearer authentication_token",
then: function($rout) {
// Custom logic for successful authentication
// Access $rout['data'] to get the authorization header
},
orelse: function($rout) {
// Custom logic for failed authentication
// Access $rout['data'] to get the authorization header
},
allowfail: true
);

Example with hashing

Api::auth(
token: "your_hash_with_prefix_and_token",
hash: "hash_method_used_for_hashing_the_token",
then: function($rout) {
// Custom logic for successful authentication
// Access $rout['data'] to get the authorization header
},
orelse: function($rout) {
// Custom logic for failed authentication
// Access $rout['data'] to get the authorization header
},
allowfail: true
);

Above, the user can be given the token:

Readeable Token
Bearer HelloWorld

but to use the hash, both must be hashed together while being put into the token parameter

sha256 hash
44ce1c5513af128a297a0b133a98b32499bc11746ace4ae3c02b11f95ab0a775
// this is the sha256 of "Bearer HelloWorld"

The hashing is done only on the server side, to avoid API Key's and Tokens being exposed in the backend.

caution

Not setting allowfail to true will cause the auth method to break out, to prevent any issues, this will return an error statement and a status code, this will also not allow your orelse callback to run. To prevent the exit, set allowfail to true.