Creating a HTTP Scripted Realm

Introduction

This article shows you how to connect to a HTTP based web server to get your users and groups as well as authenticating.

Pre-requisite

Your web server must contain functions for listing users/groups and authenticating users, which can then be called using scripts from the Hypersocket server.

The HTTP Connector extension must be installed.

This extension allows you to connect to any generic web server that is able to serve up users and password that Hypersocket can then use to cache and use for authentication.

As there is no single way to achieve this, the Hypersocket server allows you to develop a script (in JavaScript) that you can develop to ensure that the Hypersocket server can get all of the information it needs.

Configuring

Click the Realms  icon in the top navigation bar, then Manage Realms.

In the Realms screen that appears, click the Create button.

Give the new realm a meaningful name then choose HTTP (Scripted) from the Realm Type dropdown list. The screen will update to show the relevant tabs for this configuration.

In the first tab, Connection, enter the following information:

• URL: The URL of the HTTP server to get the users from.
• Read Only: Set to ON if you do not want to manage or update users from the HTTP server. Defaults to OFF.
• Username: The username to use for authenticating with the HTTP server.
• Password: The username to use for authenticating with the HTTP server.

The next tab is Script. The HTTP Connector comes with a default script to show an example of how it works.

The HTTP Connector needs the following functions, listed below with a brief description on what the function needs to return:

• onOpen(parameters): Invoked when the connector is opened. Can be empty if no initial setup is required for the service you are connecting to.
• onClose(): Invoked when the connector is closed. Can also be empty.
• allRoles(): Get an iterator of available roles. Mainly makes sense only when connecting to another Hypersocket server, but there is a separate connector available for Hypersocket. Return a new empty iterator if this function will not be used with return new java.util.ArrayList().iterator();
• allIdentities(): Get an iterator containing all available users. Hypersocket uses this to cache the user list.
• countIdentities(): Get a count of how many users there are on the system. This function is optional but recommended for performance reasons.
• getIdentityByName(name): Get more information on a user given its principal name, such as the user’s full name and other attributes.
• areCredentialsValid(identity, password): Tests if the user’s credentials are valid. Used by Hypersocket to test the user’s authentication during logon.
• setPassword(identity, password, forceChangeAtNextLogon): Sets a user’s password.
• getPasswordCharacteristics(): Gets any password strength requirements. If this function is not used, you can return Hypersocket’s default security requirements using return  new com.identity4j.util.passwords.DefaultPasswordCharacteristics();

The third tab is Hosts. If more than one realm is being set up it is advised to configure the settings in this tab. 

• Restrict Hosts: if this option is turned on, then users from another realm will not be able to authenticate to the Hypersocket server when accessing via the defined Realm Host. This can be especially useful in a Managed Service Provider environment. If Restrict Hosts is off, then a user from another realm will be able to authenticate as long as their username is not a duplicate of one on this realm.
• Realm Hosts: It is strongly advised to configure this setting. Type in the hostname that your users will be using to access the Hypersocket server for this realm. The Hypersocket server then will know to send authentication attempts to this host to the correct User Database. A different hostname should be used for each realm, which requires you are able to configure your domain’s DNS settings so that these hostnames point to the Hypersocket server.

Type in the realm host and press enter to add the host. Multiple hostnames can be configured on a realm.

Without a Realm Host setting, Hypersocket will attempt to authenticate a user on the Default realm first, before trying to find that user on other realms. This can lead to unpredictable behavior in a multi-realm environment.

The next tab that is available is Reconcile. This contains settings relating to how the users are cached in Hypersocket. Hypersocket connects to the remote user database periodically to update its list of cached users and then performs an update (reconcile) of this cache by either adding new users, deleting users that no longer exist or updating existing users.

The reconcile settings are:

• Reconcile Every (mins): The number of minutes between each successive user re-caching periods. Defaults to 60 minutes.
• Retry on Failure (mins): If a connection attempt fails during the reconcile, the number of minutes to wait before retrying. Defaults to 5 minutes.
• Rebuild Cache: On next reconcile, delete the cache and import all user objects from scratch. This takes more time than a normal reconcile. Defaults to OFF.
• Purge Duplicates: On rare occasions an out of date cache can cause duplicate users to be created in the cache. If that happens, this option can force removal of these duplicate users and rebuilds the cache. Defaults to OFF.
• Cache Passwords: Hypersocket will generate a one-way hash of the users’ passwords the next time they log on and cache this. Subsequent authentication attempts do not need to contact the domain controller for authentication until the Hypersocket server is restarted. Defaults to OFF.
• Reconcile at Login: Performs a reconcile of the user’s account at login. This can ensure that the latest information for that user (such as group membership and AD attributes) are perfectly up to date each login. Generally this is not needed as user accounts do not change very often. Defaults to OFF.

The fifth tab, Filter, allows you to restrict which user objects are cached by the server. Individual Users and/or Groups can be defined to exclude them.

Type in the user or group you wish to exclude then press enter to add it to the list.

There is one more tab that only appears after editing the Realm after it has been created. This tab is Status and contains information relating to the reconcile status:

• Status: Contains the status of the last reconcile, which can be Completed or Failed.
• Next Due: The date and time that the next reconcile is due to run.
• Last Performed: The date and time that the last reconcile was performed.
• Last Error: If the last reconcile failed, any errors appear in this field.

Once you have entered all the required configuration, click the Create button to create the new Realm.