<html>
<head>
<meta content="text/html; charset=ISO-8859-1"
http-equiv="Content-Type">
</head>
<body bgcolor="#FFFFFF" text="#000000">
<div class="moz-cite-prefix">On 11/14/2012 08:51 AM, Pete Muir
wrote:<br>
</div>
<blockquote
cite="mid:564E743E-C3F7-47EC-BE17-8E5FA25683CE@redhat.com"
type="cite"><br>
<div>
<div>On 14 Nov 2012, at 00:26, Shane Bryzak wrote:</div>
<br class="Apple-interchange-newline">
<blockquote type="cite">
<meta http-equiv="content-type" content="text/html;
charset=ISO-8859-1">
<div bgcolor="#FFFFFF" text="#000000"> I'd like to go through
the proposed design for Realms and Applications in detail,
as this is quite an important feature to get right and we
all need to be on the same page with this before we proceed.<br>
<br>
To start with the basics, let's look at the relationship
between Realms and Applications:<br>
<br>
<img alt="Realms and Applications"
id="9be26f65-8ba3-4dcc-807c-c15ffc5ac162"
apple-width="yes" apple-height="yes"
src="cid:part1.02030308.08070801@redhat.com" height="245"
width="623"><br>
<br>
Each realm is a totally segregated "island" of identity
state, with no crossover of state between the realms.
Applications, Users, Groups and Roles only exist within the
scope of their containing realm. Realms are top level
constructs, and due to reasons of complexity and
practicality we don't support a Realm "hierarchy"; i.e.
there are no Realms within Realms.<br>
<br>
Let's take a look next at how Users and Groups fit into
this:<br>
<br>
<img alt="Users and Groups"
id="a9e53088-c62b-4e06-a208-ecaf9ab9db27"
apple-width="yes" apple-height="yes"
src="cid:part2.05010503.06020002@redhat.com" height="244"
width="599"><br>
<br>
All User and Group objects are first class citizens within a
Realm. If we think of this in terms of the corporate model,
a company may be represented by a single Realm, with its
employees as Users. Each department and sub-division could
be represented as a Group, with Users (employees) belonging
to one or more of these Groups. There is also a hierarchy
for Groups, which allows greater flexibility in defining the
company structure. Let's take a closer look at how this
structure is defined:<br>
<br>
<img alt="User and Group Memberships"
id="f5ef3e20-0c27-436b-8892-dd8c6f4bee78"
apple-width="yes" apple-height="yes"
src="cid:part3.08080707.08060403@redhat.com" height="244"
width="506"><br>
<br>
Each User can be a member of zero or more Groups, while each
Group may be a subgroup of one parent Group.<br>
<br>
Let's take a look at Roles next. While both Users and
Groups sit at the top level of the Realm, Roles are all
application specific:<br>
<br>
<br>
<img alt="Roles" id="496b9c02-e693-4e7a-b3f3-be085651dd2a"
apple-width="yes" apple-height="yes"
src="cid:part4.05070108.09060309@redhat.com" height="244"
width="312"><br>
<br>
Each Application may define zero or more Roles, each of
which may be used within the scope of the Application's
authorization rules to determine the appropriate privilege
levels for Users. Roles may be granted to either a User or
a Group, as illustrated by the following diagram:<br>
<br>
<br>
<img alt="User and Group Roles"
id="e22d27ce-d05d-4b80-8016-0a140d6a44b2"
apple-width="yes" apple-height="yes"
src="cid:part5.07070102.06000407@redhat.com" height="278"
width="608"><br>
<br>
Each role may be granted as an Application Role (i.e. a Role
membership that has no Group component) or as a "standard"
Role (which does have a Group component). An Application
Role is used to grant broad application privileges to a
select User or Group, for example you might wish to grant an
Application-specific "admin" role to all members of the
"/employees/itdepartment/managers" Group. A standard role
is used when you wish to grant a Group-specific privilege to
either an individual User or a Group of Users, for example
granting a User the Role "TechSupport" for the Group
"/department/cardiology/doctors".<br>
<br>
So in summary, PicketLink will support:<br>
<br>
1) Realms, which represent top level boundaries of
segregated identity state, and are arranged in a flat
(rather than hierarchical) structure.<br>
<br>
2) Applications, which essentially represent a group of
services and resources.<br>
<br>
3) Roles, which are specific to an Application and are
defined for the purpose of controlling access to the
services and resources provided by the Application.<br>
<br>
4) Users, a top level construct within a Realm that
represents an entity that may access the services and
resources provided by one or more Applications.<br>
<br>
5) Groups, another type of top level construct within a
Realm, arranged within a hierarchical structure and that may
be used to define broader associations of Users and
sub-Groups for the purpose of assigning coarse-grained
privileges to an Application's services and resources.<br>
<br>
Impact on Identity Management API<br>
-----------------------------------------------<br>
One of the most important factors in implementing support
for Realms and Applications is the impact on the IDM API.
As a primary goal for PicketLink is to provide a simplified
API for developers, this support must be provided in a
manner that doesn't pollute the API with unnecessary
complexity. To that end, let's start by looking at the
simplest use case, in which a developer embeds PicketLink
into their own application.<br>
<br>
Default Realm and Application<br>
--------------------------------------<br>
To allow for a developer to use PicketLink in the simplest
way possible, I propose that we introduce the concept of a
"default" Realm and "default" Application. By doing this,
we can allow the developer to simply use the basic
PicketLink API without having to be aware of these more
advanced features. For example, let's pretend that the
developer wants to create a new User:<br>
<br>
User user = new SimpleUser("jsmith");<br>
<br>
If we were forcing the developer to deal with Realms and
Applications, they would then have to write something like
this to create the new User:<br>
<br>
identityManager<br>
.forRealm("default")<br>
.createUser(user);<br>
<br>
However by assuming that an unspecified Realm is the
"default" realm, the code looks like this:<br>
<br>
identityManager<br>
.createUser(user);<br>
<br>
If the default Realm doesn't exist at the time, it will be
created automatically (the same goes for the default
Application).<br>
<br>
Likewise, when creating a new Role:<br>
<br>
Role role = new SimpleRole("admin");<br>
<br>
The developer would have to write the following code if we
didn't support a default application:<br>
<br>
identityManager<br>
.forApplication("default")<br>
.createRole(role);<br>
<br>
If we do support a default though, the code looks like this:<br>
<br>
identityManager<br>
.createRole(role);<br>
<br>
As a side note, the above examples are slightly contrived
because the forRealm() and forApplication() methods wouldn't
accept a String (rather they'd expect either a Realm or
Application object) - this leads us into our next point.<br>
<br>
Realm and Application Management<br>
----------------------------------------------<br>
To properly support Realms and Applications we will require
a number of management methods, similar to what we have for
Users, Groups and Roles. I propose the addition of the
following methods to IdentityManager:<br>
<br>
void createRealm(Realm realm);<br>
Realm getRealm(String realm);<br>
void removeRealm(Realm realm);<br>
Collection<Realm> getRealms();<br>
<br>
void createApplication(Application application);<br>
Application getApplication(Realm realm, String application);<br>
void removeApplication(Application application);<br>
Collection<Application> getApplications(Realm realm);<br>
<br>
This obviously requires the addition of two new classes to
the model API also, Realm and Application:<br>
<br>
public class Realm {<br>
private String name;<br>
public Realm(String name) {<br>
this.name = name;<br>
};<br>
public String getName() {<br>
return name;<br>
}<br>
}<br>
<br>
public class Application {<br>
private Realm realm;<br>
private String name;<br>
public Application(Realm realm, String name) {<br>
this.realm = realm;<br>
this.name = name;<br>
}<br>
public Realm getRealm() {<br>
return realm;<br>
}<br>
public String getName() {<br>
return name;<br>
}<br>
}<br>
<br>
Usage<br>
--------<br>
One other thing I'd like to discuss is usage scenarios,
specifically in Java EE6 applications. I'd like to propose
that we provide a producer method that supports the
following form of injection for the IdentityManager:<br>
<br>
First of all, injecting an IdentityManager that uses the
default Realm and default Application (the most common use
case for embedded PicketLink):<br>
<br>
@Inject IdentityManager identityManager;<br>
<br>
Secondly, injecting an IdentityManager for a specific Realm:<br>
<br>
@Inject @ForRealm("public") IdentityManager identityManager;<br>
<br>
Lastly, injecting an IdentityManager for a specific
Application:<br>
<br>
@Inject @ForRealm("public") @ForApplication("forums")
IdentityManager identityManager;<br>
</div>
</blockquote>
<div><br>
</div>
<div>This seems good, except we should allow for creating
annotations to represent realms, applications etc. A bit like
resource producers.</div>
</div>
</blockquote>
Additionally we need annotations. We need to be able to work the IDM
in a non injectable environment too, where people want to wire
things themselves.<br>
<blockquote
cite="mid:564E743E-C3F7-47EC-BE17-8E5FA25683CE@redhat.com"
type="cite">
<div><br>
<blockquote type="cite">
<div bgcolor="#FFFFFF" text="#000000"> <br>
It would also be nice if we could provide support for
"configure once", where the developer can configure a
specific Realm and Application and any injected
IdentityManager would default to using them. There's
probably a few different ways to achieve this, so if anyone
has a preference please let me know.<br>
<br>
Summary<br>
------------<br>
This pretty much describes the entire proposal for Realms
and Applications. I'd like all stakeholders to please
carefully review the design, in particular the 5 summary
points that describe the restrictions of this model. If we
all agree on this, then we should be able to release a
stable version of the API very shortly. Some further work
may be required the bring the configuration and some
IdentityStore implementation details inline with the new
design, but that won't affect the API.<br>
<br>
Thanks!<br>
Shane<br>
</div>
</blockquote>
</div>
</blockquote>
</body>
</html>