JSDO properties, methods, and events reference : login( ) method (Session class)
  

login( ) method (Session class)

Note: Deprecated in Progress Data Objects Version 4.4 and later. Please use the login( ) method (JSDOSession class) instead.
Starts a JSDO login session on the current Session object by sending an HTTP request with specified user credentials to the URI of a specified web application.
On a successful login, the Session object sets its connected property to true. If the login fails, the object leaves its connected property set to false.
This method can be called synchronously or asynchronously, depending on parameters that you pass.
Note: Before invoking this method, ensure that you set the authenticationModel property on the Session object correctly (see the notes on authentication models).
Note: If the browser or mobile device has already authenticated a JSDO login session, this method completes successfully.
Note: This method does not support proxy servers (servers that function as a security service).
Return type: number
Applies to: progress.data.Session class

Syntax

login ( service-uri [ , username , password [ , login-target ] ] )
login ( parameter-object )
Note: If you call login( ) passing service-uri, the method executes synchronously. If you call it passing parameter-object, the method executes synchronously or asynchronously, depending on the setting of parameter-object.
service-uri
A string expression containing the URI of the web application for which to start the JSDO login session. This web application must support one or more Data Object Services in order to create JSDOs for the service resources provided by the application. If HTTP Basic Authentication is in effect for the web application (see the notes on authentication models), this URI is appended with a string that identifies a protected resource against which to authenticate the login session (see login-target).
If the mobile app from which you are logging in is a hybrid app that will be installed to run directly in a native device container, or if it is a web app deployed to a different web server from the web application that hosts the JSDO login session, you must specify service-uri as an absolute URI to the Tomcat server domain or host and port, for example, http://www.progress.com/SportsMobileApp, or perhaps for testing, http://testmach:8980/SportsMobileApp.
If the mobile app from which you are logging in is a web app deployed to the same Apache Tomcat server as the web application that hosts the JSDO login session, you can specify service-uri as a relative URI, for example, /SportsMobileApp, which is relative to the deployment end point (Tomcat server domain or host and port).
Note: Once the login( ) method executes, the value you pass for service-uri also sets the value of the sessionURI property on the current Session object, whether or not JSDO login completes successfully.
username
A string expression containing a user ID for the method to send to the web server for authentication.
Note: The userName property of the Session object returns the most recent value passed to this method for the current Session object.
password
A string expression containing a password for the method to send to the web server to authenticate the specified user.
login-target
A string expression that when appended to service-uri specifies a web application resource against which the specified user is authenticated. If you do not specify a value for login-target, the value is set to "/static/home.html" by default.
Note: The value returned by the loginTarget property of the Session object is either the value of the login-target parameter or the default ("/static/home.html").
parameter-object
An object that has one or more of the following properties:
*serviceURI — (Required) Same value as the service-uri parameter.
*userName — (Optional) Same value as the username parameter.
*password — (Optional) Same value as the password parameter.
*loginTarget — (Optional) Same value as the login-target parameter.
*async — (Optional) A boolean that, if true, tells login( ) to execute asynchronously. If false or absent, login( ) executes synchronously.
*iOSBasicAuthTimeout — (Optional) A number that specifies the time, in milliseconds, that the login( ) method waits for a response before returning an error. This error might mean that the user entered invalid credentials. If you set this value to zero (0), no timeout is set, and login( ) can wait indefinitely before returning an error. If you do not set the iOSBasicAuthTimeout property, login( ) uses 4000 (4 seconds) as the default value.
Any non-zero timeout value (default or otherwise) for this parameter-object property operates only under certain conditions, including when login( ) is executed asynchronously. Otherwise, any setting of this property has no effect. For more information, see the notes of the progress.data.Session class description.
When the method completes, it returns one of the following numeric constants to indicate the result:
*progress.data.Session.ASYNC_PENDING — The method is executing asynchronously. All asynchronous execution results (including any server errors) are returned in the afterLogin event that is fired on the Session object after the method completes. Before calling the method, you can subscribe one or more handlers to this event using the subscribe( ) method on the Session object.
*progress.data.Session.SUCCESS — JSDO login session started successfully. After you have downloaded Data Service Catalogs using the addCatalog( ) method for supported Data Object Services, you can create JSDOs for each Data Object resource provided by these services.
*progress.data.Session.AUTHENTICATION_FAILURE — JSDO login failed because of invalid user credentials (username or password).
*progress.data.Session.GENERAL_FAILURE — JSDO login failed because of a non-authentication failure.
It is also possible for this method to throw an Error object, in which case it does not return a value at all. You can also return the result for the most recent login attempt on the current Session object by reading the loginResult property. For a more specific status code returned in the HTTP response, you can check the value of the loginHttpStatus property. For more detailed information about any response (successful or unsuccessful) returned from the web server, you can also check the XMLHttpRequest object (XHR) returned by the lastSessionXHR property.
Note: When called asynchronously, any handler for the afterLogin event is passed the same information that is available for the login( ) method when it is called synchronously, including the Session object that executed login( ) (with the same property settings) and any Error object that was thrown processing the server response.
The general web server interaction with and response to this method depends on the authentication model that the web server uses and how resources are accessed and protected. You configure the authentication model for each web application deployed to the Apache Tomcat.
The JSDO supports the following authentication models, depending on the web application configuration:
*progress.data.Session.AUTH_TYPE_ANON — The web application supports Anonymous access. No authentication is required. This is the default value if you do not set it.
*progress.data.Session.AUTH_TYPE_BASIC — The web application supports HTTP Basic authentication and requires a valid username and password. To have the Session object manage access to the web application's resources for you, you need to pass these credentials in a call to the Session object's login( ) method. Typically, you would require the user to enter their credentials into a login dialog provided by your mobile app, either using a form of your own design or using a template provided by Progress Software.
*progress.data.Session.AUTH_TYPE_FORM — The web application uses HTTP Form-based authentication. Like HTTP Basic, Form-based authentication requires user credentials for access to protected resources; the difference is that the web application itself sends a form to the client to get the credentials. However, when you have the Session object manage access to the web application's resources, you handle Form-based authentication the same way that you handle Basic—get the user's credentials yourself and pass them to the login( ) method. The Session intercepts the form sent by the web application and handles the authentication without that form being displayed.
If the web application requires authentication, you must set this value in the Session object's authenticationModel property correctly to ensure that users can log in.
For more information on these authentication models and how to configure them for a web application, see the sections on configuring web server authentication models in the server documentation for your Data Object Service.
Caution: You must be sure that security is configured to complete authentication before the application requests resources in the Data Service Catalog. Although it is possible to configure application security so that only the Data Object resources in the Catalog require authentication, Progress does not recommend this approach. Instead, Progress recommends that you require authentication for application resources in addition to those defined in the Catalog, and require that the authentication occur prior to accessing any resources in the Catalog. (Note: This is the purpose of the login-target parameter, either one you pass to the login( ) method or its default.) Once the user is authenticated, the web server provides access to all other resources, including Catalog resources, according to the user's authorization settings.
Note: Unless the application design guarantees that the user will be prompted by the web browser or native device container to provide credentials before a login( ) call occurs, Progress recommends (in some cases requires) that the mobile app pass the credentials as parameters to the login( ) method. In addition, you must correctly set the value of the Session object's authenticationModel property. Coding the mobile app in this way ensures that the proper credentials are submitted to the server and promotes a favorable user experience.
Caution: To help ensure that HTTP Forms access to web applications works in certain web browsers, such as Firefox, when the web application is configured for Cross-Origin Resource Sharing (CORS), always call the login( ) method asynchronously.

Example

The following code fragment calls the login( ) method synchronously on the session, empSession by omitting the async property from its object parameter. For a similar example with the method called asynchronously, see the reference entry for the afterLogin event. This synchronous example uses try and catch blocks to check for either an expected return value, an invalid return value (as part of a test), or a thrown Error object with an unknown error, then assembles an appropriate message to display in an alert box:
var retValue;
var msg;

try {
retValue = empSession.login( {
serviceURI : "http://testmach:8980/SportsMobileApp",
userName : uname,
password : pw } );

if ( retValue === progress.data.Session.LOGIN_AUTHENTICATION_FAILURE ) {
msg = "Employee Login failed. Authentication error";
}
else if ( retValue === progress.data.Session.LOGIN_GENERAL_FAILURE ) {
msg = "Employee Login failed. Unspecified error";
}
else if ( retValue === progress.data.Session.LOGIN_SUCCESS ) {
msg = "Logged in successfully”;
}
else {
msg = "TEST ERROR! UNEXPECTED loginResult" + msg;
}
}
catch(errObj) {
msg = "Employee Login failed. Error attempting to call login";
msg = '\n' + errObj.message;
}

msg = msg +
"\nloginResult: " + empSession.loginResult +
"\nloginHttpStatus: " + empSession.loginHttpStatus +
"\nuserName: " + empSession.userName +
"\nlastSessionXHR: " + empSession.lastSessionXHR;

alert(msg);

See also:

addCatalog( ) method (Session class), afterLogin event, authenticationModel property (Session class), connected property, lastSessionXHR property, loginHttpStatus property, loginResult property, loginTarget property, logout( ) method (Session class), offline event, online event, serviceURI property, subscribe( ) method (Session class), userName property