Author: julien(a)jboss.com Date: 2007-02-12 18:00:07 -0500 (Mon, 12 Feb 2007) New Revision: 6239 Modified: docs/trunk/referenceGuide/en/modules/identity.xml Log: big monkey format on identity Modified: docs/trunk/referenceGuide/en/modules/identity.xml =================================================================== --- docs/trunk/referenceGuide/en/modules/identity.xml 2007-02-12 22:47:26 UTC (rev 6238) +++ docs/trunk/referenceGuide/en/modules/identity.xml 2007-02-12 23:00:07 UTC (rev 6239) @@ -22,37 +22,33 @@ The <emphasis role="bold">org.jboss.portal.identity.User</emphasis> interface represents a user and exposes the following operations: </para> - <programlisting> - <![CDATA[ - /** The user identifier. */ - public Object getId(); + <programlisting><![CDATA[ + /** The user identifier. */ + public Object getId(); - /** The user name. */ - public String getUserName(); + /** The user name. */ + public String getUserName(); - /** Set the password using proper encoding. */ - public void updatePassword(String password); + /** Set the password using proper encoding. */ + public void updatePassword(String password); - /** Return true if the password is valid. */ - public boolean validatePassword(String password); - ]]> - </programlisting> + /** Return true if the password is valid. */ + public boolean validatePassword(String password); + ]]></programlisting> <warning> Important Note! The proper usage of getId() method is: - <programlisting> - <![CDATA[ - // Always use it like this: - user.getId().toString(); + <programlisting><![CDATA[ +// Always use it like this: +user.getId().toString(); - // Do not use it like this: +// Do not use it like this: - // We would get a Long object if we are using the database implementation - (Long)user.getId(); +// We would get a Long object if we are using the database implementation +(Long)user.getId(); - // We would get a String with an LDAP server - (String)user.getId(); - ]]> - </programlisting> +// We would get a String with an LDAP server +(String)user.getId(); +]]></programlisting> This is because the ID value depends on the User implementation. It'll probably be String object with the LDAP implementation and a Long object with the database implementation but it could be something else if one has chosen to make its own implementation. @@ -63,109 +59,103 @@ The <emphasis role="bold">org.jboss.portal.identity.Role</emphasis> interface represents a Role and exposes the following operations: </para> - <programlisting> - <![CDATA[ - /** The role identifier. */ - public Object getId(); + <programlisting><![CDATA[ +/** The role identifier. */ +public Object getId(); - /** The role name used in security rules. This name can not be modified */ - public String getName(); +/** The role name used in security rules. This name can not be modified */ +public String getName(); - /** The role display name used on screens. This name can be modified */ - public String getDisplayName(); +/** The role display name used on screens. This name can be modified */ +public String getDisplayName(); - /** */ - public void setDisplayName(String name); - ]]> - </programlisting> +/** */ +public void setDisplayName(String name); +]]></programlisting> </listitem> <listitem> <para> The <emphasis role="bold">org.jboss.portal.identity.UserModule</emphasis> interface exposes operations for users management: </para> - <programlisting> - <![CDATA[ - /**Retrieve a user by its name.*/ - User findUserByUserName(String userName) throws IdentityException, IllegalArgumentException, NoSuchUserException; + <programlisting><![CDATA[ +/**Retrieve a user by its name.*/ +User findUserByUserName(String userName) throws IdentityException, IllegalArgumentException, NoSuchUserException; - /**Retrieve a user by its id.*/ - User findUserById(Object id) throws IdentityException, IllegalArgumentException, NoSuchUserException; +/**Retrieve a user by its id.*/ +User findUserById(Object id) throws IdentityException, IllegalArgumentException, NoSuchUserException; - /**Retrieve a user by its id.*/ - User findUserById(String id) throws IdentityException, IllegalArgumentException, NoSuchUserException; +/**Retrieve a user by its id.*/ +User findUserById(String id) throws IdentityException, IllegalArgumentException, NoSuchUserException; - /** Creates a new user with the specified name.*/ - User createUser(String userName, String password) throws IdentityException, IllegalArgumentException; +/** Creates a new user with the specified name.*/ +User createUser(String userName, String password) throws IdentityException, IllegalArgumentException; - /** Remove a user.*/ - void removeUser(Object id) throws IdentityException, IllegalArgumentException; +/** Remove a user.*/ +void removeUser(Object id) throws IdentityException, IllegalArgumentException; - /** Get a range of users.*/ - Set findUsers(int offset, int limit) throws IdentityException, IllegalArgumentException; +/** Get a range of users.*/ +Set findUsers(int offset, int limit) throws IdentityException, IllegalArgumentException; - /** Get a range of users.*/ - Set findUsersFilteredByUserName(String filter, int offset, int limit) throws IdentityException, IllegalArgumentException; +/** Get a range of users.*/ +Set findUsersFilteredByUserName(String filter, int offset, int limit) throws IdentityException, IllegalArgumentException; - /**Returns the number of users.*/ - int getUserCount() throws IdentityException, IllegalArgumentException; - ]]> - </programlisting> +/**Returns the number of users.*/ +int getUserCount() throws IdentityException, IllegalArgumentException; +]]></programlisting> </listitem> <listitem> <para> The <emphasis role="bold">org.jboss.portal.identity.RoleModule</emphasis> interface exposes operations for roles management: </para> - <programlisting> - <![CDATA[ - /** Retrieves a role by its name*/ - Role findRoleByName(String name) throws IdentityException, IllegalArgumentException; + <programlisting><![CDATA[ +/** Retrieves a role by its name*/ +Role findRoleByName(String name) throws IdentityException, IllegalArgumentException; - /**Retrieve a collection of role from the role names.*/ - Set findRolesByNames(String[] names) throws IdentityException, IllegalArgumentException; +/**Retrieve a collection of role from the role names.*/ +Set findRolesByNames(String[] names) throws IdentityException, IllegalArgumentException; - /** Retrieves a role by its id.*/ - Role findRoleById(Object id) throws IdentityException, IllegalArgumentException; +/** Retrieves a role by its id.*/ +Role findRoleById(Object id) throws IdentityException, IllegalArgumentException; - /** Retrieves a role by its id.*/ - Role findRoleById(String id) throws IdentityException, IllegalArgumentException; +/** Retrieves a role by its id.*/ +Role findRoleById(String id) throws IdentityException, IllegalArgumentException; - /** Create a new role with the specified name.*/ - Role createRole(String name, String displayName) throws IdentityException, IllegalArgumentException; +/** Create a new role with the specified name.*/ +Role createRole(String name, String displayName) throws IdentityException, IllegalArgumentException; - /** Remove a role.*/ - void removeRole(Object id) throws IdentityException, IllegalArgumentException; +/** Remove a role.*/ +void removeRole(Object id) throws IdentityException, IllegalArgumentException; - /** Returns the number of roles. */ - int getRolesCount() throws IdentityException; +/** Returns the number of roles. */ +int getRolesCount() throws IdentityException; - /** Get all the roles */ - Set findRoles() throws IdentityException;/** Retrieves a role by its name*/ - Role findRoleByName(String name) throws IdentityException, IllegalArgumentException; +/** Get all the roles */ +Set findRoles() throws IdentityException;/** Retrieves a role by its name*/ +Role findRoleByName(String name) throws IdentityException, IllegalArgumentException; - /**Retrieve a collection of role from the role names.*/ - Set findRolesByNames(String[] names) throws IdentityException, IllegalArgumentException; +/**Retrieve a collection of role from the role names.*/ +Set findRolesByNames(String[] names) throws IdentityException, IllegalArgumentException; - /** Retrieves a role by its id.*/ - Role findRoleById(Object id) throws IdentityException, IllegalArgumentException; +/** Retrieves a role by its id.*/ +Role findRoleById(Object id) throws IdentityException, IllegalArgumentException; - /** Retrieves a role by its id.*/ - Role findRoleById(String id) throws IdentityException, IllegalArgumentException; +/** Retrieves a role by its id.*/ +Role findRoleById(String id) throws IdentityException, IllegalArgumentException; - /** Create a new role with the specified name.*/ - Role createRole(String name, String displayName) throws IdentityException, IllegalArgumentException; +/** Create a new role with the specified name.*/ +Role createRole(String name, String displayName) throws IdentityException, IllegalArgumentException; - /** Remove a role.*/ - void removeRole(Object id) throws IdentityException, IllegalArgumentException; +/** Remove a role.*/ +void removeRole(Object id) throws IdentityException, IllegalArgumentException; - /** Returns the number of roles. */ - int getRolesCount() throws IdentityException; +/** Returns the number of roles. */ +int getRolesCount() throws IdentityException; - /** Get all the roles */ - Set findRoles() throws IdentityException; - ]]> - </programlisting> +/** Get all the roles */ +Set findRoles() throws IdentityException; +]]></programlisting> </listitem> <listitem> <para> @@ -176,40 +166,36 @@ a many to many relationship with an intermediary table), with an LDAP server there a different ways to define relationships between users and roles. </para> - <programlisting> - <![CDATA[ - /** Return the set of role objects that a given user has.*/ - Set getRoles(User user) throws IdentityException, IllegalArgumentException; + <programlisting><![CDATA[ +/** Return the set of role objects that a given user has.*/ +Set getRoles(User user) throws IdentityException, IllegalArgumentException; - Set getUsers(Role role) throws IdentityException, IllegalArgumentException; +Set getUsers(Role role) throws IdentityException, IllegalArgumentException; - /** Creates a relationship beetween a role and set of users. Other roles that have assotiontions with those users remain unaffected.*/ - void assignUsers(Role role, Set users) throws IdentityException, IllegalArgumentException; +/** Creates a relationship beetween a role and set of users. Other roles that have assotiontions with those users remain unaffected.*/ +void assignUsers(Role role, Set users) throws IdentityException, IllegalArgumentException; - /** Creates a relationship beetween a user and set of roles. This operation will erase any other assotientions beetween the user and roles not specified in the provided set.*/ - void assignRoles(User user, Set roles) throws IdentityException, IllegalArgumentException; +/** Creates a relationship beetween a user and set of roles. This operation will erase any other assotientions beetween the user and roles not specified in the provided set.*/ +void assignRoles(User user, Set roles) throws IdentityException, IllegalArgumentException; - /** Returns role members based on rolename - depreciated method ethod here only for compatibility with old RoleModule interface */ - Set findRoleMembers(String roleName, int offset, int limit, String userNameFilter) throws IdentityException, IllegalArgumentException; - ]]> - </programlisting> +/** Returns role members based on rolename - depreciated method ethod here only for compatibility with old RoleModule interface */ +Set findRoleMembers(String roleName, int offset, int limit, String userNameFilter) throws IdentityException, IllegalArgumentException; +]]></programlisting> </listitem> <listitem> <para> The <emphasis role="bold">UserProfileModule</emphasis> interface exposes operations to access and manage informations stored in User profile: </para> - <programlisting> - <![CDATA[ - public Object getProperty(User user, String propertyName) throws IdentityException, IllegalArgumentException; + <programlisting><![CDATA[ +public Object getProperty(User user, String propertyName) throws IdentityException, IllegalArgumentException; - public void setProperty(User user, String name, Object property) throws IdentityException, IllegalArgumentException; +public void setProperty(User user, String name, Object property) throws IdentityException, IllegalArgumentException; - public Map getProperties(User user) throws IdentityException, IllegalArgumentException; +public Map getProperties(User user) throws IdentityException, IllegalArgumentException; - public ProfileInfo getProfileInfo() throws IdentityException; - ]]> - </programlisting> +public ProfileInfo getProfileInfo() throws IdentityException; +]]></programlisting> <warning> UserProfileModule.getProperty() method returns an Object. In most cases with DB backend it will always be String object. But normally you should check what @@ -223,52 +209,48 @@ <emphasis role="bold">UserProfileModule</emphasis> and exposes meta information of a profile: </para> - <programlisting> - <![CDATA[ - /** Returns a Map o PropertyInfo objects describing profile properties */ - public Map getPropertiesInfo(); + <programlisting><![CDATA[ +/** Returns a Map o PropertyInfo objects describing profile properties */ +public Map getPropertiesInfo(); - public PropertyInfo getPropertyInfo(String name); - ]]> - </programlisting> +public PropertyInfo getPropertyInfo(String name); +]]></programlisting> </listitem> <listitem> <para> <emphasis role="bold">PropertyInfo</emphasis> interface expose methods to obtain information about accessible property in User profile </para> - <programlisting> - <![CDATA[ - public static final String ACCESS_MODE_READ_ONLY = "read-only"; - public static final String ACCESS_MODE_READ_WRITE = "read-write"; - public static final String USAGE_MANDATORY = "mandatory"; - public static final String USAGE_OPTIONAL = "optional"; - public static final String MAPPING_DB_TYPE_COLUMN = "column"; - public static final String MAPPING_DB_TYPE_DYNAMIC = "dynamic"; + <programlisting><![CDATA[ +public static final String ACCESS_MODE_READ_ONLY = "read-only"; +public static final String ACCESS_MODE_READ_WRITE = "read-write"; +public static final String USAGE_MANDATORY = "mandatory"; +public static final String USAGE_OPTIONAL = "optional"; +public static final String MAPPING_DB_TYPE_COLUMN = "column"; +public static final String MAPPING_DB_TYPE_DYNAMIC = "dynamic"; - public String getName(); +public String getName(); - public String getType(); +public String getType(); - public String getAccessMode(); +public String getAccessMode(); - public String getUsage(); +public String getUsage(); - public LocalizedString getDisplayName(); +public LocalizedString getDisplayName(); - public LocalizedString getDescription(); +public LocalizedString getDescription(); - public String getMappingDBType(); +public String getMappingDBType(); - public String getMappingLDAPValue(); +public String getMappingLDAPValue(); - public String getMappingDBValue(); +public String getMappingDBValue(); - public boolean isMappedDB(); +public boolean isMappedDB(); - public boolean isMappedLDAP(); - ]]> - </programlisting> +public boolean isMappedLDAP(); +]]></programlisting> </listitem> </itemizedlist> @@ -279,27 +261,23 @@ The best way to access identity modules is by using JNDI: </para> <programlisting> - import org.jboss.portal.identity.UserModule; - import org.jboss.portal.identity.RoleModule; - import org.jboss.portal.identity.MembershipModule; - import org.jboss.portal.identity.UserProfileModule; +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/UserModule"); - (RoleModule)new InitialContext().lookup("java:portal/RoleModule"); - (MembershipModule)new InitialContext().lookup("java:portal/MembershipModule"); - (UserProfileModule)new InitialContext().lookup("java:portal/UserProfileModule"); - - </programlisting> +(UserModule)new InitialContext().lookup("java:portal/UserModule"); +(RoleModule)new InitialContext().lookup("java:portal/RoleModule"); +(MembershipModule)new InitialContext().lookup("java:portal/MembershipModule"); +(UserProfileModule)new InitialContext().lookup("java:portal/UserProfileModule");</programlisting> <para> Another way to do this is, if you are fimiliar with JBoss Mikrokernel architecture is to get the <emphasis role="bold">IdentityServiceController</emphasis> mbean. You may want to inject it into your services like this: </para> - <programlisting> - <![CDATA[<depends optional-attribute-name="IdentityServiceController" proxy-type="attribute">portal:service=Module,type=IdentityServiceController</depends>]]> - </programlisting> + <programlisting><![CDATA[<depends optional-attribute-name="IdentityServiceController" proxy-type="attribute">portal:service=Module,type=IdentityServiceController</depends>]]></programlisting> <para> or simply obtain in your code by doing a lookup using the <emphasis role="bold">portal:service=Module,type=IdentityServiceController</emphasis> @@ -308,11 +286,10 @@ </para> <programlisting> - (UserModule)identityServiceController.getIdentityContext().getObject(IdentityContext.TYPE_USER_MODULE); - (RoleModule)identityServiceController.getIdentityContext().getObject(IdentityContext.TYPE_ROLE_MODULE); - (MembershipModule)identityServiceController.getIdentityContext().getObject(IdentityContext.TYPE_MEMBERSHIP_MODULE); - (UserProfileModule)identityServiceController.getIdentityContext().getObject(IdentityContext.TYPE_USER_PROFILE_MODULE); - </programlisting> +(UserModule)identityServiceController.getIdentityContext().getObject(IdentityContext.TYPE_USER_MODULE); +(RoleModule)identityServiceController.getIdentityContext().getObject(IdentityContext.TYPE_ROLE_MODULE); +(MembershipModule)identityServiceController.getIdentityContext().getObject(IdentityContext.TYPE_MEMBERSHIP_MODULE); +(UserProfileModule)identityServiceController.getIdentityContext().getObject(IdentityContext.TYPE_USER_PROFILE_MODULE);</programlisting> </sect2> <sect2> @@ -333,65 +310,61 @@ <para> For the <emphasis role="bold">User</emphasis> interface: </para> - <programlisting> - <![CDATA[ - // Instead of: user.getEnabled() - userProfileModule.getProperty(user, User.INFO_USER_ENABLED); + <programlisting><![CDATA[ +// Instead of: user.getEnabled() +userProfileModule.getProperty(user, User.INFO_USER_ENABLED); - // Instead of: user.setEnabled(value) - userProfileModule.setProperty(user, User.INFO_USER_ENABLED, value); +// Instead of: user.setEnabled(value) +userProfileModule.setProperty(user, User.INFO_USER_ENABLED, value); - // In a similar way you should change rest of methods that are missing in User interface in 2.6 by the call to the UserProfileModule +// In a similar way you should change rest of methods that are missing in User interface in 2.6 by the call to the UserProfileModule - // Instead of: user.getProperties() - userProfileModule.getProperties(user); +// Instead of: user.getProperties() +userProfileModule.getProperties(user); - // Instead of: user.getGivenName() - userProfileModule.getProperty(user, User.INFO_USER_NAME_GIVEN); +// Instead of: user.getGivenName() +userProfileModule.getProperty(user, User.INFO_USER_NAME_GIVEN); - // Instead of: user.getFamilyName() - userProfileModule.getProperty(user, User.INFO_USER_NAME_FAMILY); +// Instead of: user.getFamilyName() +userProfileModule.getProperty(user, User.INFO_USER_NAME_FAMILY); - // Instead of: user.getRealEmail() - userProfileModule.getProperty(user, User.INFO_USER_EMAIL_REAL); +// Instead of: user.getRealEmail() +userProfileModule.getProperty(user, User.INFO_USER_EMAIL_REAL); - // Instead of: user.getFakeEmail() - userProfileModule.getProperty(user, User.INFO_USER_EMAIL_FAKE); +// Instead of: user.getFakeEmail() +userProfileModule.getProperty(user, User.INFO_USER_EMAIL_FAKE); - // Instead of: user.getRegistrationDate() - userProfileModule.getProperty(user, User.INFO_USER_REGISTRATION_DATE); +// Instead of: user.getRegistrationDate() +userProfileModule.getProperty(user, User.INFO_USER_REGISTRATION_DATE); - // Instead of: user.getViewRealEmail() - userProfileModule.getProperty(user, User.INFO_USER_VIEW_EMAIL_VIEW_REAL); +// Instead of: user.getViewRealEmail() +userProfileModule.getProperty(user, User.INFO_USER_VIEW_EMAIL_VIEW_REAL); - // Instead of: user.getPreferredLocale() - userProfileModule.getProperty(user, User.INFO_USER_LOCALE); +// Instead of: user.getPreferredLocale() +userProfileModule.getProperty(user, User.INFO_USER_LOCALE); - // Instead of: user.getSignature() - userProfileModule.getProperty(user, User.INFO_USER_SIGNATURE); +// Instead of: user.getSignature() +userProfileModule.getProperty(user, User.INFO_USER_SIGNATURE); - // Instead of: user.getLastVisitDate() - userProfileModule.getProperty(user, User.INFO_USER_LAST_LOGIN_DATE);]]> - </programlisting> +// Instead of: user.getLastVisitDate() +userProfileModule.getProperty(user, User.INFO_USER_LAST_LOGIN_DATE);]]></programlisting> </listitem> <listitem> <para> The <emphasis role="bold">RoleModule</emphasis> interface: </para> - <programlisting> - <![CDATA[ - // Instead of - // RoleModule.findRoleMembers(String roleName, int offset, int limit, String userNameFilter) throws IdentityException; - membershipModule.findRoleMembers(String roleName, int offset, int limit, String userNameFilter) + <programlisting><![CDATA[ +// Instead of +// RoleModule.findRoleMembers(String roleName, int offset, int limit, String userNameFilter) throws IdentityException; +membershipModule.findRoleMembers(String roleName, int offset, int limit, String userNameFilter) - // Instead of - // RoleModule.setRoles(User user, Set roles) throws IdentityException; - membershipModule.assignRoles(User user, Set roles) +// Instead of +// RoleModule.setRoles(User user, Set roles) throws IdentityException; +membershipModule.assignRoles(User user, Set roles) - // Instead of - // RoleModule.getRoles(User user) throws IdentityException; - membershipModule.getRoles(User user)]]> - </programlisting> +// Instead of +// RoleModule.getRoles(User user) throws IdentityException; +membershipModule.getRoles(User user)]]></programlisting> </listitem> </itemizedlist> </sect2> @@ -407,23 +380,20 @@ <emphasis role="bold">jboss-porta.sar/META-INF/jboss-service.xml</emphasis> in section: </para> - <programlisting> - <![CDATA[ - <mbean - code="org.jboss.portal.identity.IdentityServiceControllerImpl" - name="portal:service=Module,type=IdentityServiceController" - xmbean-dd="" - xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean"> - <xmbean/> - <depends>portal:service=Hibernate</depends> - <!--<depends>jboss.jca:service=DataSourceBinding,name=@portal.datasource.name@</depends>--> - <attribute name="JndiName">java:/portal/IdentityServiceController</attribute> - <attribute name="RegisterMBeans">true</attribute> - <attribute name="ConfigFile">conf/identity/identity-config.xml</attribute> - <attribute name="DefaultConfigFile">conf/identity/standardidentity-config.xml</attribute> - </mbean> - ]]> - </programlisting> + <programlisting><![CDATA[ +<mbean + code="org.jboss.portal.identity.IdentityServiceControllerImpl" + name="portal:service=Module,type=IdentityServiceController" + xmbean-dd="" + xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean"> + <xmbean/> + <depends>portal:service=Hibernate</depends> + <!--<depends>jboss.jca:service=DataSourceBinding,name=@portal.datasource.name@</depends>--> + <attribute name="JndiName">java:/portal/IdentityServiceController</attribute> + <attribute name="RegisterMBeans">true</attribute> + <attribute name="ConfigFile">conf/identity/identity-config.xml</attribute> + <attribute name="DefaultConfigFile">conf/identity/standardidentity-config.xml</attribute> +</mbean>]]></programlisting> <para> change <emphasis role="bold">identity-config.xml</emphasis> @@ -444,49 +414,43 @@ 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 configure LDAP connection options in section: </para> - <programlisting> - <![CDATA[ - <datasource> - <name>LDAP</name> - <config> - <option> - <name>host</name> - <value>jboss.com</value> - </option> - <option> - <name>port</name> - <value>10389</value> - </option> - <option> - <name>adminDN</name> - <value>cn=Directory Manager</value> - </option> - <option> - <name>adminPassword</name> - <value>qpq123qpq</value> - </option> - </config> - </datasource> - ]]> - </programlisting> + <programlisting><![CDATA[ +<datasource> + <name>LDAP</name> + <config> + <option> + <name>host</name> + <value>jboss.com</value> + </option> + <option> + <name>port</name> + <value>10389</value> + </option> + <option> + <name>adminDN</name> + <value>cn=Directory Manager</value> + </option> + <option> + <name>adminPassword</name> + <value>qpq123qpq</value> + </option> + </config> +</datasource>]]></programlisting> <para> You also need to specify options for your LDAP tree (described in configuration documentation) like those: </para> - <programlisting> - <![CDATA[ - <option-group> - <group-name>common</group-name> - <option> - <name>userContainerDN</name> - <value>ou=People,dc=portal26,dc=jboss,dc=com</value> - </option> - <option> - <name>roleContainerDN</name> - <value>ou=Roles,dc=portal26,dc=jboss,dc=com</value> - </option> - </option-group> - ]]> - </programlisting> + <programlisting><![CDATA[ +<option-group> + <group-name>common</group-name> + <option> + <name>userContainerDN</name> + <value>ou=People,dc=portal26,dc=jboss,dc=com</value> + </option> + <option> + <name>roleContainerDN</name> + <value>ou=Roles,dc=portal26,dc=jboss,dc=com</value> + </option> +</option-group>]]></programlisting> <note> Under <emphasis role="bold">PORTAL_SOURCES/identity/src/resources/example/</emphasis> you can find a sample ldif that @@ -500,35 +464,29 @@ <title>SSL</title> <para>The setup is very similar to the one described in LdapLoginModule <ulink url="http://www.jboss.org/wiki/Wiki.jsp?page=LdapLoginModule"&g... page</ulink></para> <para>You need to modify your identity configuration file and add "protocol"</para> - <programlisting> - <![CDATA[ - <datasource> - <name>LDAP</name> - <config> - ... - <option> - <name>protocol</name> - <value>ssl</value> - </option> - ... - </config> - </datasource> - ]]> - </programlisting> + <programlisting><![CDATA[ +<datasource> + <name>LDAP</name> + <config> + ... + <option> + <name>protocol</name> + <value>ssl</value> + </option> + ... + </config> +</datasource>]]></programlisting> <para> Then you need to have LDAP server certificate imported into your keystore. You can use following command: <programlisting>keytool -import -file ldapcert.der -keystore ldap.truststore</programlisting> </para> <para> Now you need to change the settings to use the alternative truststore. That can be done in the properties-service.xml in deploy directory: - <programlisting> - <![CDATA[ - <attribute name="Properties"> - javax.net.ssl.trustStore=../some/path/to/ldap.truststore - javax.net.ssl.trustStorePassword=somepw - </attribute> - ]]> - </programlisting> + <programlisting><![CDATA[ +<attribute name="Properties"> + javax.net.ssl.trustStore=../some/path/to/ldap.truststore + javax.net.ssl.trustStorePassword=somepw +</attribute>]]></programlisting> </para> </sect2> <sect2> @@ -536,19 +494,16 @@ <para>Instead of configuring your own connection you can use JNDI context federation mechanism in JBoss Application Server. Configuration of ExternalContext is described in <ulink url="http://docs.jboss.com/jbossas/guides/j2eeguide/r2/en/html_singl... Application Server documentation</ulink></para> <para>When you have ExternalContext configured you can use it in JBoss Portal by providing proper JNDI name in the configuration: - <programlisting> - <![CDATA[ - <datasource> - <name>LDAP</name> - <config> - <option> - <name>externalContextJndiName</name> - <value>external/ldap/jboss</value> - </option> - </config> - </datasource> - ]]> - </programlisting> + <programlisting><![CDATA[ +<datasource> + <name>LDAP</name> + <config> + <option> + <name>externalContextJndiName</name> + <value>external/ldap/jboss</value> + </option> + </config> +</datasource>]]></programlisting> <note>When using "externalContextJndiName" you don't need to specify any other option for this datasource</note> </para> </sect2> @@ -583,23 +538,20 @@ <emphasis>jboss-portal.sar/META-INF/jboss-service.xml</emphasis> </para> - <programlisting> - <![CDATA[ - <mbean - code="org.jboss.portal.identity.IdentityServiceControllerImpl" - name="portal:service=Module,type=IdentityServiceController" - xmbean-dd="" - xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean"> - <xmbean/> - <depends>portal:service=Hibernate</depends> - <!--<depends>jboss.jca:service=DataSourceBinding,name=@portal.datasource.name@</depends>--> - <attribute name="JndiName">java:/portal/IdentityServiceController</attribute> - <attribute name="RegisterMBeans">true</attribute> - <attribute name="ConfigFile">conf/identity/identity-config.xml</attribute> - <attribute name="DefaultConfigFile">conf/identity/standardidentity-config.xml</attribute> - </mbean> - ]]> - </programlisting> + <programlisting><![CDATA[ +<mbean + code="org.jboss.portal.identity.IdentityServiceControllerImpl" + name="portal:service=Module,type=IdentityServiceController" + xmbean-dd="" + xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean"> + <xmbean/> + <depends>portal:service=Hibernate</depends> + <!--<depends>jboss.jca:service=DataSourceBinding,name=@portal.datasource.name@</depends>--> + <attribute name="JndiName">java:/portal/IdentityServiceController</attribute> + <attribute name="RegisterMBeans">true</attribute> + <attribute name="ConfigFile">conf/identity/identity-config.xml</attribute> + <attribute name="DefaultConfigFile">conf/identity/standardidentity-config.xml</attribute> +</mbean>]]></programlisting> <para> We can specify few options here: <itemizedlist> @@ -631,66 +583,60 @@ <para> The file describing portal identity services contains three sections: </para> - <programlisting> - <![CDATA[ - <identity-configuration> - <datasources> - <!-- Datasources section --> - <datasource> ... </datasource> - <datasource> ... </datasource> - ... - </datasources> - <modules> - <!-- Modules section --> - <module> ... </module> - <module> ... </module> - ... - </modules> - <options> - <!-- Options section --> - <option-group> ... </option-group> - <option-group> ... </option-group> - ... - </options> - </identity-configuration> - ]]> - </programlisting> + <programlisting><![CDATA[ +<identity-configuration> + <datasources> + <!-- Datasources section --> + <datasource> ... </datasource> + <datasource> ... </datasource> + ... + </datasources> + <modules> + <!-- Modules section --> + <module> ... </module> + <module> ... </module> + ... + </modules> + <options> + <!-- Options section --> + <option-group> ... </option-group> + <option-group> ... </option-group> + ... + </options> +</identity-configuration>]]></programlisting> <sect3> <title>Datasources</title> <para>This section defines datasource components. They will be processed and instantiated before components in <emphasis role="bold">Module</emphasis> section, so they will be ready to serve them.</para> <note>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</note> - <programlisting> - <![CDATA[ - <datasource> - <name>LDAP</name> - <service-name>portal:service=Module,type=LDAPConnectionContext</service-name> - <class>org.jboss.portal.identity.ldap.LDAPConnectionContext</class> - <config> - <option> - <name>host</name> - <value>jboss.com</value> - </option> - <option> - <name>port</name> - <value>10389</value> - </option> - <option> - <name>adminDN</name> - <value>cn=Directory Manager</value> - </option> - <option> - <name>adminPassword</name> - <value>xxxxx</value> - </option> + <programlisting><![CDATA[ +<datasource> + <name>LDAP</name> + <service-name>portal:service=Module,type=LDAPConnectionContext</service-name> + <class>org.jboss.portal.identity.ldap.LDAPConnectionContext</class> + <config> + <option> + <name>host</name> + <value>jboss.com</value> + </option> + <option> + <name>port</name> + <value>10389</value> + </option> + <option> + <name>adminDN</name> + <value>cn=Directory Manager</value> + </option> + <option> + <name>adminPassword</name> + <value>xxxxx</value> + </option> - <!-- Other options here.... --> + <!-- Other options here.... --> - </config> - </datasource> - ]]> - </programlisting> + </config> +</datasource>]]></programlisting> <note>If you look into JBoss Portal configuration files you will find that <![CDATA[<service-name/> and <class/>]]> are specified in <emphasis role="bold">DefaultConfigFile</emphasis> and not in <emphasis role="bold">ConfigFile</emphasis>. So this is how it works. Those two will be picked up from default configuration. The same rule takes place @@ -700,31 +646,28 @@ <sect3> <title>Modules</title> <para>Modules are core service components like UserModule, RoleModule and etc. </para> - <programlisting> - <![CDATA[ - <module> - <!--type used to correctly map in IdentityContext registry--> - <type>User</type> - <implementation>DB</implementation> + <programlisting><![CDATA[ +<module> + <!--type used to correctly map in IdentityContext registry--> + <type>User</type> + <implementation>DB</implementation> - <!--name of service and class for creating mbean--> - <service-name>portal:service=Module,type=User</service-name> - <class>org.jboss.portal.identity.db.HibernateUserModuleImpl</class> + <!--name of service and class for creating mbean--> + <service-name>portal:service=Module,type=User</service-name> + <class>org.jboss.portal.identity.db.HibernateUserModuleImpl</class> - <!--set of options that are passed to a class constructor--> - <config> - <option> - <name>sessionFactoryJNDIName</name> - <value>java:/portal/IdentitySessionFactory</value> - </option> - <option> - <name>jndiName</name> - <value>java:/portal/UserModule</value> - </option> - </config> - </module> - ]]> - </programlisting> + <!--set of options that are passed to a class constructor--> + <config> + <option> + <name>sessionFactoryJNDIName</name> + <value>java:/portal/IdentitySessionFactory</value> + </option> + <option> + <name>jndiName</name> + <value>java:/portal/UserModule</value> + </option> + </config> +</module>]]></programlisting> <itemizedlist> <listitem> <para> @@ -762,16 +705,13 @@ The above code snippet with User module comes from <emphasis role="bold">standardidentity-config.xml</emphasis>, 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: - <programlisting> - <![CDATA[ - <module> - <!--type used to correctly map in IdentityContext registry--> - <type>User</type> - <implementation>DB</implementation> - <config/> - </module> - ]]> - </programlisting> + <programlisting><![CDATA[ +<module> + <!--type used to correctly map in IdentityContext registry--> + <type>User</type> + <implementation>DB</implementation> + <config/> +</module>]]></programlisting> As you see we specify only type and implementation - all the 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. @@ -782,66 +722,63 @@ <title>Options</title> <para>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 many values:</para> - <programlisting> - <![CDATA[ - <options> - <!--Common options section--> - <option-group> - <group-name>common</group-name> - <option> - <name>userContainerDN</name> - <value>ou=People,dc=example,dc=com</value> - </option> - <option> - <name>uidAttributeID</name> - <value>uid</value> - </option> - <option> - <name>passwordAttributeID</name> - <value>userPassword</value> - </option> - <option> - <name>roleContainerDN</name> - <value>ou=Roles,dc=example,dc=com</value> - </option> - <option> - <name>ridAttributeId</name> - <value>cn</value> - </option> - <option> - <name>roleDisplayNameAttributeID</name> - <value>cn</value> - </option> - <option> - <name>membershipAttributeID</name> - <value>member</value> - </option> - <option> - <name>membershipAttributeIsDN</name> - <value>true</value> - </option> - </option-group> - <option-group> - <group-name>userCreateAttibutes</group-name> - <option> - <name>objectClass</name> - <value>top</value> - <value>uidObject</value> - <value>person</value> - <value>inetUser</value> - </option> - <!--Schema requires those to have initial value--> - <option> - <name>cn</name> - <value>none</value> - </option> - <option> - <name>sn</name> - <value>none</value> - </option> - </option-group> - ]]> - </programlisting> + <programlisting><![CDATA[ +<options> +<!--Common options section--> +<option-group> + <group-name>common</group-name> + <option> + <name>userContainerDN</name> + <value>ou=People,dc=example,dc=com</value> + </option> + <option> + <name>uidAttributeID</name> + <value>uid</value> + </option> + <option> + <name>passwordAttributeID</name> + <value>userPassword</value> + </option> + <option> + <name>roleContainerDN</name> + <value>ou=Roles,dc=example,dc=com</value> + </option> + <option> + <name>ridAttributeId</name> + <value>cn</value> + </option> + <option> + <name>roleDisplayNameAttributeID</name> + <value>cn</value> + </option> + <option> + <name>membershipAttributeID</name> + <value>member</value> + </option> + <option> + <name>membershipAttributeIsDN</name> + <value>true</value> + </option> +</option-group> +<option-group> + <group-name>userCreateAttibutes</group-name> + <option> + <name>objectClass</name> + <value>top</value> + <value>uidObject</value> + <value>person</value> + <value>inetUser</value> + </option> + <!--Schema requires those to have initial value--> + <option> + <name>cn</name> + <value>none</value> + </option> + <option> + <name>sn</name> + <value>none</value> + </option> +</option-group>]]></programlisting> <note>In this section we use the same inheritance mechanism. When option is not set, it's value will be taken from the default config file. But this also means that you need to overwrite some values that are specific for your LDAP architecture. All the options will be described along with module implementations