WWPass for Developers

Overview. Login with WWPass

WWPass is a third-party authentication provider, which can be used for reliable, secure and convenient multi-factor authentication on Websites and in mobile and desktop applications.

The most basic form of WWPass authentication works like the following:

1. When your website needs to log in a user, it obtains a new authentication ticket from WWPass and displays it as a QR code;
2. The user scans the QR code with WWPass Key App (or taps it on a mobile device screen) and follows the app instructions to log in;
3. When the user completes logging in, WWPass notifies your website;
4. In the described basic form, your website uses the authentication ticket to obtain the user identifier from WWPass.

The user identifier supplied by WWPass is called a PUID (Provider-Specific User Identifier). PUID is a unique string that you can use to recognize the user. PUID remains the same each time the same user logs in to your website. When the same user logs in to a different website, PUID received by that website is different. The latter helps to maintain the anonymity of users.

Authentication tickets and PUIDs are requested via the WWPass API. To access the API, you need to register your website at manage.wwpass.com.

Web authentication Quick Start

This tutorial will help you add WWPass authentication to your website. It focuses on QR-code based authentication. Users of your website log in with WWPass Key App.

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

Step 1. Create a WWPass Developer Account

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

note

Creating an account on manage.wwpass.com requires you to provide a valid e-mail address. This e-mail address is used to restore access to your account if your WWPass Key is lost and cannot be recovered. It is also used to send important information about your account and websites.

Open manage.wwpass.com and click "Sign Up". Scan the QR code with the WWPass Key App to create an account. Provide your e-mail address when prompted and click Activate Account. Open your mailbox and find a message from WWPass. Click the verification link in the message to complete account activation.

Step 2. Register your website

Before you can add a website, WWPass must verify that you are the website owner. The verification process requires your website to have a publicly accessible domain name. This domain name is displayed to the users during authentication to your website.

Log in to manage.wwpass.com and click "Native Integrations" in the main menu. Click "Add new Application". Enter the domain name of your website and click "Add Domain".

Follow the instructions on the next page to create a new verification file. Make sure the file name and its content are the same as shown on the page. Upload the verification file to the root directory of your website. Make sure you can access the verification file with your browser.

Click "Validate" to start the verification process. Once your website is verified, you can issue a digital certificate needed to access the WWPass API.

note

if your website does not have HTTPS, the verification process falls back to HTTP, which can be useful for development. However, you should consider deploying HTTPS to production websites.

Step 3. Obtain digital certificates for your website

WWPass uses digital certificates to authenticate requests to the API. You should issue at least one certificate for your website. If your website runs on multiple servers, it is best to use a separate certificate for each server.

note

while this document focuses on OpenSSL for generating certificate requests, you are free to use any other similar tool of your choice.

At this phase of the website registration WWPass provides you with corresponding OpenSSL command, with proper parameters already substituted. Copy the command and execute it on your server. This is how the command to generate a new certificate request looks like:

openssl req -new -newkey rsa:4096 -nodes -subj "/O=example.org" -keyout example.org.key -out example.org.req
"example.org" will be replaced with the domain name of your website.

Click "Attach certificate request" and select the certificate request file that you have just generated. This file has a ".req" extension.

Alternatively, you can click "Paste a request contents" and put the content of the certificate request file into the text field that appears.

Click "Submit" to send your certificate request. Once the request is processed, click "Download" and save your new digital certificate.

Store the certificate and key files in a secure location on your website server. These files should be accessible by the server-side code of your website. Make sure this location is outside of your site webroot.

Download the WWPass CA certificate and store it on your server together with your website certificate and key files. Now that you have successfully obtained a digital certificate, you can proceed with adding WWPass authentication to your website.

Step 4. Modify website login page

Whatever your server-side technology is, the browser-side code is the same: add an HTML element - QR code placeholder. <div> is the best option, e.g.

<div id="qrcode">

</div>

Now add the JavaScript code to support Login with WWPass.

For an npm-based project, install wwpass-frontend module:

npm install wwpass-frontend

Alternatively, download the compiled standalone script on Github.

Add the code itself:

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

Here, qrcode parameter is any valid CSS-selector of the QR code container element.

ticketURL is the link to the server-side API to obtain or renew WWPass ticket - see below.

The code above initializes WWPass login, requests authentication tickets using ticketURL and displays dynamic QR code based on the ticket data. Once the user has completed authentication in WWPass Key App, the wwpass-frontend sends the resulting data to the callbackURL via HTTP GET request.

For example, PHP website may look like

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

For more details, see documentation in Github.

Step 5. Add server library

Due to the wide variety of server-side languages and technologies, we shortly describe only the PHP library here. See WWPass Github for all the available libraries.

he WWPass PHP library is available in Composer repository.

composer require wwpass/apiclient

Server-side code communicates with WWPass core network using digital certificates, obtained during the website registration.

Here is the getTicket a URL handler to obtain authentication tickets and encode to the format expected by wwpass-frontend.

getticket.php file is basically the same for all the websites.

// getticket.php

...

define('WWPASS_CERT_FILE', "path/to/example.org.crt");
define('WWPASS_KEY_FILE', "path/to/example.org.key");
define('WWPASS_CA_FILE', "path/to/wwpass.ca.cer");
define('WWPASS_PIN_REQUIRED', true);

try {
    $wwc = new WWPass\Connection(
        ['key_file' => WWPASS_KEY_FILE,
        'cert_file' => WWPASS_CERT_FILE,
        'ca_file' => WWPASS_CA_FILE]
    );
    $ticket = $wwc->getTicket(
        ['pin' => WWPASS_PIN_REQUIRED,
        'client_key' => true,
        ]
    );
} catch (WWPass\Exception $e) {
    $err_msg = 'Caught WWPass exception: ' . $e->getMessage();
    error_log($err_msg);
} catch (Exception $e) {
    $err_msg = 'Caught exception: ' . $e->getMessage();
    error_log($err_msg);
}
$data = $ticket;

header('Content-type: application/json');
echo json_encode($data);

On user authentication, wwpass-frontend script sends GET request to the callback URL, with authentication details in the request parameters. It is quite natural to process the request in the same login.php URL which generates login page.

// login.php...define('WWPASS_CERT_FILE', "path/to/example.org.crt");define('WWPASS_KEY_FILE', "path/to/example.org.key");define('WWPASS_CA_FILE', "path/to/wwpass.ca.cer");if ((array_key_exists('wwp_status', $_GET)  && ( $_GET['wwp_status'] == 200)   && (array_key_exists('wwp_ticket', $_GET)) {        $ticket = $_GET['wwp_ticket'];        try {            $wwc = new WWPass\Connection(                ['key_file' => WWPASS_KEY_FILE,                'cert_file' => WWPASS_CERT_FILE,                'ca_file' => WWPASS_CA_FILE]            );            $puid = $wwc->getPUID(['ticket' => $ticket]);            $_SESSION['PUID'] = $puid;            header("Location: index.php");            exit();        }  catch (Exception $e) {            error_log("wwp exception: " . $e->getMessage());        }    }}

On success, the session variable PUID is set, identifying the user, and control is passed to index.php URL. Otherwise, render the login page, e.g.

echo theTwig()->render('login.html');

A PUID is a unique string that identifies the user. A particular way of using PUID depends on the architecture of your application. If your application already has a database that stores application users, add a new table that maps PUIDs to the existing user identifiers. See "How WWPass Authentication Works" below.

Website code example

You can find a PHP demo application code on GitHub.