Authentication

Authenticator packages integrate with the QUIQQER login flow. They can provide primary authentication, secondary authentication, login controls, password reset controls, settings controls, and CLI authentication.

Register An Authenticator

Register authenticator classes as package providers:

<quiqqer>
    <package>
        <provider>
            <auth src="\Vendor\Package\Auth\Provider"/>
        </provider>
    </package>
</quiqqer>

The class must be autoloadable and implement QUI\Users\AuthenticatorInterface. In normal packages, extend QUI\Users\AbstractAuthenticator and override the methods your authenticator needs.

Authenticator Contract

An authenticator receives a user reference in the constructor and authenticates through auth().

namespace Vendor\Package\Auth;

use QUI;
use QUI\Interfaces\Users\User;
use QUI\Users\AbstractAuthenticator;

class Provider extends AbstractAuthenticator
{
    private ?User $User = null;
    private ?string $username = null;

    public function __construct(null|array|int|string|User $user = null)
    {
        if ($user instanceof User) {
            $this->User = $user;
            return;
        }

        if (is_string($user) || is_int($user)) {
            $this->username = (string)$user;
        }
    }

    public function auth(string|array|int $authParams): bool
    {
        if (!is_array($authParams) || empty($authParams['token'])) {
            throw new QUI\Users\Exception('Authentication failed');
        }

        // Validate the token and bind the authenticated user here.
        return true;
    }

    public function getUser(): User
    {
        if ($this->User !== null) {
            return $this->User;
        }

        if ($this->username === null) {
            throw new QUI\Users\Exception('Authentication failed');
        }

        $this->User = QUI::getUsers()->getUserByName($this->username);

        return $this->User;
    }

    public function getTitle(?QUI\Locale $Locale = null): string
    {
        return 'Vendor Authentication';
    }

    public function getDescription(?QUI\Locale $Locale = null): string
    {
        return 'Authenticates users through the vendor login provider.';
    }

    public function getIcon(): string
    {
        return 'fa fa-key';
    }
}

Throw QUI\Users\Exception when authentication fails. Do not return a partially authenticated state.

Login Controls

Override getLoginControl() when the authenticator needs its own form or JavaScript flow.

public static function getLoginControl(): ?QUI\Control
{
    return new \Vendor\Package\Controls\Auth\Login();
}

The returned control is rendered by the QUIQQER login control. Use it for provider-specific fields, buttons, or client-side authentication flows.

Primary And Secondary Authentication

Authenticators can opt into primary and secondary login steps:

public function isPrimaryAuthentication(): bool
{
    return true;
}

public function isSecondaryAuthentication(): bool
{
    return false;
}

Use secondary authentication for additional verification such as one-time codes or verified mail flows. Use getSecondaryAuthenticationButton() when the secondary flow needs a dedicated button in the login UI.

CLI Compatibility

Console authentication is only used when the authenticator explicitly supports it:

public static function isCLICompatible(): bool
{
    return true;
}

public function cliAuthentication(\QUI\System\Console $Console): void
{
    // Read required arguments or prompt through the console.
}

Keep CLI authentication non-interactive when the command is meant for automated jobs.

Operational Notes

QUIQQER imports authenticator providers during setup and creates permissions for usable authenticators. After a package is installed, enable the authenticator in the system authentication settings and assign permissions to the users or groups that may use it.