Introduction to pam_xacml


Authors: Andreas Klenk, Tobias Heide

Documentation: Tobias Heide

Supported by: Universität Tübingen and Technische Universität München

pam_xacml includes work from Joseph Bester[1] within it‘s distribution.

1.Aims of pam_xacml

pam_xacml shall ease the integration of XACML to existing applications. It can operate in two modes, the first one allowing the use of XACML Policy Decision Points without changes to the application (the so-called legacy-mode) and the second mode requiring changes to the application, but allowing more powerful authorization.

pam_xacml is based on the Pluggable Authentication Modules that are standardized by the Open Group[2]. In legacy mode, pam_xacml is fully compliant to current PAM implementations. When using the extended mode, custom message types are passed over the PAM conversation mechanism, which have to be understood by the application.


You will need development versions of the following external libraries to build pam_xacml: PAM, gSOAP, libxml2, pkg-config, patch

For GSOAP you will need: bison/yacc, flex, libssl/openssl

We rely on the standard GNU autotools to build pam_xacml. You should install gSOAP version 2.7.10 before starting the installation of pam_xacml. You can get it from [3]. Afterwards compile gSOAP typing the following commands:

 ./configure --prefix=/usr


 sudo make install

It is important to install gSOAP into a location where it can be found by the configure script of pam_xacml. When done installing gSOAP you can progress with the installation of pam_xacml. Normally you can skip running the autotools when using the distribution, so only issue the following five commands if you run into trouble.





 automake -a -c --foreign

Afterwards just follow the standard GNU autotools installation steps:

 ./configure --prefix=/usr


 sudo make install

Installation on Mac OS X

When compiling on Mac OS X platform, you will need to take a different build process. First, install fink some other GNU environment.[4] You will need to install several libraries:

 fink install pkgconfig

 fink install libxml2 libxml2-bin

 fink install libxml2-shlibs

 export PKG_CONFIG_PATH=/usr/lib/pkgconfig/

The process of initializing the autotools environment also differs a bit from above:





 automake -a -c --foreign

(Note the use of glibtoolize instead of libtoolize). Then issue the following commands to compile pam_xacml:

 ./configure --prefix=/usr \



 sudo make install

You need to provide the PAM_DIR variable to configure, because Mac OS uses a non-standard location for the PAM libraries. After compilation the installation behaves like a installation on a „normal“ UNIX environment.


To add pam_xacml to an authentication chain of an application, you need to edit the corresponding file under /etc/pam.d. For example, if you would like to add pam_xacml to sudo, you will have to add the following line to /etc/pam.d/sudo:

account sufficient <param>

<param> is a list of configuration options that is explained in the following sections.

General options






If present, pam_xacml will generate verbose syslog messages.



If present, pam_xacml will dump the XACML request and reponse to syslog.


Option requestBuilder

This option provides information to pam_xacml, how the request that is sent to the PDP shall be generated. Several values are possible:



Further parameters


Fills out a XML template with several values



The application is XACML capable and will provide a complete request



An external script will generate the request.



Option requestTemplate

This option is used in conjunction with the INTERNAL request builder. As a value, you shall provide the complete path to an XML template which will be filled out by pam_xacml. You may use the following fields in your template:




Konstanter String "TestRessource"


Username of the currently logged on user


Konstanter String "TestAction"


The hostname of the host executing PamXacml.


A random string that is also passed to the obligationsScript as first parameter. This can be used in helper scripts to identify the response that was given by a PDP to a request, because you can insert <pamxacml:GUID /> as an argument to a <pamxacml:INVOKE /> command. This value is also passed to the obligationsScript as first argument, if specified in the PAM configuration file.


The value of a field can be requested by writing  <pamxacml:Fieldname /> inside the XML template. Another powerful capability of the template mechanism is to call external scripts. If you use a line like

<pamxacml:INVOKE>/path/to/Script argument1 argument2 <pamxacml:Fieldname /></pamxacml:INVOKE>

The script /path/to/script will be invoked and will be given the parameters you specified. You can even provide pam_xacmls fields as arguments like Username or GUID. You can see a complete example in the appendix.

Legacy parameters

The following options control the behavior of pam_xacml in regards of compatibility to existing applications:






If present, pam_xacml will not fail if the application does not understand the obligations.



If present, pam_xacml will not send any obligations to the application (for legacy applications). This can only be set together with obligationsNotMandatory.


Option pdpRequester

This option controls what PDP will be asked for the decision. Several PDPs exist, some only useful for deb ugging purposes. To implement your own PDP requesters, have a look at the appropriate directory in the source code (src/core/...).



Further parameters


Will always return this XACML response, independent of the request.



For a simple TCP PDP that accepts plain XACML Requests and sends pure XACML Response. (Without SOAP, SAML, Security!)



For a PDP that accepts SOAP encapsulated XACML Requests and XACML Response.



For the PDP written by Hannes Angst.



Arguments to pdpRequester




Path to a file containing a valid XACML response.


This parameter contains the ip address and port number of a TCP service. Look for example at the SimplePDP in the PDP subdirectory of the pam_xacml distribution. The value of this parameter should look like


The value of this parameter is an URL to a webservice which answers XACML requests. For example, use http://localhost:8080/webservice


Parameter obligationsScript

This parameter needs as value the complete path to a script which receives the XACML response from the PDP on STDIN and exits with 0 if it understood the obligations and was able to enforce them or any other return code if it could not ensure the obligations. Additionally, the script is passed the GUID as first command line argument which is also passed to the INTERNAL and the SCRIPT engine request generators. A sample script can be seen in the appendix.

4.First Steps

Sample Configuration Files

You can find some sample configurations files in the dist/ directory of the distribution. Configuration files for the included test program are contained within the dist/pam.d directory and should be copied to /etc/pam.d. The dist/templates directory contains a request templated that can be used with the internal request builder.

Simple PDP

We included a simple, Java-based Policy Decision Point that is based upon the Sun XACML framework. It can be found in the PDP/SimplePDP subdirectory of the distribution. To build it, you will need to get several libraries from the internet:




Place them into the subdirectories according to the README in the PDP/SimplePDP directory.

Afterwards, you will be able to run the build and the execute script. You can test your installation by running

SimplePDP listens on Port 1234 by default and receives raw XACML requests over a TCP/IP connection and responses in a raw format.

Joseph Besters PDP

Joseph Besters PDP is build automatically when you build pamxacml. It is contained in the subdirectory src/ext-lib/xacml-1.0. The server is named „xacml-server“. When you start it, you will be able to use it with pdpRequester=BESTER. Please specifiy http://localhost:8080/wsrt/services/XACML as pdpEndpoint (or modify it appropiatly).


Sample request template

<?xml version="1.0" encoding="UTF-8"?>

<Request xmlns="urn:oasis:names:tc:xacml:2.0:context:schema:os" xmlns:xsi="" xsi:schemaLocation="urn:oasis:names:tc:xacml:2.0:context:schema:os">


    <Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:subject:subject-id" DataType="">

      <AttributeValue><pamxacml:Username /></AttributeValue>




     <Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:resource:resource-id" DataType=""><AttributeValue><pamxacml:Resource /></AttributeValue></Attribute>



     <Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:action:action-id" DataType=""><AttributeValue>TestAction</AttributeValue></Attribute>



     <Attribute AttributeId="urn:pamxacml:hostname" DataType=""><AttributeValue><pamxacml:Hostname /></AttributeValue></Attribute>

     <Attribute AttributeId="urn:pamxacml:extended" DataType=""><AttributeValue><pamxacml:INVOKE>/Users/theide/Documents/workspace/pamxacml/tests/ Arg1 <pamxacml:Username /> Arg2 Arg3</pamxacml:INVOKE></AttributeValue></Attribute>

     <Attribute AttributeId="urn:pamxacml:guid" DataType=""><AttributeValue><pamxacml:GUID /></AttributeValue></Attribute>



A sample obligationsScript

Please pay attention to the line breaks when testing this example.



x=`cat /dev/stdin`


echo "=========================" >>/tmp/


echo "Unique ID: $1" >>/tmp/


echo "Received on $date" >>/tmp/


echo $x >> /tmp/obligations-receiver


#exit -2

exit 0


[1] Joseph Besters original work can be found at

[2] see X/Open Single Sign-on Service (XSSO) - Pluggable Authentication Modules,

[3] gSOAP download page

[4] Fink can be obtained from