Getting started

Eunomia realizes a system for HTTP/HTTPS based user authentication. This system has the following main functions.

  • Defines a minimal system unit as a "realm" in which all user IDs are unique. When authenticating a user, it uses not only the user ID but also the realm name to distinguish same user names among different realms.
  • Allows all web servers in this system to authenticate users and generate single sign-on messaging to other servers.
  • Has each server possess an exchangeable attribute list for attribute requests from other servers.

Realm and message definition

Most systems are designed not to allow duplicate user IDs in their systems. So, we assign a unique realm name to the unit.

A realm name is composed of text data. It should be unique among the trusted realm group. (In order to easily achieve this, you may use your service name as the realm name. You may also use your domain name, if your system is in a single domain.)

When "UserA" in "RealmA" accesses a server in "RealmB", "UserA" is treated as "UserA, authenticated by RealmA" when in "RealmB". This way, even if the same user name "UserA" is already registered in a server in "RealmB", it is distinguishable from "RealmA"'s "UserA" by using the name "UserA, authenticated by RealmB". In this system, we describe this authentication information as "<realm name>-<user id>" to handle users' requests.

All realms have their own private/public key pairs, and they exchange public keys among preliminarily trusted realms. All authentication messages among the servers in the realms are encrypted by their private keys. A message encrypted with a private key can be decrypted only with the paired public key, so these encrypted messages also become a kind of endorsement from the source server acknowledging that it belongs to the realm. Note, Eunomia is built on the premise that RSA asymmetric cryptography is used.

The next picture shows the request/response message data structure for authentication. The encrypted parts are encoded with Base64 (with no linefeed code) to send over the network.

message format

The message is enclosed in brackets. Each attribute in the message is separeted by a semicolon. The following is a message sample.

message sample

For further processes like authorization or portalization, user attributes (such as telephone number, e-mail address, etc..) are also transferred in the message. In respect of privacy concerns, servers can be configured to judge whether they send the requested attributes or not. Details are described in the following chapter.

Attribute exchange

Each Eunomia server has an exchangeable attribute list to transfer attributes of an authenticated user. This list is only used for remote requests since there is no reason to reject a local attribute request.

Each Eunomia server which claims authentication to another server may include attribute request messages in the authentication request. The attribute requests may be generated without having to be aware of what attributes the responder server can share. For example, the attributes the requester claims may not be in the registry of the responder server or may not be allowed to be returned by the responder server, but it is possible to request them without receiving an error. It will simply return an null value. The responder will only return allowed attributes in the request message in regard to the exchangeable attribute list.

message sample

Return URL definition

Some authentication applications can preserve a unauthenticated user's first request in order to redirect users back to the URL after the authentication. In general, these applications retain URL information together with session IDs in their memory area. This information will be deleted when a session timeout happens or memory usage is exceeded.

Eunomia authentication messages contain this URL information and exchange it among servers so that the user requesting access will be redirected accurately to the intended URL after the authentication process.

Sign-on definition

All servers in a trusted realm group can be accessed by all users registered in each realm.

In the interest of brevity, we will call servers registered the requested user ID "authentication servers", and the others "service servers".

The authentication message flows are shown in the next pictures. There are 2 patterns of authentication flows.

One is a pattern in which a user accesses the authentication server before accessing the service server. Another is a pattern in which a user accesses the service server before the user is authenticated by the other server. (It makes no difference whether these servers are in a same realm or not. If the service server and the authentication server is as one, the authentication flow is as simple as a normal local authentication.)

sign-on flow 1 sign-on flow 2

Message handling

The next pictures show the flows of how request/response messages are handled during a sign-on process.

message handling 1 message handling 2