README

Version 4.0.2 This repository provides the combined WWPass PHP SDK and Composer-compliant API client library, enabling multifactor authentication for websites and applications. It includes documentation, server library, a standalone script (wwpass.php), and demo examples for easy integration.

Overview

WWPass is a third-party authentication provider that offers reliable, secure, and convenient multi-factor authentication for websites, as well as mobile and desktop applications. It uses QR-code-based authentication, where users scan a code with the WWPass Key App to log in. Each user is assigned a unique identifier by WWPass, called a PUID (Provider-Specific User Identifier), which ensures consistent identification on the same website while preserving anonymity across different websites.

Repository Structure

demo/: Contains example code demonstrating WWPass authentication. src/: Includes the server library classes to interact with the WWPass API. wwpass.php: A standalone script for implementing WWPass authentication.

Installation

To install the Composer-compliant API client library:

composer require wwpass/apiclient

Usage

The library defines two main classes: WWPass\Connection and WWPass\Exception.

require_once 'vendor/autoload.php';

try {
    $wwc = new WWPass\Connection([
        'key_file' => WWPASS_SPFE_KEY_FILE,
        'cert_file' => WWPASS_SPFE_CERT_FILE,
        'ca_file' => WWPASS_SPFE_CA_FILE
    ]);
    $response = $wwc->getTicket(['ttl' => 300, 'pin' => true]);

    $ttl = $response['ttl'];
    $ticket = $response['ticket'];
} catch (WWPass\Exception $e) {
    echo 'Caught WWPass exception: ' . $e->getMessage();
} catch (Exception $e) {
    echo 'Caught exception: ' . $e->getMessage();
}

Setup Instructions

Before following this tutorial, make sure you have installed the WWPass Key App. The application is available for free at AppStore and Google Play.

Step 1: Register with WWPass

Skip this section if you already have an account on manage.wwpass.com

• Register your site on the WWPass Developers.
• Obtain your Service Provider (SP) credentials (certificate and private key), and download the WWPass CA certificate.

Step 2: Domain Validation

• Add your domain in the WWPass portal and verify ownership by placing a unique verification file in your website’s root directory.
• Make sure the file is accessible via a public URL.

Step 3: Obtain Digital Certificates

• Use OpenSSL to generate a private key and a certificate signing request (CSR):

openssl req -new -newkey rsa:4096 -nodes -subj "/O=example.org" -keyout example.org.key -out example.org.req

• Upload the certificate signing request (CSR) to WWPass and download the issued certificate.

Step 4: Implement QR Code Authentication

• Add a QR code placeholder to your HTML

<div id="qrcode"></div>

• Include the WWPass authentication script to generate and display the QR code:

<script>
  WWPass.authInit({
    qrcode: '#qrcode',
    ticketURL: 'getticket.php',
    callbackURL: 'login.php',
  });
</script>

• Ensure your server-side code can handle ticket generation and retrieve the user's PUID.

License

This project is licensed under the Apache License, Version 2.0. See the LICENSE file for details.

Additional Resources

• For more details on implementing WWPass, see the Documentation.
• For server library setup, refer to the Server Library Integration.