You are here: Home » Development » Documentation » Guidance on Using A&A

Guidance on Using A&A

A Concise Developer Guidance on how to use the A&A infrastructure API



Set Up A&A server

  1. OpenSSO (Note: the product has been renamed to OpenAM, the terms are used interchangeably).
    • Download [OpenAM] and set up using a suitable web application container (Guidance) and OpenAM default settings.
    • Set 'ssoadm.disabled = false' in the site preferences (advanced settings).
    • In the console, change into your local realm.
      • Privileges: Set as shown here.
      • Data Store: Create a module which represents your LDAP backend server.
      • Services: Modify the policy configuration to use your LDAP subjects as policy subjects.
      • Hook your LDAP server into the authentication chain.
        • Create an authentication module with your LDAP, then insert it into the authentication chain (condition: SUFFICIENT). Now you can login to OpenAM with the LDAP user accounts.

      • Some Hints:
        • Under Authentication => Core => Show all core settings, set User Profile: Ignored.
        • Under Services => Policy Configuration, set Selected Policy Subjects to LDAP Groups, LDAP Roles, LDAP Users.

  2. Policy service.
    • Download [Github].
    • Configure it (see README).
    • Build WAR file using Maven (see README), deploy WAR in the same web application container as in 1.

  3. MySQL.
    • Set up using the same root password as for the admin user in OpenAM. Furthermore, allow connections from localhost.
    • Create database Pol.
    • Create table pol (see the Policy Service README).



Important Links



Certain wildcards are now allowed in resource URIs in policies. These are:



Generic API

There exist  generic APIs mapping policy and OpenSSO services as follows:

/pol =>/Pol/opensso-pol

and the OpenSSO interface at

/auth/attributes => /opensso/identity/attributes
/auth/authenticate => /opensso/identity/authenticate
/auth/isTokenValid => /opensso/identity/isTokenValid
/auth/authorize => /opensso/identity/authorize
/auth/logout => /opensso/identity/logout

This document uses the latter. In case of problems with the generic interface please consider also using the latter.


Example Workflow




 Example Session (Authentication & Authorisation)

After configuring policies for target URI http://opentox:8080/protected, the REST calls below may be used for authentication and authorisation.

Note: OpenSSO accesses the Plone user data repository for authentication. Thus, the fields UID and SEC should be replaced with values for a user configured in the OpenTox website.

# Authentication...
curl -i -d "username=<UID>" -d "password=<SEC>"

Reply: HTTP/1.1 200 OK
Content-Type: text/plain

# Authorisation...
curl -i -d "uri=" –d "action=GET" 
-d "subjectid=AQIC5wM2LY4SfcxrnpcZCmbfdsKTyxG9E66uu5FVhefps7I%3D%40AAJTSQACMDE%3D%23"

Reply: HTTP/1.1 200 OK
Content-Type: text/plain

Here, authorisation is granted for the user (boolean=true). <UID> and <SEC> should be replaced with credentials of a Plone website user.

Note: All parts of the query were URL-encoded here.
Note: For multiple authentications of the same user the ForceAuth flag may be used by appending &uri=ForceAuth=true to the authentication query



Example Session (Policies)

# Listing all my policies...
curl -i -X GET \
-H “subjectid:AQIC5wM2LY4SfcyH9ELyynby356aOvAkimDYeEz2wzWTSX4=@AAJTSQACMDE=#”

HTTP/1.1 200 OK
Content-Type: text/plain

# Creating a policy...
curl -i -H "Content-Type: application/xml" -T /home/am/aa/Pol-REST/sample-pol.xml \ 
-H “subjectid:AQIC5wM2LY4SfcyH9ELyynby356aOvAkimDYeEz2wzWTSX4=@AAJTSQACMDE=#”

HTTP/1.1 200 OK
Content-Type: text/plain
Policies were created under realm, /.

# Listing all my policies (again)...
curl -i -X GET \ 
-H “subjectid:AQIC5wM2LY4SfcyH9ELyynby356aOvAkimDYeEz2wzWTSX4=@AAJTSQACMDE=#”

HTTP/1.1 200 OK
Content-Type: text/plain

# Listing my s2 policy...
curl -i -X GET -H "subjectid: AQIC5wM2LY4SfcyH9ELyynby356aOvAkimDYeEz2wzWTSX4=@AAJTSQACMDE=#" -H "id: s2_policy"
HTTP/1.1 200 OK
Server: nginx/0.6.32
Content-Type: text/xml
<?xml version="1.0" encoding="UTF-8"?>
    <Policy name="s2_policy" createdby="id=amadmin,ou=user,dc=opensso,dc=java,dc=net"
lastmodifiedby="id=amadmin,ou=user,dc=opensso,dc=java,dc=net" creationdate="1275290803394"
lastmodifieddate="1275290803394" referralPolicy="false" active="true">
        <Rule name="s2 rule 2">
            <ServiceName name="iPlanetAMWebAgentService"/>
            <ResourceName name=""/>
                <Attribute name="POST"/>
                <Attribute name="GET"/>
        <Subjects name="s2 subject 2" description="">
            <Subject name="amaunz" type="LDAPUsers" includeType="inclusive">
                    <Attribute name="Values"/>

# Deleting my policy...
curl -i -X DELETE -H "id: s2_policy" -H "subjectid:
HTTP/1.1 200 OK
Content-Type: text/plain
Policies were deleted under realm, /.

REST interface (Policies)

To create a policy, issue a POST to http://<pol-server>/Pol/opensso-pol with the XML file to transfer and header
entry "Content-Type: application/xml".  See Documentation and Authentication and Authorisation API.


Obtaining User Attributes

OpenSSO provides user attributes associated with a specific token, such as the distinguished name (dn) needed in policies, as well as other information, through a dedicated service:


# User attributes...
curl -i –d "attributes_names=uid” –d “subjectid=AQIC5wM2LYaSfcyjBrAxpCWyKYD7SYN0yh%2Ba2TCDf2Fz97E%3D%40AAJTSQACMDE%3D%23" \

HTTP/1.1 200 OK
Content-Type: text/plain
userdetails.attribute.value=Maunz Andreas

Obtaining Group Membership Data

Since policies allow for authorisation based on groups, services for finding groups, and the groups a specific
user is in, should be in available. OpenSSO provides such facilities with the “search” and “read” services (9).

# Listing all groups...
curl -i -d "attributes_names=objecttype" -d "attributes_values_objecttype=group" \ 
-d "admin=AQIC5wM2LY4SfcwSwYFi4MY3Z%2Ff52VpgCovcl%2FItde2OC0I%3D%40AAJTSQACMDE%3D%23" \

HTTP/1.1 200 OK
Content-Type: text/plain

# Membership of a specific user...
curl -i -d "name=amaunz" -d attributes_names="group" \ 
-d "admin=AQIC5wM2LY4SfcwSwYFi4MY3Z%2Ff52VpgCovcl%2FItde2OC0I%3D%40AAJTSQACMDE%3D%23" \

HTTP/1.1 200 OK
Content-Type: text/plain

There exist two groups, “development” and “partner”. User “amaunz” is member of both.

Note, that the parameter for the token is now “admin”. Any registered user is entitled to search for groups and memberships. It is also possible to search for all existing usernames by setting attributes_values_objecttype=user in the first query above.

Managing Privileges

A privilege is a “policy for policies”, i.e. a privilege regulates access to the URI of the policy. Our system implements such a service (see chapter 4) by allowing only the owner to change the policy.

Creating and Deleting Privileges

For every newly created policy, a privilege is simultaneously created. On write access (currently only DELETE) to the policy, authorisation is requested from the privilege unless the policy has not been existent before (creation of a policy). In the latter case, the user creating the policy is associated with it as the owner of the policy.

There are two basic use cases for policy p at URI u, protected by privilege q:

  1. Create p at URI u, where there is no existing policy for u. This requires no authorisation and creates q. As a side effect, the system remembers the user and associates him/her with q as the owner of q.
  2. Delete p. This requires write access to u, granted or denied by q. Only the owner has write access.

The described procedure gives the owner full control over the policies created by him. In this way, he/she can control who has the right to access a particular algorithm, model, dataset, etc.  Deleting a policy releases the protected URIs.

Multiple Policies

The owner can register multiple policies referencing the same resource “on top" of the first policy. Upon an authorisation request, OpenSSO calculates then the effective policy from all policies, as described in section 4 of the deliverable.

Document Actions