Author: bdaw Date: 2009-11-03 07:08:04 -0500 (Tue, 03 Nov 2009) New Revision: 902 Modified: idm/trunk/idm-doc/ReferenceGuide/en/Author_Group.xml idm/trunk/idm-doc/ReferenceGuide/en/ReferenceGuide.xml idm/trunk/idm-ldap/src/main/java/org/jboss/identity/idm/impl/store/ldap/LDAPIdentityStoreImpl.java idm/trunk/pom.xml Log: - docs update Modified: idm/trunk/idm-doc/ReferenceGuide/en/Author_Group.xml =================================================================== --- idm/trunk/idm-doc/ReferenceGuide/en/Author_Group.xml 2009-11-03 09:41:59 UTC (rev 901) +++ idm/trunk/idm-doc/ReferenceGuide/en/Author_Group.xml 2009-11-03 12:08:04 UTC (rev 902) @@ -3,4 +3,5 @@ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> <authorgroup> <corpauthor>Bolesław Dawidowicz</corpauthor> + <corpauthor>Jeff Yu</corpauthor> </authorgroup> Modified: idm/trunk/idm-doc/ReferenceGuide/en/ReferenceGuide.xml =================================================================== --- idm/trunk/idm-doc/ReferenceGuide/en/ReferenceGuide.xml 2009-11-03 09:41:59 UTC (rev 901) +++ idm/trunk/idm-doc/ReferenceGuide/en/ReferenceGuide.xml 2009-11-03 12:08:04 UTC (rev 902) @@ -13,39 +13,36 @@ <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/> - <releaseinfo> - 1.0.0.Beta4 - </releaseinfo> + <releaseinfo> + 1.0.0.Beta4 + </releaseinfo> </bookinfo> - <!--<preface>--> - <!--<title>What this Book Covers</title>--> + <preface> + <title>What this Book Covers</title> + <para>This book aims to help you become familiar with JBoss Identity + IDM component</para> + <para>Part I 'Design and Architecture' introduces the the main concepts behind framework design</para> + <para>Part II 'Concepts behind API to SPI mappings' describes framework concepts in a more detailed way and explains + relationship between API and SPI layer.</para> + <para>Part III 'Quick Start' provides a reader with best way to start playing with the framework</para> + <para>Part IV 'Configuration' describes framework configuration. + </para> + <para>Part VI 'IdentityStore Implementations' provides detailed view on provided IdentityStore implementations. + </para> + <para>Part VII 'IdentityStoreRepository Implementations' provides detailed view on provided IdentityStoreRepository + implementations. + </para> + <para>Part VIII 'Attributes' describes how attributes can be used in the API. + </para> + <para>Part IX 'Credentials' describes how credentials can be used in the API. + </para> + <para>Part X 'Deployment' provides additional insight on how IDM component can be leveraged inside JEE container. + </para> + </preface> - <!--<para>This book aims to help you become familiar with JBoss Identity--> - <!--Federation in order that you can use it to build your own Federated--> - <!--Identity based services or applications.</para>--> - - <!--<para>Part I 'Getting Started' introduces the federated identity--> - <!--technologies that are provided in this product. It also indicates--> - <!--the libraries required for the installation.</para>--> - - <!--<para>Part II 'Simple Usage' describes SAML v2 Web Browser based --> - <!--Single Sign On (SSO).</para>--> - - <!--<para>Part III 'Advanced Usage' describes SAML v2 Web Browser based SSO --> - <!--with advanced features such as Trust Management and XML--> - <!--Digital Signatures.</para>--> - <!----> - <!--<para>Part IV 'Trouble Shooting' describes some basic--> - <!--troubleshooting tips when things do not work the way they were intended.--> - <!--</para>--> - <!----> - <!--<para>Part V 'Resources' provides additional resources.--> - <!--</para>--> - <!--</preface>--> - <part> <title>Design and Architecture</title> @@ -54,12 +51,12 @@ <para>JBoss Identity IDM aims to provide a common identity model for various JBoss projects. As every project has it's own specific needs it's hard to design a common API and identity model that will - fit all of them. Therefore JBoss Identity architecture consists of two main parts:</para> + fit all of them. Therefore JBoss Identity IDM architecture consists of two main parts:</para> <itemizedlist> <listitem> - <para><emphasis role="bold">Core SPI</emphasis> with an abstract identity model that provides the flexibility for defining different identity - object types and possible relationships between them.</para> + <para><emphasis role="bold">Core SPI</emphasis> with an abstract identity model that provides the + flexibility for defining different identity object types and possible relationships between them.</para> </listitem> <listitem> @@ -92,39 +89,62 @@ </para> <itemizedlist> <listitem> - <para> org.jboss.identity.idm.api.IdentityType - is a parent interface for Group and Identity + <para> + <emphasis role="bold">org.jboss.identity.idm.api.IdentityType</emphasis> + - is a parent interface for Group and Identity </para> </listitem> <listitem> - <para> org.jboss.identity.idm.api.Identity - represents Identity which can be a user (within organization) or a machine (in authentication or security use case) + <para> + <emphasis role="bold">org.jboss.identity.idm.api.Identity</emphasis> + - represents Identity which can be a user + (within organization) or a machine (in authentication or security use case) </para> </listitem> <listitem> - <para> org.jboss.identity.idm.api.Group - represents typed Group + <para> + <emphasis role="bold">org.jboss.identity.idm.api.Group</emphasis> + - represents typed Group </para> </listitem> <listitem> - <para> org.jboss.identity.idm.api.GroupType - represents type of a Group. It can be an organization, organization unit, administration group, global role, community or any other entity. + <para> + <emphasis role="bold">org.jboss.identity.idm.api.GroupType</emphasis> + - represents type of a Group. It can be an organization, organization unit, administration group, + global role, community or any other entity. </para> </listitem> <listitem> - <para> org.jboss.identity.idm.api.Role - represents one to one relationship between Identity and Group. Role has a type. The idea behind the concept is described below. + <para> + <emphasis role="bold">org.jboss.identity.idm.api.Role</emphasis> + - represents one to one relationship between Identity and Group. Role has a type. + The idea behind the concept is described below. </para> </listitem> <listitem> - <para> org.jboss.identity.idm.api.RoleType - represents type of a Role. + <para> + <emphasis role="bold">org.jboss.identity.idm.api.RoleType</emphasis> + - represents type of a Role. </para> </listitem> <listitem> - <para> org.jboss.identity.idm.api.Attribute - represents attribute connected with IdentityType (Group or Identity). Can have many complex type values (text or binary). AttributeDescription describes such properties of Attribute like: name, type of values, readonly, multivalued, required. + <para> + <emphasis role="bold">org.jboss.identity.idm.api.Attribute</emphasis> + - represents attribute connected with IdentityType (Group or Identity). + Can have many complex type values (text or binary). AttributeDescription describes such + properties of Attribute like: name, type of values, readonly, multivalued, required. </para> </listitem> <listitem> - <para> org.jboss.identity.idm.api.Credential - represents credential connected with Identity. + <para> + <emphasis role="bold">org.jboss.identity.idm.api.Credential</emphasis> + - represents credential connected with Identity. </para> </listitem> <listitem> - <para> org.jboss.identity.idm.api.CredentialType - represents type of a Credential. For example it can be text password or binary certificate. + <para> + <emphasis role="bold">org.jboss.identity.idm.api.CredentialType</emphasis> + - represents type of a Credential. For example it can be text password or binary certificate. </para> </listitem> @@ -144,7 +164,8 @@ </para> <para> Roles are direct typed connections between Identity and Group objects. If you think about a sentence: - "John is the Manager of XX Team" what matters is the context. So "John (Identity) is the Manager (RoleType) + "<emphasis role="bold">John</emphasis> is the <emphasis role="bold">Manager</emphasis> of + <emphasis role="bold">XX Team"</emphasis> what matters is the context. So "John (Identity) is the Manager (RoleType) of XX Team (Group)". The whole sentence describes the Role that John has. This type of information is hard to map with typical Group object as John can be a manager of several different groups and other identities (Marry, Jack, Stan...) can have the same RoleType in context of different groups (XY Team, YY Team). @@ -163,38 +184,50 @@ </para> <itemizedlist> <listitem> - <para> org.jboss.identity.idm.spi.model.IdentityObject - represents identity object. Contains information - about object name and type (IdentityObjectType). Name and IdentityObjectType pair should be unique + <para> + <emphasis role="bold">org.jboss.identity.idm.spi.model.IdentityObject</emphasis> + - represents identity object. Contains information + about object name and type (IdentityObjectType). Name and IdentityObjectType pair should be unique within realm. </para> </listitem> <listitem> - <para>org.jboss.identity.idm.spi.model.IdentityObjectType - represents identity object type. Name of - IdentityType is unique. + <para> + <emphasis role="bold">org.jboss.identity.idm.spi.model.IdentityObjectType</emphasis> + - represents identity object type. Name of IdentityType is unique. </para> </listitem> <listitem> - <para> org.jboss.identity.idm.spi.model.IdentityObjectAttribute - attribute assigned to IdentityObject + <para> + <emphasis role="bold">org.jboss.identity.idm.spi.model.IdentityObjectAttribute</emphasis> + - attribute assigned to IdentityObject </para> </listitem> <listitem> - <para> org.jboss.identity.idm.spi.model.IdentityObjectCredential - credential assigned to IdentityObject + <para> + <emphasis role="bold">org.jboss.identity.idm.spi.model.IdentityObjectCredential</emphasis> + - credential assigned to IdentityObject </para> </listitem> <listitem> - <para> org.jboss.identity.idm.spi.model.IdentityObjectCredentialType - represents type of - IdentityObjectCredential. + <para> + <emphasis role="bold">org.jboss.identity.idm.spi.model.IdentityObjectCredentialType</emphasis> + - represents type of IdentityObjectCredential. </para> </listitem> <listitem> - <para> org.jboss.identity.idm.spi.model.IdentityObjectRelationship - Directional relationship between + <para> + <emphasis role="bold">org.jboss.identity.idm.spi.model.IdentityObjectRelationship</emphasis> + - Directional relationship between two IdentityObject objects. Relationship is directional as it keeps information about from and to IdentityObject. Each IdentityObjectRelationship has a type (IdentityObjectRelationshipType) and can have a name (not required). </para> </listitem> <listitem> - <para> org.jboss.identity.idm.spi.model.IdentityObjectRelationshipType - named type of relationship + <para> + <emphasis role="bold">org.jboss.identity.idm.spi.model.IdentityObjectRelationshipType</emphasis> + - named type of relationship </para> </listitem> </itemizedlist> @@ -234,41 +267,52 @@ <itemizedlist> <listitem> <para> - Realm - described later in this document. Groups configuration of several identity stores and exposes all of them with one consistent identity model. + <emphasis role="bold">Realm</emphasis> + - described later in this document. Groups configuration of several identity stores and exposes + all of them with one consistent identity model. </para> </listitem> <listitem> <para> - IdentitySessionFactory - Main entry point in the API. Enables to create/get IdentitySession for a given Realm + <emphasis role="bold">IdentitySessionFactory</emphasis> + - Main entry point in the API. Enables to create/get IdentitySession for a given Realm </para> </listitem> <listitem> <para> - IdentitySession - Session that groups all identity management operation. Contains transaction support and exposes four managers that handle all identity management operations. + <emphasis role="bold">IdentitySession</emphasis> - Session that groups all identity management + operation. Contains transaction support and exposes four managers that handle all identity management operations. </para> </listitem> <listitem> <para> - PersistenceManager - Operates witin IdentitySession. Performs all operations on Identity and Group objects. Create/Remove/Find + <emphasis role="bold">PersistenceManager</emphasis> + - Operates witin IdentitySession. Performs all operations on Identity and Group objects. Create/Remove/Find </para> </listitem> <listitem> <para> - RelationshipManager - Operates witin IdentitySession. Associate and deassociate Identity and Group objects. Find Idenity and Group objects depending on their relationships + <emphasis role="bold">RelationshipManager</emphasis> + - Operates witin IdentitySession. Associate and deassociate Identity and Group objects. + Find Idenity and Group objects depending on their relationships </para> </listitem> <listitem> <para> - RoleManager - Operates witin IdentitySession. Operations on Role objects. Optional feature. + <emphasis role="bold">RoleManager</emphasis> - Operates witin IdentitySession. Operations on Role objects. + Optional feature. </para> </listitem> <listitem> <para> - AttributeManager - Operates witin IdentitySession. Manages Identity and Group (IdentityType objects) attributes. Each configured attribute is described with AttributeDescription interface + <emphasis role="bold">AttributeManager</emphasis> - Operates witin IdentitySession. Manages Identity + and Group (IdentityType objects) attributes. Each configured attribute is described with AttributeDescription interface </para> </listitem> <listitem> - <para>IdentitySearchControl - Enables to apply additional conditions to search operations. May be leveraged to receive results sorted, paginated or filtered with attributes.</para> + <para> + <emphasis role="bold">SearchCriteria</emphasis> - Enables to apply additional conditions to search operations. + May be leveraged to receive results sorted, paginated or filtered with attributes.</para> </listitem> </itemizedlist> <para> @@ -277,25 +321,46 @@ </para> <itemizedlist> <listitem> - <para>IdentityStoreSession - Session that groups all identity management operations within identity persistence stores.</para> + <para> + <emphasis role="bold">IdentityStoreSession</emphasis> + - Session that groups all identity management operations within identity persistence stores.</para> </listitem> <listitem> - <para>IdentityStoreSessionFactory - Entry point in the SPI to initialize IdentityStoreSession inside IdentityStore or AttributeStore.</para> + <para> + <emphasis role="bold">IdentityStoreSessionFactory</emphasis> + - Entry point in the SPI to initialize IdentityStoreSession inside IdentityStore or AttributeStore.</para> </listitem> <listitem> - <para>IdentityStoreInvocationContext - IdentityStoreSession aware context object that is passed during any invocation of AttributeStore or IdentityStore methods. Thanks to this actual store implementation doesn't need to be aware of current session state. Therefore one instance of AttributeStore or IdentityStore can be invoked by different realms at the same time.</para> + <para> + <emphasis role="bold">IdentityStoreInvocationContext</emphasis> + - IdentityStoreSession aware context object that is passed during any invocation of AttributeStore + or IdentityStore methods. Thanks to this actual store implementation doesn't need to be aware of + current session state. Therefore one instance of AttributeStore or IdentityStore can be invoked by + different realms at the same time.</para> </listitem> <listitem> - <para>AttributeStore - Exposes operations on identity store with attributes. This is a separate interface as in multi store configuration scenario, profile may need to be stored outside of actual data store for a given identity (LDAP + DB)</para> + <para> + <emphasis role="bold">AttributeStore</emphasis> - Exposes operations on identity store with attributes. + This is a separate interface as in multi store configuration scenario, profile may need to be + stored outside of actual data store for a given identity (LDAP + DB)</para> </listitem> <listitem> - <para>IdentityStore - Extends AttributeStore. Implementation of this interface performs operations on the real data store.</para> + <para> + <emphasis role="bold">IdentityStore</emphasis> - Extends AttributeStore. Implementation of + this interface performs operations on the real data store.</para> </listitem> <listitem> - <para>IdentityStoreRepository - Extends IdentityStore. Groups several IdentityStore objects and exposes operations on them within single interface for the API. The implementation is responsible for aggregate identity objects from many configured underlaying IdentityStore objects and map different IdentityObjectTypes between them. The place where the whole magic happens </para> + <para> + <emphasis role="bold">IdentityStoreRepository</emphasis> - Extends IdentityStore. Groups + several IdentityStore objects and exposes operations on them within single interface for the + API. The implementation is responsible for aggregate identity objects from many configured + underlaying IdentityStore objects and map different IdentityObjectTypes between them. + The place where the whole magic happens </para> </listitem> <listitem> - <para>IdentityObjectSearchControl - Enables to apply additional conditions to search operations. May be leveraged to receive results sorted, paginated or filtered withattributes.</para> + <para> + <emphasis role="bold">IdentityObjectSearchControl</emphasis> - Enables to apply additional conditions to + search operations. May be leveraged to receive results sorted, paginated or filtered withattributes.</para> </listitem> </itemizedlist> @@ -312,7 +377,8 @@ <mediaobject> <imageobject> - <imagedata fileref="./images/IDM-global-realm.png" format="PNG" contentwidth="6in" contentdepth="6in"/> + <imagedata fileref="./images/IDM-global-realm.png" format="PNG" contentwidth="6in" + contentdepth="6in"/> </imageobject> <caption align="right"> <para> @@ -366,11 +432,11 @@ <imageobject> <imagedata fileref="./images/SPI1.png" format="PNG"/> </imageobject> - <!--<caption align="right">--> - <!--<para>--> - <!--<emphasis role="bold"></emphasis>--> - <!--</para>--> - <!--</caption>--> + <!--<caption align="right">--> + <!--<para>--> + <!--<emphasis role="bold"></emphasis>--> + <!--</para>--> + <!--</caption>--> </mediaobject> </chapter> @@ -398,11 +464,11 @@ <imageobject> <imagedata fileref="./images/SPI2.png" format="PNG"/> </imageobject> - <!--<caption align="right">--> - <!--<para>--> - <!--<emphasis role="bold"></emphasis>--> - <!--</para>--> - <!--</caption>--> + <!--<caption align="right">--> + <!--<para>--> + <!--<emphasis role="bold"></emphasis>--> + <!--</para>--> + <!--</caption>--> </mediaobject> </chapter> <chapter> @@ -438,11 +504,11 @@ <imageobject> <imagedata fileref="./images/SPI3.png" format="PNG"/> </imageobject> - <!--<caption align="right">--> - <!--<para>--> - <!--<emphasis role="bold"></emphasis>--> - <!--</para>--> - <!--</caption>--> + <!--<caption align="right">--> + <!--<para>--> + <!--<emphasis role="bold"></emphasis>--> + <!--</para>--> + <!--</caption>--> </mediaobject> <para> What is important to note about the Role concept is that it is not natural in all kinds of @@ -486,17 +552,17 @@ <part> <title>Quick Start</title> - <!--<para>--> - <!--Please read JBossIdentity IDM Design and Architecture to understand all concepts behind the framework.--> - <!--</para>--> + <!--<para>--> + <!--Please read JBossIdentity IDM Design and Architecture to understand all concepts behind the framework.--> + <!--</para>--> - <chapter> + <chapter> <title>Test Cases</title> <para> One of the best ways to get familiar with the JBoss Identity IDM component is to look at the source code. You will find link to the subversion repository in the project webpage. There are couple of quite meaningful testcases there. One of the best to start with is - org.jboss.identity.idm.impl.api.OrganizationTest. It contains two example identity structures. + org.jboss.identity.idm.impl.api.OrganizationTest under 'idm-testsuite' module . It contains two example identity structures. One mapping hierarchical organization of Red Hat and JBoss projects and the other describes theoretical portal tree for ACME company. </para> @@ -526,7 +592,178 @@ </para> </chapter> <chapter> - <title></title> + <title>Needed files</title> + <para>Although the best way to start playing with the framework is to look at Maven2 sample project + mentioned above lets list minimal set of configuration files. To setup the basic framework core depending + on hibernate IdentityStore two files will be needed</para> + <para> + <emphasis role="bold">idm-config.xml</emphasis> - that will set proper configuration for all + framework components described in section above. Sample one below. + </para> + <programlisting> + <![CDATA[ +<?xml version="1.0" encoding="UTF-8"?> +<jboss-identity xmlns="urn:jboss:identity:idm:config:v1_0_beta" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="urn:jboss:identity:idm:config:v1_0_beta identity-config.xsd"> + <realms> + <realm> + <id>realm://JBossIdentityExample/SampleRealm</id> + <repository-id-ref>Sample Repository</repository-id-ref> + <identity-type-mappings> + <user-mapping>USER</user-mapping> + </identity-type-mappings> + </realm> + </realms> + <repositories> + <repository> + <id>Sample Repository</id> + <class>org.jboss.identity.idm.impl.repository.WrapperIdentityStoreRepository</class> + <external-config/> + <default-identity-store-id>Sample DB Store</default-identity-store-id> + <default-attribute-store-id>Sample DB Store</default-attribute-store-id> + </repository> + </repositories> + <stores> + <attribute-stores/> + <identity-stores> + <identity-store> + <id>Sample DB Store</id> + <class>org.jboss.identity.idm.impl.store.hibernate.HibernateIdentityStoreImpl</class> + <external-config/> + <supported-relationship-types> + <relationship-type>JBOSS_IDENTITY_MEMBERSHIP</relationship-type> + <relationship-type>JBOSS_IDENTITY_ROLE</relationship-type> + </supported-relationship-types> + <supported-identity-object-types> + <identity-object-type> + <name>USER</name> + <relationships> + <relationship> + <relationship-type-ref>JBOSS_IDENTITY_ROLE</relationship-type-ref> + <identity-object-type-ref>GROUP</identity-object-type-ref> + </relationship> + </relationships> + <credentials> + <credential-type>PASSWORD</credential-type> + </credentials> + <attributes> + <attribute> + <name>picture</name> + <mapping>user.picture</mapping> + <type>binary</type> + <isRequired>false</isRequired> + <isMultivalued>false</isMultivalued> + <isReadOnly>false</isReadOnly> + </attribute> + </attributes> + <options/> + </identity-object-type> + <identity-object-type> + <name>ORGANIZATION</name> + <relationships> + <relationship> + <relationship-type-ref>JBOSS_IDENTITY_ROLE</relationship-type-ref> + <identity-object-type-ref>USER</identity-object-type-ref> + </relationship> + <relationship> + <relationship-type-ref>JBOSS_IDENTITY_MEMBERSHIP</relationship-type-ref> + <identity-object-type-ref>USER</identity-object-type-ref> + </relationship> + <relationship> + <relationship-type-ref>JBOSS_IDENTITY_MEMBERSHIP</relationship-type-ref> + <identity-object-type-ref>GROUP</identity-object-type-ref> + </relationship> + </relationships> + <credentials/> + <attributes/> + <options/> + </identity-object-type> + <identity-object-type> + <name>GROUP</name> + <relationships> + <relationship> + <relationship-type-ref>JBOSS_IDENTITY_ROLE</relationship-type-ref> + <identity-object-type-ref>USER</identity-object-type-ref> + </relationship> + <relationship> + <relationship-type-ref>JBOSS_IDENTITY_MEMBERSHIP</relationship-type-ref> + <identity-object-type-ref>USER</identity-object-type-ref> + </relationship> + <relationship> + <relationship-type-ref>JBOSS_IDENTITY_MEMBERSHIP</relationship-type-ref> + <identity-object-type-ref>GROUP</identity-object-type-ref> + </relationship> + </relationships> + <credentials/> + <attributes/> + <options/> + </identity-object-type> + </supported-identity-object-types> + <options> + <option> + <name>hibernateConfiguration</name> + <value>hibernate-jboss-identity.cfg.xml</value> + </option> + <option> + <name>populateRelationshipTypes</name> + <value>true</value> + </option> + <option> + <name>populateIdentityObjectTypes</name> + <value>true</value> + </option> + <option> + <name>allowNotDefinedAttributes</name> + <value>true</value> + </option> + <option> + <name>isRealmAware</name> + <value>true</value> + </option> + </options> + </identity-store> + </identity-stores> + </stores> +</jboss-identity> + ]]> + </programlisting> + + <para> + <emphasis role="bold">hibernate.cfg.xml</emphasis> - hibernate SessionFactory setup + </para> + + <programlisting> + <![CDATA[ +<!DOCTYPE hibernate-configuration PUBLIC + "-//Hibernate/Hibernate Configuration DTD//EN" + "http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd"> +<hibernate-configuration> + <session-factory> + + + <property name="hibernate.cache.provider_class">org.hibernate.cache.EhCacheProvider</property> + + <property name="show_sql">false</property> + <property name="cache.use_second_level_cache">true</property> + <property name="cache.use_query_cache">true</property> + + + <property name="current_session_context_class">thread</property> + + <!--<property name="connection.datasource"></property>--> + + <property name="hibernate.connection.url">jdbc:hsqldb:mem:unit-testing-jpa1</property> + <property name="hibernate.connection.driver_class">org.hsqldb.jdbcDriver</property> + <property name="hibernate.dialect">org.hibernate.dialect.HSQLDialect</property> + <property name="hibernate.hbm2ddl.auto">create-drop</property> + <property name="hibernate.connection.username">sa</property> + <property name="hibernate.connection.password"></property> + + </session-factory> +</hibernate-configuration> + ]]> + </programlisting> </chapter> </part> @@ -574,18 +811,24 @@ <para>Identity XML configuration can be divided into three parts:</para> <itemizedlist> <listitem> - <para><![CDATA[<stores/>]]> - defines IdentityStore and AttributeStore instances</para> + <para><emphasis role="bold"><![CDATA[<stores/>]]></emphasis> + - defines IdentityStore and AttributeStore instances</para> </listitem> <listitem> - <para><![CDATA[<repositories/>]]> - defines IdentityStoreRepository instances</para> + <para><emphasis role="bold"><![CDATA[<repositories/>]]></emphasis> + - defines IdentityStoreRepository instances</para> </listitem> <listitem> - <para><![CDATA[<realms/>]]> - defines identity realms</para> + <para><emphasis role="bold"><![CDATA[<realms/>]]></emphasis> + - defines identity realms</para> </listitem> </itemizedlist> </chapter> <chapter> - <title>IdentityStore <![CDATA[<stores><identity-store>...]]></title> + <title>IdentityStore</title> + <para>This part is represented by + <emphasis role="bold"><![CDATA[<stores><identity-store>...]]></emphasis> + element</para> <programlisting> <![CDATA[ <stores> @@ -598,8 +841,11 @@ ]]> </programlisting> <note> - <para><![CDATA[<stores/>]]> element contains <![CDATA[<identity-store>]]> and <![CDATA[<attribute-store>]]> - elements. Currently <![CDATA[<attribute-store>]]> configuration is ignored so only <![CDATA[<identity-store>]]> + <para><emphasis role="bold"><![CDATA[<stores/>]]></emphasis> + element contains <emphasis role="bold"><![CDATA[<identity-store>]]></emphasis> + and <emphasis role="bold"><![CDATA[<attribute-store>]]></emphasis> + elements. Currently <emphasis role="bold"><![CDATA[<attribute-store>]]></emphasis> + configuration is ignored so only <emphasis role="bold"><![CDATA[<identity-store>]]></emphasis> elements can be configured.</para></note> <programlisting> <![CDATA[ @@ -643,29 +889,32 @@ ]]> </programlisting> - <para><![CDATA[<identity-store>]]> element: + <para><emphasis role="bold"><![CDATA[<identity-store>]]></emphasis> element: </para> <itemizedlist> <listitem> - <para>id - IdentityStore id</para> + <para><emphasis role="bold">id</emphasis> - IdentityStore id</para> </listitem> <listitem> - <para>class - IdentityStore class name</para> + <para><emphasis role="bold">class</emphasis> - IdentityStore class name</para> </listitem> <listitem> - <para>external-config - external configuration file used by IdentityStore</para> + <para><emphasis role="bold">external-config</emphasis> - external configuration file used by IdentityStore</para> </listitem> <listitem> - <para>supported-relationship-types - IdentityObjectRelationshipType names that are supported by this + <para><emphasis role="bold">supported-relationship-types</emphasis> + - IdentityObjectRelationshipType names that are supported by this IdentityStore. JBOSS_IDENTITY_MEMBERSHIP is standard value used by default framework implementation for membership type relationships (between two Group objects) and JBOSS_IDENTITY_ROLE is standard value for Role type memberships (named relationships)</para> </listitem> <listitem> - <para>supported-identity-object-types - configuration of IdentityObjectType objects mapped by IdentityStore</para> + <para><emphasis role="bold">supported-identity-object-types</emphasis> + - configuration of IdentityObjectType objects mapped by IdentityStore</para> </listitem> <listitem> - <para>options - other IdentityStore configuration options</para> + <para> + <emphasis role="bold">options</emphasis> - other IdentityStore configuration options</para> </listitem> </itemizedlist> @@ -734,62 +983,67 @@ </para> <itemizedlist> <listitem> - <para>name - IdentityObjectType name</para> + <para><emphasis role="bold">name</emphasis>- IdentityObjectType name</para> </listitem> <listitem> - <para>relationships - relationships in which IdentityObjectType can be parent side. - <![CDATA[<relationship-type-ref>]]> must point to one of values from - <![CDATA[<supported-relationship-types>]]>. <![CDATA[<identity-object-type-ref>]]> - must be one of <![CDATA[<identity-object-type><name>]]> values configured in this IdentityStore.</para> + <para><emphasis role="bold">relationships</emphasis> + - relationships in which IdentityObjectType can be parent side. + <emphasis role="bold"><![CDATA[<relationship-type-ref>]]></emphasis> must point to one of values from + <emphasis role="bold"><![CDATA[<supported-relationship-types>]]></emphasis> + . <emphasis role="bold"><![CDATA[<identity-object-type-ref>]]></emphasis> + must be one of <emphasis role="bold"><![CDATA[<identity-object-type><name>]]></emphasis> + values configured in this IdentityStore.</para> </listitem> <listitem> - <para>credentials - IdentityObjectCredentialType names allowed for this IdentityObjectType</para> + <para><emphasis role="bold">credentials</emphasis> + - IdentityObjectCredentialType names allowed for this IdentityObjectType</para> </listitem> <listitem> - <para>attributes - allowed attribute mappings. Each contains: + <para><emphasis role="bold">attributes</emphasis> - allowed attribute mappings. Each contains: <itemizedlist> <listitem> <para> - name - attribute name + <emphasis role="bold">name</emphasis> - attribute name </para> </listitem> <listitem> <para> - mapping - real name to be used inside IdentityStore. For example LDAP attribute name + <emphasis role="bold">mapping</emphasis> - real name to be used inside IdentityStore. For example LDAP attribute name </para> </listitem> <listitem> <para> - type - either "binary" or "text" value + <emphasis role="bold">type</emphasis> - either "binary" or "text" value </para> </listitem> <listitem> <para> - isRequired - if attribute cannot have no values + <emphasis role="bold">isRequired</emphasis> - if attribute cannot have no values </para> </listitem> <listitem> <para> - isMultivalued - if attribute can have many values + <emphasis role="bold">isMultivalued</emphasis> - if attribute can have many values </para> </listitem> <listitem> <para> - isReadonly - if attribute values can be modified + <emphasis role="bold">isReadonly</emphasis> - if attribute values can be modified </para> </listitem> </itemizedlist> </para> </listitem> <listitem> - <para>options - other options for IdentityObjectType configuration</para> + <para><emphasis role="bold">options</emphasis> - other options for IdentityObjectType configuration</para> </listitem> </itemizedlist> </chapter> <chapter> - <title>IdentityStoreRepository / <![CDATA[<repositories><repository>]]></title> - + <title>IdentityStoreRepository</title> + <para>This section is represented by <emphasis role="bold"> <![CDATA[<repositories><repository>]]></emphasis> + element</para> <programlisting> <![CDATA[ <repositories> @@ -859,31 +1113,36 @@ </programlisting> - <para><![CDATA[<repository>]]> element contains: + <para><emphasis role="bold"><![CDATA[<repository>]]></emphasis> element contains: </para> <itemizedlist> <listitem> - <para>id - IdentityStoreRepository id.</para> + <para><emphasis role="bold">id</emphasis> - IdentityStoreRepository id.</para> </listitem> <listitem> - <para>class - class name of IdentityStoreRepository implementation.</para> + <para><emphasis role="bold">class</emphasis> - class name of IdentityStoreRepository implementation.</para> </listitem> <listitem> - <para>external-config - external configuration file used by IdentityStoreRepository.</para> + <para><emphasis role="bold">external-config</emphasis> - external configuration file used by + IdentityStoreRepository.</para> </listitem> <listitem> - <para>default-identity-store-id - id of configured IdentityStore to be used by default.</para> + <para><emphasis role="bold">default-identity-store-id</emphasis> - id of configured IdentityStore + to be used by default.</para> </listitem> <listitem> - <para>default-attribute-store-id - id of configured AttributeStore (or IdentityStore) to be used by default</para> + <para><emphasis role="bold">default-attribute-store-id</emphasis> - id of configured AttributeStore + (or IdentityStore) to be used by default</para> </listitem> <listitem> - <para>identity-store-mappings - optional element. Mappings between IdentityObjectType names and IdentityStore ids. </para> + <para><emphasis role="bold">identity-store-mappings</emphasis> - optional element. Mappings between + IdentityObjectType names and IdentityStore ids. </para> </listitem> </itemizedlist> </chapter> <chapter> - <title>Realm / <![CDATA[<realms><realm>]]></title> + <title>Realm</title> + <para>This section is represented by <emphasis role="bold"><![CDATA[<realms><realm>]]></emphasis> element</para> <programlisting> <![CDATA[ @@ -899,20 +1158,21 @@ </programlisting> <para> - <![CDATA[<realm>]]> element contains: + <emphasis role="bold"><![CDATA[<realm>]]></emphasis> element contains: </para> <itemizedlist> <listitem> - <para>id - realm id</para> + <para><emphasis role="bold">id</emphasis> - realm id</para> </listitem> <listitem> - <para>repository-id-ref - id of configured IdentityStoreRepository </para> + <para><emphasis role="bold">repository-id-ref</emphasis> - id of configured IdentityStoreRepository </para> </listitem> <listitem> - <para>identity-type-mappings + <para><emphasis role="bold">identity-type-mappings</emphasis> <itemizedlist> <listitem> - <para>identity-mapping - name of IdentityObjectType that should be maped as Identity + <para><emphasis role="bold">identity-mapping</emphasis> + - name of IdentityObjectType that should be maped as Identity object on the API side</para> </listitem> </itemizedlist> @@ -958,32 +1218,68 @@ <itemizedlist> <listitem> - <para>persistenceUnit - The name of persistence unit with proper Hibernate entities. - See example below.</para> + <para><emphasis role="bold">hibernateConfiguration</emphasis> + - the hibernate configuration file that will be used to + create SessionFactory</para> </listitem> <listitem> - <para>populateRelationshipTypes - true/false - Populate configured <![CDATA[<supported-relationship-types>]]> + <para> + <emphasis role="bold">hibernateSessionFactoryJNDIName</emphasis> + - JNDI name of hibernate SessionFactory that will be used + to obtain it</para> + </listitem> + <listitem> + <para> + <emphasis role="bold">hibernateSessionFactoryRegistryName</emphasis> + - name of hibernate SessionFactory placed in the + IdentityConfigurationRegistry that will be used to obtain it</para> + </listitem> + <listitem> + <para> + <emphasis role="bold">addMappedClasses</emphasis> + - of set to true all annotated hibernate model classes will be added + to the hibernate configuration before SessionFactory is created</para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">populateRelationshipTypes</emphasis> + - true/false - Populate configured <![CDATA[<supported-relationship-types>]]> (IdentityObjectRelationshipType in SPI model) during IdentityStore initialization. Default value is 'false'</para> </listitem> <listitem> - <para>populateIdentityObjectTypes - true/false - Populate configured <![CDATA[<supported-identity-object-types>]]> + <para><emphasis role="bold">populateIdentityObjectTypes</emphasis> + - true/false - Populate configured <![CDATA[<supported-identity-object-types>]]> (IdentityObjectType in SPI model) during IdentityStore initialization. Default value is 'false'</para> </listitem> <listitem> - <para>allowNotDefinedAttributes - true/false - Allow to set IdentityObject attributes that + <para><emphasis role="bold">allowNotDefinedAttributes</emphasis> + - true/false - Allow to set IdentityObject attributes that are not specified in <![CDATA[<identity-object-type>]]> configuration. Such attributes are assumed to have "text" type and many values. Default value is 'false'.</para> </listitem> <listitem> - <para>isRealmAware - true/false - If set to true HibernateIdentityStoreImpl will create + <para><emphasis role="bold">isRealmAware</emphasis> + - true/false - If set to true HibernateIdentityStoreImpl will create separate namespaces for different Realms from which method invocations come. This means that each IdentityObject, IdentityObjectRelationship and IdentityObjectRelationshipName will be connected and only accessible with a realm name in which it was created. Entities representing IdentityObjectType, IdentityObjectCredentialType and IdentityObjectRelationshipType are always same for all realms and not affected with this option. Default value is 'false'. </para> </listitem> - <listitem><para></para></listitem> + <listitem> + <para><emphasis role="bold">manageTransactionDuringBootstrap</emphasis> + - true/false - indicate that transactions should be managed + manually during store bootstrap when initial entities are created. </para> + </listitem> + <listitem> + <para><emphasis role="bold">allowNotDefinedIdentityObjectTypes</emphasis> + - true/false - indicate that store won't check + for a given IdentityObjectType configuration and if one is not specified it will be just + lazily created. This option enables to have minimal xml config without definition of all + constraints in relationship between types. </para> + </listitem> </itemizedlist> </para> </sect1> @@ -1003,12 +1299,7 @@ <supported-identity-object-types> <identity-object-type> <name>IDENTITY</name> - <relationships> - <relationship> - <relationship-type-ref>JBOSS_IDENTITY_ROLE</relationship-type-ref> - <identity-object-type-ref>ORGANIZATION</identity-object-type-ref> - </relationship> - </relationships> + <relationships/> <credentials> <credential-type>PASSWORD</credential-type> </credentials> @@ -1043,6 +1334,10 @@ <relationship-type-ref>JBOSS_IDENTITY_MEMBERSHIP</relationship-type-ref> <identity-object-type-ref>ORGANIZATION</identity-object-type-ref> </relationship> + <relationship> + <relationship-type-ref>JBOSS_IDENTITY_ROLE</relationship-type-ref> + <identity-object-type-ref>IDENTITY</identity-object-type-ref> + </relationship> </relationships> <credentials/> <attributes/> @@ -1051,8 +1346,8 @@ </supported-identity-object-types> <options> <option> - <name>persistenceUnit</name> - <value>jboss-identity-model-xxx</value> + <name>hibernateConfiguration</name> + <value>hibernate-jboss-identity.cfg.xml</value> </option> <option> <name>populateRelationshipTypes</name> @@ -1079,29 +1374,22 @@ ]]> </programlisting> <para> - Persistence unit need to map all needed hibernate entities. For example: + In case 'addMappedClasses' option is not set to true hibernate configuration need to list all + annotated model classes: </para> <programlisting> <![CDATA[ -<persistence-unit name="sample-persistence-unit" transaction-type="RESOURCE_LOCAL"> - - <provider>org.hibernate.ejb.HibernatePersistence</provider> - - <class>org.jboss.identity.idm.impl.model.hibernate.HibernateRealm</class> - <class>org.jboss.identity.idm.impl.model.hibernate.HibernateIdentityObject</class> - <class>org.jboss.identity.idm.impl.model.hibernate.HibernateIdentityObjectCredential</class> - <class>org.jboss.identity.idm.impl.model.hibernate.HibernateIdentityObjectCredentialType</class> - <class>org.jboss.identity.idm.impl.model.hibernate.HibernateIdentityObjectAttribute</class> - <class>org.jboss.identity.idm.impl.model.hibernate.HibernateIdentityObjectType</class> - <class>org.jboss.identity.idm.impl.model.hibernate.HibernateIdentityObjectRelationship</class> - <class>org.jboss.identity.idm.impl.model.hibernate.HibernateIdentityObjectRelationshipType</class> - <class>org.jboss.identity.idm.impl.model.hibernate.HibernateIdentityObjectRelationshipName</class> - - .... - .... - .... - -</persistence-unit> +<mapping class="org.jboss.identity.idm.impl.model.hibernate.HibernateRealm"/> +<mapping class="org.jboss.identity.idm.impl.model.hibernate.HibernateIdentityObject"/> +<mapping class="org.jboss.identity.idm.impl.model.hibernate.HibernateIdentityObjectCredential"/> +<mapping class="org.jboss.identity.idm.impl.model.hibernate.HibernateIdentityObjectCredentialType"/> +<mapping class="org.jboss.identity.idm.impl.model.hibernate.HibernateIdentityObjectAttribute"/> +<mapping class="org.jboss.identity.idm.impl.model.hibernate.HibernateIdentityObjectTextAttribute"/> +<mapping class="org.jboss.identity.idm.impl.model.hibernate.HibernateIdentityObjectBinaryAttribute"/> +<mapping class="org.jboss.identity.idm.impl.model.hibernate.HibernateIdentityObjectType"/> +<mapping class="org.jboss.identity.idm.impl.model.hibernate.HibernateIdentityObjectRelationship"/> +<mapping class="org.jboss.identity.idm.impl.model.hibernate.HibernateIdentityObjectRelationshipType"/> +<mapping class="org.jboss.identity.idm.impl.model.hibernate.HibernateIdentityObjectRelationshipName"/> ]]> </programlisting> @@ -1134,49 +1422,112 @@ <para><![CDATA[<identity-object-type><options>]]></para> <itemizedlist> <listitem> - <para>idAttributeName - attribute name under which IdentityObject name is specified. Required.</para> + <para><emphasis role="bold">idAttributeName</emphasis> + - attribute name under which IdentityObject name is specified. Required.</para> </listitem> <listitem> - <para>passwordAttributeName - attribute name under which IdentityObject password is specified. Optional.</para> + <para><emphasis role="bold">passwordAttributeName</emphasis> + - attribute name under which IdentityObject password is specified. Optional.</para> </listitem> <listitem> - <para>ctxDNs - DN that will be used as context for IdentityObject searches. More than one value can be specified.</para> + <para><emphasis role="bold">ctxDNs</emphasis> + - DN that will be used as context for IdentityObject searches. More than one value can be specified.</para> </listitem> <listitem> - <para>allowCreateEntry - true/false - Specify if new IdentityObject can be created.</para> + <para><emphasis role="bold">allowCreateEntry</emphasis> + - true/false - Specify if new IdentityObject can be created.</para> </listitem> <listitem> - <para>createEntryAttributeValues - defines a set of ldap attributes that will be set on IdentityObject entry creation. Values are in "name=value" format. This enables to fulfill LDAP schema requirements.Default is false</para> + <para><emphasis role="bold">createEntryAttributeValues</emphasis> + - defines a set of ldap attributes that will be set on IdentityObject entry creation. Values + are in "name=value" format. This enables to fulfill LDAP schema requirements.Default is false</para> </listitem> <listitem> - <para>membershipAttributeName - LDAP attribute that defines children of IdentityObject. This will be used to retrieved relationships from IdentityObject entry. Option is required if IdentityObjectType can be part of relationship.</para> + <para><emphasis role="bold">parentMembershipAttributeName</emphasis> + - LDAP attribute that defines children of IdentityObject. This will be used to retrieved + relationships from IdentityObject entry. Option is required if IdentityObjectType can be part of relationship.</para> </listitem> <listitem> - <para>isMembershipAttributeDN - defines if values of attribute defined in membershipAttributeID are fully qualified LDAP DNs.</para> + <para><emphasis role="bold">isParentMembershipAttributeDN</emphasis> + - defines if values of attribute defined in parentMembershipAttributeName are fully qualified LDAP DNs.</para> </listitem> <listitem> - <para>allowEmptyMemberships - defines if IdentityObject entry can have no members. Sometimes it is not allowed by LDAP schema.</para> + <para><emphasis role="bold">allowEmptyMemberships</emphasis> + - defines if IdentityObject entry can have no members. Sometimes it is not allowed by LDAP schema.</para> </listitem> <listitem> - <para>entrySearchFilter - ldap filter to search IdentityObject with. {0} will be substitute with IdentityObject name. Example filter can look like this: "(uid={0})". This substitution behavior comes from the standard DirContext.search(Name, String, Object, SearchControls cons) method</para> + <para><emphasis role="bold">parentMembershipAttributePlaceholder</emphasis> + - if LDAP schema doesn't allow empty memberships this value will be used as a placeholder. IdentityObject + specified here won't be recognized as a member and ignored</para> + </listitem> + <listitem> + <para><emphasis role="bold">childMembershipAttributeName</emphasis> + - LDAP attribute that defines parents of IdentityObject. This will be used to retrieved + relationships from IdentityObject entry. Good example of such attribute in LDAP schema is 'memberOf'</para> + </listitem> + <listitem> + <para><emphasis role="bold">childMembershipAttributeDN</emphasis> + - defines if values of attribute defined in childMembershipAttributeName are fully qualified LDAP DNs.</para> + </listitem> + <listitem> + <para><emphasis role="bold">childMembershipAttributeVirtual</emphasis> + - specifies if attribute defined in 'childMembershipAttributeName' is a real attribute that + can be updated or virtual one which value is managed by a directory and should not be updated</para> + </listitem> + <listitem> + <para><emphasis role="bold">entrySearchFilter</emphasis> + - ldap filter to search IdentityObject with. {0} will be substitute with IdentityObject name. + Example filter can look like this: "(uid={0})". This substitution behavior comes from the + standard DirContext.search(Name, String, Object, SearchControls cons) method</para> </listitem> + <listitem> + <para><emphasis role="bold">enclosePasswordWith</emphasis> + - if specified password will be surunted with a given chars before update</para> + </listitem> + <listitem> + <para><emphasis role="bold">passwordEncoding</emphasis> + - if specified password will be encoded before update. For example Microsoft Active Directory + requires password to be enclosed with '"' and encoded using 'UTF-16LE' for update.</para> + </listitem> + <listitem> + <para><emphasis role="bold">passwordUpdateAttributeValues</emphasis> + - list of attributes that should be changed during password update</para> + </listitem> + </itemizedlist> - <para><![CDATA[<identity-store><options>]]></para> + <para><emphasis role="bold"><![CDATA[<identity-store><options>]]></emphasis></para> <itemizedlist> <listitem> - <para>providerURL - LDAP connection URL. For example "ldap://localhost:389"</para> + <para><emphasis role="bold">providerURL</emphasis> + - LDAP connection URL. For example "ldap://localhost:389"</para> </listitem> <listitem> - <para>adminDN - LDAP entry used to connect to the server.</para> + <para><emphasis role="bold">adminDN</emphasis> + - LDAP entry used to connect to the server.</para> </listitem> <listitem> - <para>adminPassword - password related to adminDN</para> + <para><emphasis role="bold">adminPassword</emphasis> + - password related to adminDN</para> </listitem> <listitem> - <para>searchTimeLimit -searchTimeLimit for LDAP search operations in miliseconds. Default value is 10000.</para> + <para><emphasis role="bold">searchTimeLimit</emphasis> + -searchTimeLimit for LDAP search operations in miliseconds. Default value is 10000.</para> </listitem> - + <listitem> + <para><emphasis role="bold">customJNDIConnectionParameters</emphasis> + - list of additional 'key=value' parameters that will be used to create JNDI context. Can be + usefull to use additional JNDI options.</para> + </listitem> + <listitem> + <para><emphasis role="bold">customSystemProperties</emphasis> + - list of 'key=value' properties that will be added using System.setProperty() method. This + can be used to configure LDAP JNDI connection pooling which is set per JVM</para> + </listitem> + <listitem> + <para><emphasis role="bold">externalJNDIContext</emphasis> + - name that will be used to perform JDNI lookup to grab JNDI connection context </para> + </listitem> </itemizedlist> </sect1> @@ -1325,6 +1676,92 @@ </programlisting> </sect1> </chapter> + <chapter> + <title>Minimal Configuration</title> + <para>The main role of configuration is to define relationship between separate framework components. It also + enables to specify a lot of meta data information describing possible connections between IdentityObject types. + It is however possible to not define all those meta data information and let the framework to be maximum permissive + about allowed operations and lazily create not defined types:</para> + + <programlisting> + <![CDATA[ +<?xml version="1.0" encoding="UTF-8"?> +<jboss-identity xmlns="urn:jboss:identity:idm:config:v1_0_beta" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="urn:jboss:identity:idm:config:v1_0_beta identity-config.xsd"> + <realms> + <realm> + <id>realm://FlexibleRealm</id> + <repository-id-ref>Flexible Repo</repository-id-ref> + <identity-type-mappings> + <user-mapping>USER</user-mapping> + </identity-type-mappings> + </realm> + </realms> + <repositories> + <repository> + <id>Flexible Repo</id> + <class>org.jboss.identity.idm.impl.repository.WrapperIdentityStoreRepository</class> + <external-config/> + <default-identity-store-id>Hibernate Identity Store</default-identity-store-id> + <default-attribute-store-id>Hibernate Identity Store</default-attribute-store-id> + <options> + <option> + <name>allowNotDefinedAttributes</name> + <value>true</value> + </option> + <option> + <name>allowNotDefinedIdentityObjectTypes</name> + <value>true</value> + </option> + </options> + </repository> + </repositories> + <stores> + <attribute-stores/> + <identity-stores> + <identity-store> + <id>Hibernate Identity Store</id> + <class>org.jboss.identity.idm.impl.store.hibernate.HibernateIdentityStoreImpl</class> + <external-config/> + <supported-relationship-types> + <relationship-type>JBOSS_IDENTITY_MEMBERSHIP</relationship-type> + <relationship-type>JBOSS_IDENTITY_ROLE</relationship-type> + </supported-relationship-types> + <supported-identity-object-types/> + <options> + <option> + <name>hibernateSessionFactoryJNDIName</name> + <value>java:/jbossidentity/HibernateStoreSessionFactory</value> + </option> + <option> + <name>populateRelationshipTypes</name> + <value>true</value> + </option> + <option> + <name>populateIdentityObjectTypes</name> + <value>true</value> + </option> + <option> + <name>isRealmAware</name> + <value>true</value> + </option> + <option> + <name>allowNotDefinedAttributes</name> + <value>true</value> + </option> + <option> + <name>allowNotDefinedIdentityObjectTypes</name> + <value>true</value> + </option> + </options> + </identity-store> + </identity-stores> + </stores> +</jboss-identity> + ]]> + </programlisting> + </chapter> </part> <part> @@ -1354,6 +1791,7 @@ ]]> </programlisting> </sect1> + </chapter> <chapter> <title>FallbackIdentityStoreRepository</title> @@ -1372,7 +1810,8 @@ <title>Configuration Options</title> <itemizedlist> <listitem> - <para>allowNotDefinedAttributes - if mapped IdentityStore doesn't support any attribute that was + <para><emphasis role="bold">allowNotDefinedAttributes</emphasis> + - if mapped IdentityStore doesn't support any attribute that was passed in method invocation FallbackIdentityStoreRepository will try to store it in defaultAttributeStore. If this option is set to true such attribute will be passed to defaultAttributeStore even if it is not mapped there.</para> @@ -1433,80 +1872,80 @@ AttributeDescription that contains its properties such as:</para> <itemizedlist> <listitem> - <para>name - attribute name</para> + <para><emphasis role="bold">name</emphasis> - attribute name</para> </listitem> <listitem> - <para>readonly - if attribute values can be changed</para> + <para><emphasis role="bold">readonly</emphasis> - if attribute values can be changed</para> </listitem> <listitem> - <para>multivalued - if attribute can have many values</para> + <para><emphasis role="bold">multivalued</emphasis> - if attribute can have many values</para> </listitem> <listitem> - <para>required - if attribute can be removed</para> + <para><emphasis role="bold">required</emphasis> - if attribute can be removed</para> </listitem> <listitem> - <para>type - type of attribute values. </para> + <para><emphasis role="bold">type</emphasis> - type of attribute values. </para> </listitem> </itemizedlist> <para>Default implementation provides two attribute types:</para> <itemizedlist> <listitem> - <para>text - java.lang.String object</para> + <para><emphasis role="bold">text</emphasis> - java.lang.String object</para> </listitem> <listitem> - <para>binary - byte[] object</para> + <para><emphasis role="bold">binary</emphasis> - byte[] object</para> </listitem> </itemizedlist> <sect1> <title>Sample operations</title> <programlisting role="java"> - Identity user = session.getPersistenceManager(). - createIdentity("sampleUser"); +Identity user = session.getPersistenceManager(). +createIdentity("sampleUser"); - // Check that binary attribute 'picture' is mapped +// Check that binary attribute 'picture' is mapped - AttributeDescription attributeDescription = - session.getAttributesManager(). - getAttributeDescription(user, "picture"); - assertNotNull(attributeDescription); - assertEquals("binary", attributeDescription.getType()); +AttributeDescription attributeDescription = +session.getAttributesManager(). +getAttributeDescription(user, "picture"); +assertNotNull(attributeDescription); +assertEquals("binary", attributeDescription.getType()); - // Generate random binary data for binary attribute +// Generate random binary data for binary attribute - Random random = new Random(); - byte[] picture = new byte[5120]; - random.nextBytes(picture); +Random random = new Random(); +byte[] picture = new byte[5120]; +random.nextBytes(picture); - // User attributes - Attribute[] userInfo = new Attribute[] - { - new SimpleAttribute(P3PConstants.INFO_USER_NAME_GIVEN, - new String[]{"John"}), - new SimpleAttribute(P3PConstants.INFO_USER_NAME_FAMILY, - new String[]{"Doe"}), - new SimpleAttribute("picture", new byte[][]{picture}) - }; +// User attributes +Attribute[] userInfo = new Attribute[] +{ +new SimpleAttribute(P3PConstants.INFO_USER_NAME_GIVEN, +new String[]{"John"}), +new SimpleAttribute(P3PConstants.INFO_USER_NAME_FAMILY, +new String[]{"Doe"}), +new SimpleAttribute("picture", new byte[][]{picture}) +}; - session.getAttributesManager(). - addAttributes(user, userInfo); +session.getAttributesManager(). +addAttributes(user, userInfo); - .... +.... - AttributesManager attrMgr = session.getAttributesManager(); +AttributesManager attrMgr = session.getAttributesManager(); - attrMgr.addAttribute(anneUser, - P3PConstants.INFO_USER_NAME_GIVEN, "Anne"); - attrMgr.addAttribute(anneUser, - P3PConstants.INFO_USER_NAME_FAMILY, "Smith"); - attrMgr.addAttribute(anneUser, - P3PConstants.INFO_USER_JOB_TITLE, "Senior Software Developer"); - attrMgr.addAttribute(anneUser, - P3PConstants.INFO_USER_BUSINESS_INFO_ONLINE_EMAIL, &quot;anne.smith(a)acme.com&quot;); - attrMgr.addAttribute(anneUser, - P3PConstants.INFO_USER_BUSINESS_INFO_TELECOM_MOBILE_NUMBER, "777 777 777 7 77"); +attrMgr.addAttribute(anneUser, +P3PConstants.INFO_USER_NAME_GIVEN, "Anne"); +attrMgr.addAttribute(anneUser, +P3PConstants.INFO_USER_NAME_FAMILY, "Smith"); +attrMgr.addAttribute(anneUser, +P3PConstants.INFO_USER_JOB_TITLE, "Senior Software Developer"); +attrMgr.addAttribute(anneUser, +P3PConstants.INFO_USER_BUSINESS_INFO_ONLINE_EMAIL, &quot;anne.smith(a)acme.com&quot;); +attrMgr.addAttribute(anneUser, +P3PConstants.INFO_USER_BUSINESS_INFO_TELECOM_MOBILE_NUMBER, "777 777 777 7 77"); </programlisting> </sect1> @@ -1514,31 +1953,32 @@ <chapter> <title>SPI</title> <para>On the SPI level IdentityObject can be associated with several IdentityObjectAttribute objects. - IdentityObjectAttribute is described by IdentityObjectAttributeMetaData object that contains its properties such as:</para> + IdentityObjectAttribute is described by IdentityObjectAttributeMetaData object that contains its + properties such as:</para> <itemizedlist> <listitem> - <para>name - attribute name</para> + <para><emphasis role="bold">name</emphasis> - attribute name</para> </listitem> <listitem> - <para>readonly - if attribute values can be changed</para> + <para><emphasis role="bold">readonly</emphasis> - if attribute values can be changed</para> </listitem> <listitem> - <para>multivalued - if attribute can have many values</para> + <para><emphasis role="bold">multivalued</emphasis> - if attribute can have many values</para> </listitem> <listitem> - <para>required - if attribute can be removed</para> + <para><emphasis role="bold">required</emphasis> - if attribute can be removed</para> </listitem> <listitem> - <para>type - type of attribute values. </para> + <para><emphasis role="bold">type</emphasis> - type of attribute values. </para> </listitem> </itemizedlist> <para>IdentityObjectAttribute types supported by default implementations are the same as in the API level:</para> <itemizedlist> <listitem> - <para>text - java.lang.String object</para> + <para><emphasis role="bold">text</emphasis> - java.lang.String object</para> </listitem> <listitem> - <para>binary - byte[] object</para> + <para><emphasis role="bold">binary</emphasis> - byte[] object</para> </listitem> </itemizedlist> @@ -1559,10 +1999,10 @@ </para> <itemizedlist> <listitem> - <para>PASSWORD - text password represented by java.lang.String object</para> + <para><emphasis role="bold">PASSWORD</emphasis> - text password represented by java.lang.String object</para> </listitem> <listitem> - <para>BINARY - binary credential represented by byte[]. For example some kind of certificate.</para> + <para><emphasis role="bold">BINARY</emphasis> - binary credential represented by byte[]. For example some kind of certificate.</para> </listitem> </itemizedlist> @@ -1571,10 +2011,12 @@ </para> <itemizedlist> <listitem> - <para>org.jboss.identity.idm.impl.api.BinaryCredential - Credential with BINARY CredentialType</para> + <para><emphasis role="bold">org.jboss.identity.idm.impl.api.BinaryCredential</emphasis> + - Credential with BINARY CredentialType</para> </listitem> <listitem> - <para>org.jboss.identity.idm.impl.api.PasswordCredential - Credential with PASSWORD CredentialType</para> + <para><emphasis role="bold">org.jboss.identity.idm.impl.api.PasswordCredential</emphasis> + - Credential with PASSWORD CredentialType</para> </listitem> </itemizedlist> @@ -1586,8 +2028,23 @@ </para> <programlisting role="java"> - TODO +User anotherOne = session.getPersistenceManager().createUser("blah1"); + +session.getAttributesManager().updatePassword(anotherOne, "Password2000"); +assertTrue(session.getAttributesManager().validatePassword(anotherOne, "Password2000")); + +Credential password = new PasswordCredential("SuperPassword2345"); +session.getAttributesManager().updateCredential(anotherOne, password); +assertTrue(session.getAttributesManager().validateCredentials(anotherOne, new Credential[]{password})); + +// binary credential +byte[] cert = new byte[512000]; +random.nextBytes(cert); +Credential binaryCredential = new BinaryCredential(cert); +session.getAttributesManager().updateCredential(anotherOne, binaryCredential); +assertTrue(session.getAttributesManager().validateCredentials(anotherOne, new Credential[]{binaryCredential})); + </programlisting> </chapter> <chapter> @@ -1604,23 +2061,161 @@ </para> <itemizedlist> <listitem> - <para>getValue - returns either String for text based credentials or byte[] for binary. + <para><emphasis role="bold">getValue</emphasis> - returns either String for text based credentials or + byte[] for binary. True credential value may be needed by different IdentityStore implementations for validation. For example with LDAP authentication for IdentityObject entry will be performed</para> </listitem> <listitem> - <para>getEncodedValue - Enables to provide IdentityStore with custom credential encoding method. + <para><emphasis role="bold">getEncodedValue</emphasis> - Enables to provide IdentityStore with custom + credential encoding method. IdentityStore is not obligated to use encoded value. This should return either String for text based credentials or byte[] for binary. May return null if credential implementation doesn't provide encoding mechanism. IdentityStore </para> </listitem> - </itemizedlist> </chapter> - </part> + <part> + <title>Deployment</title> + <chapter> + <title>IDM Usage Scenario</title> + <para>There are two ways to use the jboss idm:</para> + <itemizedlist> + <listitem> + <para> + Use it as the embedded way + </para> + </listitem> + <listitem> + <para> + Deploy it into the container (JBoss AS5), and then all other projects can use it + by getting IdentitySessionFactory from JNDI. + </para> + </listitem> + </itemizedlist> + <para> + For the 1st case, users need to use the API to start the IdentitySessionFactory, and then use it. + The code is as following, which you can find on the example module. + </para> + <programlisting> + <![CDATA[ +IdentitySessionFactory identitySessionFactory = new IdentityConfigurationImpl(). + configure(new File("src/test/resources/example-db-config.xml")).buildIdentitySessionFactory(); +IdentitySession identitySession = identitySessionFactory.createIdentitySession("realm://JBossIdentityExample/SampleRealm"); + ]]> + </programlisting> + <para> + And then use the IdentitySession to do the operations etc. So it is very easy to use. We will look closer + at the second scenario in the next chapter + </para> + </chapter> + <chapter> + <title>JBoss AS 5 Deployment</title> + <para>Now, lets look at the second case, by deploying the idm into the JBoss AS 5. By doing this different + services can share the identity component, instead of having its own seperate identity component.</para> + <para>The jobs that need to be done for the deployment in the container is quite simple:</para> + <itemizedlist> + <listitem> + <para> + Populate the idm schema if neccessary. + </para> + </listitem> + <listitem> + <para> + Start the IdentitySessionFactory, and then register it into the JNDI. + </para> + </listitem> + </itemizedlist> + <para> + Before we look at it further, lets see the configuration files that jboss idm needed typically. + (Say using db back-end, hibernate impl combination) + </para> + <itemizedlist> + <listitem> + <para>jboss idm configuration file. say jboss.idm.cfg.xml</para> + </listitem> + <listitem> + <para>datasource file, say idm-ds.xml</para> + </listitem> + <listitem> + <para>hibernate cfg file, say jboss.idm.hibernate.cfg.xml.</para> + </listitem> + </itemizedlist> - + <para>With regard to the detail of jboss idm configuration file, you can refer to the configuration documentation.</para> + <para>So, if we want to deploy the idm into container with a specified JNDI name, we need to have a deployment + file to define the JNDI and other neccessary properties.</para> + <para> + For the integration with JBoss AS5, the AS5 has a great deployment feature, we've built our own deployer to + extend it, so that the AS can listen on the -jboss-idm.xml suffix file to start the IdentitySessionFactory. + </para> + <para> + Basically, we had two deployer, one is: IDMConfigParsingDeployer class, which is taking responsible for + parsing files that ends with the -jboss-idm.xml suffix into Java object. The other is: IDMDeployer class, + this one is to do the real job, which means it might populate the schema, initial dataset into target db, + and then start the IdentitySessionFactory, register it into the JNDI with the specified name at last. + </para> + <para> + We will see a very typical deployment file looks like. (default-jboss-idm.xml) + </para> + <programlisting> + <![CDATA[ +<?xml version="1.0" encoding="UTF-8"?> +<jboss-idm-deployer xmlns="urn:jboss:identity:idm:deployer:v1_0_alpha" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="urn:jboss:identity:idm:deployer:v1_0_alpha identity-deployer.xsd"> + <JNDIName>java:/IdentitySessionFactory</JNDIName> + <idmConfigFile>jboss.idm.cfg.xml</idmConfigFile> + <hibernateDeployer> + <hibernateConfiguration>jboss.idm.hibernate.cfg.xml</hibernateConfiguration> +<hibernateSessionFactoryJNDIName>java:/IDMHibernateSessionFactory</hibernateSessionFactoryJNDIName> + </hibernateDeployer> + <initializers> + <datasource>java:/jbossidmDS</datasource> + <sqlInitializer> + <sqlFile>idm-sql/jboss.idm.@database@.create.sql</sqlFile> + <exitSQL>select * from jbid_io</exitSQL> + </sqlInitializer> + </initializers> +</jboss-idm-deployer> + ]]> + </programlisting> + + <itemizedlist> + <listitem> + <para>The deployment file must be named -jboss-idm.xml as suffix, otherwise, it won't be recoginzed + in the JBoss AS5 container. + </para> + </listitem> + <listitem> + <para> + The "JNDIName" and "idmConfigFile" attributes are required. The JNDIName is the name for + keeping the started IdentitySessionFactory. + </para> + </listitem> + <listitem> + <para> + The hibernateDeployer is optional, the reason that why we had the hibernateDeployer is that + we can reuse the hibernateSessionFactory in the jboss idm configuration file. + </para> + </listitem> + <listitem> + <para>The Initializer is optional, it is responsible for populating the db schema + and initialized dataset if any. + </para> + </listitem> + + </itemizedlist> + <para>detailed information about the deployment file is specified in the identity-deployer.xsd file.</para> + <para> + Once you've deployed the idm into JBoss AS5, by using the distribution. It will copy the idm-deployer + into the JBoss AS5/server/$config/deployers folder, and the idm folder into the JBoss AS5/server/$config/deploy + folder, which contains the default configuration files, like the jboss.idm.cfg.xml, idm-ds.xml etc. + </para> + </chapter> + + </part> </book> Modified: idm/trunk/idm-ldap/src/main/java/org/jboss/identity/idm/impl/store/ldap/LDAPIdentityStoreImpl.java =================================================================== --- idm/trunk/idm-ldap/src/main/java/org/jboss/identity/idm/impl/store/ldap/LDAPIdentityStoreImpl.java 2009-11-03 09:41:59 UTC (rev 901) +++ idm/trunk/idm-ldap/src/main/java/org/jboss/identity/idm/impl/store/ldap/LDAPIdentityStoreImpl.java 2009-11-03 12:08:04 UTC (rev 902) @@ -89,8 +89,6 @@ public class LDAPIdentityStoreImpl implements IdentityStore { - //TODO: external JNDI - //TODO: more options for connection configuration //TODO: JNDI connection credentials encoding (pluggable?) private static Logger log = Logger.getLogger(LDAPIdentityStoreImpl.class.getName()); Modified: idm/trunk/pom.xml =================================================================== --- idm/trunk/pom.xml 2009-11-03 09:41:59 UTC (rev 901) +++ idm/trunk/pom.xml 2009-11-03 12:08:04 UTC (rev 902) @@ -26,6 +26,7 @@ <module>idm-auth</module> <module>idm-testsuite</module> <module>integration</module> + <module>idm-doc</module> <module>example/simple</module> <module>example/auth</module> <module>example/auth-simple</module>