Page tree
Skip to end of metadata
Go to start of metadata


The XmlBasedAuthenticationProvider reads an XML file of users and groups to implement simple user authentication (username, password) for AIE Web Applications.

You can define groups within the XML file for implementing role-based restrictions on access to AIE"s Web applications. You can also load the same XML file of users and groups into the AIE universal index to implement Content Security when combined with a source of Access Control Lists for the system"s ingested documents.

This page describes:


HTTP Basic Authentication and HTTPS Encryption

AIE uses HTTP Basic Authentication to send user passwords across the network. HTTP Basic Authentication does not adequately protect passwords from interception, so using HTTPS with any form of user authentication is recommended.

View incoming links.


XmlAuthenticationProvider Configuration

The XML Authentication Provider is configured as a Java bean in the <project-dir>\conf\bean directory. These are configured as beans in an appropriately named xml file.  For example, to use an XML file based authentication named 'default-users-authentication-provider', create an XML file named <project-dir>\conf\bean\default-users-authentication-provider.xml with the following contents.  Features that use this authentication provider (such as f:deployWebapp) must identify the provider by name (id).

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns:xsi="" xmlns="" xmlns:util="" xmlns:sec="" xsi:schemaLocation="">

  <bean name="default-users-authentication-provider" class="">
    <property name="xmlFile" value="users.xml"/>


The only property is the xmlFile location, which typically resides in the <project-dir>\resources directory.  By placing this XML file in <project-dir>\resources, it ensures that this file is deployed to all AIE nodes in an appropriate location for access by the authentication mechanism.

XML File of Users/Groups

This example of the XML users/groups input file includes encrypted passwords. It is for user authentication by means of a username/password dialog box in the Web browser.

You can also create the file without passwords in situations where Content Security is desired, but user authentication is not needed. For example, user authentication might be performed by a client program that then issues queries to AIE. The query contains the user's name and realm, which filter the results at the document level. This filtering does not require AIE to match user passwords.

XML File Syntax

 Only ISO-8859-1 (Latin-1) characters may be the principalID, realmID and password.

The syntax of the XML file includes users, groups, memberships, and aliases.

  <!-- batman is a member of the JusticeLeague group. -->
  <user id="batman@superheros" name="Caped Crusader" password="MD5:8ee60a2e00c90d7e00d5069188dc115b">
    <membership principal="batman@superheros" group="JusticeLeague@superheros"/>
  <group id="JusticeLeague@superheros" name="Justice League" />

  <!-- bwayne is a member of the WayneEnterprises group. -->
  <user id="bwayne@gotham" name="Bruce Wayne" password="MD5:8ee60a2e00c90d7e00d5069188dc115b" />
  <group id="WayneEnterprises@gotham" name="Wayne Enterprises">
    <membership principal="bwayne@gotham" group="WayneEnterprises@gotham" />

  <!-- bwayne and batman can be aliased, effectively joining each other's groups. -->
  <group id="bwayne-batman@aliases" name="bwayne-batman">
    <alias principal="bwayne@gotham" group="bwayne-batman@aliases" />
    <alias principal="batman@superheros" group="bwayne-batman@aliases" />

Attributes and elements of this XML syntax are described in the following subsections.

@id, @group, @principal Attributes

These attributes each contain a value in the form principalID@realmID. For example, "batman@superheros" is interpreted as principalId=batman, realmId=superheros. This is important because the role-authentication feature takes the principalID alone as its argument.

@name Attribute

This attribute defines the display name for the given principal, as in "Wayne Enterprises".

@password Attribute

You can omit the password attribute if the file of users and groups is used for content security only, and you leave user authentication to some other mechanism. If AIE handles user authentication, demanding a username and password when a user tries to connect to SAIL, for instance, you must provide passwords in the XML file.

You can enter the passwords in the clear, or use the method described below to encrypt the passwords.

The password shown in the example (above) is the encrypted form of "robin".

<user> Element

The <user> element defines a new user and contains any number of <membership> elements.

<group> Element

The <group> element defines a new group and contains any number of <membership> elements.

<membership> Element

The <membership> element defines a relationship between a group and a principal (group or user). The @principal attribute defines the child and the @group defines the parent – that is, the @principal is a member of the @group.

The <membership> element must be inside a <group> or <user> element. Either the @principal or @group attribute must match the @id attribute of the containing element.

Note that this connector does not do cycle checking. That is, you could accidentally specify a file where group A is directly or indirectly a member of group B, and group B is directly or indirectly a member of group A. Cycle checking happens at query time, but it is a good idea to avoid setting up cyclic memberships anyway.

<alias> Element

The <alias> element defines an alternate definition for a principal. In the example above, Bruce Wayne and Batman are the same person but they are two separate accounts. The <alias> element can link these two accounts so that query by either account returns all documents. To create the <alias>, create a synthetic group (bwayne-batman@aliases) to contains all the aliases for Batman. The synthetic group is required so there is a clean mechanism of cleaning up if the aliases are redefined.

Adding User Passwords

If you use your XML file of users and groups for authenticating users, you must include user passwords in the file. You can use cleartext passwords, but then anyone who views the file can read the passwords. To avoid this issue, AIE provides two kinds of encrypted passwords for the file.

AIE uses an embedded Jetty instance to generate and test XML user passwords. To generate passwords for users you can use the aie-exec password utility.

On Windows:

> bin\aie-exec.exe password -p <your password>

<your password>

On Linux:

$ ./bin/aie-exec password -p <your password>

<your password>

Interpreting Results

This utility returns two different encrypted passwords. Place either of these values in the password attribute of a <user> element. The two values provide different levels/kinds of security:

  • OBF: Passwords that begin with OBF are obfuscated. Obfuscated passwords are required if a system needs to recover the full password (for example, so that it may be passed to another system). They are not secure, but prevent casual observation.
  • MD5: Password is encrypted using MD5. This is a more secure way to store passwords that requires checking rather than recovery. Note that MD5 is still not strong security, especially if simple passwords are used.

You can use either of these password versions in the password fields for the XML users.

Ingesting the XML File

See XML Principal Scanner for details on how to ingest XML file principals to support Content Security or role-based security.  


Securing the Web Application UI

Main Article: AIE Web Application (webapp) Security

The easiest way to configure authentication:

  • for all webapps as well as AIE-SQL is to specify the default-authentication-provider element in the <project-dir>\conf\configuration.xml configuration.  
  • for a single webapp, add the authentication-provider-ref attribute to the f:deployWebapp feature element.  

See AIE Web Application (webapp) Security for more information.

Accessing a Secure SQL Data Source

The authentication provider for a SQL data source for a single project can be specified by adding the authentication-provider-ref attribute to the fsql:catalogs element in the <project-dir>/conf/features/sqlsdk/SqlModel.index.xml configuration file.  See the Security Guide for more information.

See Also

  • No labels