WWPass Basics

Overview

WWPass is essentially a third party Identity Provider (IdP) - much like OpenID and SAML servers. Similar to other third-party IdPs, WWPass authenticates a user and sends user-related data to the Relying Party (i.e. a website).

There are two important differences however. First, WWPass heavily relies on a hardware token. In a sense, the token is the first authentication factor, while an optional "access code" (or password, or PIN) is the second factor.

The other aspect is the origin of user data sent to a website upon user authentication. SAML and OpenID usually send a subset of user attributes stored in their databases. To the contrary, WWPass user data is specific to each WWPass-enabled website. The content of the data - and even data format - are fully defined by the Relying Party. WWPass only acts as a "storage service" for websites. Depending on the needs of your application, all or part, of the user data collected by your website may be stored at WWPass - e.g. social security number, bank card number, addresses etc. In its simplest form, the website may still keep all user information in its databases, while keeping at WWPass storage only a pointer to a particular user record (see What is a PUID below)

Authentication Steps

To implement WWPass authentication, you should first register your site at WWPass. Upon registration your website gets a Service Provider name (SP name), Service Provider ID (SpID) and an X.509 certificate.

Now, if a ready-made WWPass module (Apache, WordPress, SAML, etc.) fits your needs, download the module and follow the instructions provided.

Otherwise you should modify your website code. The modification includes two distinct parts.

1. Browser-side. Add the "Login with WWPass" button bound to SP name and wwp_auth function (see implementation). When a user clicks on the "Login with WWPass" button, a browser plugin starts mutual authentication between user’s WWPass Key and the WWPass core network. On success the WWPass Key delivers user digital identity (UserID), stored in the WWPass Key and the SP name to WWPass over a ciphered channel. Now WWPass core binds together the SP name and UserID and issues a transaction identifier (called a "ticket" - see the link). The ticket is then sent back to your website via the WWPass Key and browser plugin.
2. Server side. Now it is time for your server and the WWPass core network to mutually authenticate each other. Only upon a successful authentication, the website will then present the ticket to WWPass core. Now that all digital IDs of all parties check out, WWPass brings user data to your web server.

Where does the data come from? Well, if the user visits your site for the first time, there is no data at all. It is up to you (the service provider) to decide when and what data will be stored at WWPass. And when the data is stored, only your website has rights to access it.

What is a Ticket

A Ticket is one of the cornerstone concepts of WWPass technology. The term itself was borrowed from the Kerberos protocol, but the underlying mechanism is quite different. A Ticket is a small piece of information, circulating between a user, a Service Provider and WWPass. Its formal representation is:

<spname:>[p:]<nonce>@<issuer>

<spname> is the human-readable name of the Service Provider (URL-encoded), This is presented to the user in the consent dialog p – optional but if present, indicates two-factor authentication (access code required)

<nonce> stands for "number used once", random sequence of hex digits

<issuer> is a WWPass network node where the ticket was created

Why Ticket?

Mutual authentications in pairs ( user ⬄ WWPass ) and ( Service Provider ⬄ WWPass ) are not enough to address a data container with user data to the Service Provider. Since the communication between a Service Provider and a user is a many-to-many relationship, WWPass needs to identify a particular session between the user and the Service Provider. Tickets help to solve the task.

How It Works

1. User and Service Provider

   • The user starts authentication at the Service Provider with WWPass by pressing a button on the Service Provider’s web page.
   • JavaScripts started with the spname as an argument
   • The browser plugin gets spname and displays a consent dialog.

2. User and WWPass

   • The spname is presented to the user in the consent dialog, and if the user agrees to continue, the user authentication with WWPass is initiated.
   • As a result of successful mutual authentication, WWPass gets the UserID and generates a random sequence. At this point, the Ticket itself is created by concatenation of spname, nonce, and issuer network address, e.g.:

   Example%20Provider:0be4a4c407f021a6e39032755fec65611ed6c758e7ead6309412c0cbb966fa08bd887c421b3d@WWPass_srv15:16032
   • The WWPass server that issued the Ticket remembers the (Ticket, UserID) pair.
   • The Ticket is sent back to the user.

3. The User and Service Provider

   • The user forwards the Ticket to the Service provider (Note: this is the most important point, the Ticket is now tied to a specific user/Service Provider session).

4. The Service Provider and WWPass

   • The Service Provider and WWPass are mutually authenticated (with X.509 certificates) and the Ticket is sent to WWPass. As a result of authentication, the WWPass server, communicating with the Service Provider gets SPID.
   • WWPass server checks if the <issuer> recognizes the Ticket and gets the UserID corresponding to the Ticket.
   • Combining the UserID and SPID, the WWPass server calculates the data container address and restores its content.
   • The data container is sent to the Service Provider.

Second Factor

It is the Service Provider who decides whether to ask for a second factor. If so, the Service Provider adds the "p:" suffix to <spname> on its web page. The protocol described above will behave in a slightly different manner. After WWPass Key is authenticated (Step 2), WWPass initiates an "access code" check. If a user enters correct access code, WWPass creates a new Ticket as described, with "p:" part. When the Service Provider validates the Ticket with WWPass (Step 4) it passes a flag to WWPass indicating that the Ticket is to be validated only if the access code has been submitted. While the Service Provider may check for p: itself, it is not recommended because of possible Ticket format changes in future.

Ticket as a Session Identifier

Depending on a particular scenario, the Service Provider may want to access the data containers more than once during a single user session. For example, the data container may first be read and then modified and the user data is stored back (read-modify-write cycle). It is possible to avoid extra user authentications. The same Ticket may be reused in the Service Provider/WWPass communication to access data containers. This requires the first Ticket to be validated by a "put Ticket" command. This command returns a newly issued Ticket that can be reused. This Ticket may be viewed as a "cookie" in the Service Provider/WWPass communication. All tickets are assigned time-to-live (TTL) parameter. The TTL for a newly issued Ticket may be specified as a parameter to "get/put Ticket" commands.

What is a PUID

PUID (Provider's User ID) is a random number which is initially generated by the WWPass core network for a particular SP-User pair.

It may be used in a basic authentication scenario as a reference to user data, stored at Service Provider's databases.

For each Service Provider (SP) PUIDs are guaranteed to be unique and different for each user. Every SP has its own PUID set. User will rather have another PUID in another SP namespaces. However, the uniqueness is checked only inside a particular SP domain.

Obviously the PUID may serve as a pointer to the user record in a Service Provider database. Particularly, we can add a new "PUID" field into a user record. Now, instead of identifying users by

SELECT * FROM users WHERE username='$myusername' and passcode='$mypassword';

we will write

SELECT * FROM users WHERE wwpass_puid='$puid';

Implementation details

Add the following line into the of your authentication page:

<script src="//cdn.wwpass.com/packages/latest/wwpass.js"></script>

In the body of the page, place a "Login with WWPass" button which triggers wwpass_auth function:

<img src="./images/loginwWWP-257x56.png"
      alt="Login with WWPass"
      onmousedown="this.src='images/loginwWWP-257x56_mouseover.png';"
      onmouseup="this.src='images/loginwWWP-257x56.png';
      wwpass_auth('', wwpass_login_callback)" >

Same functionality with a link:

<a href="#" onclick="wwpass_auth(
      '<Your Service Provider name>',
      wwpass_login_callback
    ); return false;">
  Authenticate with WWPass
</a>

The wwpass_auth function coordinates a WWPass Key and WWPass core network authentication and data exchange. wwpass_auth accepts two parameters: registered WWPass name of your SP (usually an URL, e.g. mysite.com) and a name of a callback function. This callback redirects the user to the page that handles the server side of the authentication process.

The very callback function in turn is given two arguments: the authentication status code and the ticket:

function wwpass_login_callback(status, ticket) {
  if (status == 200) {
    window.location="/handle_wwpass_auth?ticket="+ticket;
  }
}

Now the ticket is on the server side. website establishes an SSL connection with WWPass core (using its WWPass client certificate)

wwc = New WWPassConnection(Cert_file, PrivateKey_file );

Now the web server can save and retrieve user private info:

data = wwc->readData(ticket);
wwc->writeData(ticket,newdata);

When you implement an authentication (PUID) only, the server-side process is as follows:

wwc = New WWPassConnection(Cert_file, PrivateKey_file);
puid = wwc->getPUID(ticket);