Webinos Logo

Authentication API

Webinos API Specifications

23 Aug 2012

Authors


Abstract

Provides information to applications about the current authentication status of users

Table of Contents

  1. Introduction
  2. Interfaces and Dictionaries
    1. AuthStatus
    2. WebinosAuthenticationInterface
    3. Webinos
  3. Callbacks
    1. AuthSuccessCB
    2. IsAuthenticatedSuccessCB
    3. AuthErrorCB
  4. Features
  5. Full WebIDL

Summary of Methods

Interface Method
WebinosAuthenticationInterface void authenticate(AuthSuccessCB successCB, AuthErrorCB errorCB)
void isAuthenticated(IsAuthenticatedSuccessCB successCB, AuthErrorCB errorCB)
void getAuthenticationStatus(AuthSuccessCB successCB, AuthErrorCB errorCB)
Webinos

Introduction

Authentication API for providing applications with information about whether the current user has authenticated, and requesting re-authentication at runtime.

Requirement/architectural reference: PS-USR-Oxford-121

This API intentionally does not reveal identity information, but can give details about authentication method, which may reveal device information.

Interfaces and Dictionaries

Dictionary AuthStatus

The object returned when user authentication status is queried. This contains information about when and how authentication occurred.

WebIDL
  dictionary AuthStatus  {
     DOMString? lastAuthTime;
     DOMString? authMethod;
     DOMString? authMethodDetails;
  };

Dictionary Members

DOMString? lastAuthTime

The time of last authentication, as a valid date or time string.

Code example
 {lastAuthTime: '2011-03-24T09:00-08:00'} // last authentication was on March 24, 2011 @ 5pm (UTC)
 
DOMString? authMethod

An identifier for the type of authentication performed by the user.
Intended to be flexible for different devices. Examples include "PIN", "Password", "Fingerprint". This is a high-level method name, no details.

DOMString? authMethodDetails

Further details as to the authentication method. This might include the authentication device identifier, or the numberof digits in PINS, or any device-specific value. Optional.

Interface WebinosAuthenticationInterface

The authentication interface provides three methods which allow applications to check the current user authentication status and prompt for re-authentication.

WebIDL
  [NoInterfaceObject]
  interface WebinosAuthenticationInterface {
     void authenticate (AuthSuccessCB successCB, optional AuthErrorCB errorCB);
     void isAuthenticated(IsAuthenticatedSuccessCB successCB, optional AuthErrorCB errorCB);
     void getAuthenticationStatus(AuthSuccessCB successCB, optional AuthErrorCB errorCB);
   };

Methods

authenticate

This method instructs the runtime to request that the user authenticate themselves.
The method for authentication is not specified, it may be through any means provided by the platform.

Signature
void authenticate(AuthSuccessCB successCB, optional AuthErrorCB errorCB);

Errors can occur due to: a policy restricting access to this API, or an unknown error in the device-specific authentication method.

This is an asynchronous method, although it may well be used (practice) synchronously.

Parameters
  • successCB
    • Optional: No.
    • Nullable: No
    • Type: AuthSuccessCB
    • Description: contains the status of the user with regards to authentication, including when and how he or she was last authenticated. It does not include user identity.
  • errorCB
    • Optional: Yes.
    • Nullable: No
    • Type: AuthErrorCB
    • Description: is a callback for when errors occur
Return value
void
isAuthenticated

Query the runtime to ask whether the user has recently been authenticated. How the platform determines this is not specified. It may return true if the user entered their PIN in the last 10 minutes, for example. It is expected that a platform preference based on current authentication status would be defined. These preferences are security-sensitive.

Signature
void isAuthenticated(IsAuthenticatedSuccessCB successCB, optional AuthErrorCB errorCB);

Throws a SecurityError exception if policy restricts access to the API, or if the platform does not have a definitive answer due to a misconfigured preference or lack of information.

This is a synchronous method. Expected use would be to check at an important place whether the user is authenticated and, if not, call "authenticate" to do so.

Parameters
  • successCB
    • Optional: No.
    • Nullable: No
    • Type: IsAuthenticatedSuccessCB
    • Description: True if the user has been authenticated to the satisfaction of the platform.
  • errorCB
    • Optional: Yes.
    • Nullable: No
    • Type: AuthErrorCB
    • Description: is a callback for when errors occur
Return value
void
getAuthenticationStatus

Query the runtime for precise details about the current state of the user with regard to authentication.
Throws a SecurityError exception if policy restricts access to the API

Signature
void getAuthenticationStatus(AuthSuccessCB successCB, optional AuthErrorCB errorCB);

This is an asynchronous method. Expected use is for when an application is determining whether the user ought to re-authenticate, or whether the user is suitably authenticated for a particular action. Future versions of this API may be able to insist that the user authenticates in a certain way.

Parameters
  • successCB
    • Optional: No.
    • Nullable: No
    • Type: AuthSuccessCB
    • Description: contains the boolen status of the user with regards to authentication
  • errorCB
    • Optional: Yes.
    • Nullable: No
    • Type: AuthErrorCB
    • Description: is a callback for when errors occur
Return value
void

Interface Webinos (partial interface)

The Webinos interface describes the part of the Authentication API accessible through the webinos object.

WebIDL
  partial interface Webinos {
     readonly attribute WebinosAuthenticationInterface authentication;
  };

Attributes

readonly WebinosAuthenticationInterface authentication

webinos.authentication object.

This attribute is readonly.

Callbacks

AuthSuccessCB

Success callback for authenticate() and getAuthenticationStatus() methods.

WebIDL
  callback AuthSuccessCB = void (AuthStatus status);
Signature
void AuthSuccessCB(AuthStatus status);
Parameters
  • status
    • Optional: No.
    • Nullable: No
    • Type: AuthStatus
    • Description: contains information about when and how authentication occurred

IsAuthenticatedSuccessCB

Success callback for isAuthenticated() method.

WebIDL
  callback IsAuthenticatedSuccessCB = void (boolean authenticated);
Signature
void IsAuthenticatedSuccessCB(boolean authenticated);
Parameters
  • authenticated
    • Optional: No.
    • Nullable: No
    • Type: boolean
    • Description: specifies whether the user is authenticated or not

AuthErrorCB

Error callback for authentication events.

WebIDL
  callback AuthErrorCB = void (DOMError error);
Signature
void AuthErrorCB(DOMError error);
Parameters
  • error
    • Optional: No.
    • Nullable: No
    • Type: DOMError
    • Description: DOMError object detailing what went wrong; e.g. SecurityError if permission denied, TimeoutError if operation timed out

Features

This is the list of URIs used to declare this API's features, for use in the widget config.xml and as identifier for service type in service discovery functionality. For each URI, the list of functions covered is provided.

http://webinos.org/api/authentication

Full WebIDL

WebIDL
  dictionary AuthStatus  {
     DOMString? lastAuthTime;
     DOMString? authMethod;
     DOMString? authMethodDetails;
  };
  
  callback AuthSuccessCB = void (AuthStatus status);
  
  callback IsAuthenticatedSuccessCB = void (boolean authenticated);

  callback AuthErrorCB = void (DOMError error);
  
  [NoInterfaceObject]
  interface WebinosAuthenticationInterface {
     void authenticate (AuthSuccessCB successCB, optional AuthErrorCB errorCB);
     void isAuthenticated(IsAuthenticatedSuccessCB successCB, optional AuthErrorCB errorCB);
     void getAuthenticationStatus(AuthSuccessCB successCB, optional AuthErrorCB errorCB);
   };
   
  partial interface Webinos {
     readonly attribute WebinosAuthenticationInterface authentication;
  };