Websydian v6.1 online documentationOnline documentation - WebsydianExpress v3.5

Using the AS400 login system in WebsydianExpress

Overview

In some intranet applications it can be desirable to use the AS400 login system instead of the login system that is delivered with WebsydianExpress. This can be the case when all the users, which are going to log in to the WebsydianExpress application, already are created as AS400 user profiles. In this case, using the AS400 login system allows the user to avoid remembering both a password for the AS400 and for the WebsydianExpress application.

One significant difference between the AS400 authorization system and the WebsydianExpress authorization system is the use of roles in WebsydianExpress. The fact that the AS400 login system authenticates the user does not mean that the AS400 login system can assign the roles to the session.

To be able to assign roles to the session, this description assumes that the users are still created and the roles are assigned to the user in WebsydianExpress - so it is only the check of user login name and password that is being replaced by the AS400 login system.

The following description is not an attempt to describe all of the possible ways to handle this issue. It is an attempt to give an overview over one specific solution, which can be used as the basis for a solution targeting your specific needs.

Description of the solution

The easiest way to change the way WebsydianExpress handles the login is to create your own login business process and replace the existing business process in the site structure. The new business process will provide the following functionality:

The first page shown is the login page, containing user login name and password as input fields for a "Login" button.

The login check on the AS400 is called.

If the login check returns success, the session is updated with the roles specified for the WebsydianExpress user and the site is reloaded.

If the login check returns error, the login page is called again - and an error is shown.

Example model

Use this link to obtain a Plex local model containing the example.

Create Functions

Create ProcessEntryPoint

The ProcessEntryPoint is the function that is called by the runtime when the login business process is activated. In this example the ProcessEntryPoint will just be used to call the first PageGenerator (the PageGenerator for the Login page).

Specify the following triples to create the ProcessEntryPoint:

Source Object Verb Target Object
AS400Login is a FNC WSYAPI/ProcessEntryPoint
implement SYS Yes
impl name NME AS400LI
file name NME AS400LI
includes FNC Fields

Create Login PageGenerator

The Login PageGenerator is the main page for the login process, it will contain a login event and have the ability to show a list of error messages.

Specify the following triples to create the PageGenerator for the Login page.

Source Object Verb Target Object
AS400Login includes FNC LoginPage
AS400Login.LoginPage is a FNC WSYAPI/Abstract.PageGeneratorErrorListForProcess
local FLD

...for VAR

WSYAPI/APIFields.LoginName
WsyDetails
local FLD

...for VAR

WSYAPI/APIFields.UserPassword
WsyDetails
local FLD

...for VAR

WSYAPI/APIFields.LoginName
OmitDetailsFields
local FLD

...for VAR

WSYAPI/APIFields.UserPassword
OmitDetailsFields
implement SYS Yes
impl name NME AS400LIP
filename NME AS400LIP
AS400Login.LoginPage._DocumentTemplateGenerator implement SYS Yes

Create the Login EventHandler

This is the function that will be called when the Login event is activated, it receives the values for two fields (login name and password) and validates these values using the AS400 login system.

If any errors occurs, the Login Page is called as an error page.

If the validation is successful, the session is updated with roles and folder list according to the definitions for the user and the site is reloaded so that these settings are used.

Specify the following triples to create the EventHandler for the Login button on the Login page.

Source Object Verb Target Object
AS400Login.LoginPage includes FNC Login
AS400Login.LoginPage.Login is a FNC WSYAPI/EventHandlerForProcess
implement SYS Yes
local FLD

...for VAR

WSYAPI/APIFields.LoginName
WebInput
local FLD

...for VAR

WSYAPI/APIFields.UserPassword
WebInput
replaces FNC

...by FNC

WSYAPI/ErrorPageForProcess
AS400Login.LoginPage
AS400Login.LoginPage.Login.IdentifyInputFields implement SYS Yes
AS400Login.LoginPage.Login.
_DocumentTemplateGenerator.Login
implement SYS No
AS400Login.LoginPage._DocumentTemplateGenerator.

Login.IdentifyInputFields

implement SYS No

Create Check Password server function

This is the definitions necessary to call the server function that will be used to perform the check of the combination of login and password.

Specify the following triples to create the API definitions for the function that will check whether the password is valid.

Source Object Verb Target Object
AS400Login.Fields field FLD ErrorID
AS400.Login.Fields.ErrorID is a FLD ShortDescription
length NBR 7
AS400Login includes FNC CheckPassword
AS400Login.CheckPassword type SYS API
input FLD APIFields.LoginName
APIFields.UserPassword
output FLD AS400Login.Fields.ErrorID
implement SYS Yes
file name NME WSCHKPWD
impl name NME WSCHKPWD

Create Messages

Create error message for failed login

Source Object Verb Target Object
AS400Login message MSG Login Failed
As400Login.Login Failed parameter FLD AS400Login.Fields.ErrorID

Specify the following text for the message:

Login failed. Error ID: &(1:)

Create error message for read of user data

Source Object Verb Target Object
AS400Login message MSG User Not Found
As400Login.User Not  Found parameter FLD WSYAPI/APIFields.LoginName

Specify the following text for the message:

Login failed. The User &(1:) has not been created in the WebsydianExpress User table.

Create error message for update of session

Source Object Verb Target Object
AS400Login message MSG Update of Session Failed

Specify the following text for the message:

Login failed. The session could not be updated.

Enter Action Diagram Code in the ProcessEntryPoint

Insert the following in the Post Point: Call to first PageGenerator:

Call Function: AS400Login.LoginPage

<ErrorMode.*No>

Enter Action Diagram Code in the Login EventHandler

Specify mapping for the call to the Login PageGenerator

As part of the definitions for the EventHandler, the error page was replaced with the Login PageGenerator, as the parameter interface for the Login PageGenerator is a bit different from the standard error page, you need to specify the parameter mapping for the additional parameter.

Find the call to the AS400Login.LoginPage function in the subroutine Error Handler - specify the value *Yes for the Input parameter Error Mode.

Call the Check Password API

Enter the following code in the Post Point 0 Process of input:

Call AS400Login.CheckPassword

//Map with Webinput

If AS400Login.CheckPassword/Output<AS400Login.Fields.ErrorID> == <AS400Login.Fields.ErrorID.*Blank>

    Go Sub Handle Successful Login

Else

    Format Message Message: AS400Login.Login Failed, Environment<*Message text>

//Map with AS400Login.CheckPassword/Output<AS400LoginExample.AS400Login.Fields.ErrorID>

 

    Go Sub Send Message

    Go Sub Error Handler

Create Subroutine for handling successful login

Create a subroutine: Handle Successful Login

In the subroutine, add the following code:

Call WSYAPI/APIServer.User.SingleFetchSiteLogin

//Map with:

//Webinput<APIFields.LoginName>

//APIServer.GetBasicSessionData/Output<APIFields.SiteKey>

 

If Environment<*Returned status> != <*Returned status.*Successful>

    Format Message Message: AS400Login.User Not Found, Environment<*Message text>

//Map with: WebInput<APIFields.LoginName>

    Go Sub Send message

    Go sub Error Handler

 

Call WSYAPI/APIServer.Session.SetUserAndUpdate

//Map with:

//WebInput<APIFields.SessionSurrogate>

//APIServer.User.SingleFetchSiteLogin/FetchedData<APIFields.UserSurrogate>

 

If Environment<*Returned status> != <*Returned status.*Successful>

    Format Message Message: AS400Login.Update of Session Failed, Environment<*Message text>

    Go Sub Send message

    Go sub Error Handler

 

Call WSYAPI/APIWebServer.ReloadSitePageGenerator

 

Explanation:

The call to APIServer.User.SingleFetchSiteLogin obtains the unique identification of the user known by the specified login name.

The call to APIServer.Session.SetUserAndUpdate updates the session with the roles and folder list for the user.

The call to APIWebServer.ReloadSitePageGenerator reloads the site so that the new settings for the session is used.

Please note that the Error Handler contains a Go Sub Terminate statement - so a call to this subroutine terminates the EventHandler.

Create the Check Password Server Function

The Server function that is used to check the password is an ILE-RPG function.

Please note that this is just an example of one way to handle the password check. It has not been tested for use in a production environment. If you want to have this functionality you must investigate how you want to do the actual password check and you must ensure that it the method is suitable for your needs.

Generate and Build

Generate and build the Functions:

AS400Login

AS400Login.LoginPage

AS400Login.LoginPage._DocumentTemplateGenerator

AS400Login.LoginPage.Login

AS400Login.LoginPage.Login.IdentifyInputFields

 

IF you are using the iSeries/iSeries variant:

Generate and build the AS400 Message File.

 

Compile the Check Password ILE-RPG function.

Create HTML Template

Run the AS400Login.LoginPage._DocumentTemplateGenerator function.

In the generated file AS400LIP.htm - change the following line:

<P>UserPassword<INPUT TYPE="TEXT" NAME="WSAPIPWD" VALUE="/(WSAPIPWD)" MAXLENGTH="32" SIZE="32"></P>

to:

<P>UserPassword<INPUT TYPE="password" NAME="WSAPIPWD" VALUE="/(WSAPIPWD)" MAXLENGTH="32" SIZE="32"></P>

This change means that the input field for the password will show asterisks instead of characters when the password is entered.

Deploy Objects

Win/iSeries

Move the following functions to the "PlaceObjectsHere" folder:

AS400Login

AS400Login.LoginPage

AS400Login.LoginPage.Login

Move the WSCHKPWD object to the WXP20APP library on the iSeries

Move the file AS400LIP.htm to the folder used by the site where you want to deploy the functionality (e.g. the basicsite or the demosite folders).

iSeries/iSeries

Move the following functions to the WXP20APP library on the iSeries

AS400Login

AS400Login.LoginPage

AS400Login.LoginPage.Login

WSCHKPWD

Move the file AS400LIP.htm to the IFS folder used by the site where you want to deploy the functionality (e.g. the basicsite or the demosite folders).

Move or update the message file used by the application with the new messages.

Change Site Structure

Define Business Process in the administration interface

Before changing the site structure you must define the new login business process.

In the administration interface use menu item Content Loaders→Business Processes, Press Insert.

Press Insert to create the content loader.

Replace Login in the Site Structure

Use the Site Structure→Site Structure menu item, select the existing Login Business Process and press Remove. On the confirmation page, press Remove again.

Select the parent element of the original login business process and press Add.

Go through the process to add the AS400 Login business process to the location in the site structure previously occupied by the original login process.

Test the Login Process

Use the new login process to check whether the login is validated correctly and that the roles and folder list are assigned according to the definitions for the WebsydianExpress user that has the specified login name.

Please note that this change does not affect the login to the administration interface, this login will still be using the normal WebsydianExpress login functionality.

Extending the Example

To keep the example as simple as possible, only the absolutely necessary functionality has been implemented, there are a couple of extensions that you might want to consider. These will not be explained in detail - but an outline of how to implement them will be provided.

Handle expired passwords

This is a special case, where you might want to provide the user with the option to change his password. When the password is expired, the ErrorID CPF22E4 will be returned by the function validating the password.

This can be implemented with relative ease.

Create a Change Password page, which includes a Change Password EventHandler. The EventHandler must have LoginName, Password, and a new password field in webinput.

In the Login Eventhandler:

After the call to the Check Password function, check for the ErrorID CPF22E4 - if this error occurs, call the ChangePassword PageGenerator.

In the ChangePassword EventHandler call a serverfunction that uses the CHGPWD command to change the password as specified by the user.

If the change is successful, perform the same functionality as the Handle Successful Login subroutine in the Login EventHandler.

Create WebsydianExpress user profiles if they do not exist

As the example is described above, each user must be defined using an AS400 user profile and as a WebsydianExpress user. The password validation will be done using the AS400 user profile, while the assignment of roles and folder list will be done using the WebsydianExpress user.

This makes it possible to define specific access for specific users even thought the AS400 user profiles have no information about roles.

However, this also means that you need to manually create the WebsydianExpress users.

In some cases, all users should get the same default roles and folder list. If this is the case, you can automatically create the WebsydianExpress users as follows:

In the Login EventHandler - after the call to APIServer.User.SingleFetchSiteLogin:

If the user does not exist - create the user profile using the APIWebServer.UserCreate function (you might want to extract the user name etc. from the user profile, otherwise just set some default values).

Add the roles using the APIServer.User.AddRole function.

After this, you just proceed as described above using the created user profile.