In case the authentication server is able to authenticate the user, it has to respond with XML content that contains the user's username, e.g. sending a valid authentication for user "JohnDoe", the authentication server should respond:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
    <entry key="username">JohnDoe</entry>
</properties>

Important: You have to make sure that the user name is always returned in way that is unique to the system (e.g. always make it lowercase - even if the user logs in with uppercase letters) - the reason behind this is: case-insensitivity is supported in every permission checking context, but it will respect folder names case-sensitively. If you had a user named "JohnDoe" and he logs into the system with "johndoe" there would be two different home directories in the repository though you meant the same user.

Note: If the login script administrates the user by domain and user name (as in "DOMAIN/User"), the permissions have to be configured the same way later on.

To check whether a user is in certain roles, the roles to check is appended as a parameters to the request URL. The server than has to check for each role and extend the XML appropriately:

REQUEST: 
http://<YourServer>/login.aspx?abc=&somerole=
 
RESPONSE:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
    <entry key="username">JohnDoe</entry>
    <entry key="abc">False</entry>
    <entry key="somerole">True</entry>
</properties>

Using roles is a convenient way to specify restrictions for many users at once. Furthermore you can even use the roles in the formulas of a report to adapt the report to the executing user. The formula function to check a role is isWebUserInRole( <roleName> ).

For the most common cases of authentication servers running ASP.NET, PHP or Java Server Pages, please use the following samples as a reference:

Create a file with the extension *.aspx (e.g. login.aspx) in the IIS and copy the following script into this file. Enable the authentication method "Basic authentication" for this .aspx file in the IIS configuration.

An installed Microsoft .Net Framework version 2.0 or higher is required to execute this script.

<%@ Page Language=VB ResponseEncoding="utf-8" %>
<%
If User.Identity.Name = "" Then
	Response.Write( "401 Access Denied" )
	Response.Status = "401 Access Denied"
	Response.End
end if
Response.ContentType = "text/xml; charset=utf-8"
 
Response.Write( "<?xml version=""1.0"" encoding=""UTF-8""?>" & Chr(10))
Response.Write( "<!DOCTYPE properties SYSTEM ""http://java.sun.com/dtd/properties.dtd"">" & Chr(10))
Response.Write( "<properties>" & Chr(10))
 
Response.Write( "<entry key=""username"">" & Server.HTMLEncode(User.Identity.Name) & "</entry>" & Chr(10) )
 
Dim Key
For Each Key In Request.QueryString
    if Key <> "" Then
        Try
            Response.Write("<entry key=""" & Server.HtmlEncode(Key) & """>" & Server.HtmlEncode(User.IsInRole(Key)) & "</entry>" & Chr(10))
        Catch
            Response.Write("<entry key=""" & Server.HtmlEncode(Key) & """>false</entry>" & Chr(10))
        End Try
    End If
Next
 
For Each Key In Request.Form
    if Key <> "" Then
        Try
            Response.Write("<entry key=""" & Server.HtmlEncode(Key) & """>" & Server.HtmlEncode(User.IsInRole(Key)) & "</entry>" & Chr(10))
        Catch
            Response.Write("<entry key=""" & Server.HtmlEncode(Key) & """>false</entry>" & Chr(10))
        End Try
    End If
Next
Response.Write( "</properties>" & Chr(10))
%> 

Create a file with the extension *.jsp and copy it into any web context.

<%@page language="java" contentType="text/xml; charset=utf-8" pageEncoding="UTF-8"
import="java.security.Principal"
import="java.io.*"
import="java.util.*"
 
%><%!
public static String encode(String s){
	StringBuilder out = new StringBuilder();
	for(int i=0; i<s.length(); i++){
		char c = s.charAt(i);
		if(c > 127 || c=='"' || c=='<' || c=='>'){
			out.append("&#"+(int)c+";");
		}else{
			out.append(c);
		}
	}
    return out.toString();
}
 
%><?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
<%
	Principal p = request.getUserPrincipal();
	if( p != null ){
		out.write( "<entry key=\"username\">" + encode( p.getName() ) + "</entry>\n" );
	}
 
	Enumeration e = request.getParameterNames();
	while(e.hasMoreElements()){
		String key = (String)e.nextElement();
		key = new String( key.getBytes("ISO8859_1"), "UTF8");
		out.write( "<entry key=\"" + encode( key ) + "\">" + request.isUserInRole(key) + "</entry>\n" );
	}
%>
</properties>

Create the files .htaccess, .htpasswd and .htgroups. This file can look like this:

.htaccess

# dont allow htaccess and htpasswd
<Files ~ "^.(htaccess|htpasswd)$">
deny from all
</Files>
 
# .htpasswd contains the password and users
AuthUserFile /opt/lampp/htdocs/.htpasswd
AuthGroupFile /opt/lampp/htdocs/.htgroups
AuthName "Please enter your ID and password"
AuthType Basic
require valid-user

.htpasswd - A user test with password test.

test:WCt/yYmXR2kLA

.htgroups

admin: test

Create a php login file with the following content:

<?php
  // This is the .htgroups file - the web server requires to have read permission for this file!
  $AuthGroupFile = file("/path/to/.htgroups");
 
  // If the Apache has AUTH Info, set them for PHP as well
  if (!empty($_SERVER['AUTH_USER']))
  {
     $_SERVER['PHP_AUTH_USER'] = $_SERVER['AUTH_USER'];
     $_SERVER['PHP_AUTH_PW']   = $_SERVER['AUTH_PASSWORD'];
  } else if (!empty($_SERVER['REMOTE_USER'])){
    $_SERVER['PHP_AUTH_USER'] = $_SERVER['REMOTE_USER'];
  }
 
  // Check whether someone has authenticated - if not, request another Basic Authentication
  if (!isset($_SERVER['PHP_AUTH_USER'])) {
    header('WWW-Authenticate: Basic realm="Server Authentication"');
    header('HTTP/1.0 401 Unauthorized');
    echo 'Access Denied';
    exit;
  }
 
  // Here you may insert additional checks for the user, like querying a database.
  // Alternatively this can be done via .htaccess in apache
 
  $return = '';
  $return .= '<entry key="username">' . strtolower(htmlentities($_SERVER['PHP_AUTH_USER'])) . "</entry>\n";
 
  foreach ( $_REQUEST AS $key => $value ) {
    $status = !preg_grep("/$key:.*?\s" . htmlentities($_SERVER['PHP_AUTH_USER'])  . "(\s.*?)?$/", $AuthGroupFile) ? 'false' : 'true';
    $return .= '<entry key="' . htmlentities($key) . '">' . $status . "</entry>\n";
        }
 
  header('Content-Type: text/xml; charset=utf-8');
  print <<<OUTPUT
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
$return
</properties>
OUTPUT;
?>