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:
GSSWEB GETTER |
---|
gssweb = navigator.gssweb(); |
This method will return one gssweb session object per origin. Applications should not assume that this object will represent an authenticated session.
Properties
The gssweb object provides the following properties:
GSSWEB PROPERTIES |
|
---|---|
version |
The version of the gssweb library |
serverPath |
The path on the web server where authentication and release can occur |
authenticationState |
The current authentication state |
credential |
The credential used for authentication, if known |
onAuthenticateSuccess |
The function called upon successful authentication |
onAuthenticateError |
The function called upon error in authentication |
onRelease |
The function called upon release of the authentication session |
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:
GSSWEB METHODS |
|
---|---|
authenticate |
Create an authentication session |
release |
Destroy the current authentication session |
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.
Properties
The credential object provides no properties.
Methods
The credential object provides the following methods:
CREDENTIAL METHODS |
|
---|---|
setUsername |
Set the username for this credential |
getUsername |
Get the username from this credential |
setPassword |
Set the password for this credential |
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.
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