Single Sign-On Example

• Background
  • Versions
• Obtaining the Plex model
• General information about authorizing Websydian Express sessions
• Example description
  • The authentication system
• Functionality
  • Retrieving the parameters from the request
  • Call the external authentication system
  • Update the session with the user
  • Add roles to the session
  • Set folder list
• Related information

Background

It is not uncommon that a web environment consists of several web applications developed by different vendors in different languages.

In such an environment you want to externalize the authentication of users, so users only have to login once to access the applications they are authorized to use.

The externalization of the authentication process to a central location is known as single sign-on.

This document shows an example of how to use an external system to control the authentication and authorization in Websydian Express.

The document is not an exhaustive treatment of the single sign-on problem domain; it is more meant to be an inspiration for developers who want to use another system to authorize Websydian Express users.

Versions

The functionality described in this document is relevant for Websydian Express version 2.0 and later.

The prototype is made using Plex/Websydian as the development tool. The exact same functionality can be developed using 2E and/or RPG developer, but at the moment we do not have examples that demonstrate this.

Obtaining the Plex model

To understand the example, you should download the local model containing the implementation of the example.

General information about authorizing Websydian Express sessions

When a user logs in to Websydian Express, several session attributes are affected. After the session has been updated, the site is reloaded, using the new session attributes.

The session attributes are:

1. User

2. Roles

3. Folder list

When an external system is used for authentication, the end-result of the authentication process must be that these session attributes are set.

Which information the external system will be able to provide will vary from case to case, but in almost all cases the external system will contain user information - and in many cases the external system will have a role concept that can be mapped to the Websydian Express roles.

It is unlikely, although not impossible, that an external system will have information about the folder list that should be assigned to the session. But this is not a problem as the Websydian Express runtime provides functionality for determining the folder list based on the roles assigned to the session.

Example description

The example shows how to implement a solution where an external system is used to check the user and password. The external system will provide information about the roles assigned to the user in the external system.

The login must be made without showing a login panel. This is meant to show how to handle the situation, where the user credentials are provided by some kind of front-end application.

The information about the user and password will be added to the initial request used to access the application.

The authentication system

For the purpose of this example, a very simple authentication system has been created. It offers a service "AuthorizeSession" that accepts two input parameters: Login and Password.

AuthorizeSession returns a flag indicating whether the user credentials (login and password) are valid. In addition to this flag, the service returns a list of up to 20 roles assigned to the user.

This service has been implemented in the function: SimpleAuthorizationSystem.AuthorizeSession. To keep the example simple, the system will consider all requests where both the login and password are specified as valid.

It is assumed that the external system uses the login as the unique identification of the user.

Functionality

All of the functionality will be placed in a function SimpleAuthorizationSystem.SessionAfterCreate that replaces the callback function SessionAfterCreate.

SessionAfterCreate is called immediately after a session has been created. This offers the opportunity to change the session attributes before the site is loaded.

SimpleAuthorizationSystem.SessionAfterCreate is described in detail in the rest of the section.

Retrieving the parameters from the request

To bypass the login page, the user credentials (login and password) has been added to the initial request, which will have the format:

http://www.websydian.com/express/site/basicsite?SSOLOGIN=ASN&SSOPWD=ABC

The function SimpleAuthorizationSystem.SessionAfterCreate.GetRequestInformation retrieves the login and password from the request.

This is done by inheriting from PopulateWebInput, and adding two fields with the implementation names SSOLOGIN and SSOPWD to the WebInput variable.

The retrieved values are returned in the output for the function.

Call the external authentication system

The data retrieved from the request are used as parameters for the call to the "AuthorizeSession" service.

If the external system does not recognize the user credentials the callback function is terminated. This has the effect that the session will keep the roles that was assigned when it was created.

The rest of the functionality will only be performed if the user has been authenticated by the external system.

Update the session with the user

The session should be updated with the user who has logged in. This is done by writing a unique identification of the user in the Websydian Express user table to the session. However, as the user information belongs to an external system, the user might not exist in the Websydian Express user table.

So to make it possible to store user information on the session, it is necessary to use the Websydian Express user table as a mapping table to the user in the external system.

To make this possible, a record is created in the Websydian Express user table containing the unique identification in the external system in the Login field. Before creating the record, it is checked whether the record already exists.

The user is updated on the session using the APIServer.Session.Update function.

The user is created as an inactive user, as it should not be used to perform a manual login using the Websydian Express authorization system; it is only meant to provide a key for reading the user data in the external system.

Add roles to the session

Before adding any roles to the session, the roles assigned as part of the session creation is removed using the APIServer.Session.RemoveAllRoles API.

The AuthorizeSession service returned an array containing the roles that is specified for the user in the external system. This array is read record by record and each role is handled as described below.

Map roles returned by the external system to Websydian Express roles

There is no reason to assume that all the external roles correspond to Websydian Express roles and there is no reason to expect that the roles that corresponds to Websydian Express roles has the same name (ID) in Websydian Express and the external system.

To provide a mapping of the roles, and a way to identify the relevant roles, a custom field has been specified for the role entity. This custom field has the name EXTERNALNAME. This makes it possible to use the Websydian Express administration interface to specify the external name for each Websydian Express role that the external system may assign.

So for each role returned by the external system, the corresponding Websydian Express role is found using the APIServer.CustomField.GetInstancesForValue API. If no corresponding Websydian Express role is found, the returned role is disregarded.

Add the role to the session

The Websydian Express role is added to the session using the APIServer.Session.AddRole API.

Set folder list

The external system has no information about folder lists, so the folder list is just assigned to the session based on the roles assigned to the session. This is done using the APIServer.Session.RefreshFolderList API.

Related information

Users and Roles - Describes the Websydian Express authorization system.

Custom Fields - Describes how you can use custom fields to extend the role entity.

How to use callback functions - Describes how you can use callback functions to change the normal functionality of Websydian Express