EGL single sign-on

Combining application and proxy authentication

By using EGL single sign-on, you can combine the following aspects of security into a single step: authentication to your application (protected by custom security) and authentication to the EGL Rich UI Proxy (protected by JEE security). You can also include authentication to web services.

Although the user registries that you use for authentication to the application, EGL Rich UI Proxy, and web services do not need to be the same, the user ID and password used during EGL single sign-on must exist in all the relevant user registries to prevent an authentication error.

For EGL single sign-on, the Rich UI application must define a login screen that contains a user ID field, password field, and command button, as in the following example:

useridLabel TextLabel { text = "User ID:", width = 80 };
useridField TextField { width = 100 };
useridBox  Box { children = [ useridLabel, 
                 useridField ], margin = 3 };
passwordLabel TextLabel { text = "Password:", width = 80 };
passwordField PasswordTextField { width = 100 };
passwordBox Box { children = [ passwordLabel, 
                  passwordField ], margin = 3};
button Button { text = "Log in", onClick ::= authenticate };
ui Box { background = "blue",
         children = [ useridBox, passwordBox, button ], 
         columns = 1, width = 200 };

Whenever a web service is called, a request is sent to the EGL Rich UI Proxy. Because the proxy is secured with JEE basic authentication, a user must log in before accessing it. If a user has not logged in yet, a browser-provided login screen that is similar to the example in "Using basic authentication to secure the EGL Rich UI Proxy" will be displayed the first time a web service is invoked.

With EGL single sign-on, when the user authenticates to the Rich UI application using the user-defined login screen above, EGL passes those credentials (user ID and password) to JEE security to use to authenticate to the proxy also. Therefore, authenticating to the application is combined with authentication to the proxy in one step. For EGL single sign-on to work, design the Rich UI application so that the web service for authentication to the application is invoked before any other web service. Doing so bypasses the browser-provided login dialog.

To implement EGL single sign-on, use the ServiceLib.setProxyBasicAuthentication() system function to pass the user ID and password to authenticate to the proxy. Before you call the service to log in to the application, invoke this system function. The authenticate function for the EGL code above might look like the following example:

function authenticate( e Event in )
   ServiceLib.setProxyBasicAuthentication(useridField.text,passwordField.text );
   srvc LDAPLoginService{ @bindService };
   call srvc.login( useridField.text, passwordField.text )
                    returning to loginCallback onException loginException;
end

Adding web service authentication

Typically, to authenticate to a secure web service, a Rich UI application must prompt the user for a user ID and password. However, you can pass the user ID and password that you use for EGL single sign-on to a secure web service. To do so, invoke the ServiceLib.setHTTPBasicAuthentication() system function before you call the secure web service and pass it the user ID and password used for EGL single sign-on.

function withdraw( e Event in )
   ServiceLib.setHTTPBasicAuthentication(srvc, useridField.text,
                                         passwordField.text );
   srvc BankingService{ @bindService };
   call srvc.withdraw( useridField.text, passwordField.text )
                       returning to withdrawCallback onException withdrawException;
end

Handling authentication errors

If you use EGL single sign-on to authenticate to your application and to the EGL Rich UI Proxy, authentication to the proxy occurs before authentication to your application. Because the EGL Rich UI Proxy is secured using JEE basic authentication, the web container, not the application, handles login failures. Because the web container steps in, you can no longer authenticate in a single step. At this point, the user must authenticate to the EGL Rich UI Proxy first, and log in to the application, web services, or both afterward.

If users enter an invalid password for EGL Rich UI Proxy authentication on the login screen, a browser-provided login dialog is displayed so that they can try to authenticate again. In JEE basic authentication, the web container prompts the browser to display this dialog until the user logs in successfully. The application cannot access the password that a user enters on this dialog.

After users enter valid credentials for the EGL Rich UI Proxy, they must authenticate to the application, web services, or both. The application should direct users to re-enter a valid user ID and password in the user-defined login screen and to click the "Login" button again.

If an error occurs when users authenticate to a web service that is secured with HTTP basic authentication, control falls into the exception handler that is specified on the call statement. Your Rich UI application must detect this error and present appropriate instructions to the user to reauthenticate. The following example shows the specifics of this kind of error:

Web service authentication error

Configuration: A web service is secured using JEE basic authentication.
Problem: A valid user ID and password for the web service are not found in the HTTP header.
Error: A ServiceInvocationException is thrown with message ID "EGL1539E" and message, "An exception occurred while communicating with the service. URL: {0}" is issued where {0} is the URL of the web service. detail1 of the ServiceInvocationException is set to "401"; detail2 is set to "Unauthorized"; detail3 is set to "Server returned HTTP response code: 401 for URL: {0}", "name": "egl.core.ServiceInvocationException".
Solution: Call ServiceLib.setHTTPBasicAuthentication() to set a valid user ID and password in the HTTP header before consuming the web service.

If both EGL Rich UI Proxy and web service authentication are successful but an error occurs when you try to authenticate to your application, your Rich UI application must handle the error. When the web service returns, control passes to the callback or "returning to" function that is specified on your call statement.