From portal-commits at lists.jboss.org Wed Jan 31 18:48:33 2007
Content-Type: multipart/mixed; boundary="===============7265474228854577493=="
MIME-Version: 1.0
From: portal-commits at lists.jboss.org
To: portal-commits at lists.jboss.org
Subject: [portal-commits] JBoss Portal SVN: r6134 -
docs/trunk/referenceGuide/en/modules.
Date: Wed, 31 Jan 2007 18:48:33 -0500
Message-ID:
--===============7265474228854577493==
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable
Author: bdaw
Date: 2007-01-31 18:48:33 -0500 (Wed, 31 Jan 2007)
New Revision: 6134
Modified:
docs/trunk/referenceGuide/en/modules/identity.xml
Log:
some more stuff about identity
Modified: docs/trunk/referenceGuide/en/modules/identity.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- docs/trunk/referenceGuide/en/modules/identity.xml 2007-01-31 15:51:38 U=
TC (rev 6133)
+++ docs/trunk/referenceGuide/en/modules/identity.xml 2007-01-31 23:48:33 U=
TC (rev 6134)
@@ -1,29 +1,29 @@
-
-
- Boleslaw
- Dawidowicz
- boleslaw.dawidowicz at jboss dot com
-
-
- JBoss Portal Identity management
- This chapter addresses identity management in JBoss Portal 2.6=
para>
-
- Identity management API
- Since JBoss Portal 2.6 there are 4 identity services and 2 i=
dentity related interfaces. The goal of
- having such a fine grained API is to enable flexible implement=
ations based on different
- identity storage like relational databases or LDAP servers. Th=
e Membership service takes care of managing the relationship
- between user objects and role objects. The User Profile servic=
e is responsible for managing the profile of a user,
- it has database and LDAP implementations as well as a mode tha=
t combines data from both.
-
-
-
-
- The org.jboss.portal.identity.=
User
- interface represents a user and exposes the following =
operations:
-
-
-
+
+ Boleslaw
+ Dawidowicz
+ boleslaw.dawidowicz at jboss dot com
+
+
+ JBoss Portal Identity management
+ This chapter addresses identity management in JBoss Portal 2.6
+
+ Identity management API
+ Since JBoss Portal 2.6 there are 4 identity services and 2 ide=
ntity related interfaces. The goal of
+ having such a fine grained API is to enable flexible implementati=
ons based on different
+ identity storage like relational databases or LDAP servers. The M=
embership service takes care of managing the relationship
+ between user objects and role objects. The User Profile service i=
s responsible for managing the profile of a user,
+ it has database and LDAP implementations as well as a mode that c=
ombines data from both.
+
+
+
+
+ The org.jboss.portal.identity.User<=
/emphasis>
+ interface represents a user and exposes the following opera=
tions:
+
+
+
-
-
- Important Note! The proper usage of getId() method is:
-
-
+
+ Important Note! The proper usage of getId() method is:
+
+
-
- This is because the ID value depends on the User imple=
mentation. It'll probably be String object with the LDAP
- implementation and a Long object with the database imp=
lementation but it could be something else
- if one has chosen to make its own implementation.
-
-
-
-
- The org.jboss.portal.identity.=
Role interface represents a Role
- and exposes the following operations:
-
-
-
+ This is because the ID value depends on the User implementa=
tion. It'll probably be String object with the LDAP
+ implementation and a Long object with the database implemen=
tation but it could be something else
+ if one has chosen to make its own implementation.
+
+
+
+
+ The org.jboss.portal.identity.Role<=
/emphasis> interface represents a Role
+ and exposes the following operations:
+
+
+
-
-
-
-
- The org.jboss.portal.identity.=
UserModule
- interface exposes operations for users management:
-
-
-
+
+
+
+ The org.jboss.portal.identity.UserM=
odule
+ interface exposes operations for users management:
+
+
+
-
-
-
-
- The org.jboss.portal.identity.=
RoleModule
- interface exposes operations for roles management:
-
-
-
+
+
+
+ The org.jboss.portal.identity.RoleM=
odule
+ interface exposes operations for roles management:
+
+
+
-
-
-
-
- The MembershipModule
- interface exposes operations for obtaining or managing=
relationships beetween users and roles.
- The role of this service is to decouple relationship i=
nformation from user and roles.
- Indeed while user role relationship is pretty straight=
forward with a relational database (using
- a many to many relationship with an intermediary table=
), with an LDAP server there a different
- ways to define relationships between users and roles.
-
-
-
+
+
+
+ The MembershipModule
+ interface exposes operations for obtaining or managing rela=
tionships beetween users and roles.
+ The role of this service is to decouple relationship inform=
ation from user and roles.
+ Indeed while user role relationship is pretty straightforwa=
rd with a relational database (using
+ a many to many relationship with an intermediary table), wi=
th an LDAP server there a different
+ ways to define relationships between users and roles.
+
+
+
-
-
-
-
- The UserProfileModule
- interface exposes operations to access and manage info=
rmations stored in User profile:
-
-
-
+
+
+
+ The UserProfileModule
+ interface exposes operations to access and manage informati=
ons stored in User profile:
+
+
+
-
-
- UserProfileModule.getProperty() method returns an Obje=
ct.
- In most cases with DB backend it will always be String=
object. But normally you should check what
- object will be retreived using getProfileInfo() method.
-
-
-
-
- The ProfileInfo
- interface can be obtained using the
- UserProfileModule
- and exposes meta information of a profile:
-
-
-
+
+ UserProfileModule.getProperty() method returns an Object.
+ In most cases with DB backend it will always be String obje=
ct. But normally you should check what
+ object will be retreived using getProfileInfo() method.
+
+
+
+
+ The ProfileInfo
+ interface can be obtained using the
+ UserProfileModule
+ and exposes meta information of a profile:
+
+
+
-
-
-
-
- PropertyInfo
- interface expose methods to obtain information about a=
ccessible property in User profile
-
-
-
+
+
+
+ PropertyInfo
+ interface expose methods to obtain information about access=
ible property in User profile
+
+
+
-
-
+
+
=
-
+
=
-
- Ways to access identity modules
-
- The best way to access identity modules is by using JNDI:
-
-
- import org.jboss.portal.identity.UserModule;
- import org.jboss.portal.identity.RoleModule;
- import org.jboss.portal.identity.MembershipModule;
- import org.jboss.portal.identity.UserProfileModule;
+
+ Ways to access identity modules
+
+ The best way to access identity modules is by using JNDI:
+
+
+ import org.jboss.portal.identity.UserModule;
+ import org.jboss.portal.identity.RoleModule;
+ import org.jboss.portal.identity.MembershipModule;
+ import org.jboss.portal.identity.UserProfileModule;
=
- [...]
+ [...]
=
- (UserModule)new InitialContext().lookup("java:portal/UserM=
odule");
- (RoleModule)new InitialContext().lookup("java:portal/RoleM=
odule");
- (MembershipModule)new InitialContext().lookup("java:portal=
/MembershipModule");
- (UserProfileModule)new InitialContext().lookup("java:porta=
l/UserProfileModule");
+ (UserModule)new InitialContext().lookup("java:portal/UserModul=
e");
+ (RoleModule)new InitialContext().lookup("java:portal/RoleModul=
e");
+ (MembershipModule)new InitialContext().lookup("java:portal/Mem=
bershipModule");
+ (UserProfileModule)new InitialContext().lookup("java:portal/Us=
erProfileModule");
=
-
-
- Another way to do this is, if you are fimiliar with JBoss =
Mikrokernel architecture is to
- get the IdentityServiceController=
- mbean. You may want to inject it into your services like t=
his:
-
-
- portal:service=3DModule,type=3DIdent=
ityServiceController]]>
-
-
- or simply obtain in your code by doing a lookup using
- the portal:service=3DModule,type=
=3DIdentityServiceController
- name. Please refer to the JBoss Application Server documen=
tation if you want to learn more
- about service MBeans. Once you obtained the object you can=
use it:
-
+
+
+ Another way to do this is, if you are fimiliar with JBoss Mikr=
okernel architecture is to
+ get the IdentityServiceController
+ mbean. You may want to inject it into your services like this:
+
+
+ portal:service=3DModule,type=3DIdentityS=
erviceController]]>
+
+
+ or simply obtain in your code by doing a lookup using
+ the portal:service=3DModule,type=3DIde=
ntityServiceController
+ name. Please refer to the JBoss Application Server documentati=
on if you want to learn more
+ about service MBeans. Once you obtained the object you can use=
it:
+
=
-
- (UserModule)identityServiceController.getIdentityContext()=
.getObject(IdentityContext.TYPE_USER_MODULE);
- (RoleModule)identityServiceController.getIdentityContext()=
.getObject(IdentityContext.TYPE_ROLE_MODULE);
- (MembershipModule)identityServiceController.getIdentityCon=
text().getObject(IdentityContext.TYPE_MEMBERSHIP_MODULE);
- (UserProfileModule)identityServiceController.getIdentityCo=
ntext().getObject(IdentityContext.TYPE_USER_PROFILE_MODULE);
-
+
+ (UserModule)identityServiceController.getIdentityContext().get=
Object(IdentityContext.TYPE_USER_MODULE);
+ (RoleModule)identityServiceController.getIdentityContext().get=
Object(IdentityContext.TYPE_ROLE_MODULE);
+ (MembershipModule)identityServiceController.getIdentityContext=
().getObject(IdentityContext.TYPE_MEMBERSHIP_MODULE);
+ (UserProfileModule)identityServiceController.getIdentityContex=
t().getObject(IdentityContext.TYPE_USER_PROFILE_MODULE);
+
=
-
-
- API changes since 2.4
- Because in JBoss Portal 2.4 there were only
- UserModule
- ,
- RoleModule
- ,
- User
- and
- Role
- interfaces some API usages changed. Here are the most impo=
rtant changes you will need to aply to your
- code while migrating your aplication to 2.6:
-
-
-
-
- For the User in=
terface:
-
-
-
+
+ API changes since 2.4
+ Because in JBoss Portal 2.4 there were only
+ UserModule
+ ,
+ RoleModule
+ ,
+ User
+ and
+ Role
+ interfaces some API usages changed. Here are the most importan=
t changes you will need to aply to your
+ code while migrating your aplication to 2.6:
+
+
+
+
+ For the User interfac=
e:
+
+
+
-
-
-
-
- The RoleModule =
interface:
-
-
-
+
+
+
+ The RoleModule interf=
ace:
+
+
+
-
-
-
-
-
-
- How to enable LDAP usage in JBoss Portal
- We'll describe here the simple steps that you'll need to ena=
ble LDAP support in JBoss Portal.
- For additional information you need to study more about configurat=
ion of identity and specific implementations of identity modules
- There are two ways to achieve this:
-
-
- In
- jboss-porta.sar/META-INF/jboss=
-service.xml
- in section:
-
-
-
+
+
+
+
+
+ How to enable LDAP usage in JBoss Portal
+ We'll describe here the simple steps that you'll need to enabl=
e LDAP support in JBoss Portal.
+ For additional information you need to study more about configura=
tion of identity and specific implementations of identity modules
+ There are two ways to achieve this:
+
+
+ In
+ jboss-porta.sar/META-INF/jboss-serv=
ice.xml
+ in section:
+
+
+ conf/identit=
y/standardidentity-config.xml
]]>
-
-
- change
- identity-config.xml
- to
- ldap_identity-config.xml
-
-
-
- Swap the names or content of files in
- jboss-porta.sar/conf/identity/=
identity-config.xml
- and
- jboss-porta.sar/conf/identity/=
ldap_identity-config.xml
+
+
+ change
+ identity-config.xml
+ to
+ ldap_identity-config.xml
+
+
+
+ Swap the names or content of files in
+ jboss-porta.sar/conf/identity/ident=
ity-config.xml
+ and
+ jboss-porta.sar/conf/identity/ldap_=
identity-config.xml
=
-
-
-
-
- After doing on of above changes you need to edit configuration=
file that you choose to
- use (identity-config.xml or ldap_identity-config.xml) and conf=
igure LDAP connection options in section:
-
-
-
+
+
+
+ After doing on of above changes you need to edit configuration fi=
le that you choose to
+ use (identity-config.xml or ldap_identity-config.xml) and configu=
re LDAP connection options in section:
+
+
+
LDAP
@@ -468,12 +468,12 @@
]]>
-
-
- You also need to specify options for your LDAP tree (described=
in configuration documentation) like those:
-
-
-
+
+ You also need to specify options for your LDAP tree (described in=
configuration documentation) like those:
+
+
+
common
]]>
-
+
=
=
-
-
- Identity configuration
- TODO: About the format and architecture of identity configur=
ation files
+
+
+ Identity configuration
+ At the beginning to understand identity configuration you need=
to understand how it is designed to work in portal.
+ Different identity services like UserModule, RoleModule and etc a=
re just plain java classes that are instantiated and exposed
+ by portal. So *example* UserModule service could be plain java b=
ean object tha will be:
+
+ Instantiated usin=
g relfection
+ Initialized/Started by invoking some methods
+ Registered/Exposed using JNDI and/or mbeans (JBoss Mikrokernel) services, so
+ other citizens of the portal can use it
+ Managed in the ma=
tter of lifecycle - so it'll be stopped and unregistered during
+ portal shutdown
+
+ As you see from this standpoint configuration just specifies whic=
h java class and how should be used by portal as a service.
+ We use JBoss Microcontainer to manage state of those compon=
ents so if you are interested in implementation of
+ custom ones - look on the methods that are leveraged by this fram=
ework.
+
+
+ In JBoss Portal we provide very flexible configuration. It's very=
easy to rearange and customize services,
+ provide and plug in own implementations, extend current ones or e=
xtend identity model with own solutions using
+ provided configuration service.
+
+ To have the complete picture of the configuration of identity =
services let's start from it's root
+ component. Whole configuration and setup of identity components i=
s made by
+ IdentityServiceController. It =
brings to life and registers all other components
+ like UserModule, RoleModule, MembershipModule and UserProfileModu=
le.
+ IdentityServiceController is d=
efined in
+ jboss-portal.sar/META-INF/jboss-service.xml
+
=
-
-
- Identity modules implementations
- TODO:
-
-
- Possible configuration scenarios with LDAP and RDBMS
- TODO:
-
+
+
+
+ portal:service=3DHibernate
+
+ java:/portal/Identity=
ServiceController
+ true
+ conf/identity/ident=
ity-config.xml
+ conf/identit=
y/standardidentity-config.xml
+
+ ]]>
+
+
+ We can specify few options here:
+
+
+
+ RegisterMBeans - defi=
nes if IdentityServiceController should
+ register components which are instantiated as mbeans
+
+
+
+
+ ConfigFile - defines =
location of main identity services configuration
+ file. It describes and configures all the components lik=
e UserModule, RoleModule... that need to be
+ instantiated
+
+
+
+
+ DefaultConfigFile - d=
efines location of configuration file containing
+ default values. For each component defined in ConfigFile IdentityServiceController
+ will look into this location to grab set of default opti=
ons. This simply makes the main configuration file
+ simpler and shorter while still enabling more powerfull =
customization.
+
+
+
+
+
+ Main configuration file architecture (identity-config.xml)=
+
+ The file describing portal identity services contains three se=
ctions:
+
+
+
+
+
+ ...
+ ...
+ ...
+
+
+
+ ...
+ ...
+ ...
+
+
+
+ ...
+ ...
+ ...
+
+
+ ]]>
+
+
+ Datasources
+ This section defines datasource components. They will be=
processed and instantiated before components in
+ Module section, so they wil=
l be ready to serve them.
+ This section isn't used whith Database configuration as =
in JBoss Portal services exposing Hibernate
+ are defined separately. It's used by LDAP configuration and we=
'll use it as an example
+
+
+ LDAP
+ portal:service=3DModule,type=3DLDAPConn=
ectionContext
+ org.jboss.portal.identity.ldap.LDAPConnectionC=
ontext
+
+
+
+
+
+
+
+
+
+
+ ]]>
+
+ If you look into JBoss Portal configuration files you wi=
ll find that and ]]>
+ are specified in DefaultConfigFile and not in ConfigFile.
+ So this is how it works. Those two will be picked up from defa=
ult configuration. The same rule takes place
+ for options - additional will be picked up from default config=
uration. Whats linking configuration in those two files
+ is the ]]> t=
ag.
+
+
+ Modules
+ Modules are core service components like UserModule, Rol=
eModule and etc.
+
+
+
+ User
+ DB
+
+
+ portal:service=3DModule,type=3DUser
+ org.jboss.portal.identity.db.HibernateUserModuleI=
mpl
+
+
+
+
+
+
+
+ ]]>
+
+
+
+
+ implementation - d=
efines the scope under which
+ configuration for different implementations of module=
s types are kept.
+ It enables to keep configurations of different implem=
entations of same module types in one configuration file
+ with default options.
+
+
+
+
+ type - must be uni=
que name across all modules defined in the main
+ configuration file. This is important as module will =
be stored with such name within IdentityContext
+ registry on runtime. Standard names are used (User, R=
ole, Membership, UserProfile). Together with
+ implementation wil=
l create unique pair within file with default configuration values.
+
+
+
+
+ service-name - wil=
l be used for registration as an MBean.
+
+
+
+
+ class - java class=
that will be use to instantiate the module.
+
+
+
+
+ config - contains =
options related to this module =
+
+
+
+ Here you can easily see the whole idea about having two =
config files - main one and the one with default values.
+ The above code snippet with User module comes from standardidentity-config.xml, so the file
+ that defines default configuration values. Because of this in =
the main configuration file the definition of
+ User module will be as short as:
+
+
+
+ User
+ DB
+
+
+ ]]>
+
+ As you see we specify only type and implementation - all th=
e other values (service-name, class and set of options)
+ will be taken from default configuration. But remember that=
still you can overwrite any of those values in the
+ main config simply by specifying them.
+
+
+
+
+ Options
+ This section provides common options that are accessible=
by identity modules. We put here options
+ that may need to be shared. They are groupped, and can have ma=
ny values:
+
+
+
+
+ common
+
+
+
+
+
+
+
+
+
+
+ userCreateAttibutes
+
+
+
+
+
+ ]]>
+
+ In this section we use the same inheritance mechanism. W=
hen option is not set, it's value will be taken
+ from the default config file. But this also means that you nee=
d to overwrite some values that
+ are specific for your LDAP architecture. All the options will =
be described along with module implementations
+ that use them.
+
+
+
+
+ Identity modules implementations
+ TODO:
+
+
+ Possible configuration scenarios with LDAP and RDBMS
+ TODO:
+
+ =
--===============7265474228854577493==--