Authentication

Authentication is a crucial aspect of web applications, ensuring that users are who they claim to be and have the necessary permissions to access resources. Prisma PHP simplifies the authentication process by providing a built-in authentication system that supports various authentication methods, including email/password, social logins, and third-party services. By integrating authentication into the development workflow, Prisma PHP streamlines the process of securing applications, making it easier for developers to implement user authentication and authorization features.

Prisma PHP Supports Two Authentication Modes:

By default, all routes are public. However, Prisma PHP also allows you to make all routes private, requiring authentication for access. To switch to this mode, simply go to the src/Lib/Auth/AuthConfig.php file and set the IS_ALL_ROUTES_PRIVATE configuration to true. This will enforce authentication across all routes, enhancing the security of your application.

Use Cases for Authentication Modes:

If your application has more public routes than private ones, you can use the default authentication mode where all routes are public by default. However, if your application has more private routes than public ones, you can switch to the mode where all routes are private by default, requiring authentication for access. This approach ensures that your application is secure and only accessible to authenticated users.

By default, Prisma PHP use the package firebase/php-jwt for authentication. This package is a PHP library that enables developers to encode and decode JSON Web Tokens (JWTs) in PHP. JWTs are a popular method for securely transmitting information between parties as a JSON object. They are commonly used for authentication and authorization in web applications, providing a secure and efficient way to verify the identity of users and grant access to resources. For more information about JWTs, you can visit the official website: jwt.io.

To get stated with authentication you have to follow the following steps:

1. Set the AUTH_SECRET environment variable in the .env file.
2. Use the Auth class to authenticate users and generate JWTs, location src/Lib/Auth/Auth.php.
3. Use the AuthConfig class to configure the authentication settings, location src/Lib/Auth/AuthConfig.php.
4. Implement authentication middleware AuthMiddleware to protect routes and resources, location src/Lib/Middleware/AuthMiddleware.php.
5. Secure your application by validating JWTs and verifying user roles.

Set the AUTH_SECRET Environment Variable

The AUTH_SECRET environment variable is used to sign and verify JWTs. It should be a random string of characters that is kept secret and not shared with others. You can generate a secure secret using a password manager or a random string generator. The secret should be unique for each application and should not be hard-coded in the source code.

By default Prisma PHP give you a random secret key AUTH_SECRET=your_secret_key just for development purposes, you can change it in the .env file.

• Get your secret key from openssl CLI, openssl rand -base64 33
• Alternatively, randomkeygen.com.
• Or install the package on local running the command npm exec auth secret, this will generate a random secret key and save it in the .env file.

Use the Auth Class

To authenticate users and generate JWT tokens, you can use the Auth singleton class located in src/Lib/Auth/Auth.php. This class provides all the necessary methods for authentication, such as:

• getInstance Get the instance of the Auth class, $auth = Auth::getInstance();
• signIn Sign In the user and generate a JWT token, $jwt = $auth->signIn($data);
• isAuthenticated Check if the user is authenticated, $auth->isAuthenticated();
• getPayload Get the payload of the JWT token. Use the $user = $auth->getPayload() method to retrieve the information encrypted in the JWT token. This method will return the user information that was saved while generating the token, but decrypted.
• verifyToken Verify the JWT token, $auth->verifyToken($token);
• refreshToken Refresh the JWT token, $auth->refreshToken($token);
• signOut Sign Out the user and destroy the JWT token, $auth->signOut('/redirect');

Use the AuthConfig Class

To configure the AuthConfig class you can find it in src/Lib/Auth/AuthConfig.php file, you can change the default values as you want.

• ROLE_IDENTIFIER: The key used to identify the user role in the JWT payload.
• IS_ROLE_BASE: A boolean value indicating whether the application uses role-based access control.
• IS_TOKEN_AUTO_REFRESH: A boolean value indicating whether the JWT token should be automatically refreshed.
• IS_ALL_ROUTES_PRIVATE: A boolean value indicating whether all routes are private and require authentication.
• DEFAULT_SIGNIN_REDIRECT: The default route to redirect users after sign-in. This setting is effective only when IS_ALL_ROUTES_PRIVATE is set to true.
• API_AUTH_PREFIX: The prefix used for third-party API authentication routes (e.g., GitHub, Google, etc.). This setting is only effective when IS_ALL_ROUTES_PRIVATE is set to true.
• public static array $privateRoutes: An array of routes that require authentication but are accessible to all authenticated users, regardless of their roles. This is the (default) authentication mode.
• public static array $publicRoutes: An array of routes that remain accessible without authentication. This setting is only effective when IS_ALL_ROUTES_PRIVATE is set to true.
• public static array $authRoutes: An array of routes that are used for authentication, such as sign-in and sign-up routes.
• public static array $roleBasedRoutes: An associative array mapping specific routes to required user roles for access control.

Here is an example of how to configure the role base access control in the AuthConfig class:

if you going to use the role base access control you have to set the IS_ROLE_BASE to true and set the roles for each route in the public static $privateRoutes and public static $roleBasedRoutes array. The roles should be defined in the AuthRole enum, you can find it in the src/Lib/Auth/AuthConfig.php file.

enum AuthRole: string
  {
      case Admin = 'Admin';
      case User = 'User';
  
      public function equals($role)
      {
          return $this->value === $role;
      }
  }

Here is an example of how to configure the AuthConfig class:

final class AuthConfig
    {
        const ROLE_IDENTIFIER = 'role'; // The key used to identify the user role in the JWT payload
        const IS_ROLE_BASE = false; // Enable role-based access control (true/false)
        const IS_TOKEN_AUTO_REFRESH = false; // Enable token auto refresh (true/false)
        // Be default all routes is public
        public static $privateRoutes = [
            '/dashboard', // All routes that is inside the dashboard route is private and require authentication
            '/settings/profile', // All routes that is inside the settings/profile route is private and require authentication 
            **Note** the settings route is public
        ];
        public static $roleBasedRoutes = [
            'dashboard' => [self::ROLE_IDENTIFIER => [AuthRole::Admin, AuthRole::User]], // The dashboard route require Admin or User role to access
            'dashboard/users' => [self::ROLE_IDENTIFIER => [AuthRole::Admin]], // The dashboard/users route require Admin role to access 
            **Note** the dashboard route is accessible by Admin and User roles
        ];
    }

After configuring the AuthConfig class, you can use the Auth class to authenticate users and generate JWTs. The Auth class provides methods for authenticating users and generating JWTs. You can use the Auth->signIn($data, $tokenValidity) method to authenticate users and generate a JWT token. The method takes a mixed $data and a string $tokenValidity as arguments and returns a signed JWT token. You can use the token to authenticate requests and grant access to protected resources.

You can modify the signIn method to accept the user ID and token validity as arguments, this makes the method more flexible and allows you to specify the $data can be the user model that you want to store in the JWT payload.

• For the token validity $tokenValidity, you can use the following formats:
• 30s for 30 seconds
• 1m for 1 minute
• 1h for 1 hour
• 1d for 1 day
• By default, the token validity is set to 1h for 1 hour. If you don't specify the token validity, it will use the default value.

Here is an example of how to use the Auth class to authenticate users and generate JWTs:

<?php
  
  use Lib\Auth\Auth;
  
  $auth = Auth::getInstance();
  $loginUserInfo = ['id' => 1, 'username' => 'john.doe', 'email' => 'john.doe@gmail.com'];
  try {
      $jwt = $auth->signIn($loginUserInfo);
      echo "JWT: " . $jwt;
  } catch (\InvalidArgumentException $e) {
      echo "Error: " . $e->getMessage();
  }

Note: The basic way to signIn the user is by passing the user info directly to the `signIn` method. In this case, there is no need to handle the `Role` separately.

Basic way to signIn the user or login the user is by passing the user info directly to the `signIn` method, in this case, there is no need to handle the `Role` separately.

<?php

  use Lib\Auth\Auth;
  use Lib\StateManager;
  
  $auth = Auth::getInstance();
  
  $user = StateManager::getState('user');
  
  if ($auth->isAuthenticated()) {
      StateManager::setState('user', $auth->getPayload());
  }
  
  function login()
  {
      $auth = Auth::getInstance();
      $jwt = $auth->signIn(['name' => 'admin'], '1m');
      echo "JWT: $jwt";
  }
  
  ?>
  
  <button onclick="login">Login</button>
  <p><?= $user->name ?? '' ?></p>

<?php
  
  use Lib\Auth\Auth;
  use Lib\Auth\AuthRole;
  
  $auth = Auth::getInstance();
  
  try {
      $jwt = $auth->signIn(AuthRole::Admin, '1m');
      echo "JWT: " . $jwt;
  } catch (\InvalidArgumentException $e) {
      echo "Error: " . $e->getMessage();
  }

In this example, we create a new instance of the Auth class from the Lib\Auth namespace. We then attempt to authenticate a user as an Admin with a token expiration time of '1m' (one minute). The authenticate method generates a JWT (JSON Web Token) which is then printed out. If an error occurs during authentication, such as invalid arguments, it catches the exception and prints the error message.

To check is the user is authenticated you can use the Auth->isAuthenticated() method, this method will return true if the user is authenticated and false if the user is not authenticated.

For logout you can use the Auth->signOut() method to logout the user and destroy the JWT token, this method will redirect the user to the login page.

Here is an example of how to use the Auth class to logout the user:

To log out the user, you can use the signOut function and then redirect the user to the home page.

<?php

  use Lib\Auth\Auth;
  
  function logout {
    Auth::getInstance()->signOut('/'); // Replace '/path/to/redirect' with the actual path where you want to redirect the user after logout, when the mode is set to IS_ALL_ROUTES_PRIVATE the user will be redirected automatically to the sing-in page
  }

  ?>

  <button onclick="logout">Logout</button>

using get to logout the user, <a href="?logout">Logout</a>

<?php

  use Lib\Auth\Auth;
  use Lib\Request;
  
  $auth = Auth::getInstance();
  
  if (Request::$isGet && isset(Request::$params->logout)) {
      $auth->signOut('/'); // Replace '/path/to/redirect' with the actual path where you want to redirect the user after logout, when the mode is set to IS_ALL_ROUTES_PRIVATE the user will be redirected automatically to the sing-in page
  }
  
  ?>
  
  <a href="?logout">Logout</a>

Implement Authentication Middleware

Once you have generated a JWT token, you can use it to authenticate requests and grant access to protected resources. To do this, you need to implement authentication middleware that verifies the JWT token and grants access to authenticated users. The middleware should extract the JWT token from the request headers, decode the token, and verify the signature to ensure that it is valid. If the token is valid, the middleware should grant access to the protected resource; otherwise, it should return an error response or redirect.

Prisma PHP provides built-in middleware for authenticating requests and protecting routes. You can use the AuthMiddleware class to authenticate requests and grant access to protected resources. The middleware extracts the JWT token from the request headers, decodes the token, and verifies the signature to ensure that it is valid. If the token is valid, the middleware grants access to the protected resource; otherwise, it returns an error response or redirect.

For the complete implementation of the authentication middleware, please refer to the src/Lib/Middleware/AuthMiddleware.php file.

public static function handle($requestPathname) {}

The AuthMiddleware class's public static function handle($requestPathname) method is responsible for authenticating requests and protecting routes. It first checks if the requested URI matches any of the private routes that require authentication. If the URI does not match, the middleware allows the request to proceed without further checks. If it matches, the middleware verifies whether the user is authenticated. If the user is not authenticated, it redirects them to the login page. Additionally, if role-based access control is enabled and the user does not have the required role for the route, it redirects to an access denied page. This setup ensures that only authenticated users with the appropriate roles can access specific routes, enhancing the security of your application. This function handles both scenarios: when IS_ALL_ROUTES_PRIVATE is set to true and when the default authentication mode is used.

Secure Your Application

After implementing the authentication middleware, you can use it to secure your application and its routes. This middleware validates JWT tokens, ensuring that only authenticated users with the appropriate roles can access protected areas of your application. The configuration for this, including specifying which routes are protected and the roles that are permitted access, is managed through the AuthConfig class.

Integrating authentication and authorization mechanisms into your application is essential for protecting sensitive information and resources from unauthorized access. It ensures that only users with the correct permissions can access protected resources. Prisma PHP simplifies this process with its built-in authentication system, making it easier for developers to implement these critical security features.

For more details on implementing authentication and authorization with Prisma PHP, refer to the official documentation and API guide. These resources provide comprehensive guidance on authenticating users, generating JWT tokens, and securing routes and resources using the framework's authentication capabilities.