From portal-commits at lists.jboss.org Wed Jan 31 18:48:33 2007 Content-Type: multipart/mixed; boundary="===============2072222544171113921==" 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: --===============2072222544171113921== 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 - - 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: + + = --===============2072222544171113921==--