XML Response Format
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:
ASP.NET Sample
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)) %>
JSP Sample
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>
PHP Sample
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; ?>