Authenticators

Authenticators are services responsible for turning raw credentials into an AuthIdentity.

Authenticators encapsulate the logic required to verify a user’s credentials. This could be a JWT token, an API key, or a session cookie.

Task-focused guides:

• Authenticate with JWT (JWKS)
• Authenticate with a custom API key header
• Authenticate, authorize, and inspect identity — the full picture

AuthenticatorInterface

All authenticators must implement the AuthenticatorInterface.

Methods

• authenticate(string $token): ?AbstractAuthIdentity: Takes a raw token (or credential string) and returns an identity object if valid, or null if authentication fails.

---

JwtAuthenticator

Apivalk provides a production-ready JwtAuthenticator that uses the firebase/php-jwt library. It is designed to work with OAuth2 providers (like Auth0, Okta, or Keycloak) that expose a JWKS (JSON Web Key Set) endpoint.

Features

• JWKS Support: Automatically fetches and parses public keys from a remote URL.
• Claim Validation: Validates the iss (issuer), aud (audience), and exp (expiration) claims. A configured issuer or audience has to be present in the token and match; an empty string disables that check. The aud claim may be a single string or a list of strings, and matches when the configured audience is among them.
• Scope Extraction: Automatically parses scopes from the scope or scp claims.
• Identity Creation: Returns a JwtAuthIdentity populated with the sub, email, username, scopes, permissions, and audiences.

Usage

use apivalk\apivalk\Security\Authenticator\JwtAuthenticator;

$authenticator = new JwtAuthenticator(
    'https://YOUR_DOMAIN/.well-known/jwks.json',
    $cache, // Instance of CacheInterface or null
    'https://YOUR_ISSUER/',
    'YOUR_AUDIENCE'
);

$identity = $authenticator->authenticate($jwtToken);

---

Custom Authenticators

You can easily implement your own authenticator by implementing the interface. This is useful for API keys or custom database-backed authentication.

use apivalk\apivalk\Security\Authenticator\AuthenticatorInterface;use apivalk\apivalk\Security\AuthIdentity\AbstractAuthIdentity;use apivalk\apivalk\Security\AuthIdentity\JwtAuthIdentity;

class ApiKeyAuthenticator implements AuthenticatorInterface
{
    public function authenticate(string $token): ?AbstractAuthIdentity
    {
        // 1. Check if the API key exists in your database
        $user = $this->db->findUserByApiKey($token);
        
        if (!$user) {
            return null;
        }

        // 2. Return a JwtAuthIdentity (or a custom identity class)
        return new JwtAuthIdentity(
            $user->username,
            $user->email,
            (string)$user->id,
            $user->getScopes(),
            $user->getPermissions()
        );
    }
}