developer’s setup guide

DEVELOPER’S SETUP GUIDE WWPass® Web Application SDK for Python® Version 2.0.1

April 2014

© 2014 WWPass Corporation. All rights reserved.

WWPass is a registered trademark or trademark of WWPass Corporation in the United States and/or other jurisdictions.

Microsoft, Internet Explorer, and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

Linux is a registered trademark of Linus Torvalds.

All other product marks and names mentioned herein are trademarks of their respective owners.

This document supports the version of each product listed and supports all subsequent versions until the document is replaced by a new edition. To check for more recent editions of this document, see http://www.wwpass.com/support/documentation.

http://www.wwpass.com/support/documentation

Web Application SDK for Python Developer’s Setup Guide

TABLE OF CONTENTS

About this Document .................................................................................................................................. 5 SDK Overview ........................................................................................................................................ 5 Licensing ................................................................................................................................................ 5

Third-Party Licenses .......................................................................................................................... 5 Supported Operating Systems ............................................................................................................... 5 Developer’s Setup Guide Description .................................................................................................... 5

Document Organization ..................................................................................................................... 6 Customer Assistance ............................................................................................................................. 6

Please Give Us Feedback .................................................................................................................. 6

Chapter 1 — Functional Description .......................................................................................................... 7 Introduction............................................................................................................................................. 7 Prerequisites .......................................................................................................................................... 7

Chapter 2 — Python Package ................................................................................................................... 9 About the WWPass Python Authentication Library ................................................................................ 9

Class WWPassConnection ................................................................................................................ 9 Class WWPassConnectionMT ........................................................................................................... 9

Functions .............................................................................................................................................. 10 getName() ........................................................................................................................................ 11 getTicket() ........................................................................................................................................ 11 getPUID() ......................................................................................................................................... 11 putTicket() ........................................................................................................................................ 12 readData() ........................................................................................................................................ 13 readDataAndLock() .......................................................................................................................... 13 writeData() ........................................................................................................................................ 14 writeDataAndUnlock() ...................................................................................................................... 14 lock() ................................................................................................................................................. 15 unlock() ............................................................................................................................................. 15 createPFID() ..................................................................................................................................... 16 removePFID() ................................................................................................................................... 16 readDataSP() ................................................................................................................................... 16 readDataSPandLock() ...................................................................................................................... 17 writeDataSP() ................................................................................................................................... 17 writeDataSPandUnlock() .................................................................................................................. 18 lockSP() ............................................................................................................................................ 18 unlockSP() ........................................................................................................................................ 19

Authentication Example ....................................................................................................................... 20

Appendix A — Authentication Example ................................................................................................... 21 Basic WWPass Authentication Example Setup ................................................................................... 21

Preconditions.................................................................................................................................... 21 Environmental Setup ........................................................................................................................ 21

Python Authentication Example ........................................................................................................... 21

WWPass Corporation


Basic Authentication Example – webapp.py .................................................................................... 21

Appendix B — Document Text Conventions............................................................................................ 23 Appendix C — Abbreviations and Definitions .......................................................................................... 25

Appendix D — JavaScript Usage ............................................................................................................. 27 About the WWPass JavaScript Library ................................................................................................ 27 Including wwpass.js in a Web Page ..................................................................................................... 27 Functions of wwpass.js ........................................................................................................................ 27

Function wwpass_auth (ticket, callback) .......................................................................................... 27 Function wwpass_plugin_on_key_removed (callback) .................................................................... 28

Variables of wwpass.js ......................................................................................................................... 29 Variables in the wwpass.js Library ....................................................................................................... 30

Index ......................................................................................................................................................... 31

WWPass Corporation


ABOUT THIS DOCUMENT

SDK Overview The WWPass Web Application SDK for Python® includes all the components necessary to work with the WWPass Authentication Core API, including files, libraries and sample code, and facilitates development of client authentication solutions that target the WWPass Authentication Core API. The API will be described in detail as to what functionality is provided as well as the options/parameters that can be passed, and the errors that may be seen.

The WWPass PassKey™ is a requirement for user authentication. The PassKey is a hardware device that enables authentication and access for a given user. When configured with a second authentication method, WWPass authentication allows the ability to use login/password pairs to provide seamless binding of a PassKey to existing user accounts.

For more information about how to obtain a PassKey and register it, please refer to the WWPass web site (http://www.wwpass.com)

Licensing The WWPass Web Application SDK for Python is licensed under the Apache® 2.0 license. This license applies to all source code, code examples and accompanying documentation contained herein. You can modify and re-distribute the code with the appropriate attribution. This software is subject to change without notice and should not be construed as a commitment by WWPass.

You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, the software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

Third-Party Licenses This product may include software developed by parties other than WWPass. The text of the license agreements applicable to third-party software in this product may be viewed online at wwpass.com.

Supported Operating Systems Python is a general-purpose programming language. The WWPass Web Application SDK for Python is supported on any operating system that can run Python.

Developer’s Setup Guide Description The Web Application SDK for Python Developer’s Setup Guide is intended for application developers and describes the Service Provider Front End Client Libraries and how to use an example implementation of WWPass authentication. This guide also includes information about running the sample application included with the Web Application SDK for Python, as well as using JavaScript® in certain Web applications.

This document assumes the reader has some programming proficiency with Python, JavaScript, and HTML.

WWPass Corporation

http://www.wwpass.com/

http://www.apache.org/licenses/LICENSE-2.0

http://wwpass.com/


Document Organization This section contains a brief overview of this guide. The remainder of the document is organized as follows:

• Chapter 1 — Functional Description • Chapter 2 — Python Package • Appendix A — Authentication Example • Appendix B — Document Text Conventions • Appendix C — Abbreviations and Definitions • Appendix D — JavaScript Usage • Index

Customer Assistance If you encounter a problem or have a question, you can contact the WWPass Service Desk as follows:

Phone 1-888-WWPASS0 (+1-888-997-2770)

Email [email protected]

Online Support form

Please Give Us Feedback We are interested in receiving opinions on this manual from our users. In particular, we’d like to hear from users who have never used WWPass before. Does this guide explain the topic well? Please let us know what you think; we can be reached at [email protected].

WWPass Corporation

mailto:[email protected]

http://www.wwpass.com/support/support-form

mailto:[email protected]


CHAPTER 1 — FUNCTIONAL DESCRIPTION

Introduction The WWPass Web Application SDK for Python comprises a library, examples and documentation that is installed on a Service Provider’s system to allow authentication using the WWPass system. The WWPass Authentication Service is an alternative to, or replacement for, other authentication methods such as user name/password. The sections that follow describe language-specific API calls associated with the WWPass Authentication Service. Each reference will describe the declaration of the API, the parameters required and their meaning, followed by the expected return value(s) and raised exceptions, if any.

Prerequisites To use the WWPass Authentication Service, you must have a WWPass PassKey, and a major component of the WWPass authentication capability is the software that supports the PassKey itself. Without this software, requests to an end user to authenticate their identity will fail since this software is used to directly access information stored on the PassKey and communicate with WWPass. To allow Administrator testing of the authentication infrastructure, this client software and an accompanying PassKey is required.

Note: The WWPass PassKey is a small electronic device that is available as a USB/NFC token. Before a user can authenticate with a PassKey, the PassKey and its corresponding Service Keys must be initialized with WWPass Key Services (https://ks.wwpass.com).

WWPass Corporation

https://ks.wwpass.com/

https://ks.wwpass.com/


This page intentionally left blank.

WWPass Corporation


CHAPTER 2 — PYTHON PACKAGE

About the WWPass Python Authentication Library The Python library consists of a single file, wwpass.py. There are two classes:

• WWPassConnection • WWPassConnectionMT

Both classes have the same interface. MT stands for Multi-Threaded; it should be used if several threads will access the same instance of the class. WWPassConnectionMT allocates a pool of connections to the SPFE. The pool will grow on demand.

The WWPass Python library depends on the Python cURL library with SSL support.

Class WWPassConnection

Declaration

WWPASSConnection(key_file, cert_file, timeout = 10, spfe_addr='https://spfe.wwpass.com'. cafile = None)

Purpose

WWPassConnection is the class for a WWPass SPFE connection, and a new connection is initiated every time a connection request is made. The WWPass CA certificate is required for validating the SPFE certificate and can be downloaded at https://spfe.wwpass.com/downloads.

Parameters

Name Description

key_file The path to the Service Provider’s private key.

cert_file The path to the Service Provider’s certificate.

timeout Timeout measured in seconds. It is used in all operations. The default is 10 seconds.

spfe_addr The hostname or base URL of the SPFE. The default name is https://spfe.wwpass.com.

cafile The path to the WWPass Service Provider CA certificate (optional).

Exception (Throw)

WWPassException is thrown.

Class WWPassConnectionMT

Declaration

WWPASSConnectionMT(key_file, cert_file, timeout=10, spfe_addr='https://spfe.wwpass.com', ca_file = None, initial_connections = 2)

Purpose

WWPassConnectionMT is an extension over the WWPassConnection class to support multi-threaded applications. The actual number of connections grows based on demand.

Parameters

WWPass Corporation

https://spfe.wwpass.com/downloads

https://spfe.wwpass.com/


Name Description

keyFile The path to the Service Provider's private key.

certFile The path to the Service Provider's certificate.

timeout Timeout measured in seconds. It is used in all operations. The default is 10 seconds.

spfeAddr The hostname or base URL of the SPFE. The default name is https://spfe.wwpass.com.

ca_file The path to the WWPass Service Provider CA certificate (optional).

initial_connections The number of connections to the SPFE that are initially set up. The default is 2.

Exception (Throw)

WWPassException is thrown.

Functions The following functions operate the same way for both classes, WWPassConnection and WWPassConnectionMT. All functions return a tuple (success, data). If an operation was successful, a tuple is (True, <return value>). If an error has occurred, a (False, <error message>) tuple is returned.

• getName() • getTicket() • getPUID() • putTicket() • readData() • readDataAndLock() • writeData() • writeDataAndUnlock() • lock() • unlock() • createPFID() • removePFID() • readDataSP() • readDataSPandLock() • writeDataSP() • writeDataSPandUnlock() • lockSP() • unlockSP()

WWPass Corporation

https://spfe.wwpass.com/


getName()

Declaration

WWPASSConnection.getName()

Purpose

Calls to this function acquire the SP name on the certificate which was used for initiate this WWPassConnection instance.

Returns

(True, <SP name>) or (False, <error message>)

getTicket()

Declaration

WWPassConnection.getTicket(ttl=120, auth_types = '')

Purpose

A call to this function acquires a newly-issued ticket from SPFE.

Parameters

Name Description

ttl The period in seconds for the ticket to remain valid since issuance. The default value is 120 seconds.

auth_types Defines which credentials will be asked of the user to authorize this ticket. Currently only two values supported: ‘p’: to ask for PassKey and password; empty string to ask for PassKey only (default).

Returns

(True, <Ticket issued by the SPFE>) or (False, <error message>)

getPUID()

Declaration

WWPASSConnection.getPUID(ticket, auth_types='')

Purpose

WWPassConnection.getPUID gets the id of the user from the Service Provider Front End. This ID is unique for one Service Provider, and different for different Service Providers.

WWPass Corporation


Parameters

Name Description

ticket The authenticated ticket.

auth_types Defines which credentials should have been asked of the user to authenticate this ticket. Currently, only two values are supported: 'p' for a PassKey and access code, '' (empty string) for a PassKey only (default).

Returns

(True, <PUID>) or (False, <error message>)

putTicket()

Declaration

WWPassConnection.putTicket(ticket, ttl=120, auth_types = '')

Purpose

A call to this function checks the authentication of the ticket and may issue a new ticket from SPFE. All subsequent operations should use a returned ticket instead of one provided to putTicket.

Parameters

Name Description

ticket The ticket to validate.

ttl The period in seconds for the ticket to remain valid since issuance. The default value is 120 seconds.

auth_types Defines which credentials will be asked of the user to authorize this ticket. Currently only two values supported: ‘p’: to ask for PassKey and password; empty string to ask for PassKey only (default).

Returns

(True, <original or newly-issued ticket>) or (False, <error message>)

The new ticket should be used in future operations with the SPFE.

WWPass Corporation


readData()

Declaration

WWPASSConnection.readData(ticket, container='')

Purpose

Calls to this function request data stored in the user’s data container.

Parameters

Name Description

ticket The authenticated ticket issued by the SPFE.

container Arbitrary string (only the first 32 bytes matter) that identifies the user’s data container.

Returns

(True, <data>) or (True, None) if the container was never written to, or (False, <error message>)

readDataAndLock()

Declaration

WWPASSConnection.readDataAndLock(ticket, lockTimeout, container='')

Purpose

Calls to this function request data stored in the user’s data container and tries to atomically lock an associated lock.

Parameters

Name Description


lockTimeout The period in seconds for the data container to remain protected from the new data being accessed.


Returns

(True, <data>) or (True, None) if the container was never written to, or (False, <error message>)

WWPass Corporation


writeData()

Declaration

WWPASSConnection.writeData(ticket, data, container='')

Purpose

Calls to this function write data into the user’s data container.

Parameters

Name Description


data The string to write into the container.


Returns

(True, None) or (False, <error message>)

writeDataAndUnlock()

Declaration

WWPASSConnection.writeDataAndUnlock(ticket, data, container='')

Purpose

A call to this function writes data into the user's Data Container and unlocks an associated lock. If the lock is already unlocked, the write will succeed, but the function will return an appropriate error.

Parameters

Name Description




Returns


WWPass Corporation


lock()

Declaration

WWPASSConnection.lock(ticket, lockTimeout, lockid='')

Purpose

A call to this function tries to lock a lock identified by the user (by authenticated ticket) and lock ID.

Parameters

Name Description


lockTimeout The period in seconds for the data container to remain protected from the new data being accessed.

lockid The arbitrary string (only the first 32 bytes matter) that identifies the lock.

Returns


unlock()

Declaration

WWPASSConnection.unlock(ticket, lockid='')

Purpose

A call to this function tries to unlock a lock identified by the user (by authenticated ticket) and lock ID.

Parameters

Name Description


lockid The arbitrary string (only the first 32 bytes matter) identifying the lock.

Returns


WWPass Corporation


createPFID()

Declaration

WWPASSConnection.createPFID(data='')

Purpose

A call to this function creates a new SP-only container with a unique name and returns its name. If the data parameter is provided, it writes data to this container. Concurrent create requests will never return the same PFID.

Parameters

Name Description

data The data to write to this container.

Returns

(True, <PFID of created container>) or (False, <error message>)

removePFID()

Declaration

WWPASSConnection.removePFID(pfid)

Purpose

Destroys the SP-specific data container. The container will then become non-existent as if it were never created.

Parameters

Name Description

pfid The PFID of the data container to destroy.

Returns


readDataSP()

Declaration

WWPASSConnection.readDataSP(pfid)

Purpose

Calls to this function request data stored in the SP-specific data container.

Parameters

Name Description

pfid The PFID of the Data Container as returned by createPFID.

WWPass Corporation


Returns

(True, <data>) or (True, None) if the container does not exist, or (False, <error message>)

readDataSPandLock()

Declaration

WWPASSConnection.readDataSPandLock(pfid, lockTimeout)

Purpose

Calls to this function request the binary data stored in the Service Provider's Data Container and try to atomically lock an associated lock.

Parameters

Name Description

pfid The Data Container Identifier as returned by createPFID.

lockTimeout Timeout in seconds after which the lock will expire.

Returns

(True, <data>) or (True, None) if the container does not exist, or (False, <error message>)

writeDataSP()

Declaration

WWPASSConnection.writeDataSP(pfid, data)

Purpose

Writes data into the SP-specific data container.

Parameters

Name Description



Returns


WWPass Corporation


writeDataSPandUnlock()

Declaration

WWPASSConnection.writeDataSPandUnlock(pfid, data)

Purpose

Writes data into the SP-specific data container and unlocks an associated lock. If the lock is already unlocked, the write will succeed, but the function will return an appropriate error.

Parameters

Name Description



Returns


lockSP()

Declaration

WWPASSConnection.lockSP(lockid, lockTimeout)

Purpose

A call to this function tries to lock a lock identified by lockid.

Parameters

Name Description


lockTimeout The period in seconds for the SP data to remain protected from the new data being accessed.

Returns


WWPass Corporation


unlockSP()

Declaration

WWPASSConnection.unlockSP(lockid)

Purpose

A call to this function tries to unlock a lock identified by lockid.

Parameters

Name Description


Returns


WWPass Corporation


Authentication Example The Python authentication example is located in Appendix A of this guide.

WWPass Corporation


APPENDIX A — AUTHENTICATION EXAMPLE

Basic WWPass Authentication Example Setup

Preconditions You have registered your site and have received WWPass Service Provider (SP) credentials (certificate and private key). If, for example, your site has the URL of "mysite.com" and you follow the recommended file naming convention when obtaining SP credentials, the files will be named as mysite.com.crt (for the certificate) and mysite.com.key (for the private key). The WWPass CA certificate should also be downloaded and made accessible to our application. If you have root access to your computer, then the /etc/ssl folder is an appropriate place to store the certificates and the key. Make sure that the script will have enough rights to read the files there. Usually access to /etc/ssl/private is quite limited.

Environmental Setup

Linux

1. Verify that you have Python Version 2.7 on your system. 2. Download the Python SDK from the WWPass Developer Site. 3. Place your SP credentials (certificate and private key) in a directory that is accessible by your

Python script.

Python Authentication Example

Basic Authentication Example – webapp.py In this snippet, the parameters of the code are established. Set your own ServiceProvider name and paths to the certificate files. As the server we are using creates a new thread for each request, we use WWPassConnectionMT.

Next, if the SPNAME was not set, it will be determined automatically.

SPNAME = None FCA = wwpass.ca.crt

Note: The following example code intentionally lacks error checking and reporting for the sake of simplicity and clarity. You will need to configure the following parameters in the example code Configuration Block:

• SPNAME – Service Provider name (i.e. mycompany.com)

• FKEY – Absolute path to your Service Provider’s private key (i.e. /home/user/ssl/mycompany.com.key OR C:/ssl/mycompany.com.key)

• FCERT – Absolute path to your Service Provider’s client certificate (i.e. /home/user/ssl/mycompany.com.crt OR C:/ssl/mycompany.com.crt)

• FCA – Absolute path to the WWPass CA certificate (i.e. /home/user/ssl/wwpass_sp_ca.crt OR C:/ssl/ wwpass_sp_ca.crt)

conn = WWPASSConnectionMT(FKEY, FCERT, 15, 'https://spfe.wwpass.com', FCA, 0)

WWPass Corporation

https://developers.wwpass.com/downloads/wwpass.ca


Next, the three templates of HTML pages are loaded. The first template (templates/home.html) is a login page. This template is simply served by the do_GET() handler of the HelloHandler class. It contains a simple JavaScript that loads the WWPass JavaScript library, starts the WWPass authentication and passes the result through a form back to the server. Note that SPNAME is set by the server in this template. The second page (templates/puid.html) is displayed on the form's POST request. The handler for it is a do_POST() function in the same class. After parsing the query parameters, the status of the authentication is checked. If the response code is 200 (OK), an authenticated ticket is extracted from the POST parameters.

Then, a getPUID is called to get a user's PUID, which is simply displayed to the user with the second page (templates/puid.html). (If this had been a real application, the PUID would be used in a query to a user database.)

In this snippet, the status will be True or False depending on whether or not the operation was successful. After the PUID or an error message is received, the result is displayed to the user using the appropriate template with the second page (templates/puid.html) displaying the PUID in case of success, or the third page (templates/error.html) displaying an error message if the call failed.

if not SPNAME: status, SPNAME = conn.getName() if not status: exit('Connection fail :(')

if 'wwpass_status' in postvars and postvars['wwpass_status'][0] == '200': # Success ticket = postvars['wwpass_response'][0]

# load template HOME = open(‘templates/home.html’).read() PUID = open(‘templates/puid.html’).read() ERROR = open(‘templates/error.html’).read()

status, response = conn.getPUID(ticket)

WWPass Corporation


APPENDIX B — DOCUMENT TEXT CONVENTIONS

Table 1 shows a list of type styles used throughout this document.

Table 1. Document Text Conventions

Convention Description Example

Monospace Indicates source code, code examples, input to the command line, application output, and code lines embedded in text, and variables and code elements.

Public Class apt-get

Bold Indicates most predefined programming elements, including namespaces, classes, interfaces, methods, functions, macros, structures, properties, enumerations, fields, operators, statements, data types, keywords, exceptions, and non-HTML attributes. Also indicates filenames with appropriate file type extension, if applicable, and directory paths.

Namespace req Config.txt /var/www

Bracket Indicates a placeholder for valid options within configuration files. All valid options will be listed within brackets (‘<>’) and separated by vertical bar (ASCII character ‘|’), sometimes called a "pipe.“

<your_file_here.txt> <on | off>

Code Snippet A code snippet is a block of reusable code that can be inserted where you need it. Snippets can either be simple or complex—for example, blocks such as “try-finally” and “if-else” are commonly used, but snippets can also be used to insert entire classes or methods.

try { } finally { }

Italic Indicates placeholders, most often method or function parameters and HTML placeholders; these placeholders represent information that must be supplied by the implementation or the user. Also used to indicate a document note.

Cookie=wwpass.com Note: Text

Hypertext Link Indicates a web address that can be accessed outside of the current document that contains application source code, application binaries, or supplemental reference information to the text provided.

http://www.google.com

Capital Letters Indicates the names of keys and key sequences. Also indicates HTML element names

ENTER CTRL+R

<A HREF>

Plus Sign Indicates a combination of keys. For example, ALT+F1 means to hold down the ALT key while pressing the F1 key.

ALT+F1

WWPass Corporation

http://www.google.com/


This page intentionally left blank.

WWPass Corporation


APPENDIX C — ABBREVIATIONS AND DEFINITIONS

Table 2 describes the common terminology and abbreviations that are associated with WWPass authentication technology.

Table 2. Common Terminology and Abbreviations

Term Abbreviation Definition

Certificate Authority CA An entity that issues a digital certificate which validates the authenticity of a Service Provider.

Clockwise scheme CW One of two possible protocol flavors which may be used depending on many factors (e.g., on available or desired data transmission media (physical layer). Recommended for new development.

Counterclockwise scheme CCW One of two possible protocol flavors which may be used depending on many factors (e.g., on available or desired data transmission media (physical layer). Not recommended for new development.

Data Container User’s data stored in WWPass infrastructure describing a particular user for a particular Service Provider.

Hypertext Transfer Protocol

HTTP A file transfer protocol primarily used to send/receive data formatted using the Hypertext Markup Language (HTML).

Identity Provider IdP Any entity that can verify the authenticity of a user.

PassKey™ The WWPass PassKey is a small electronic device that is available as a USB/NFC token.

Provider User Identifier PUID A random string that identifies the user to the service provider. The PUID stays the same for multiple authorization of same User with same Service Provider. It is guaranteed that different users will have different PUIDs on one Service Provider. The PUIDs that a user may have across multiple Service Providers do not correlate in any way.

Provider File Identifier PFID Name of data container that can be accessed by the Service Provider without a user. This container is not linked to any user and can be used as a general storage for sensitive but not user-specific information

Service Provider SP An entity that provides services to third parties while using WWPass Authentication Services.

Service Provider Identifier SPID A unique identifier attributed to a specific Service Provider within the WWPass authentication system.

Ticket The distinct unique identifier for a single-authentication transaction.

User ID The unique user identifier referenced by the WWPass system.

WWPass Service Provider WWP-SP The designation for any entity that provides services to third parties while using the WWPass Authentication

WWPass Corporation


Term Abbreviation Definition

Service.

WWPass Service Provider Front End

SPFE A part of the WWPass infrastructure responsible for communication with Service Providers.

WWPass User Front End User FE A part of the WWPass infrastructure responsible for communication with Users.

WWPass Corporation


APPENDIX D — JAVASCRIPT USAGE

About the WWPass JavaScript Library The WWPass JavaScript Library consists solely of the wwpass.js file. This library enables the ticket exchange process between a Service Provider’s application and the WWPass Authentication Service. The main purpose of the library is to simplify interactions with WWPass browser plugin that is installed on a user’s system as to facilitate authentication with a WWPass PassKey.

The most common usage scenario is to include wwpass.js in a web page containing a "Login" button or link. The embedded link calls the wwpass_auth function with an authentication ticket and callback arguments. When authentication is completed, the callback is invoked and the result, including a status code and an authenticated ticket, is passed to the callback.

The latest version of the WWPass JavaScript Library is available on the WWPass website: http://cdn.wwpass.com/packages/wwpass.js/2.1/wwpass.js

Including wwpass.js in a Web Page To include wwpass.js in an HTML page or template, use the following script tag.

In the preceding snippet, wwpass.js is included from the WWPass website. While there may be a reason to use a local copy of wwpass.js, it is generally better to include it from the WWPass website. Referring to the remote copy ensures that the Service Provider stays in sync with the latest version of the code.

Functions of wwpass.js The main function exported by the wwpass.js library is wwpass_auth.

Function wwpass_auth (ticket, callback) Authentication is performed with the wwpass_auth function. When a user asks to log in with WWPass, wwpass_auth is called with the arguments ticket and callback.

The function attempts to authenticate the ticket by querying the authentication software installed on a user's computer (WWPass browser plugin). When the authentication operation is complete, the callback is invoked and the authentication result, including authentication status code and authenticated ticket or exception message string, is passed to the callback.

Applications should check the resultCode argument and either proceed with authentication or display an exception message to users based on the value of the argument.

<html> <head> <script type="text/javascript"

src="//cdn.wwpass.com/packages/wwpass.js/2.1/wwpass.js"> </script> </head> <body>

.

.

. </body>

</html>

WWPass Corporation

http://cdn.wwpass.com/packages/wwpass.js/2.1/wwpass.js


Parameters

Name Description

ticket Either the ticket recently issued by an SPFE or the SP’s name in URL-encoded form (like “SomeServiceProvider”); add ":p" at the end of SP’s name string in order to enable two-factor authentication.

callback

(resultCode, ticketOrMessage)

Function to be called when authentication operation is complete.

resultCode – Integer number.

Function wwpass_plugin_on_key_removed (callback) The function wwpass_plugin_on_key_removed is designed for use when a Service Provider wants to terminate a user session when the user’s PassKey is removed. The function detects whether a PassKey has been removed. When the authentication operation is complete, the callback function is invoked and the result, including removal detection status code and result message string, is passed to the callback.

Parameters

Name Description

Callback Function to be called when authentication operation is complete.

(resultCode, resultMessage)

resultCode – Integer number.

resultMessage – A human readable status message for PassKey removal detection.

WWPass Corporation


Variables of wwpass.js In case a little tweaking of WWPass.js behavior is needed, the function has a few internal variables that can be modified.

One of the important variables included in the wwpass.js library is WWPass_DebugJs.

The WWPass_DebugJs variable controls wwpass.js debug output:

• If the variable is set to 1 or True, wwpass.js outputs debug information that can be viewed using the debugging facilities of a browser (e.g. Firebug in Firefox, Developer Tools in Safari, etc.).

• If the variable is set to 0 or False, wwpass.js debug output is turned off.

The code snippet below demonstrates how to turn on the wwpass.js debugging output:

<html> <head> <script type="text/javascript"> var WWPass_DebugJs = 1; // Turn wwpass.js debugging output on </script> <script type="text/javascript" src="//cdn.wwpass.com/packages/wwpass.js/2.1/wwpass.js"> </script> </head> </html>

WWPass Corporation

https://cdn.wwpass.com/packages/wwpass.js/2.1/wwpass.js


Variables in the wwpass.js Library All of the variables in the wwpass.js library are shown WWPass.js library are shown below.

/* Configuration */ var WWPass_Interfaces = WWPass_Interfaces || ['plugin']; // list of interfaces in order of preference var WWPass_DebugJs = WWPass_DebugJs || false; var WWPass_JsVersion = '2.1.4'; /* Constants */ /* Status codes */ var WWPass_CONTINUE = 100; var WWPass_OK = 200; var WWPass_OK_Msg = 'OK'; var WWPass_INTERNAL_ERROR = 400; var WWPass_ALREADY_PERSONALIZED = 401; var WWPass_PASSWORD_MISMATCH = 402; var WWPass_PASSWORD_LOCKOUT = 403; var WWPass_WRONG_KEY = 404; var WWPass_WRONG_KEY_SECOND = 405; var WWPass_NOT_A_KEY = 406; var WWPass_NOT_A_KEY_SECOND = 407; var WWPass_KEY_DISABLED = 408; var WWPass_NOT_ALLOWED = 409; var WWPass_BLANK_TOKEN = 410; var WWPass_BLANK_SECOND_TOKEN = 411; var WWPass_ACTIVITY_PROFILE_LOCKED = 412; var WWPass_SSL_REQUIRED = 413; var WWPass_BLANK_NORMAL_TOKEN = 414; var WWPass_BLANK_SECOND_NORMAL_TOKEN = 415; var WWPass_BLANK_MASTER_TOKEN = 416; var WWPass_BLANK_SECOND_MASTER_TOKEN = 417; var WWPass_NOT_ACTIVATED_TOKEN = 418; var WWPass_NOT_ACTIVATED_SECOND_TOKEN = 419; var WWPass_WRONG_KEY_SET = 420; var WWPass_NO_VERIFIER = 421; var WWPass_INCOMPLETE_KEYSET = 422; var WWPass_INVALID_TICKET = 423; var WWPass_TERMINAL_ERROR = 500; var WWPass_TERMINAL_NOT_FOUND = 501; var WWPass_TERMINAL_BAD_REQUEST = 502; var WWPass_NO_CONNECTION = 503; var WWPass_NETWORK_ERROR = 504; var WWPass_PROTOCOL_ERROR = 505; var WWPass_UNKNOWN_HANDLER = 506; var WWPass_TERMINAL_CANCELED = 590; var WWPass_TIMEOUT = 600; var WWPass_USER_REJECT = 603; var WWPass_NO_AUTH_INTERFACES_FOUND = 604; var WWPass_NO_AUTH_INTERFACES_FOUND_Msg = "No WWPass software found"; var WWPass_TERMINAL_TIMEOUT = 605; /* end of status codes*/

WWPass Corporation


INDEX

A Abbreviations and Definitions, 25

About the WWPass Python Authentication Library, 9 About this Document, 5

C Customer Assistance, 6

D Document Text Conventions, 23

F Feedback, 6 Function wwpass_auth (ticket, callback), 27 Function wwpass_on_key_removed (callback), 28 Functional Description, 7

I Including wwpass.js in a web page, 27

J JavaScript Authentication Library, 27

L Licensing,5

P Prerequisites, 7

S Supported Operating Systems, 5

T Third-Party Licenses, 5

V Variables of wwpass.js, 29 Variables in the wwpass.js library, 30

WWPass Corporation

WWPass | 1155 Elm Street, Manchester, NH 03110 | Tel: +1.603.836.4932 or +1.888.997.2771 | www.wwpass.com

http://www.wwpass.com/

developer’s setup guide

Documents