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, LiveCycle 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.
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.)
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
LiveCycle 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:
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.
If Header based SSO is enabled, then the servlet looks for
configured headers to determine the user's identity.
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.
