Creating Flash Builder applications that perform SSO authentication using HTTP tokens

You can create a client application using Flash Builder that performs single-sign on (SSO) authentication using HTTP tokens. Assume, for example, that you create a web-based application using Flash Builder. Next assume that the application contains different views, where each view invokes a different LiveCycle operation. Instead of authenticating a user for each LiveCycle operation, you can create a login page that lets a user authenticate once. Once authenticated, a user is able to invoke multiple operations without having to authenticate again. For example, if a user has logged into Workspace (or another LiveCycle application), the user would not need to authenticate again.

Although the client application contains required application logic to perform SSO authentication, AEM forms user Management performs the actual user authentication. To authenticate a user using HTTP tokens, the client application invokes the Authentication Manager service’s authenticateWithHTTPToken operation. User Management is able to authenticate users using a HTTP token. For subsequent remoting or web service calls to LiveCycle, you do not have to pass credentials for authentication.

Note: Before reading this section, it is recommended that you are familair with Invoking LiveCycle using Remoting. (See Invoking LiveCycle using Remoting .)

The following LiveCycle short-lived process, named MyApplication/EncryptDocument , is invoked after a user is authenticated using SSO. (For information about this process such as its input and output values, see Short lived process example .)

View full size graphic
Note: This process is not based on an existing LiveCycle process. To follow along with the code examples that discuss how to invoke this process, create a process named MyApplication/EncryptDocument using workbench. (See Using Workbench .)

The client application built using Flash Builder interacts with the User Manager’s security servlet configured at /um/login and /um/logout . That is, the client application sends a request to the /um/login URL during startup to determine the status of the user. Then User Manager responds with the user status. The client application and the User Manager security servlet communicate using HTTP.

Request format

The security servlet requires the following input variables:

  • um_no_redirect - This value must be true . This variable accompanies all the requests made to the User Manager security servlet. It also helps the security servlet differentiate the incoming request coming from a flex client or other web applications.

  • j_username - This value is the login identifier value of the user as provided in the login form.

  • j_password - This value is the corresponding password of the user as provided in the login form.

The j_password value is only required for credential requests. If the password value is not specified, then the security servlet checks to determine if the account you are using is already authenticated. If so, you are able to proceed; however, the security servlet does not authenticate you again.

Note: For proper handling of i18n, ensure that these values are in POST form.

Response format

The security servlet configured at /um/login responds by using the URLVariables format. In this format, the output of the content type is text/plain. The output contains name value pairs separated by an ampersand (&) character. The response contains the following variables:

  • authenticated - The value is either true or false .

  • authstate - This value can contain one of the following values:

    • CREDENTIAL_CHALLENGE - This state indicates that User Manager is not able to determine the user's identity through any means. In order for authentication to occur, the user's username and password is required.

    • SPNEGO_CHALLENGE - This state is treated the same as CREDENTIAL_CHALLENGE .

    • COMPLETE - This state indicates that User Manager is able to authenticate the user.

    • FAILED - This state indicates that User Manager was not able to authenticate the user. As a response to this state, the flex client can show an error message to the user.

    • LOGGED_OUT - This state indicates that the user has successfully logged out.

  • assertionid - If the state was COMPLETE then it contains the user's assertionId value. A client application can obtain the AuthResult for the user.

Login process

When a client application starts, you can make a POST request to the /um/login security servlet. For example, http://<your_serverhost>:<your_port>/um/login?um_no_redirect=true . When the request reaches the User Manager security servlet, it performs the following steps:

  1. It looks for a cookie named lcAuthToken . If the user has already logged in to another LiveCycle application, then this cookie is present. If the cookie is found, then its content is validated.

  2. If Header based SSO is enabled, then the servlet looks for configured headers to determine the user's identity.

  3. If SPNEGO is enabled, then the servlet tries to initiate SPNEGO and tries to determine the user's identity.

If the security servlet locates a valid token that matches a user, the security servlet lets you proceed and responds with authstate=COMPLETE . Otherwise the security servlet responds with authstate=CREDENTIAL_CHALLENGE . The following list explains these values:

  • Case authstate=COMPLETE : Indicates that the user is authenticated and the assertionid value contains the assertion identifier for the user. At this stage, the client application can connect to LiveCycle. The servlet configured for that URL can obtain the AuthResult for the user by invoking the AuthenticationManager.authenticate(HttpRequestToken) method. The AuthResult instance can create the user manager context and store it in the session.

  • Case authstate=CREDENTIAL_CHALLENGE : Indicates that the security servlet requires the user's credentials. As a response, the client application can display the login screen to the user and send the obtained credential to the security servlet (for example, http://<your_serverhost>:<your_port>/um/login?um_no_redirect=true&j_username=administrator&j_password=password) . If authentication is successful, then the security servlet responds with authstate=COMPLETE .

If the authentication is still not successful, then the security servlet responds with authstate=FAILED . To respond to this value, the client application can display a message to obtain the credentials again.

Note: While authstate=CREDENTIAL_CHALLENGE , it's recommended that client send the obtained credential to the security servlet in a POST form.

Logout process

When a client application logs out, you can send a request to the following URL:

http://<your_serverhost>:<your_port>/um/logout?um_no_redirect=true

On receiving this request, the User Manager security servlet deletes the lcAuthToken cookie and responds with authstate=LOGGED_OUT . After the client application receives this value, the application can perform cleanup tasks.

// Ethnio survey code removed