The gssweb API

The gssweb web authentication libraries implement user authentication using the gssweb protocols. The libraries add an a new gssweb getter on the window.navigator object, which is the means of accessing the gssweb API.

The gssweb getter

The gssweb getter is one call:

This method will return one gssweb session object per origin. Applications should not assume that this object will represent an authenticated session.

The gssweb Object

Properties

The gssweb object provides the following properties:

version

The version property is the version number for the gssweb library.

serverPath

The serverPath property specifies the path to the gssweb endpoint on the server. This endpoint must exist on the origin server for the current web page. The system will append '/authenticate' and '/release' to the serverPath when issuing requests for the authenticate() and release() methods, respectively. This defaults to '/gssweb'.

authenticationState

The authenticationState property holds the current authentication state for this gssweb object. Possible values are true for authenticated and false for not authenticated.

credential

The credential property is an object representing the credential currently held by the user. It is defined later in this document.

onAuthenticateSuccess

A callback function invoked upon successful creation of the authentication session. Applications should use this callback to inform the user of the new authentication status. This function should have the following signature:

function onAuthenticateSuccess(data) {};

Its parameter, data, is used to communicate information about the authentication session from the server to the client. (This is intentionally left opaque at this point.)

onAuthenticateError

A callback function invoked upon a failed attempt to create the authentication session. Applications should use this callback to inform the user of the error in creating the authentication session. If this callback is not supplied, then a default This function should have the following signature:

function onAuthenticateError(err) {};

Its parameter, err, holds the error that caused the failure in the creation of the authentication session. It should be used to inform the user of the error status.

onRelease

A callback function invoked upon the release of the authentication session. Applications should use this callback to inform the user that the authentication session has been released. After this callback runs, the authenticationState property will be reset to false, the credentials will be destroyed, and the authentication session will be destroyed on the client.

Methods

The gssweb object provides two methods:

authenticate()

The authenticate() method is invoked to request that the system authenticate the user. When processing is completed, either the authenticateSuccess or authenticateError callback will be invoked.

release()

The release() method is invoked to release the authentication credential from the system. When it completes, the release callback is invoked. Unlike request(), there is no separate handling for an error state; the credential is destroyed on the client even if an error occurs in its destruction on the server.

The credential Object

Properties

The credential object provides no properties.

Methods

The credential object provides the following methods:

setUsername()

The setUsername() method sets the username on the unauthenticated credential. If called with undefined, called without also calling setPassword(), or not called at all, the system will prompt the user to provide the credentials for this authentication session. Once the session has been authenticated, the setUsername() function will return an error.

This username should be in Network Access Identifier form – generally speaking, “user@realm”.

getUsername()

The getUsername() method returns the current username of the credential.

setPassword()

The setPassword() sets the password on the unauthenticated credential. If the password is set without the username being set, the password will be ignored. If setPassword() is called after the session has been authenticated, it will return an error.

The GSS API

In addition, the library provides access to GSS-API functions through a gss property on the gssweb object. While this API is available, it should be considered unstable for application development, and is provided primarily as reference for library implementation.

• navigator.gss_eap.gss.init_sec_context

• navigator.gss_eap.gss.import_name

• navigator.gss_eap.gss.acquire_cred

• navigator.gss_eap.gss.wrap

• navigator.gss_eap.gss.unwrap

• navigator.gss_eap.pseudo_random

• navigator.gss_eap.get_mech