Authentication and

Authorization

Contract No. Health-F5-2008-200787

Document Type: Authentication and Authorization in Opentox
WP/Task:
Document ID: AuthAuth-100305
Version: 2
Date:
Status: Draft Status

Organisation:
Authors:

Distribution: Developers

Purpose of Document:

Document History: 1 - Produced by Andreas Maunz (IST)

2 – Updated 100319 by Andreas Maunz (IST)
3 - Updated 100405 by Andreas Maunz (IST)

1
 Authentication and
Authorization

1 Introduction

Authentication and Authorization should impact the current OpenTox API as less as possible, but are high
priority at the same time. To that end we propose an approach that

• relies entirely on REST calls for authentication & authorization, as well as policy management, and
may be easily integrated into the current API

• features a full-grown user and group administration, as well as customizable rules based on a
multitude of criteria.

These criteria are met by OpenSSO, a single sign-on authentication and authorization server by Sun
Microsystems, plus a custom REST policy webservice, due to missing support in OpenSSO.

REST interfaces are of increasing importance. Quote from the developers:

“The recent rapid advancements and adoption of Web services, service-oriented architecture (SOA), and
Representational State Transfer (REST) architecture within enterprises have left the industry wanting more.
Organizations and developers, such as those who focus on Web 2.0, are demanding interface support from
identity and access management software. The Open Web SSO Project, called OpenSSO for short, answers
those demands.”

1.1 OpenSSO/OpenAM

OpenAM is a community-based clone of OpenSSO. OpenAM maintains 100% compatibilty to existing

OpenSSO versions. Here are some important links:

Download OpenAM: http://forgerock.com/downloads.html

OpenAM Wiki: https://wikis.forgerock.org/confluence/display/openam/Home

Download OpenSSO: http://www.sun.com/software/products/opensso_enterprise/get.jsp

Sun OpenSSO Enterprise 8.0 Administration Guide: http://docs.sun.com/app/docs/doc/820-3885

Securing Applications With Identity Services

Upgrade to OpenAM
OpenSSO Users Mailinglist
READ THIS: OpenSSO REST interface (short summary)

1.2 OpenLDAP

OpenLDAP is an LDAPv3 compatible directory server intended to hold identity information. OpenSSO can
attach a variety of such databases in a very flexible manner, including Microsofts Active Directory, and
generic LDAP servers. We use OpenLDAP as a common backend to the PLONE website and OpenSSO.

1.3 Installation
Installation is very simple and is described in “Securing Applications With Identity Services". It is only
necessary to extract and start the webserver, as well as deploy OpenSSO as a web application within it (WAR
file). Any J2EE compatible webserver can be used (e.g. Tomcat, Glassfish).

2
 Authentication and
Authorization

2 Managing Authentication and Authorization

Both, authentication and authorization, use the REST interface of OpenSSO, comprehensively described at
http://blogs.sun.com/ideas/entry/opensso_webservices_rest_interfaces and at
http://blogs.sun.com/docteger/entry/opensso_and_rest.
In short, the user authenticates against the opensso server at the URI
http://<hostname>:<port>/opensso/identity/authenticate1 by POSTing “username” and “password” and
in turn receives a token. The token may be used to get authorization from the OpenSSO server to
access (I.e. GET, POST, PUT, DELETE) a specific URI. The process of deciding authorization is governed by
policies stored on the server. The authorization request itself consists of a POST to
http://<hostname>:<port>/opensso/identity/authorize. The request should contain target URI, one
of the four access methods, and a valid token. In case of a grant, a boolean value true is
returned as content. In case of a deny, boolean false is returned.
A lot of backends (e.g. LDAP servers) can be attached to OpenSSO to validate subject identity data. Also,
very flexible policies can be created using wildcards and overlapping policies.

The flow diagram to the right

describes a possible use case
involving authentication and
authorization based on
OpenSSO:

1
Sample installation at http://sens-it-iv.fdm.uni-freiburg.de:8080

3
 Authentication and
Authorization

2.1 OpenTox Authentication and Authorization Scenario

Authentication: client authenticates against OpenSSO and obtains a token. The user data is drawn from the
LDAP backend that also the Plone website uses.
• LDAP (here: OpenLDAP) is used by the Plone website as Data Store. Therefore, Plone are instantly

available as users in OpenTox webservices.

• For unknown credentials, no token is created and an appropriate status code is generated.

Authorization: Token is used to permit or deny a client a specific action. The token encodes conjunction of
user and point of time and has a certain lifetime. If token is authorized for the action according to current
server policy, the webservice performs the action.

• Tokens encode user identity and time constraints.

• Tokens are valid for a certain time period only (customizable).
• The triplet URI+Action+Token makes up the call to be authorized (not only URI+Token).
• Actions are one of GET, PUT, POST, DELETE.

4
 Authentication and
Authorization

2.2 Example Session (Authentication & Authorization)

After configuring policies for target URI http://opentox:8080/protected (see chapter 3), the REST calls
below may be used for authentication and authorization.
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>&password=<SEC>" http://sens-it-iv.fdm.uni-
freiburg.de:8080/opensso/identity/authenticate?uri=service=openldap

Reply: HTTP/1.1 200 OK

Content-Type: text/plain
token.id=AQIC5wM2LY4SfcxrnpcZCmbfdsKTyxG9E66uu5FVhefps7I=@AAJTSQACMDE=#

# Authorization...
# ================
curl -i -d
"uri=http://opentox.org:8080/protected&action=GET&subjectid=AQIC5wM2LY4SfcxrnpcZCmbfdsKTyxG
9E66uu5FVhefps7I%3D%40AAJTSQACMDE%3D%23" http://http://sens-it-iv.fdm.uni-
freiburg.de:8080/opensso/identity/authorize

Reply: HTTP/1.1 200 OK

Content-Type: text/plain
boolean=true

Here, authorization 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 (not necessary for POST). For multiple authentications of
the same user the ForceAuth flag may be used by appending &uri=ForceAuth=true to the authentication
query string.

5
 Authentication and
Authorization

3 Managing policies
This chapter describes, how policies, on the basis of which access to a specific ressource is granted (or not
granted) are managed.

3.1 Policy handling in OpenSSO

Please review http://docs.sun.com/app/docs/doc/820-3885/gipxb?a=view to understand access policies in

OpenSSO. As currently no support is available for managing policies via REST calls in OpenSSO, we created a
specific service for this purpose. Note the following important aspects about policy evaluation:
1. http://docs.sun.com/app/docs/doc/820-3885/gjeby?a=view
"When multiple policies are applicable to a particular resource, the
order in which the policies are evaluated is not deterministic."
This means that positive results - i.e. allows - add up, as long as no negative results are encountered. In the
latter case, evaluation is stopped immediately and access is denied. In the former case, the effective
outcome policy is the addition of all the (positive) results. Access is also denied, if no rule matches.

2. https://opensso.dev.java.net/servlets/ReadMsg?listName=users&msgNo=3354

There are wildcard operators for URIs (TARGET_URI). The following URI matches all possible URIs: *://*:*/*.
The wildcard operator (*) masks protocol (http or https only), hostname, port, and ressource, respectively.
The ressource may be masked more specifically, e.g. http://*:*/path/to/* matches everything only in or
below /path/to in the webserver's root directory, assuming http protocol.
The wildcard operator stretches by default across all levels, e.g. http://opentox.org/* will match
http://opentox.org/1 as well as http://opentox.org/1/2. However, there is a one-level-wildard operator:
-*- that will only match the former.
Note: in case of a deny, a matching rule's decision can not be overridden by a more specific rule.
Upon call of the authorization REST interface, OpenSSO
1. finds all policies applicable to the combination of user (encoded in the token) and target URI.
2. creates an effective policy from the policies found in 1.
Generally, the service follows a conservative principle: the effective current policy is constrained by the most
restrictive policy that applies to the current URL. If no policy applies, access is denied.

6
 Authentication and
Authorization

3.2 REST Interface

1. Creating a policy

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". The XML file must adhere to the following schema:

<!DOCTYPE Policies PUBLIC "-//Sun Java System Access Manager7.1 2006Q3

Admin CLI DTD//EN" "jar://com/sun/identity/policy/policyAdmin.dtd">

<Policies>
<Policy name="POLICY_NAME" referralPolicy="false" active="true">
<Rule name="RULE_NAME">
<ServiceName name="iPlanetAMWebAgentService" />
<ResourceName name="TARGET_URI"/>
<AttributeValuePair>
<Attribute name="ACTION_NAME" />
<Value>ACTION_VAL</Value>
</AttributeValuePair>
</Rule>
<Subjects name="SUBJECT_GROUP" description="">
<Subject name="SUBJECT_ID" type="LDAP_TYPE" includeType="inclusive">
<AttributeValuePair>
<Attribute name="Values"/>
<Value>LDAP_DN</Value>
</AttributeValuePair>
</Subject>
</Subjects>
</Policy>
</Policies>

All parts are mandatory. The bold parts may occur more than one time. This allows for multiple actions and
subjects. The following table explains the fields that must be set:

POLICY_NAME Arbitrary string, e.g. “my_policy”. Must not contain spaces!

RULE_NAME Arbitrary string, e.g. “my rule”
TARGET_URI URI to protect, e.g. “http://opentox.mybox.org/res”
ACTION_NAME One of “GET”, “PUT”, “POST”, “DELETE”
ACTION_VAL One of “allow”, “deny”
SUBJECT_GROUP Arbitrary string, e.g. “my people”
SUBJECT_ID Arbitrary string, e.g. “John Doe”
LDAP_TYPE One of “LDAPUsers”, “LDAPGroups”
LDAP_DN Distinguished name, e.g. “uid=jdoe, ou=people, dc=opentox,dc=org”2

2. Listing policies

To view all existing policies, issue a GET to http://<pol-server>/Pol/opensso-pol

To view a specific policy pol, issue a GET to http://<pol-server>/Pol/opensso-pol/pol

3. Deleting policies

2
Individuals always use : uid=<uid>,ou=people, dc=opentox,dc=org,
Groups always use : uid=<uid>,ou=groups, dc=opentox,dc=org.
Note: <uid> should be replaced with OpenTox plone user/group ids.

7
 Authentication and
Authorization

To delete an existing policy pol, issue a DELETE to http://<pol-server>/Pol/opensso-pol/pol

The following table documents the Opentox Policy REST interface:

Desired action URL Return values (conditions)
1. Create a policy POST XML file to  200 (OK)
http://<pol-server>/Pol/opensso-pol 400 (XML contains errors)
500 (Internal Server Error)
2. List all policies GET on  200 (OK)
http://<pol-server>/Pol/opensso-pol 500 (Internal Server Error)

3. List policy pol GET on  200 (OK)

http://<pol-server>/Pol/opensso-pol/pol 500 (Internal Server Error)

4. Delete policy pol DELETE on  200 (OK)

http://<pol-server>/Pol/opensso-pol/pol 400 (Policy non-existent)
500 (Internal Server Error)

Note: PUT is currently not supported.

All operations return "Content-Type: text/plain" in their header, since they return the original output of
the ssoadm command, which is used internally to fulfill the requests.

8
 Authentication and
Authorization

3.3 Example Session (Policies)

# Listing all policies...

# =======================

curl -i -X GET http://sens-it-iv.fdm.uni-freiburg.de:8080/Pol/opensso-pol

HTTP/1.1 200 OK
Content-Type: text/plain
There were not matching policies under realm, /.

# Creating a policy...
# ====================

curl -i -H "Content-Type: application/xml" -T /home/am/aa/Pol-REST/sample-pol.xml -X POST

http://sens-it-iv.fdm.uni-freiburg.de:8080/Pol/opensso-pol

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

# Listing all policies (again)...

# ===============================

curl -i -X GET http://sens-it-iv.fdm.uni-freiburg.de:8080/Pol/opensso-pol

HTTP/1.1 200 OK
Content-Type: text/plain
Policy definitions were returned under realm, /.<?xml version="1.0" encoding="ISO-8859-1"?
><!DOCTYPE Policies PUBLIC "-//OpenSSO Policy Administration
DTD//EN""jar://com/sun/identity/policy/policyAdmin.dtd"><!-- extracted from realm, /
--><Policies><Policy name="s1_policy"
createdby="id=amadmin,ou=user,dc=opensso,dc=java,dc=net"
lastmodifiedby="id=amadmin,ou=user,dc=opensso,dc=java,dc=net" creationdate="1270473833251"
lastmodifieddate="1270473833251" referralPolicy="false" active="true" ><Rule name="s1 rule
2"><ServiceName name="iPlanetAMWebAgentService" /><ResourceName
name="http://opentox.*/s1" /><AttributeValuePair><Attribute name="POST"
/><Value>allow</Value></AttributeValuePair><AttributeValuePair><Attribute name="GET"
/><Value>allow</Value></AttributeValuePair></Rule><Subjects name="s1 subject 2"
description=""><Subject name="amaunz" type="LDAPUsers"
includeType="inclusive"><AttributeValuePair><Attribute
name="Values"/><Value>uid=amaunz,ou=people,dc=opentox,dc=org</Value></AttributeValuePair></
Subject></Subjects></Policy></Policies>

# Deleting policy...
# ==================

curl -i -X DELETE http://sens-it-iv.fdm.uni-freiburg.de:8080/Pol/opensso-pol/s1_policy

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

9
 Authentication and
Authorization

4 Perspectives

• Tokens assigned to users may be also used by webservices in a “chained” configuration. This makes
webservices inherit rights of the user, permitting a workflow involving different webservices (user is
assumed to have appropriate permissions in OpenSSO)
• Privilege service for managing policies is needed.

10