[gatein-commits] gatein SVN: r7244 - in epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US: modules and 9 other directories.

Author: smumford Date: 2011-08-29 03:26:00 -0400 (Mon, 29 Aug 2011) New Revision: 7244 Added: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Attributes/ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Attributes/API.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Attributes/SPI.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Concepts_API_SPI/ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Concepts_API_SPI/Associations.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Concepts_API_SPI/Introduction.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Concepts_API_SPI/Role.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Concepts_API_SPI/User_and_Group.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Configuration/ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Configuration/API_Cache.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Configuration/IdentitySessionFactory.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Configuration/IdentityStore.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Configuration/IdentityStoreRepository.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Configuration/Realm.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Configuration/Realm_Templates.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Configuration/XML_Configuration.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Credentials/ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Credentials/Credential_API.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Credentials/Credential_SPI.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Deployment/ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Deployment/Deployment.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Deployment/Usage_Scenario.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Design_and_Architecture/ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Design_and_Architecture/API_Model.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Design_and_Architecture/Architecture.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Design_and_Architecture/Group_And_Roles.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Design_and_Architecture/Main_Concepts.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Design_and_Architecture/Realms.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Design_and_Architecture/SPI_Model.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/IdentityStoreRepository_Implementations/ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/IdentityStoreRepository_Implementations/FallbackIdentityStoreRepository.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/IdentityStoreRepository_Implementations/WrapperIdentityStoreRepository.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/IdentityStore_Implementations/ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/IdentityStore_Implementations/Hibernate_IdentityStore.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/IdentityStore_Implementations/LDAP_IdentityStore.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/IdentityStore_Implementations/Minimal_Configuration.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Quick_Start/ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Quick_Start/Core_Files.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Quick_Start/Examples.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Quick_Start/Test_Cases.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/chap_Attributes.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/chap_Concepts_API_SPI.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/chap_Configuration.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/chap_Credentials.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/chap_Deployment.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/chap_Design_and_Architecture.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/chap_IdentityStoreRepository_Implementations.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/chap_IdentityStore_Implementations.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/chap_Quick_Start.xml Removed: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/API.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/API_Cache.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/API_Model.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Architecture.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Associations.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Core_Files.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Credential_API.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Credential_SPI.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Deployment.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Examples.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/FallbackIdentityStoreRepository.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Group_And_Roles.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Hibernate_IdentityStore.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/IdentitySessionFactory.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/IdentityStore.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/IdentityStoreRepository.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Introduction.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/LDAP_IdentityStore.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Main_Concepts.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Minimal_Configuration.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Realm.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Realm_Templates.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Realms.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Role.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/SPI.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/SPI_Model.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Test_Cases.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Usage_Scenario.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/User_and_Group.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/WrapperIdentityStoreRepository.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/XML_Configuration.xml Modified: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Book_Info.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/PicketLink_IDM_Reference_Guide.ent epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/PicketLink_IDM_Reference_Guide.xml epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Revision_History.xml Log: Restructured book and updated vers/rev/pub/ed numbers Deleted: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/API.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/API.xml 2011-08-29 03:56:57 UTC (rev 7243) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/API.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -1,71 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % BOOK_ENTITIES SYSTEM "PicketLink_IDM_Reference_Guide.ent"> -%BOOK_ENTITIES; -]> -<chapter id="chap-PicketLink_IDM_Reference_Guide-API"> - <title>API</title> - <para> - On the API level each IdentityType object (Identity and Group) can have associated Attribute objects. All operations are exposed by AttributesManager interface. Each attribute is described with AttributeDescription that contains its properties such as: - </para> - <itemizedlist> - <listitem> - <para> - <emphasis role="bold">name</emphasis> - attribute name - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">readonly</emphasis> - if attribute values can be changed - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">multivalued</emphasis> - if attribute can have many values - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">required</emphasis> - if attribute can be removed - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">type</emphasis> - type of attribute values. - </para> - - </listitem> - - </itemizedlist> - <para> - Default implementation provides two attribute types: - </para> - <itemizedlist> - <listitem> - <para> - <emphasis role="bold">text</emphasis> - java.lang.String object - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">binary</emphasis> - byte[] object - </para> - - </listitem> - - </itemizedlist> - <section id="sect-PicketLink_IDM_Reference_Guide-API-Sample_operations"> - <title>Sample operations</title> - -<programlisting role="Java"><xi:include href="extras/sample-operations.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </section> - - -</chapter> - Deleted: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/API_Cache.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/API_Cache.xml 2011-08-29 03:56:57 UTC (rev 7243) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/API_Cache.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -1,51 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % BOOK_ENTITIES SYSTEM "PicketLink_IDM_Reference_Guide.ent"> -%BOOK_ENTITIES; -]> -<chapter id="chap-PicketLink_IDM_Reference_Guide-API_Cache"> - <title>API Cache</title> - <para> - At the realm level IDM API cache layer can be enabled - </para> - -<programlisting>&lt;realm&gt; - &lt;id&gt;idm_realm&lt;/id&gt; - &lt;repository-id-ref&gt;DefaultRepository&lt;/repository-id-ref&gt; - &lt;identity-type-mappings&gt; - &lt;user-mapping&gt;USER&lt;/user-mapping&gt; - &lt;/identity-type-mappings&gt; - &lt;options&gt; - &lt;option&gt; - &lt;name&gt;cache.providerClass&lt;/name&gt; - &lt;value&gt;JBossCacheAPICacheProviderImpl&lt;/value&gt; - &lt;/option&gt; - &lt;/options&gt; -&lt;/realm&gt;</programlisting> - <para> - Cache related options : - </para> - <itemizedlist> - <listitem> - <para> - <emphasis role="bold">cache.providerClass</emphasis> - class implementing APICacheProvider interface - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">cache.providerRegistryName</emphasis> - id of instantiated APICacheProvider implementation stored in configuration registry - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">cache.scope</emphasis> - namespace used to store entities in cache. Can be "realm" (default) or "session". - </para> - - </listitem> - - </itemizedlist> - -</chapter> - Deleted: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/API_Model.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/API_Model.xml 2011-08-29 03:56:57 UTC (rev 7243) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/API_Model.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -1,87 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % BOOK_ENTITIES SYSTEM "PicketLink_IDM_Reference_Guide.ent"> -%BOOK_ENTITIES; -]> -<chapter id="chap-PicketLink_IDM_Reference_Guide-API_Model"> - <title>API Model</title> - <para> - The API operates on the identity model that is defined by the following set of interfaces: - </para> - <variablelist> - <title>API Interfaces</title> - <varlistentry> - <term>org.picketlink.idm.api.IdentityType</term> - <listitem> - <para> - This is a parent interface for Group and Identity. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>org.picketlink.idm.api.Identity</term> - <listitem> - <para> - This represents an Identity, which can be a user (within organization) or a machine (in authentication or security use case) - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>org.picketlink.idm.api.Group</term> - <listitem> - <para> - This represents a Group. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>org.picketlink.idm.api.GroupType</term> - <listitem> - <para> - This represents type of a Group. It can be an organization, organization unit, administration group, global role, community or any other entity. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>org.picketlink.idm.api.Role</term> - <listitem> - <para> - This represents one to one relationship between Identity and Group. Role has a type. The idea behind the concept is described below. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>org.picketlink.idm.api.RoleType</term> - <listitem> - <para> - This represents type of a Role. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>org.picketlink.idm.api.Attribute</term> - <listitem> - <para> - This represents an attribute connected with <parameter>IdentityType</parameter> (Group or Identity). It can have many complex type values (text or binary). <parameter>AttributeDescription</parameter> describes such properties of Attribute like: name, type of values, readonly, multivalued, required. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>org.picketlink.idm.api.Credential</term> - <listitem> - <para> - This represents credentials connected with an Identity. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>org.picketlink.idm.api.CredentialType</term> - <listitem> - <para> - This represents type of a Credential. For example it can be text password or binary certificate. - </para> - </listitem> - </varlistentry> - </variablelist> -</chapter> - Deleted: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Architecture.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Architecture.xml 2011-08-29 03:56:57 UTC (rev 7243) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Architecture.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -1,123 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % BOOK_ENTITIES SYSTEM "PicketLink_IDM_Reference_Guide.ent"> -%BOOK_ENTITIES; -]> -<chapter id="chap-PicketLink_IDM_Reference_Guide-Architecture"> - <title>Architecture</title> - <para> - The most important part of architecture is a split between the API and the SPI. - </para> - <mediaobject> - <imageobject> - <imagedata contentdepth="6in" contentwidth="6in" fileref="images/IDM-api-spi.png" width="444" /> - </imageobject> - <caption align="right"> <para> - <emphasis role="bold">PicketLink IDM architecture</emphasis> - </para> - </caption> - </mediaobject> - <para> - API part contains of following interfaces: - </para> - <itemizedlist> - <listitem> - <para> - <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> - <emphasis role="bold">IdentitySessionFactory</emphasis> - Main entry point in the API. Enables to create/get IdentitySession for a given Realm - </para> - - </listitem> - <listitem> - <para> - <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> - <emphasis role="bold">PersistenceManager</emphasis> - Operates witin IdentitySession. Performs all operations on Identity and Group objects. Create/Remove/Find - </para> - - </listitem> - <listitem> - <para> - <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> - <emphasis role="bold">RoleManager</emphasis> - Operates witin IdentitySession. Operations on Role objects. Optional feature. - </para> - - </listitem> - <listitem> - <para> - <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> - <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> - SPI part contains of following interfaces - </para> - <itemizedlist> - <listitem> - <para> - <emphasis role="bold">IdentityStoreSession</emphasis> - Session that groups all identity management operations within identity persistence stores. - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">IdentityStoreSessionFactory</emphasis> - Entry point in the SPI to initialize IdentityStoreSession inside IdentityStore or AttributeStore. - </para> - - </listitem> - <listitem> - <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> - <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> - <emphasis role="bold">IdentityStore</emphasis> - Extends AttributeStore. Implementation of this interface performs operations on the real data store. - </para> - - </listitem> - <listitem> - <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> - <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> -</chapter> - Deleted: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Associations.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Associations.xml 2011-08-29 03:56:57 UTC (rev 7243) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Associations.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -1,33 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % BOOK_ENTITIES SYSTEM "PicketLink_IDM_Reference_Guide.ent"> -%BOOK_ENTITIES; -]> -<chapter id="chap-PicketLink_IDM_Reference_Guide-Associations"> - <title>Associations</title> - <para> - Group and Users can be associated. This represents simple relationship that can be described like "user John belongs to Group IT". Association can be created between Group and User or between two Groups. - </para> - <para> - Those operations are managed by RelationshipManager: - </para> - -<programlisting role="Java"> -RelationshipManager rm = identitySession.getRelationshipManager(); - -rm.associateUser(parisOffice, annUser); -rm.associateUser(atlantaOffice, stefanUser); -rm.associateUser(itDep, stefanUser); - -assertTrue(rm.isAssociated(parisOffice, annUser));</programlisting> - <para> - At the SPI level this is mapped to IdentityObjectRelationship entity. This relationship has a type. Simple assotiations can be marked with a type named "JBOSS_IDENTITY_MEMBERSHIP" (this is implementation detail) which describes simple membership. Note that IdentityObjectRelationship creates a connection between any two IdentityObject entities. - </para> - <mediaobject> - <imageobject> - <imagedata contentdepth="6in" contentwidth="6in" fileref="images/SPI2.png" width="444" /> - </imageobject> - - </mediaobject> -</chapter> - Modified: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Book_Info.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Book_Info.xml 2011-08-29 03:56:57 UTC (rev 7243) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Book_Info.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -4,32 +4,32 @@ %BOOK_ENTITIES; ]> <bookinfo id="book-PicketLink_IDM_Reference_Guide-PicketLink_IDM_Reference_Guide"> - <title>PicketLink IDM Reference Guide</title> - <subtitle>A guide to the PicketLink IDM component in JBoss Enterprise Portal Platform &VZ;</subtitle> - <productname>JBoss Enterprise Portal Platform</productname> - <productnumber>5.1</productnumber> - <edition>1</edition> - <pubsnumber>1.0</pubsnumber> - <abstract> - <!-- Source Metadata + <title>PicketLink IDM Reference Guide</title> + <subtitle>A guide to the PicketLink IDM component in JBoss Enterprise Portal Platform &VZ;</subtitle> + <productname>JBoss Enterprise Portal Platform</productname> + <productnumber>5.2</productnumber> + <edition>5.2.0</edition> + <pubsnumber>1</pubsnumber> + <abstract> + <!-- Source Metadata URL: http://www.jboss.org/picketlink/IDM.html Author [w/email]: Boleslaw Davidowicz? License: --> <para> - PicketLink IDM aims to provide a common identity model for Identity Management operations. This includes easy management of identities like Users/Groups/Roles and their attributes. Framework also provides usage of different identity stores like LDAP or RDBMS. - </para> + PicketLink IDM aims to provide a common identity model for Identity Management operations. This includes easy management of identities like Users/Groups/Roles and their attributes. Framework also provides usage of different identity stores like LDAP or RDBMS. + </para> - </abstract> - <corpauthor> - <inlinemediaobject> - <imageobject> - <imagedata fileref="Common_Content/images/title_logo.svg" format="SVG" /> - </imageobject> + </abstract> + <corpauthor> + <inlinemediaobject> + <imageobject> + <imagedata fileref="Common_Content/images/title_logo.svg" format="SVG" /> + </imageobject> - </inlinemediaobject> + </inlinemediaobject> - </corpauthor> - <xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + </corpauthor> + <xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> </bookinfo> Deleted: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Core_Files.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Core_Files.xml 2011-08-29 03:56:57 UTC (rev 7243) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Core_Files.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -1,22 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % BOOK_ENTITIES SYSTEM "PicketLink_IDM_Reference_Guide.ent"> -%BOOK_ENTITIES; -]> -<chapter id="chap-PicketLink_IDM_Reference_Guide-Core_Files"> - <title>Core 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 language="XML" role="XML"><xi:include href="extras/idm-config.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> - <emphasis role="bold">hibernate.cfg.xml</emphasis> - hibernate SessionFactory setup - </para> - -<programlisting language="XML" role="XML"><xi:include href="extras/hibernate.cfg.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> -</chapter> - Deleted: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Credential_API.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Credential_API.xml 2011-08-29 03:56:57 UTC (rev 7243) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Credential_API.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -1,67 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % BOOK_ENTITIES SYSTEM "PicketLink_IDM_Reference_Guide.ent"> -%BOOK_ENTITIES; -]> -<chapter id="chap-PicketLink_IDM_Reference_Guide-Credential_API"> - <title>Credential API</title> - <para> - API contains Credential and CredentialType interfaces. CredentialType defines type of credential object. Default implementation supports two types: - </para> - <itemizedlist> - <listitem> - <para> - <emphasis role="bold">PASSWORD</emphasis> - text password represented by java.lang.String object - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">BINARY</emphasis> - binary credential represented by byte[]. For example some kind of certificate. - </para> - - </listitem> - - </itemizedlist> - <para> - Two basic implementations are provided: - </para> - <itemizedlist> - <listitem> - <para> - <emphasis role="bold">org.picketlink.idm.impl.api.BinaryCredential</emphasis> - Credential with BINARY CredentialType - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">org.picketlink.idm.impl.api.PasswordCredential</emphasis> - Credential with PASSWORD CredentialType - </para> - - </listitem> - - </itemizedlist> - <para> - Because credentials values are stored as hash or in other encoded form both SPI and API only enables to update and validate credential value and not to read it from persistence store. API enables to only protect Identity objects with credentials. All related management operations are exposed in AttributesManager interface. - </para> - -<programlisting role="Java"> -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> - Deleted: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Credential_SPI.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Credential_SPI.xml 2011-08-29 03:56:57 UTC (rev 7243) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Credential_SPI.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -1,30 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % BOOK_ENTITIES SYSTEM "PicketLink_IDM_Reference_Guide.ent"> -%BOOK_ENTITIES; -]> -<chapter id="chap-PicketLink_IDM_Reference_Guide-Credential_SPI"> - <title>Credential SPI</title> - <para> - SPI contains IdentityObjectCredential and IdentityObjectCredentialType interfaces that correspons to Credential and CredentialType interfaces in the API. Implementation supports the same two (PASSWORD and BINARY) types. Management operations are exposed in IdentityStore interface. Each IdentityObjectType can be configured to support different IdentityObjectCredentialType. This information is exposed by FeaturesMetaData interface. - </para> - <para> - IdentityObjectCredential interface exposes two methods to retrieve credential value: - </para> - <itemizedlist> - <listitem> - <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> - <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> - Deleted: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Deployment.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Deployment.xml 2011-08-29 03:56:57 UTC (rev 7243) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Deployment.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -1,122 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % BOOK_ENTITIES SYSTEM "PicketLink_IDM_Reference_Guide.ent"> -%BOOK_ENTITIES; -]> -<chapter id="chap-PicketLink_IDM_Reference_Guide-JBoss_AS_5_Deployment"> - <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>&lt;?xml version="1.0" encoding="UTF-8"?&gt; -&lt;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"&gt; - &lt;JNDIName&gt;java:/IdentitySessionFactory&lt;/JNDIName&gt; - &lt;idmConfigFile&gt;jboss.idm.cfg.xml&lt;/idmConfigFile&gt; - &lt;hibernateDeployer&gt; - &lt;hibernateConfiguration&gt;jboss.idm.hibernate.cfg.xml&lt;/hibernateConfiguration&gt; -&lt;hibernateSessionFactoryJNDIName&gt;java:/IDMHibernateSessionFactory&lt;/hibernateSessionFactoryJNDIName&gt; - &lt;/hibernateDeployer&gt; - &lt;initializers&gt; - &lt;datasource&gt;java:/jbossidmDS&lt;/datasource&gt; - &lt;sqlInitializer&gt; - &lt;sqlFile&gt;idm-sql/jboss.idm.@database@.create.sql&lt;/sqlFile&gt; - &lt;exitSQL&gt;select * from jbid_io&lt;/exitSQL&gt; - &lt;/sqlInitializer&gt; - &lt;/initializers&gt; -&lt;/jboss-idm-deployer&gt;</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> - Deleted: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Examples.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Examples.xml 2011-08-29 03:56:57 UTC (rev 7243) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Examples.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -1,36 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % BOOK_ENTITIES SYSTEM "PicketLink_IDM_Reference_Guide.ent"> -%BOOK_ENTITIES; -]> -<chapter id="chap-PicketLink_IDM_Reference_Guide-Examples"> - <title>Examples</title> - <para> - As PicketLink IDM is a Maven2 based project it is very easy to leverage it from this build system. There is a ready to use Maven2 example project in the svn. It contains three sample test cases for with following configurations: - </para> - <itemizedlist> - <listitem> - <para> - database setup - </para> - - </listitem> - <listitem> - <para> - LDAP setup - </para> - - </listitem> - <listitem> - <para> - mixed LDAP + database setup - </para> - - </listitem> - - </itemizedlist> - <para> - Sample project uses embedded OpenDS and HSQLDB so there is no need for any additional setup to be able to play with the API. - </para> -</chapter> - Deleted: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/FallbackIdentityStoreRepository.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/FallbackIdentityStoreRepository.xml 2011-08-29 03:56:57 UTC (rev 7243) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/FallbackIdentityStoreRepository.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -1,50 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % BOOK_ENTITIES SYSTEM "PicketLink_IDM_Reference_Guide.ent"> -%BOOK_ENTITIES; -]> -<chapter id="chap-PicketLink_IDM_Reference_Guide-FallbackIdentityStoreRepository"> - <title>FallbackIdentityStoreRepository</title> - <section id="sect-PicketLink_IDM_Reference_Guide-FallbackIdentityStoreRepository-ClassName"> - <title>ClassName</title> - <para> - org.picketlink.idm.impl.repository.FallbackIdentityStoreRepository - </para> - - </section> - - <section id="sect-PicketLink_IDM_Reference_Guide-FallbackIdentityStoreRepository-Behaviour"> - <title>Behaviour</title> - <para> - Resolves proper IdentityStore from IdentityObjectType mapping and delegates method invocation. For relationship related methods, if both IdentityObjectTypes are not mapped in one store, repository will try to sync them and associate in defaultIdentityStore. For attributes that are not mapped inside mapped IdentityStore repository will try to assign those attributes in defaultAttributeStore. - </para> - - </section> - - <section id="sect-PicketLink_IDM_Reference_Guide-FallbackIdentityStoreRepository-Configuration_Options"> - <title>Configuration Options</title> - <itemizedlist> - <listitem> - <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> - - </listitem> - - </itemizedlist> - - </section> - - <section id="sect-PicketLink_IDM_Reference_Guide-FallbackIdentityStoreRepository-Sample_Configuration"> - <title>Sample Configuration</title> - -<programlisting language="XML" role="XML"><xi:include href="extras/sample_config3.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> - The <emphasis role="bold">readOnly</emphasis> options specifies that the only write operation performed on the store will be password update. - </para> - - </section> - - -</chapter> - Deleted: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Group_And_Roles.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Group_And_Roles.xml 2011-08-29 03:56:57 UTC (rev 7243) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Group_And_Roles.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -1,27 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % BOOK_ENTITIES SYSTEM "PicketLink_IDM_Reference_Guide.ent"> -%BOOK_ENTITIES; -]> -<chapter id="chap-PicketLink_IDM_Reference_Guide-Groups_and_Roles"> - <title>Groups and Roles</title> - <para> - Groups are entities that can contain other groups or identity objects which can be associated in tree-like organizational structures. These structures do not need to be hierarchical only, as a single group can be a member of many other groups (that is; a group can have many parents). - </para> - <para> - Possible relationships between groups are controlled with group types. Administrators can configure which different group types can be associated or even which group types can or can not contain identity objects. Groups have unique names per group type. This allows the existance of two groups with the same name, provided they have different group types. - </para> - <para> - Roles form connections between <emphasis>Identity</emphasis> and <emphasis>Group</emphasis> objects. A practical example of this is if we posit that user <emphasis role="bold">John</emphasis> is the <emphasis role="bold">Manager</emphasis> of <emphasis role="bold">XX Team"</emphasis>. In this example you can see how the role form the link between an Identity and a group; <emphasis role="bold">John</emphasis> (an <emphasis>Identity</emphasis>) is the <emphasis role="bold">Manager</emphasis> (a <emphasis>Role</emphasis>) of <emphasis role="bold">XX Team</emphasis> (a <emphasis>Group</emphasis>). - </para> - <para> - This type of information is difficult to map with typical Group objects as <emphasis>John</emphasis> can be a manager of several different groups. Futhermore, other identities (<emphasis>Mary</emphasis>, <emphasis>Jack</emphasis> or <emphasis>Stan</emphasis>) could have the same <emphasis>RoleType</emphasis> in different groups (<emphasis>XY Team</emphasis> or <emphasis>YY Team</emphasis>). - </para> - <para> - Within each Realm (the concept of Realms is described later) we can define several RoleType objects with unique names. Each Role defines a unique combination of Identity, Group and RoleType within a Realm. - </para> - <para> - The Role concept is very powerful but it does not fit easily into all identity store types. While quite easy to map in a relational database it does not fit into every LDAP tree present in organizations. Because of this Role support is optional in the API level - </para> -</chapter> - Deleted: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Hibernate_IdentityStore.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Hibernate_IdentityStore.xml 2011-08-29 03:56:57 UTC (rev 7243) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Hibernate_IdentityStore.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -1,119 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % BOOK_ENTITIES SYSTEM "PicketLink_IDM_Reference_Guide.ent"> -%BOOK_ENTITIES; -]> -<chapter id="chap-PicketLink_IDM_Reference_Guide-Hibernate_IdentityStore"> - <title>Hibernate IdentityStore</title> - <section id="sect-PicketLink_IDM_Reference_Guide-Hibernate_IdentityStore-Class_Name"> - <title>Class Name</title> - <para> - org.picketlink.idm.impl.store.hibernate.HibernateIdentityStoreImpl - </para> - - </section> - - <section id="sect-PicketLink_IDM_Reference_Guide-Hibernate_IdentityStore-Overview"> - <title>Overview</title> - <para> - HibernateIdentityStoreImpl maps PicketLink IDM SPI model into Hibernate entities. This enables to use any RDBMS supported by Hibernate as identity persistence store (IdentityStore). Because of flexibility that ORM gives this IdentityStore implementation support all of the optional design concepts like role management. It can be used as the default IdentityStore together with other more limited implementations. For example in combination with LDAP IdentityStore it can handle IdentityObject attributes that are not supported in LDAP schema. In such configuration part of IdentityObject profile will be stored in LDAP and part in relational database. To learn more about such setup please read FallbackIdentityStoreRepository documentation. In current version implementation doesn't have any caching mechanism besides of what can be set in hibernate configuration - </para> - - </section> - - <section id="sect-PicketLink_IDM_Reference_Guide-Hibernate_IdentityStore-Configuration_Options"> - <title>Configuration Options</title> - <para> - <itemizedlist> - <listitem> - <para> - <emphasis role="bold">hibernateConfiguration</emphasis> - the hibernate configuration file that will be used to create SessionFactory - </para> - - </listitem> - <listitem> - <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">addHibernateMappings</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 &lt;supported-relationship-types&gt; (IdentityObjectRelationshipType in SPI model) during IdentityStore initialization. Default value is 'false' - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">populateIdentityObjectTypes</emphasis> - true/false - Populate configured &lt;supported-identity-object-types&gt; (IdentityObjectType in SPI model) during IdentityStore initialization. Default value is 'false' - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">allowNotDefinedAttributes</emphasis> - true/false - Allow to set IdentityObject attributes that are not specified in &lt;identity-object-type&gt; configuration. Such attributes are assumed to have "text" type and many values. Default value is 'false'. - </para> - - </listitem> - <listitem> - <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> - <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> - - </section> - - <section id="sect-PicketLink_IDM_Reference_Guide-Hibernate_IdentityStore-Sample_Configuration"> - <title>Sample Configuration</title> - -<programlisting language="XML" role="XML"><xi:include href="extras/sample_config.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> - In case 'addHibernateMappings' option is not set to true hibernate configuration need to list all annotated model classes: - </para> - -<programlisting>&lt;mapping resource="mappings/HibernateRealm.hbm.xml"/&gt; -&lt;mapping resource="mappings/HibernateIdentityObjectCredentialBinaryValue.hbm.xml"/&gt; -&lt;mapping resource="mappings/HibernateIdentityObjectAttributeBinaryValue.hbm.xml"/&gt; -&lt;mapping resource="mappings/HibernateIdentityObject.hbm.xml"/&gt; -&lt;mapping resource="mappings/HibernateIdentityObjectCredential.hbm.xml"/&gt; -&lt;mapping resource="mappings/HibernateIdentityObjectCredentialType.hbm.xml"/&gt; -&lt;mapping resource="mappings/HibernateIdentityObjectAttribute.hbm.xml"/&gt; -&lt;mapping resource="mappings/HibernateIdentityObjectType.hbm.xml"/&gt; -&lt;mapping resource="mappings/HibernateIdentityObjectRelationship.hbm.xml"/&gt; -&lt;mapping resource="mappings/HibernateIdentityObjectRelationshipType.hbm.xml"/&gt; -&lt;mapping resource="mappings/HibernateIdentityObjectRelationshipName.hbm.xml"/&gt;</programlisting> - - </section> - - -</chapter> - Deleted: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/IdentitySessionFactory.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/IdentitySessionFactory.xml 2011-08-29 03:56:57 UTC (rev 7243) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/IdentitySessionFactory.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -1,33 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % BOOK_ENTITIES SYSTEM "PicketLink_IDM_Reference_Guide.ent"> -%BOOK_ENTITIES; -]> -<chapter id="chap-PicketLink_IDM_Reference_Guide-IdentitySessionFactory"> - <title>IdentitySessionFactory</title> - <para> - IdentitySessionFactory interface is a main entry point into the API. Default implementation IdentitySessionFactoryImpl has two constructors: - </para> - <itemizedlist> - <listitem> - <para> - public IdentitySessionFactoryImpl(IdentityConfigurationMetaData configMD) throws Exception - </para> - - </listitem> - <listitem> - <para> - public IdentitySessionFactoryImpl(File configFile) throws Exception - </para> - - </listitem> - - </itemizedlist> - <para> - Framework configuration can be defined in two ways. It can be passed as implementation of a set of metadata interfaces grouped in org.picketlink.idm.spi.configuration.metadata package. Main one is IdentityConfigurationMetaData. - </para> - <para> - Other possibility is to use xml configuration file that will be unmarshaled into JAXB model (org.picketlink.idm.impl.configuration.jaxb2.generated package) and used to create IdentityConfigurationMetaData object. XML configuration is described by identity-config.xsd file. It is good to take a look at the example organization-test-config.xml that is used in the testsuite. - </para> -</chapter> - Deleted: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/IdentityStore.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/IdentityStore.xml 2011-08-29 03:56:57 UTC (rev 7243) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/IdentityStore.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -1,148 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % BOOK_ENTITIES SYSTEM "PicketLink_IDM_Reference_Guide.ent"> -%BOOK_ENTITIES; -]> -<chapter id="chap-PicketLink_IDM_Reference_Guide-IdentityStore"> - <title>IdentityStore</title> - <para> - This part is represented by <emphasis role="bold">&lt;stores&gt;&lt;identity-store&gt;...</emphasis> element - </para> - -<programlisting>&lt;stores&gt; - &lt;attribute-stores/&gt; - &lt;identity-stores&gt; - &lt;identity-store&gt; ... &lt;/identity-store&gt; - &lt;identity-store&gt; ... &lt;/identity-store&gt; - &lt;/identity-stores&gt; - &lt;/stores&gt;</programlisting> - <note> - <para> - <emphasis role="bold">&lt;stores/&gt;</emphasis> element contains <emphasis role="bold">&lt;identity-store&gt;</emphasis> and <emphasis role="bold">&lt;attribute-store&gt;</emphasis> elements. Currently <emphasis role="bold">&lt;attribute-store&gt;</emphasis> configuration is ignored so only <emphasis role="bold">&lt;identity-store&gt;</emphasis> elements can be configured. - </para> - - </note> - -<programlisting language="XML" role="XML"><xi:include href="extras/identity-store.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> - <emphasis role="bold">&lt;identity-store&gt;</emphasis> element: - </para> - <itemizedlist> - <listitem> - <para> - <emphasis role="bold">id</emphasis> - IdentityStore id - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">class</emphasis> - IdentityStore class name - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">external-config</emphasis> - external configuration file used by IdentityStore - </para> - - </listitem> - <listitem> - <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> - <emphasis role="bold">supported-identity-object-types</emphasis> - configuration of IdentityObjectType objects mapped by IdentityStore - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">options</emphasis> - other IdentityStore configuration options - </para> - - </listitem> - - </itemizedlist> - -<programlisting language="XML" role="XML"><xi:include href="extras/identity-object-type.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> - &lt;identity-object-type&gt; element: - </para> - <itemizedlist> - <listitem> - <para> - <emphasis role="bold">name</emphasis>- IdentityObjectType name - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">relationships</emphasis> - relationships in which IdentityObjectType can be parent side. <emphasis role="bold">&lt;relationship-type-ref&gt;</emphasis> must point to one of values from <emphasis role="bold">&lt;supported-relationship-types&gt;</emphasis> . <emphasis role="bold">&lt;identity-object-type-ref&gt;</emphasis> must be one of <emphasis role="bold">&lt;identity-object-type&gt;&lt;name&gt;</emphasis> values configured in this IdentityStore. - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">credentials</emphasis> - IdentityObjectCredentialType names allowed for this IdentityObjectType - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">attributes</emphasis> - allowed attribute mappings. Each contains: - <itemizedlist> - <listitem> - <para> - <emphasis role="bold">name</emphasis> - attribute name - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">mapping</emphasis> - real name to be used inside IdentityStore. For example LDAP attribute name - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">type</emphasis> - either "binary" or "text" value - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">isRequired</emphasis> - if attribute cannot have no values - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">isMultivalued</emphasis> - if attribute can have many values - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">isReadonly</emphasis> - if attribute values can be modified - </para> - - </listitem> - - </itemizedlist> - - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">options</emphasis> - other options for IdentityObjectType configuration - </para> - - </listitem> - - </itemizedlist> -</chapter> - Deleted: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/IdentityStoreRepository.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/IdentityStoreRepository.xml 2011-08-29 03:56:57 UTC (rev 7243) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/IdentityStoreRepository.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -1,56 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % BOOK_ENTITIES SYSTEM "PicketLink_IDM_Reference_Guide.ent"> -%BOOK_ENTITIES; -]> -<chapter id="chap-PicketLink_IDM_Reference_Guide-IdentityStoreRepository"> - <title>IdentityStoreRepository</title> - <para> - This section is represented by <emphasis role="bold"> &lt;repositories&gt;&lt;repository&gt;</emphasis> element - </para> - -<programlisting language="XML" role="XML"><xi:include href="extras/repositories.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> - <emphasis role="bold">&lt;repository&gt;</emphasis> element contains: - </para> - <itemizedlist> - <listitem> - <para> - <emphasis role="bold">id</emphasis> - IdentityStoreRepository id. - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">class</emphasis> - class name of IdentityStoreRepository implementation. - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">external-config</emphasis> - external configuration file used by IdentityStoreRepository. - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">default-identity-store-id</emphasis> - id of configured IdentityStore to be used by default. - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">default-attribute-store-id</emphasis> - id of configured AttributeStore (or IdentityStore) to be used by default - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">identity-store-mappings</emphasis> - optional element. Mappings between IdentityObjectType names and IdentityStore ids. - </para> - - </listitem> - - </itemizedlist> -</chapter> - Deleted: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Introduction.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Introduction.xml 2011-08-29 03:56:57 UTC (rev 7243) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Introduction.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -1,12 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % BOOK_ENTITIES SYSTEM "PicketLink_IDM_Reference_Guide.ent"> -%BOOK_ENTITIES; -]> -<chapter id="chap-PicketLink_IDM_Reference_Guide-Introduction"> - <title>Introduction</title> - <para> - The most confusing part of the framework is probably connection between API and SPI. This part will try to explain how operations on API model are translated into the SPI. It will also enable to dive in the API and framework capabilities by looking on realcode examples - </para> -</chapter> - Deleted: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/LDAP_IdentityStore.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/LDAP_IdentityStore.xml 2011-08-29 03:56:57 UTC (rev 7243) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/LDAP_IdentityStore.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -1,239 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % BOOK_ENTITIES SYSTEM "PicketLink_IDM_Reference_Guide.ent"> -%BOOK_ENTITIES; -]> -<chapter id="chap-PicketLink_IDM_Reference_Guide-LDAP_IdentityStore"> - <title>LDAP IdentityStore</title> - <section id="sect-PicketLink_IDM_Reference_Guide-LDAP_IdentityStore-Class_Name"> - <title>Class Name</title> - <para> - org.picketlink.idm.impl.store.ldap.LDAPIdentityStoreImpl - </para> - - </section> - - <section id="sect-PicketLink_IDM_Reference_Guide-LDAP_IdentityStore-Overview"> - <title>Overview</title> - <para> - LDAPIdentityStoreImpl provides support for LDAP as identity persistence store (IdentityStore). At this stage the implementation is a bit limitted: - </para> - <itemizedlist> - <listitem> - <para> - Role management (IdentityObjectRelationshipName) is not supported - </para> - - </listitem> - <listitem> - <para> - Only "text" attribute type can be mapped - </para> - - </listitem> - <listitem> - <para> - Only "PASSWORD" &lt;credential-type&gt; can be mapped - </para> - - </listitem> - - </itemizedlist> - - </section> - - <section id="sect-PicketLink_IDM_Reference_Guide-LDAP_IdentityStore-Configuration"> - <title>Configuration</title> - <para> - &lt;identity-object-type&gt;&lt;options&gt; - </para> - <itemizedlist> - <listitem> - <para> - <emphasis role="bold">idAttributeName</emphasis> - attribute name under which IdentityObject name is specified. Required. - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">passwordAttributeName</emphasis> - attribute name under which IdentityObject password is specified. Optional. - </para> - - </listitem> - <listitem> - <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> - <emphasis role="bold">allowCreateEntry</emphasis> - true/false - Specify if new IdentityObject can be created. - </para> - - </listitem> - <listitem> - <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> - <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> - <emphasis role="bold">isParentMembershipAttributeDN</emphasis> - defines if values of attribute defined in parentMembershipAttributeName are fully qualified LDAP DNs. - </para> - - </listitem> - <listitem> - <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> - <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">entrySearchScope</emphasis> - defines a search scope. Values can be "subtree" and "object" - </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> - <emphasis role="bold">&lt;identity-store&gt;&lt;options&gt;</emphasis> - </para> - <itemizedlist> - <listitem> - <para> - <emphasis role="bold">providerURL</emphasis> - LDAP connection URL. For example "ldap://localhost:389" - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">adminDN</emphasis> - LDAP entry used to connect to the server. - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">adminPassword</emphasis> - password related to adminDN - </para> - - </listitem> - <listitem> - <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> - <listitem> - <para> - <emphasis role="bold">sortExtensionSupported</emphasis> - if set to "false" will disable the use of sort extension that triggers sort on LDAP server side - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">pagedResultsExtensionSupported</emphasis> - if set to "true" will enable paged search. Searches that exceed size defined by "pagedResultsExtensionSize" option will be splitted into few smaller ones. - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">pagedResultsExtensionSize</emphasis> - defines page size for "pagedResultsExtensionSupported" option. - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">createMissingContexts</emphasis> - if set to "true" LDAP store will try to create missing LDAP contexts defined in the configuration. - </para> - - </listitem> - - </itemizedlist> - - </section> - - <section id="sect-PicketLink_IDM_Reference_Guide-LDAP_IdentityStore-Sample_Configuration"> - <title>Sample Configuration</title> - -<programlisting language="XML" role="XML"><xi:include href="extras/sample_config2.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </section> - - -</chapter> - Deleted: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Main_Concepts.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Main_Concepts.xml 2011-08-29 03:56:57 UTC (rev 7243) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Main_Concepts.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -1,93 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % BOOK_ENTITIES SYSTEM "PicketLink_IDM_Reference_Guide.ent"> -%BOOK_ENTITIES; -]> -<chapter id="chap-PicketLink_IDM_Reference_Guide-Main_Concepts"> - <title>Main Concepts</title> - - <variablelist> - <title>Terms</title> - <varlistentry> - <term>PicketLink</term> - <listitem> - <para> - PicketLink is an umbrella project that aims to address different Identity Management needs. - </para> - <!--http://www.jboss.org/picketlink--> - </listitem> - </varlistentry> - <varlistentry> - <term>IDM</term> - <listitem> - <para> - IDM stand for <emphasis role="bold">ID</emphasis>entity <emphasis role="bold">M</emphasis>anagement. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Identity Management</term> - <listitem> - <para> - Identity management deals with the management of digital identities. Typically these identities are used to authenticate an organizations users so as to control access to organizational resources. However, other entities, including devices, processes and applications, in a networked environment may be represtented in the identity model. - </para> - <!--http://download.oracle.com/docs/cd/B14099_19/core.1012/b13995/glossary.htm#sthref2905--> - <!--http://download.oracle.com/docs/cd/B14099_19/idmanage.1012/b14080/glossary.htm#sthref2905--> - - </listitem> - </varlistentry> - <varlistentry> - <term>API</term> - <listitem> - <para> - An <emphasis role="bold">A</emphasis>pplication <emphasis role="bold">P</emphasis>rogramming <emphasis role="bold">I</emphasis>nterface (<emphasis role="bold">API</emphasis>) is a set of specifications that allow applications that use the same API to communicate and share data. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>SPI</term> - <listitem> - <para> - An <emphasis role="bold">S</emphasis>ervice <emphasis role="bold">P</emphasis>rovider <emphasis role="bold">I</emphasis>nterface (<emphasis role="bold">SPI</emphasis>) is the set of specifications that a service defines. - </para> - <!--http://www.developer.com/java/article.php/3848881/Service-Provider-Interface-Creating-Extensible-Java-Applications.htm--> - </listitem> - </varlistentry> - </variablelist> - <para> - PicketLink IDM aims to provide a common identity model for various JBoss projects. As every project has specific needs, designing a common API and identity model that will fit all of them can be difficult. Therefore the PicketLink IDM architecture consists of two main parts: - </para> - <variablelist> - <title></title> - <varlistentry> - <term>Core SPI</term> - <listitem> - <para> - The PicketLink <emphasis role="bold">SPI</emphasis> uses an abstract identity model that provides the flexibility for defining different identity object types and possible relationships between them. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Common API</term> - <listitem> - <para> - The PcketLink <emphasis role="bold">API</emphasis> uses a simpler identity model that fits most common use cases. Identity model has more strictly defined object types and possible relationships. - </para> - </listitem> - </varlistentry> - </variablelist> - - <mediaobject> - <imageobject role="html"> - <imagedata fileref="images/IDM-global-arch.png" format="PNG" align="center"/> - </imageobject> - <imageobject role="fo"> - <imagedata fileref="images/IDM-global-arch.png" format="PNG" align="center" width="120mm"/> - </imageobject> - </mediaobject> - <para> - Too much abstraction in the API layer would confuse people using the framework. One of the goals is to make the design easily extendible. Framework adopters should be able to remove the API layer and reuse core SPI implementation if needed. - </para> - -</chapter> - Deleted: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Minimal_Configuration.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Minimal_Configuration.xml 2011-08-29 03:56:57 UTC (rev 7243) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Minimal_Configuration.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -1,15 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % BOOK_ENTITIES SYSTEM "PicketLink_IDM_Reference_Guide.ent"> -%BOOK_ENTITIES; -]> -<chapter id="chap-PicketLink_IDM_Reference_Guide-Minimal_Configuration"> - <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 language="XML" role="XML"><xi:include href="extras/lazy-config.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - -</chapter> - Modified: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/PicketLink_IDM_Reference_Guide.ent =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/PicketLink_IDM_Reference_Guide.ent 2011-08-29 03:56:57 UTC (rev 7243) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/PicketLink_IDM_Reference_Guide.ent 2011-08-29 07:26:00 UTC (rev 7244) @@ -15,5 +15,5 @@ <!-- Version Specifcs: --> <!ENTITY VX "5"> -<!ENTITY VY "5.1"> -<!ENTITY VZ "5.1.1"> \ No newline at end of file +<!ENTITY VY "5.2"> +<!ENTITY VZ "5.2.0"> \ No newline at end of file Modified: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/PicketLink_IDM_Reference_Guide.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/PicketLink_IDM_Reference_Guide.xml 2011-08-29 03:56:57 UTC (rev 7243) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/PicketLink_IDM_Reference_Guide.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -6,74 +6,15 @@ <book> <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <part id="part-PicketLink_IDM_Reference_Guide-Design_and_Architecture"> - <title>Design and Architecture</title> - <xi:include href="Main_Concepts.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="API_Model.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="Group_And_Roles.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <!--Edited to here.--> - <xi:include href="SPI_Model.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="Architecture.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="Realms.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - - </part> - <part id="part-PicketLink_IDM_Reference_Guide-Concepts_behind_API_to_SPI_mappings"> - <title>Concepts behind API to SPI mappings</title> - <xi:include href="Introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="User_and_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="Associations.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="Role.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - - </part> - <part id="part-PicketLink_IDM_Reference_Guide-Quick_Start"> - <title>Quick Start</title> - <xi:include href="Test_Cases.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="Examples.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="Core_Files.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - - </part> - <part id="part-PicketLink_IDM_Reference_Guide-Configuration"> - <title>Configuration</title> - <xi:include href="IdentitySessionFactory.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="XML_Configuration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="IdentityStore.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="IdentityStoreRepository.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="Realm.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="Realm_Templates.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="API_Cache.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - - </part> - <part id="part-PicketLink_IDM_Reference_Guide-IdentityStore_Implementations"> - <title>IdentityStore Implementations</title> - <xi:include href="Hibernate_IdentityStore.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="LDAP_IdentityStore.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="Minimal_Configuration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - - </part> - <part id="part-PicketLink_IDM_Reference_Guide-IdentityStoreRepository_Implementations"> - <title>IdentityStoreRepository Implementations</title> - <xi:include href="WrapperIdentityStoreRepository.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="FallbackIdentityStoreRepository.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - - </part> - <part id="part-PicketLink_IDM_Reference_Guide-Attributes"> - <title>Attributes</title> - <xi:include href="API.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="SPI.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - - </part> - <part id="part-PicketLink_IDM_Reference_Guide-Credentials"> - <title>Credentials</title> - <xi:include href="Credential_API.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="Credential_SPI.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - - </part> - <part id="part-PicketLink_IDM_Reference_Guide-Deployment"> - <title>Deployment</title> - <xi:include href="Usage_Scenario.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="Deployment.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - - </part> + <xi:include href="modules/chap_Design_and_Architecture.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="modules/chap_Concepts_API_SPI.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="modules/chap_Quick_Start.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="modules/chap_Configuration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="modules/chap_IdentityStore_Implementations.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="modules/chap_IdentityStoreRepository_Implementations.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="modules/chap_Attributes.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="modules/chap_Credentials.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="modules/chap_Deployment.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <index /> </book> Deleted: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Realm.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Realm.xml 2011-08-29 03:56:57 UTC (rev 7243) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Realm.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -1,54 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % BOOK_ENTITIES SYSTEM "PicketLink_IDM_Reference_Guide.ent"> -%BOOK_ENTITIES; -]> -<chapter id="chap-PicketLink_IDM_Reference_Guide-Realm"> - <title>Realm</title> - <para> - This section is represented by <emphasis role="bold">&lt;realms&gt;&lt;realm&gt;</emphasis> element - </para> - -<programlisting>&lt;realm&gt; - &lt;id&gt;realm://RedHat/DB&lt;/id&gt; - &lt;repository-id-ref&gt;RedHat Repository DB&lt;/repository-id-ref&gt; - &lt;identity-type-mappings&gt; - &lt;identity-mapping&gt;IDENTITY&lt;/identity-mapping&gt; - &lt;/identity-type-mappings&gt; -&lt;/realm&gt;</programlisting> - <para> - <emphasis role="bold">&lt;realm&gt;</emphasis> element contains: - </para> - <itemizedlist> - <listitem> - <para> - <emphasis role="bold">id</emphasis> - realm id - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">repository-id-ref</emphasis> - id of configured IdentityStoreRepository - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">identity-type-mappings</emphasis> <itemizedlist> - <listitem> - <para> - <emphasis role="bold">identity-mapping</emphasis> - name of IdentityObjectType that should be maped as Identity object on the API side - </para> - - </listitem> - - </itemizedlist> - - </para> - - </listitem> - - </itemizedlist> - -</chapter> - Deleted: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Realm_Templates.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Realm_Templates.xml 2011-08-29 03:56:57 UTC (rev 7243) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Realm_Templates.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -1,51 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % BOOK_ENTITIES SYSTEM "PicketLink_IDM_Reference_Guide.ent"> -%BOOK_ENTITIES; -]> -<chapter id="chap-PicketLink_IDM_Reference_Guide-Realm_Templates"> - <title>Realm Templates</title> - <para> - Realm can be marked as a template. This means that if a different realm name is requested using the API and such name contains template realm as a prefix then this realm configuration will be used - </para> - -<programlisting>&lt;realm&gt; - &lt;id&gt;idm_realm&lt;/id&gt; - &lt;repository-id-ref&gt;DefaultRepository&lt;/repository-id-ref&gt; - &lt;identity-type-mappings&gt; - &lt;user-mapping&gt;USER&lt;/user-mapping&gt; - &lt;/identity-type-mappings&gt; - &lt;options&gt; - &lt;option&gt; - &lt;name&gt;template&lt;/name&gt; - &lt;value&gt;true&lt;/value&gt; - &lt;/option&gt; - &lt;/options&gt; - &lt;/realm&gt;</programlisting> - <para> - In this example for "idm_realm_foo" framework will return "idm_realm" configuration. Request for "foo" realm won't return valid configuration. - </para> - -<programlisting>&lt;realms&gt; - &lt;realm&gt; - &lt;id&gt;idm_realm&lt;/id&gt; - &lt;repository-id-ref&gt;DefaultRepository&lt;/repository-id-ref&gt; - &lt;identity-type-mappings&gt; - &lt;user-mapping&gt;USER&lt;/user-mapping&gt; - &lt;/identity-type-mappings&gt; - - &lt;/realm&gt; - &lt;/realms&gt; - &lt;repositories&gt;...&lt;/repositories&gt; - &lt;stores&gt;...&lt;/stores&gt; - &lt;options&gt; - &lt;option&gt; - &lt;name&gt;defaultTemplate&lt;/name&gt; - &lt;value&gt;idm_realm&lt;/value&gt; - &lt;/option&gt; - &lt;/options&gt;</programlisting> - <para> - The "defaultTemplate" option defines idm_realm as the one that should be used when requested realm name is not found in configuration - </para> -</chapter> - Deleted: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Realms.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Realms.xml 2011-08-29 03:56:57 UTC (rev 7243) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Realms.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -1,22 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % BOOK_ENTITIES SYSTEM "PicketLink_IDM_Reference_Guide.ent"> -%BOOK_ENTITIES; -]> -<chapter id="chap-PicketLink_IDM_Reference_Guide-Realms"> - <title>Realms</title> - <para> - The purpose of a Realm is to group configuration of several identity stores. IdentitySession exposes operations within single Realm - </para> - <mediaobject> - <imageobject> - <imagedata contentdepth="6in" contentwidth="6in" fileref="images/IDM-global-realm.png" width="444" /> - </imageobject> - <caption align="right"> <para> - <emphasis role="bold">PicketLink IDM architecture</emphasis> - </para> - </caption> - </mediaobject> - -</chapter> - Modified: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Revision_History.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Revision_History.xml 2011-08-29 03:56:57 UTC (rev 7243) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Revision_History.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -3,31 +3,24 @@ <!ENTITY % BOOK_ENTITIES SYSTEM "PicketLink_IDM_Reference_Guide.ent"> %BOOK_ENTITIES; ]> -<appendix id="appe-PicketLink_IDM_Reference_Guide-Revision_History"> - <title>Revision History</title> - <simpara> - <revhistory> - <revision> - <revnumber>0-0</revnumber> - <date>Mon Aug 1 2011</date> - <author> - <firstname>Dude</firstname> - <surname>McPants</surname> - <email&gt;Dude.McPants(a)example.com&lt;/email&gt; - - </author> - <revdescription> - <simplelist> - <member>Initial creation of book by publican</member> - - </simplelist> - - </revdescription> - - </revision> - - </revhistory> - - </simpara> -</appendix> - +<appendix id="appe-Release_Notes-Revision_History"> + <title>Revision History</title> + <simpara> + <revhistory> + <revision> + <revnumber>5.2.0-1</revnumber> + <date>Mon Aug 29 2011</date> + <author> + <firstname>Scott</firstname> + <surname>Mumford</surname> + <email></email> + </author> + <revdescription> + <simplelist> + <member>Updating version and resetting pubs/ed numbers.</member> + </simplelist> + </revdescription> + </revision> + </revhistory> + </simpara> +</appendix> \ No newline at end of file Deleted: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Role.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Role.xml 2011-08-29 03:56:57 UTC (rev 7243) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Role.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -1,60 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % BOOK_ENTITIES SYSTEM "PicketLink_IDM_Reference_Guide.ent"> -%BOOK_ENTITIES; -]> -<chapter id="chap-PicketLink_IDM_Reference_Guide-Role"> - <title>Role</title> - <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) 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). Within each Realm (concept of Realms is described later) we can define several RoleType objects with unique names. Each Role defines a unique combination of Identity, Group and RoleType within Realm. - </para> - <para> - Roles are managed with RoleManager interface: - </para> - -<programlisting role="Java"> -RoleManager roleManager = identitySession.getRoleManager(); - -roleManager.createRoleType("manager"); -RoleType adminRT = roleManager.createRoleType("administrator"); - -Role role1 = roleManager.createRole("manager", annUser.getId(), parisOffice.getId()); -roleManager.createRole(adminRT, stefanUser, itDep); - -assertTrue(roleManager.hasRole(stefanUser, itDep, adminRT)); -</programlisting> - <para> - At the SPI level the main difference between plain association is that IdentityObjectRelationship has a IdentityObjectRelationshipName which is simple mapping of a RoleType used in the API - </para> - <mediaobject> - <imageobject> - <imagedata contentdepth="6in" contentwidth="6in" fileref="images/SPI3.png" width="444" /> - </imageobject> - <!-- <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 identity stores. Entities represented on attached figures are easy to map in the database. However in store like LDAP typical relationships are represanted in a more plain manner. For example: - </para> - -<programlisting>dn: uid=admin,ou=People,o=test,dc=portal,dc=example,dc=com -objectclass: top -objectclass: inetOrgPerson -objectclass: person -uid: admin -cn: Java Duke -sn: Duke -userPassword: admin -mail: email(a)email.com - -dn: cn=Administrators,ou=Groups,o=test,dc=portal,dc=example,dc=com -objectClass: top -objectClass: groupOfNames -cn: Administrators -description: Portal admin role -member: uid=admin,ou=People,o=test,dc=portal,dc=example,dc=com</programlisting> - <para> - The whole relationship between User "admin" and Group "Administrators" is described by one attribute value ("member"). In such typical LDAP tree shape there is no place to store additional information that are needed to describe Role shown above. Obviously it is possible to shape LDAP tree in a way that will allow such a mapping but in most cases it is not possible to redesign already used LDAP server tree. - </para> - -</chapter> - Deleted: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/SPI.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/SPI.xml 2011-08-29 03:56:57 UTC (rev 7243) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/SPI.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -1,66 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % BOOK_ENTITIES SYSTEM "PicketLink_IDM_Reference_Guide.ent"> -%BOOK_ENTITIES; -]> -<chapter id="chap-PicketLink_IDM_Reference_Guide-SPI"> - <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> - <itemizedlist> - <listitem> - <para> - <emphasis role="bold">name</emphasis> - attribute name - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">readonly</emphasis> - if attribute values can be changed - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">multivalued</emphasis> - if attribute can have many values - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">required</emphasis> - if attribute can be removed - </para> - - </listitem> - <listitem> - <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> - <emphasis role="bold">text</emphasis> - java.lang.String object - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">binary</emphasis> - byte[] object - </para> - - </listitem> - - </itemizedlist> - <para> - All operations related to IdentityObjectAttribute are exposed by the AttributeStore interface - </para> -</chapter> - Deleted: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/SPI_Model.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/SPI_Model.xml 2011-08-29 03:56:57 UTC (rev 7243) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/SPI_Model.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -1,61 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % BOOK_ENTITIES SYSTEM "PicketLink_IDM_Reference_Guide.ent"> -%BOOK_ENTITIES; -]> -<chapter id="chap-PicketLink_IDM_Reference_Guide-SPI_Abstract_Model"> - <title>SPI (Abstract) Model</title> - <para> - SPI Model contains following interfaces: - </para> - <itemizedlist> - <listitem> - <para> - <emphasis role="bold">org.picketlink.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> - <emphasis role="bold">org.picketlink.idm.spi.model.IdentityObjectType</emphasis> - represents identity object type. Name of IdentityType is unique. - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">org.picketlink.idm.spi.model.IdentityObjectAttribute</emphasis> - attribute assigned to IdentityObject - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">org.picketlink.idm.spi.model.IdentityObjectCredential</emphasis> - credential assigned to IdentityObject - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">org.picketlink.idm.spi.model.IdentityObjectCredentialType</emphasis> - represents type of IdentityObjectCredential. - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">org.picketlink.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> - <emphasis role="bold">org.picketlink.idm.spi.model.IdentityObjectRelationshipType</emphasis> - named type of relationship - </para> - - </listitem> - - </itemizedlist> - <para> - Model described above is very flexible as IdentityObjectType is able to map any kind of entities. Identity object and Group/GroupType objects are only one of many possible options (API is a subset of SPI possibilities). IdentityObjectRelationship defines a connection between any two IdentityObject objects. Each IdentityObjectRelationship has a type. To map previously described API two IdentityObjectRelationshipType objects are needed. One to map normal MEMBERSHIP like between an Identity and a Group or Group and Group objects. Second one to map Role concept. For API Role - RoleType refers to the name of the IdentityObjectRelationship. In default Hibernate implementation possible names of IdentityObjectRelationship are kept in a separate table. All of those can be easily redefined to support different kind of API. - </para> - -</chapter> - Deleted: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Test_Cases.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Test_Cases.xml 2011-08-29 03:56:57 UTC (rev 7243) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Test_Cases.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -1,12 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % BOOK_ENTITIES SYSTEM "PicketLink_IDM_Reference_Guide.ent"> -%BOOK_ENTITIES; -]> -<chapter id="chap-PicketLink_IDM_Reference_Guide-Test_Cases"> - <title>Test Cases</title> - <para> - One of the best ways to get familiar with the PicketLink 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 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> -</chapter> - Deleted: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Usage_Scenario.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Usage_Scenario.xml 2011-08-29 03:56:57 UTC (rev 7243) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/Usage_Scenario.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -1,38 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % BOOK_ENTITIES SYSTEM "PicketLink_IDM_Reference_Guide.ent"> -%BOOK_ENTITIES; -]> -<chapter id="chap-PicketLink_IDM_Reference_Guide-IDM_Usage_Scenario"> - <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>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> - Deleted: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/User_and_Group.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/User_and_Group.xml 2011-08-29 03:56:57 UTC (rev 7243) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/User_and_Group.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -1,37 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % BOOK_ENTITIES SYSTEM "PicketLink_IDM_Reference_Guide.ent"> -%BOOK_ENTITIES; -]> -<chapter id="chap-PicketLink_IDM_Reference_Guide-User_and_Group"> - <title>User and Group</title> - <para> - Objects represented by User and Group interfaces are managed by PersistenceManager. In the example below 3 users and 4 groups are created. - </para> - -<programlisting role="Java">PersistenceManager pm = identitySession.getPersistenceManager(); -User johnUser = pm.createUser("John"); -User annUser = pm.createUser("Ann"); -User stefanUser = pm.createUser("Stefan"); - -String OFFICE = "OFFICE"; -String DEPARTMENT = "DEPARTMENT"; - -Group parisOffice = pm.createGroup("Paris", OFFICE); -Group atlantaOffice = pm.createGroup("Atlanta", OFFICE); - -assertEquals(OFFICE, parisOffice.getGroupType()); - -Group itDep = pm.createGroup("IT", DEPARTMENT); -Group hrDep = pm.createGroup("HR", DEPARTMENT);</programlisting> - <para> - At the SPI level both Group and User are mapped as IdentityObject. What differentiate them is the IdentityObjectType. IdentityObjectType "USER" is mapped to represent User objects while other are mapped to represent different Group types names. - </para> - <mediaobject> - <imageobject> - <imagedata contentdepth="6in" contentwidth="6in" fileref="images/SPI1.png" width="444" /> - </imageobject> - - </mediaobject> -</chapter> - Deleted: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/WrapperIdentityStoreRepository.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/WrapperIdentityStoreRepository.xml 2011-08-29 03:56:57 UTC (rev 7243) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/WrapperIdentityStoreRepository.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -1,39 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % BOOK_ENTITIES SYSTEM "PicketLink_IDM_Reference_Guide.ent"> -%BOOK_ENTITIES; -]> -<chapter id="chap-PicketLink_IDM_Reference_Guide-WrapperIdentityStoreRepository"> - <title>WrapperIdentityStoreRepository</title> - <section id="sect-PicketLink_IDM_Reference_Guide-WrapperIdentityStoreRepository-ClassName"> - <title>ClassName</title> - <para> - org.picketlink.idm.impl.repository.WrapperIdentityStoreRepository - </para> - - </section> - - <section id="sect-PicketLink_IDM_Reference_Guide-WrapperIdentityStoreRepository-Behaviour"> - <title>Behaviour</title> - <para> - Simply wraps single AttributeStore and IdentityStore and pass all method invocations - </para> - - </section> - - <section id="sect-PicketLink_IDM_Reference_Guide-WrapperIdentityStoreRepository-Sample_Configuration"> - <title>Sample Configuration</title> - -<programlisting>&lt;repository&gt; - &lt;id&gt;Sample Repository&lt;/id - &lt;class&gt;org.picketlink.idm.impl.repository.WrapperIdentityStoreRepository&lt;/class&gt; - &lt;external-config/&gt; - &lt;default-identity-store-id&gt;LDAP Store&lt;/default-identity-store-id&gt; - &lt;default-attribute-store-id&gt;LDAP Store&lt;/default-attribute-store-id&gt; -&lt;/repository&gt;</programlisting> - - </section> - - -</chapter> - Deleted: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/XML_Configuration.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/XML_Configuration.xml 2011-08-29 03:56:57 UTC (rev 7243) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/XML_Configuration.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -1,41 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % BOOK_ENTITIES SYSTEM "PicketLink_IDM_Reference_Guide.ent"> -%BOOK_ENTITIES; -]> -<chapter id="chap-PicketLink_IDM_Reference_Guide-XML_Configuration"> - <title>XML Configuration</title> - -<programlisting>&lt;jboss-identity xmlns="urn:jboss:identity:idm:config:v1_0_alpha" - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xsi:schemaLocation="urn:jboss:identity:idm:config:v1_0_alpha identity-config.xsd"&gt; - &lt;realms/&gt; - &lt;repositories/&gt; - &lt;stores/&gt; -&lt;/jboss-identity&gt;</programlisting> - <para> - Identity XML configuration can be divided into three parts: - </para> - <itemizedlist> - <listitem> - <para> - <emphasis role="bold">&lt;stores/&gt;</emphasis> - defines IdentityStore and AttributeStore instances - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">&lt;repositories/&gt;</emphasis> - defines IdentityStoreRepository instances - </para> - - </listitem> - <listitem> - <para> - <emphasis role="bold">&lt;realms/&gt;</emphasis> - defines identity realms - </para> - - </listitem> - - </itemizedlist> -</chapter> - Added: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Attributes/API.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Attributes/API.xml (rev 0) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Attributes/API.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -0,0 +1,71 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../../PicketLink_IDM_Reference_Guide.ent"> +%BOOK_ENTITIES; +]> +<section id="sect-PicketLink_IDM_Reference_Guide-API"> + <title>API</title> + <para> + On the API level each IdentityType object (Identity and Group) can have associated Attribute objects. All operations are exposed by AttributesManager interface. Each attribute is described with AttributeDescription that contains its properties such as: + </para> + <itemizedlist> + <listitem> + <para> + <emphasis role="bold">name</emphasis> - attribute name + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">readonly</emphasis> - if attribute values can be changed + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">multivalued</emphasis> - if attribute can have many values + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">required</emphasis> - if attribute can be removed + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">type</emphasis> - type of attribute values. + </para> + + </listitem> + + </itemizedlist> + <para> + Default implementation provides two attribute types: + </para> + <itemizedlist> + <listitem> + <para> + <emphasis role="bold">text</emphasis> - java.lang.String object + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">binary</emphasis> - byte[] object + </para> + + </listitem> + + </itemizedlist> + <section id="sect-PicketLink_IDM_Reference_Guide-API-Sample_operations"> + <title>Sample operations</title> + +<programlisting role="Java"><xi:include href="../../extras/sample-operations.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + + </section> + + +</section> + Added: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Attributes/SPI.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Attributes/SPI.xml (rev 0) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Attributes/SPI.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -0,0 +1,66 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../../PicketLink_IDM_Reference_Guide.ent"> +%BOOK_ENTITIES; +]> +<section id="sect-PicketLink_IDM_Reference_Guide-SPI"> + <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> + <itemizedlist> + <listitem> + <para> + <emphasis role="bold">name</emphasis> - attribute name + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">readonly</emphasis> - if attribute values can be changed + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">multivalued</emphasis> - if attribute can have many values + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">required</emphasis> - if attribute can be removed + </para> + + </listitem> + <listitem> + <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> + <emphasis role="bold">text</emphasis> - java.lang.String object + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">binary</emphasis> - byte[] object + </para> + + </listitem> + + </itemizedlist> + <para> + All operations related to IdentityObjectAttribute are exposed by the AttributeStore interface + </para> +</section> + Added: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Concepts_API_SPI/Associations.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Concepts_API_SPI/Associations.xml (rev 0) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Concepts_API_SPI/Associations.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -0,0 +1,33 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../../PicketLink_IDM_Reference_Guide.ent"> +%BOOK_ENTITIES; +]> +<section id="sect-PicketLink_IDM_Reference_Guide-Associations"> + <title>Associations</title> + <para> + Group and Users can be associated. This represents simple relationship that can be described like "user John belongs to Group IT". Association can be created between Group and User or between two Groups. + </para> + <para> + Those operations are managed by RelationshipManager: + </para> + +<programlisting role="Java"> +RelationshipManager rm = identitySession.getRelationshipManager(); + +rm.associateUser(parisOffice, annUser); +rm.associateUser(atlantaOffice, stefanUser); +rm.associateUser(itDep, stefanUser); + +assertTrue(rm.isAssociated(parisOffice, annUser));</programlisting> + <para> + At the SPI level this is mapped to IdentityObjectRelationship entity. This relationship has a type. Simple assotiations can be marked with a type named "JBOSS_IDENTITY_MEMBERSHIP" (this is implementation detail) which describes simple membership. Note that IdentityObjectRelationship creates a connection between any two IdentityObject entities. + </para> + <mediaobject> + <imageobject> + <imagedata contentdepth="6in" contentwidth="6in" fileref="images/SPI2.png" width="444" /> + </imageobject> + + </mediaobject> +</section> + Added: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Concepts_API_SPI/Introduction.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Concepts_API_SPI/Introduction.xml (rev 0) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Concepts_API_SPI/Introduction.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -0,0 +1,12 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../../PicketLink_IDM_Reference_Guide.ent"> +%BOOK_ENTITIES; +]> +<section id="sect-PicketLink_IDM_Reference_Guide-Introduction"> + <title>Introduction</title> + <para> + The most confusing part of the framework is probably connection between API and SPI. This part will try to explain how operations on API model are translated into the SPI. It will also enable to dive in the API and framework capabilities by looking on realcode examples + </para> +</section> + Added: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Concepts_API_SPI/Role.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Concepts_API_SPI/Role.xml (rev 0) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Concepts_API_SPI/Role.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -0,0 +1,60 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../../PicketLink_IDM_Reference_Guide.ent"> +%BOOK_ENTITIES; +]> +<section id="sect-PicketLink_IDM_Reference_Guide-Role"> + <title>Role</title> + <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) 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). Within each Realm (concept of Realms is described later) we can define several RoleType objects with unique names. Each Role defines a unique combination of Identity, Group and RoleType within Realm. + </para> + <para> + Roles are managed with RoleManager interface: + </para> + +<programlisting role="Java"> +RoleManager roleManager = identitySession.getRoleManager(); + +roleManager.createRoleType("manager"); +RoleType adminRT = roleManager.createRoleType("administrator"); + +Role role1 = roleManager.createRole("manager", annUser.getId(), parisOffice.getId()); +roleManager.createRole(adminRT, stefanUser, itDep); + +assertTrue(roleManager.hasRole(stefanUser, itDep, adminRT)); +</programlisting> + <para> + At the SPI level the main difference between plain association is that IdentityObjectRelationship has a IdentityObjectRelationshipName which is simple mapping of a RoleType used in the API + </para> + <mediaobject> + <imageobject> + <imagedata contentdepth="6in" contentwidth="6in" fileref="images/SPI3.png" width="444" /> + </imageobject> + <!-- <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 identity stores. Entities represented on attached figures are easy to map in the database. However in store like LDAP typical relationships are represanted in a more plain manner. For example: + </para> + +<programlisting>dn: uid=admin,ou=People,o=test,dc=portal,dc=example,dc=com +objectclass: top +objectclass: inetOrgPerson +objectclass: person +uid: admin +cn: Java Duke +sn: Duke +userPassword: admin +mail: email(a)email.com + +dn: cn=Administrators,ou=Groups,o=test,dc=portal,dc=example,dc=com +objectClass: top +objectClass: groupOfNames +cn: Administrators +description: Portal admin role +member: uid=admin,ou=People,o=test,dc=portal,dc=example,dc=com</programlisting> + <para> + The whole relationship between User "admin" and Group "Administrators" is described by one attribute value ("member"). In such typical LDAP tree shape there is no place to store additional information that are needed to describe Role shown above. Obviously it is possible to shape LDAP tree in a way that will allow such a mapping but in most cases it is not possible to redesign already used LDAP server tree. + </para> + +</section> + Added: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Concepts_API_SPI/User_and_Group.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Concepts_API_SPI/User_and_Group.xml (rev 0) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Concepts_API_SPI/User_and_Group.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -0,0 +1,37 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../../PicketLink_IDM_Reference_Guide.ent"> +%BOOK_ENTITIES; +]> +<section id="sect-PicketLink_IDM_Reference_Guide-User_and_Group"> + <title>User and Group</title> + <para> + Objects represented by User and Group interfaces are managed by PersistenceManager. In the example below 3 users and 4 groups are created. + </para> + +<programlisting role="Java">PersistenceManager pm = identitySession.getPersistenceManager(); +User johnUser = pm.createUser("John"); +User annUser = pm.createUser("Ann"); +User stefanUser = pm.createUser("Stefan"); + +String OFFICE = "OFFICE"; +String DEPARTMENT = "DEPARTMENT"; + +Group parisOffice = pm.createGroup("Paris", OFFICE); +Group atlantaOffice = pm.createGroup("Atlanta", OFFICE); + +assertEquals(OFFICE, parisOffice.getGroupType()); + +Group itDep = pm.createGroup("IT", DEPARTMENT); +Group hrDep = pm.createGroup("HR", DEPARTMENT);</programlisting> + <para> + At the SPI level both Group and User are mapped as IdentityObject. What differentiate them is the IdentityObjectType. IdentityObjectType "USER" is mapped to represent User objects while other are mapped to represent different Group types names. + </para> + <mediaobject> + <imageobject> + <imagedata contentdepth="6in" contentwidth="6in" fileref="images/SPI1.png" width="444" /> + </imageobject> + + </mediaobject> +</section> + Added: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Configuration/API_Cache.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Configuration/API_Cache.xml (rev 0) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Configuration/API_Cache.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -0,0 +1,51 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../../PicketLink_IDM_Reference_Guide.ent"> +%BOOK_ENTITIES; +]> +<section id="sect-PicketLink_IDM_Reference_Guide-API_Cache"> + <title>API Cache</title> + <para> + At the realm level IDM API cache layer can be enabled + </para> + +<programlisting>&lt;realm&gt; + &lt;id&gt;idm_realm&lt;/id&gt; + &lt;repository-id-ref&gt;DefaultRepository&lt;/repository-id-ref&gt; + &lt;identity-type-mappings&gt; + &lt;user-mapping&gt;USER&lt;/user-mapping&gt; + &lt;/identity-type-mappings&gt; + &lt;options&gt; + &lt;option&gt; + &lt;name&gt;cache.providerClass&lt;/name&gt; + &lt;value&gt;JBossCacheAPICacheProviderImpl&lt;/value&gt; + &lt;/option&gt; + &lt;/options&gt; +&lt;/realm&gt;</programlisting> + <para> + Cache related options : + </para> + <itemizedlist> + <listitem> + <para> + <emphasis role="bold">cache.providerClass</emphasis> - class implementing APICacheProvider interface + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">cache.providerRegistryName</emphasis> - id of instantiated APICacheProvider implementation stored in configuration registry + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">cache.scope</emphasis> - namespace used to store entities in cache. Can be "realm" (default) or "session". + </para> + + </listitem> + + </itemizedlist> + +</section> + Added: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Configuration/IdentitySessionFactory.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Configuration/IdentitySessionFactory.xml (rev 0) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Configuration/IdentitySessionFactory.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -0,0 +1,33 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../../PicketLink_IDM_Reference_Guide.ent"> +%BOOK_ENTITIES; +]> +<section id="sect-PicketLink_IDM_Reference_Guide-IdentitySessionFactory"> + <title>IdentitySessionFactory</title> + <para> + IdentitySessionFactory interface is a main entry point into the API. Default implementation IdentitySessionFactoryImpl has two constructors: + </para> + <itemizedlist> + <listitem> + <para> + public IdentitySessionFactoryImpl(IdentityConfigurationMetaData configMD) throws Exception + </para> + + </listitem> + <listitem> + <para> + public IdentitySessionFactoryImpl(File configFile) throws Exception + </para> + + </listitem> + + </itemizedlist> + <para> + Framework configuration can be defined in two ways. It can be passed as implementation of a set of metadata interfaces grouped in org.picketlink.idm.spi.configuration.metadata package. Main one is IdentityConfigurationMetaData. + </para> + <para> + Other possibility is to use xml configuration file that will be unmarshaled into JAXB model (org.picketlink.idm.impl.configuration.jaxb2.generated package) and used to create IdentityConfigurationMetaData object. XML configuration is described by identity-config.xsd file. It is good to take a look at the example organization-test-config.xml that is used in the testsuite. + </para> +</section> + Added: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Configuration/IdentityStore.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Configuration/IdentityStore.xml (rev 0) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Configuration/IdentityStore.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -0,0 +1,148 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../../PicketLink_IDM_Reference_Guide.ent"> +%BOOK_ENTITIES; +]> +<section id="sect-PicketLink_IDM_Reference_Guide-IdentityStore"> + <title>IdentityStore</title> + <para> + This part is represented by <emphasis role="bold">&lt;stores&gt;&lt;identity-store&gt;...</emphasis> element + </para> + +<programlisting>&lt;stores&gt; + &lt;attribute-stores/&gt; + &lt;identity-stores&gt; + &lt;identity-store&gt; ... &lt;/identity-store&gt; + &lt;identity-store&gt; ... &lt;/identity-store&gt; + &lt;/identity-stores&gt; + &lt;/stores&gt;</programlisting> + <note> + <para> + <emphasis role="bold">&lt;stores/&gt;</emphasis> element contains <emphasis role="bold">&lt;identity-store&gt;</emphasis> and <emphasis role="bold">&lt;attribute-store&gt;</emphasis> elements. Currently <emphasis role="bold">&lt;attribute-store&gt;</emphasis> configuration is ignored so only <emphasis role="bold">&lt;identity-store&gt;</emphasis> elements can be configured. + </para> + + </note> + +<programlisting language="XML" role="XML"><xi:include href="../../extras/identity-store.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <para> + <emphasis role="bold">&lt;identity-store&gt;</emphasis> element: + </para> + <itemizedlist> + <listitem> + <para> + <emphasis role="bold">id</emphasis> - IdentityStore id + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">class</emphasis> - IdentityStore class name + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">external-config</emphasis> - external configuration file used by IdentityStore + </para> + + </listitem> + <listitem> + <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> + <emphasis role="bold">supported-identity-object-types</emphasis> - configuration of IdentityObjectType objects mapped by IdentityStore + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">options</emphasis> - other IdentityStore configuration options + </para> + + </listitem> + + </itemizedlist> + +<programlisting language="XML" role="XML"><xi:include href="../../extras/identity-object-type.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <para> + &lt;identity-object-type&gt; element: + </para> + <itemizedlist> + <listitem> + <para> + <emphasis role="bold">name</emphasis>- IdentityObjectType name + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">relationships</emphasis> - relationships in which IdentityObjectType can be parent side. <emphasis role="bold">&lt;relationship-type-ref&gt;</emphasis> must point to one of values from <emphasis role="bold">&lt;supported-relationship-types&gt;</emphasis> . <emphasis role="bold">&lt;identity-object-type-ref&gt;</emphasis> must be one of <emphasis role="bold">&lt;identity-object-type&gt;&lt;name&gt;</emphasis> values configured in this IdentityStore. + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">credentials</emphasis> - IdentityObjectCredentialType names allowed for this IdentityObjectType + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">attributes</emphasis> - allowed attribute mappings. Each contains: + <itemizedlist> + <listitem> + <para> + <emphasis role="bold">name</emphasis> - attribute name + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">mapping</emphasis> - real name to be used inside IdentityStore. For example LDAP attribute name + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">type</emphasis> - either "binary" or "text" value + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">isRequired</emphasis> - if attribute cannot have no values + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">isMultivalued</emphasis> - if attribute can have many values + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">isReadonly</emphasis> - if attribute values can be modified + </para> + + </listitem> + + </itemizedlist> + + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">options</emphasis> - other options for IdentityObjectType configuration + </para> + + </listitem> + + </itemizedlist> +</section> + Added: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Configuration/IdentityStoreRepository.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Configuration/IdentityStoreRepository.xml (rev 0) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Configuration/IdentityStoreRepository.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -0,0 +1,56 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../../PicketLink_IDM_Reference_Guide.ent"> +%BOOK_ENTITIES; +]> +<section id="sect-PicketLink_IDM_Reference_Guide-IdentityStoreRepository"> + <title>IdentityStoreRepository</title> + <para> + This section is represented by <emphasis role="bold"> &lt;repositories&gt;&lt;repository&gt;</emphasis> element + </para> + +<programlisting language="XML" role="XML"><xi:include href="../../extras/repositories.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <para> + <emphasis role="bold">&lt;repository&gt;</emphasis> element contains: + </para> + <itemizedlist> + <listitem> + <para> + <emphasis role="bold">id</emphasis> - IdentityStoreRepository id. + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">class</emphasis> - class name of IdentityStoreRepository implementation. + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">external-config</emphasis> - external configuration file used by IdentityStoreRepository. + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">default-identity-store-id</emphasis> - id of configured IdentityStore to be used by default. + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">default-attribute-store-id</emphasis> - id of configured AttributeStore (or IdentityStore) to be used by default + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">identity-store-mappings</emphasis> - optional element. Mappings between IdentityObjectType names and IdentityStore ids. + </para> + + </listitem> + + </itemizedlist> +</section> + Added: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Configuration/Realm.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Configuration/Realm.xml (rev 0) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Configuration/Realm.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -0,0 +1,54 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../../PicketLink_IDM_Reference_Guide.ent"> +%BOOK_ENTITIES; +]> +<section id="sect-PicketLink_IDM_Reference_Guide-Realm"> + <title>Realm</title> + <para> + This section is represented by <emphasis role="bold">&lt;realms&gt;&lt;realm&gt;</emphasis> element + </para> + +<programlisting>&lt;realm&gt; + &lt;id&gt;realm://RedHat/DB&lt;/id&gt; + &lt;repository-id-ref&gt;RedHat Repository DB&lt;/repository-id-ref&gt; + &lt;identity-type-mappings&gt; + &lt;identity-mapping&gt;IDENTITY&lt;/identity-mapping&gt; + &lt;/identity-type-mappings&gt; +&lt;/realm&gt;</programlisting> + <para> + <emphasis role="bold">&lt;realm&gt;</emphasis> element contains: + </para> + <itemizedlist> + <listitem> + <para> + <emphasis role="bold">id</emphasis> - realm id + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">repository-id-ref</emphasis> - id of configured IdentityStoreRepository + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">identity-type-mappings</emphasis> <itemizedlist> + <listitem> + <para> + <emphasis role="bold">identity-mapping</emphasis> - name of IdentityObjectType that should be maped as Identity object on the API side + </para> + + </listitem> + + </itemizedlist> + + </para> + + </listitem> + + </itemizedlist> + +</section> + Added: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Configuration/Realm_Templates.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Configuration/Realm_Templates.xml (rev 0) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Configuration/Realm_Templates.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -0,0 +1,51 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../../PicketLink_IDM_Reference_Guide.ent"> +%BOOK_ENTITIES; +]> +<section id="sect-PicketLink_IDM_Reference_Guide-Realm_Templates"> + <title>Realm Templates</title> + <para> + Realm can be marked as a template. This means that if a different realm name is requested using the API and such name contains template realm as a prefix then this realm configuration will be used + </para> + +<programlisting>&lt;realm&gt; + &lt;id&gt;idm_realm&lt;/id&gt; + &lt;repository-id-ref&gt;DefaultRepository&lt;/repository-id-ref&gt; + &lt;identity-type-mappings&gt; + &lt;user-mapping&gt;USER&lt;/user-mapping&gt; + &lt;/identity-type-mappings&gt; + &lt;options&gt; + &lt;option&gt; + &lt;name&gt;template&lt;/name&gt; + &lt;value&gt;true&lt;/value&gt; + &lt;/option&gt; + &lt;/options&gt; + &lt;/realm&gt;</programlisting> + <para> + In this example for "idm_realm_foo" framework will return "idm_realm" configuration. Request for "foo" realm won't return valid configuration. + </para> + +<programlisting>&lt;realms&gt; + &lt;realm&gt; + &lt;id&gt;idm_realm&lt;/id&gt; + &lt;repository-id-ref&gt;DefaultRepository&lt;/repository-id-ref&gt; + &lt;identity-type-mappings&gt; + &lt;user-mapping&gt;USER&lt;/user-mapping&gt; + &lt;/identity-type-mappings&gt; + + &lt;/realm&gt; + &lt;/realms&gt; + &lt;repositories&gt;...&lt;/repositories&gt; + &lt;stores&gt;...&lt;/stores&gt; + &lt;options&gt; + &lt;option&gt; + &lt;name&gt;defaultTemplate&lt;/name&gt; + &lt;value&gt;idm_realm&lt;/value&gt; + &lt;/option&gt; + &lt;/options&gt;</programlisting> + <para> + The "defaultTemplate" option defines idm_realm as the one that should be used when requested realm name is not found in configuration + </para> +</section> + Added: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Configuration/XML_Configuration.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Configuration/XML_Configuration.xml (rev 0) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Configuration/XML_Configuration.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -0,0 +1,41 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../../PicketLink_IDM_Reference_Guide.ent"> +%BOOK_ENTITIES; +]> +<section id="sect-PicketLink_IDM_Reference_Guide-XML_Configuration"> + <title>XML Configuration</title> + +<programlisting>&lt;jboss-identity xmlns="urn:jboss:identity:idm:config:v1_0_alpha" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="urn:jboss:identity:idm:config:v1_0_alpha identity-config.xsd"&gt; + &lt;realms/&gt; + &lt;repositories/&gt; + &lt;stores/&gt; +&lt;/jboss-identity&gt;</programlisting> + <para> + Identity XML configuration can be divided into three parts: + </para> + <itemizedlist> + <listitem> + <para> + <emphasis role="bold">&lt;stores/&gt;</emphasis> - defines IdentityStore and AttributeStore instances + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">&lt;repositories/&gt;</emphasis> - defines IdentityStoreRepository instances + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">&lt;realms/&gt;</emphasis> - defines identity realms + </para> + + </listitem> + + </itemizedlist> +</section> + Added: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Credentials/Credential_API.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Credentials/Credential_API.xml (rev 0) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Credentials/Credential_API.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -0,0 +1,66 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../../PicketLink_IDM_Reference_Guide.ent"> +%BOOK_ENTITIES; +]> +<section id="sect-PicketLink_IDM_Reference_Guide-Credential_API"> + <title>Credential API</title> + <para> + API contains Credential and CredentialType interfaces. CredentialType defines type of credential object. Default implementation supports two types: + </para> + <itemizedlist> + <listitem> + <para> + <emphasis role="bold">PASSWORD</emphasis> - text password represented by java.lang.String object + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">BINARY</emphasis> - binary credential represented by byte[]. For example some kind of certificate. + </para> + + </listitem> + + </itemizedlist> + <para> + Two basic implementations are provided: + </para> + <itemizedlist> + <listitem> + <para> + <emphasis role="bold">org.picketlink.idm.impl.api.BinaryCredential</emphasis> - Credential with BINARY CredentialType + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">org.picketlink.idm.impl.api.PasswordCredential</emphasis> - Credential with PASSWORD CredentialType + </para> + + </listitem> + + </itemizedlist> + <para> + Because credentials values are stored as hash or in other encoded form both SPI and API only enables to update and validate credential value and not to read it from persistence store. API enables to only protect Identity objects with credentials. All related management operations are exposed in AttributesManager interface. + </para> + +<programlisting role="Java"> +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> +</section> \ No newline at end of file Added: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Credentials/Credential_SPI.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Credentials/Credential_SPI.xml (rev 0) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Credentials/Credential_SPI.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -0,0 +1,29 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../../PicketLink_IDM_Reference_Guide.ent"> +%BOOK_ENTITIES; +]> +<section id="sect-PicketLink_IDM_Reference_Guide-Credential_SPI"> + <title>Credential SPI</title> + <para> + SPI contains IdentityObjectCredential and IdentityObjectCredentialType interfaces that correspons to Credential and CredentialType interfaces in the API. Implementation supports the same two (PASSWORD and BINARY) types. Management operations are exposed in IdentityStore interface. Each IdentityObjectType can be configured to support different IdentityObjectCredentialType. This information is exposed by FeaturesMetaData interface. + </para> + <para> + IdentityObjectCredential interface exposes two methods to retrieve credential value: + </para> + <itemizedlist> + <listitem> + <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> + <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> +</section> \ No newline at end of file Added: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Deployment/Deployment.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Deployment/Deployment.xml (rev 0) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Deployment/Deployment.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -0,0 +1,121 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../../PicketLink_IDM_Reference_Guide.ent"> +%BOOK_ENTITIES; +]> +<section id="sect-PicketLink_IDM_Reference_Guide-JBoss_AS_5_Deployment"> + <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>&lt;?xml version="1.0" encoding="UTF-8"?&gt; +&lt;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"&gt; + &lt;JNDIName&gt;java:/IdentitySessionFactory&lt;/JNDIName&gt; + &lt;idmConfigFile&gt;jboss.idm.cfg.xml&lt;/idmConfigFile&gt; + &lt;hibernateDeployer&gt; + &lt;hibernateConfiguration&gt;jboss.idm.hibernate.cfg.xml&lt;/hibernateConfiguration&gt; +&lt;hibernateSessionFactoryJNDIName&gt;java:/IDMHibernateSessionFactory&lt;/hibernateSessionFactoryJNDIName&gt; + &lt;/hibernateDeployer&gt; + &lt;initializers&gt; + &lt;datasource&gt;java:/jbossidmDS&lt;/datasource&gt; + &lt;sqlInitializer&gt; + &lt;sqlFile&gt;idm-sql/jboss.idm.@database@.create.sql&lt;/sqlFile&gt; + &lt;exitSQL&gt;select * from jbid_io&lt;/exitSQL&gt; + &lt;/sqlInitializer&gt; + &lt;/initializers&gt; +&lt;/jboss-idm-deployer&gt;</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> + +</section> \ No newline at end of file Added: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Deployment/Usage_Scenario.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Deployment/Usage_Scenario.xml (rev 0) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Deployment/Usage_Scenario.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -0,0 +1,37 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../../PicketLink_IDM_Reference_Guide.ent"> +%BOOK_ENTITIES; +]> +<section id="sect-PicketLink_IDM_Reference_Guide-IDM_Usage_Scenario"> + <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>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> +</section> \ No newline at end of file Added: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Design_and_Architecture/API_Model.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Design_and_Architecture/API_Model.xml (rev 0) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Design_and_Architecture/API_Model.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -0,0 +1,87 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../../PicketLink_IDM_Reference_Guide.ent"> +%BOOK_ENTITIES; +]> +<section id="sect-PicketLink_IDM_Reference_Guide-API_Model"> + <title>API Model</title> + <para> + The API operates on the identity model that is defined by the following set of interfaces: + </para> + <variablelist> + <title>API Interfaces</title> + <varlistentry> + <term>org.picketlink.idm.api.IdentityType</term> + <listitem> + <para> + This is a parent interface for Group and Identity. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>org.picketlink.idm.api.Identity</term> + <listitem> + <para> + This represents an Identity, which can be a user (within organization) or a machine (in authentication or security use case) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>org.picketlink.idm.api.Group</term> + <listitem> + <para> + This represents a Group. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>org.picketlink.idm.api.GroupType</term> + <listitem> + <para> + This represents type of a Group. It can be an organization, organization unit, administration group, global role, community or any other entity. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>org.picketlink.idm.api.Role</term> + <listitem> + <para> + This represents one to one relationship between Identity and Group. Role has a type. The idea behind the concept is described below. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>org.picketlink.idm.api.RoleType</term> + <listitem> + <para> + This represents type of a Role. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>org.picketlink.idm.api.Attribute</term> + <listitem> + <para> + This represents an attribute connected with <parameter>IdentityType</parameter> (Group or Identity). It can have many complex type values (text or binary). <parameter>AttributeDescription</parameter> describes such properties of Attribute like: name, type of values, readonly, multivalued, required. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>org.picketlink.idm.api.Credential</term> + <listitem> + <para> + This represents credentials connected with an Identity. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>org.picketlink.idm.api.CredentialType</term> + <listitem> + <para> + This represents type of a Credential. For example it can be text password or binary certificate. + </para> + </listitem> + </varlistentry> + </variablelist> +</section> + Added: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Design_and_Architecture/Architecture.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Design_and_Architecture/Architecture.xml (rev 0) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Design_and_Architecture/Architecture.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -0,0 +1,123 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../../PicketLink_IDM_Reference_Guide.ent"> +%BOOK_ENTITIES; +]> +<section id="sect-PicketLink_IDM_Reference_Guide-Architecture"> + <title>Architecture</title> + <para> + The most important part of architecture is a split between the API and the SPI. + </para> + <mediaobject> + <imageobject> + <imagedata contentdepth="6in" contentwidth="6in" fileref="images/IDM-api-spi.png" width="444" /> + </imageobject> + <caption align="right"> <para> + <emphasis role="bold">PicketLink IDM architecture</emphasis> + </para> + </caption> + </mediaobject> + <para> + API part contains of following interfaces: + </para> + <itemizedlist> + <listitem> + <para> + <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> + <emphasis role="bold">IdentitySessionFactory</emphasis> - Main entry point in the API. Enables to create/get IdentitySession for a given Realm + </para> + + </listitem> + <listitem> + <para> + <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> + <emphasis role="bold">PersistenceManager</emphasis> - Operates witin IdentitySession. Performs all operations on Identity and Group objects. Create/Remove/Find + </para> + + </listitem> + <listitem> + <para> + <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> + <emphasis role="bold">RoleManager</emphasis> - Operates witin IdentitySession. Operations on Role objects. Optional feature. + </para> + + </listitem> + <listitem> + <para> + <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> + <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> + SPI part contains of following interfaces + </para> + <itemizedlist> + <listitem> + <para> + <emphasis role="bold">IdentityStoreSession</emphasis> - Session that groups all identity management operations within identity persistence stores. + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">IdentityStoreSessionFactory</emphasis> - Entry point in the SPI to initialize IdentityStoreSession inside IdentityStore or AttributeStore. + </para> + + </listitem> + <listitem> + <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> + <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> + <emphasis role="bold">IdentityStore</emphasis> - Extends AttributeStore. Implementation of this interface performs operations on the real data store. + </para> + + </listitem> + <listitem> + <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> + <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> +</section> + Added: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Design_and_Architecture/Group_And_Roles.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Design_and_Architecture/Group_And_Roles.xml (rev 0) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Design_and_Architecture/Group_And_Roles.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -0,0 +1,27 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../../PicketLink_IDM_Reference_Guide.ent"> +%BOOK_ENTITIES; +]> +<section id="sect-PicketLink_IDM_Reference_Guide-Groups_and_Roles"> + <title>Groups and Roles</title> + <para> + Groups are entities that can contain other groups or identity objects which can be associated in tree-like organizational structures. These structures do not need to be hierarchical only, as a single group can be a member of many other groups (that is; a group can have many parents). + </para> + <para> + Possible relationships between groups are controlled with group types. Administrators can configure which different group types can be associated or even which group types can or can not contain identity objects. Groups have unique names per group type. This allows the existance of two groups with the same name, provided they have different group types. + </para> + <para> + Roles form connections between <emphasis>Identity</emphasis> and <emphasis>Group</emphasis> objects. A practical example of this is if we posit that user <emphasis role="bold">John</emphasis> is the <emphasis role="bold">Manager</emphasis> of <emphasis role="bold">XX Team"</emphasis>. In this example you can see how the role form the link between an Identity and a group; <emphasis role="bold">John</emphasis> (an <emphasis>Identity</emphasis>) is the <emphasis role="bold">Manager</emphasis> (a <emphasis>Role</emphasis>) of <emphasis role="bold">XX Team</emphasis> (a <emphasis>Group</emphasis>). + </para> + <para> + This type of information is difficult to map with typical Group objects as <emphasis>John</emphasis> can be a manager of several different groups. Futhermore, other identities (<emphasis>Mary</emphasis>, <emphasis>Jack</emphasis> or <emphasis>Stan</emphasis>) could have the same <emphasis>RoleType</emphasis> in different groups (<emphasis>XY Team</emphasis> or <emphasis>YY Team</emphasis>). + </para> + <para> + Within each Realm (the concept of Realms is described later) we can define several RoleType objects with unique names. Each Role defines a unique combination of Identity, Group and RoleType within a Realm. + </para> + <para> + The Role concept is very powerful but it does not fit easily into all identity store types. While quite easy to map in a relational database it does not fit into every LDAP tree present in organizations. Because of this Role support is optional in the API level + </para> +</section> + Added: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Design_and_Architecture/Main_Concepts.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Design_and_Architecture/Main_Concepts.xml (rev 0) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Design_and_Architecture/Main_Concepts.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -0,0 +1,93 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../../PicketLink_IDM_Reference_Guide.ent"> +%BOOK_ENTITIES; +]> +<section id="sect-PicketLink_IDM_Reference_Guide-Main_Concepts"> + <title>Main Concepts</title> + + <variablelist> + <title>Terms</title> + <varlistentry> + <term>PicketLink</term> + <listitem> + <para> + PicketLink is an umbrella project that aims to address different Identity Management needs. + </para> + <!--http://www.jboss.org/picketlink--> + </listitem> + </varlistentry> + <varlistentry> + <term>IDM</term> + <listitem> + <para> + IDM stands for <emphasis role="bold">ID</emphasis>entity <emphasis role="bold">M</emphasis>anagement. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Identity Management</term> + <listitem> + <para> + Identity management deals with the management of digital identities. Typically these identities are used to authenticate an organization's users so as to control access to organizational resources. However, other entities, including devices, processes and applications in a networked environment may be represtented in the identity model. + </para> + <!--http://download.oracle.com/docs/cd/B14099_19/core.1012/b13995/glossary.htm#sthref2905--> + <!--http://download.oracle.com/docs/cd/B14099_19/idmanage.1012/b14080/glossary.htm#sthref2905--> + + </listitem> + </varlistentry> + <varlistentry> + <term>API</term> + <listitem> + <para> + An <emphasis role="bold">A</emphasis>pplication <emphasis role="bold">P</emphasis>rogramming <emphasis role="bold">I</emphasis>nterface (<emphasis role="bold">API</emphasis>) is a set of specifications that allow applications that use the same API to communicate and share data. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>SPI</term> + <listitem> + <para> + An <emphasis role="bold">S</emphasis>ervice <emphasis role="bold">P</emphasis>rovider <emphasis role="bold">I</emphasis>nterface (<emphasis role="bold">SPI</emphasis>) is the set of specifications that a service defines. + </para> + <!--http://www.developer.com/java/article.php/3848881/Service-Provider-Interface-Creating-Extensible-Java-Applications.htm--> + </listitem> + </varlistentry> + </variablelist> + <para> + PicketLink IDM aims to provide a common identity model for various JBoss projects. As every project has specific needs, designing a common API and identity model that will fit all of them can be difficult. Therefore the PicketLink IDM architecture consists of two main parts: + </para> + <variablelist> + <title></title> + <varlistentry> + <term>Core SPI</term> + <listitem> + <para> + The PicketLink <emphasis role="bold">SPI</emphasis> uses an abstract identity model that provides the flexibility for defining different identity object types and possible relationships between them. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Common API</term> + <listitem> + <para> + The PcketLink <emphasis role="bold">API</emphasis> uses a simpler identity model that fits most common use cases. Identity model has more strictly defined object types and possible relationships. + </para> + </listitem> + </varlistentry> + </variablelist> + + <mediaobject> + <imageobject role="html"> + <imagedata fileref="images/IDM-global-arch.png" format="PNG" align="center"/> + </imageobject> + <imageobject role="fo"> + <imagedata fileref="images/IDM-global-arch.png" format="PNG" align="center" width="120mm"/> + </imageobject> + </mediaobject> + <para> + Too much abstraction in the API layer would confuse people using the framework. One of the goals is to make the design easily extendible. Framework adopters should be able to remove the API layer and reuse core SPI implementation if needed. + </para> + +</section> + Added: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Design_and_Architecture/Realms.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Design_and_Architecture/Realms.xml (rev 0) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Design_and_Architecture/Realms.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -0,0 +1,22 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../../PicketLink_IDM_Reference_Guide.ent"> +%BOOK_ENTITIES; +]> +<section id="sect-PicketLink_IDM_Reference_Guide-Realms"> + <title>Realms</title> + <para> + The purpose of a Realm is to group configuration of several identity stores. IdentitySession exposes operations within single Realm + </para> + <mediaobject> + <imageobject> + <imagedata contentdepth="6in" contentwidth="6in" fileref="images/IDM-global-realm.png" width="444" /> + </imageobject> + <caption align="right"> <para> + <emphasis role="bold">PicketLink IDM architecture</emphasis> + </para> + </caption> + </mediaobject> + +</section> + Added: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Design_and_Architecture/SPI_Model.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Design_and_Architecture/SPI_Model.xml (rev 0) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Design_and_Architecture/SPI_Model.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -0,0 +1,61 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../../PicketLink_IDM_Reference_Guide.ent"> +%BOOK_ENTITIES; +]> +<section id="sect-PicketLink_IDM_Reference_Guide-SPI_Abstract_Model"> + <title>SPI (Abstract) Model</title> + <para> + SPI Model contains following interfaces: + </para> + <itemizedlist> + <listitem> + <para> + <emphasis role="bold">org.picketlink.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> + <emphasis role="bold">org.picketlink.idm.spi.model.IdentityObjectType</emphasis> - represents identity object type. Name of IdentityType is unique. + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">org.picketlink.idm.spi.model.IdentityObjectAttribute</emphasis> - attribute assigned to IdentityObject + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">org.picketlink.idm.spi.model.IdentityObjectCredential</emphasis> - credential assigned to IdentityObject + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">org.picketlink.idm.spi.model.IdentityObjectCredentialType</emphasis> - represents type of IdentityObjectCredential. + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">org.picketlink.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> + <emphasis role="bold">org.picketlink.idm.spi.model.IdentityObjectRelationshipType</emphasis> - named type of relationship + </para> + + </listitem> + + </itemizedlist> + <para> + Model described above is very flexible as IdentityObjectType is able to map any kind of entities. Identity object and Group/GroupType objects are only one of many possible options (API is a subset of SPI possibilities). IdentityObjectRelationship defines a connection between any two IdentityObject objects. Each IdentityObjectRelationship has a type. To map previously described API two IdentityObjectRelationshipType objects are needed. One to map normal MEMBERSHIP like between an Identity and a Group or Group and Group objects. Second one to map Role concept. For API Role - RoleType refers to the name of the IdentityObjectRelationship. In default Hibernate implementation possible names of IdentityObjectRelationship are kept in a separate table. All of those can be easily redefined to support different kind of API. + </para> + +</section> + Added: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/IdentityStoreRepository_Implementations/FallbackIdentityStoreRepository.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/IdentityStoreRepository_Implementations/FallbackIdentityStoreRepository.xml (rev 0) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/IdentityStoreRepository_Implementations/FallbackIdentityStoreRepository.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -0,0 +1,50 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../../PicketLink_IDM_Reference_Guide.ent"> +%BOOK_ENTITIES; +]> +<section id="sect-PicketLink_IDM_Reference_Guide-FallbackIdentityStoreRepository"> + <title>FallbackIdentityStoreRepository</title> + <section id="sect-PicketLink_IDM_Reference_Guide-FallbackIdentityStoreRepository-ClassName"> + <title>ClassName</title> + <para> + org.picketlink.idm.impl.repository.FallbackIdentityStoreRepository + </para> + + </section> + + <section id="sect-PicketLink_IDM_Reference_Guide-FallbackIdentityStoreRepository-Behaviour"> + <title>Behaviour</title> + <para> + Resolves proper IdentityStore from IdentityObjectType mapping and delegates method invocation. For relationship related methods, if both IdentityObjectTypes are not mapped in one store, repository will try to sync them and associate in defaultIdentityStore. For attributes that are not mapped inside mapped IdentityStore repository will try to assign those attributes in defaultAttributeStore. + </para> + + </section> + + <section id="sect-PicketLink_IDM_Reference_Guide-FallbackIdentityStoreRepository-Configuration_Options"> + <title>Configuration Options</title> + <itemizedlist> + <listitem> + <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> + + </listitem> + + </itemizedlist> + + </section> + + <section id="sect-PicketLink_IDM_Reference_Guide-FallbackIdentityStoreRepository-Sample_Configuration"> + <title>Sample Configuration</title> + +<programlisting language="XML" role="XML"><xi:include href="../../extras/sample_config3.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <para> + The <emphasis role="bold">readOnly</emphasis> options specifies that the only write operation performed on the store will be password update. + </para> + + </section> + + +</section> + Added: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/IdentityStoreRepository_Implementations/WrapperIdentityStoreRepository.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/IdentityStoreRepository_Implementations/WrapperIdentityStoreRepository.xml (rev 0) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/IdentityStoreRepository_Implementations/WrapperIdentityStoreRepository.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -0,0 +1,39 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../../PicketLink_IDM_Reference_Guide.ent"> +%BOOK_ENTITIES; +]> +<section id="sect-PicketLink_IDM_Reference_Guide-WrapperIdentityStoreRepository"> + <title>WrapperIdentityStoreRepository</title> + <section id="sect-PicketLink_IDM_Reference_Guide-WrapperIdentityStoreRepository-ClassName"> + <title>ClassName</title> + <para> + org.picketlink.idm.impl.repository.WrapperIdentityStoreRepository + </para> + + </section> + + <section id="sect-PicketLink_IDM_Reference_Guide-WrapperIdentityStoreRepository-Behaviour"> + <title>Behaviour</title> + <para> + Simply wraps single AttributeStore and IdentityStore and pass all method invocations + </para> + + </section> + + <section id="sect-PicketLink_IDM_Reference_Guide-WrapperIdentityStoreRepository-Sample_Configuration"> + <title>Sample Configuration</title> + +<programlisting>&lt;repository&gt; + &lt;id&gt;Sample Repository&lt;/id + &lt;class&gt;org.picketlink.idm.impl.repository.WrapperIdentityStoreRepository&lt;/class&gt; + &lt;external-config/&gt; + &lt;default-identity-store-id&gt;LDAP Store&lt;/default-identity-store-id&gt; + &lt;default-attribute-store-id&gt;LDAP Store&lt;/default-attribute-store-id&gt; +&lt;/repository&gt;</programlisting> + + </section> + + +</section> + Added: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/IdentityStore_Implementations/Hibernate_IdentityStore.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/IdentityStore_Implementations/Hibernate_IdentityStore.xml (rev 0) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/IdentityStore_Implementations/Hibernate_IdentityStore.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -0,0 +1,119 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../../PicketLink_IDM_Reference_Guide.ent"> +%BOOK_ENTITIES; +]> +<section id="sect-PicketLink_IDM_Reference_Guide-Hibernate_IdentityStore"> + <title>Hibernate IdentityStore</title> + <section id="sect-PicketLink_IDM_Reference_Guide-Hibernate_IdentityStore-Class_Name"> + <title>Class Name</title> + <para> + org.picketlink.idm.impl.store.hibernate.HibernateIdentityStoreImpl + </para> + + </section> + + <section id="sect-PicketLink_IDM_Reference_Guide-Hibernate_IdentityStore-Overview"> + <title>Overview</title> + <para> + HibernateIdentityStoreImpl maps PicketLink IDM SPI model into Hibernate entities. This enables to use any RDBMS supported by Hibernate as identity persistence store (IdentityStore). Because of flexibility that ORM gives this IdentityStore implementation support all of the optional design concepts like role management. It can be used as the default IdentityStore together with other more limited implementations. For example in combination with LDAP IdentityStore it can handle IdentityObject attributes that are not supported in LDAP schema. In such configuration part of IdentityObject profile will be stored in LDAP and part in relational database. To learn more about such setup please read FallbackIdentityStoreRepository documentation. In current version implementation doesn't have any caching mechanism besides of what can be set in hibernate configuration + </para> + + </section> + + <section id="sect-PicketLink_IDM_Reference_Guide-Hibernate_IdentityStore-Configuration_Options"> + <title>Configuration Options</title> + <para> + <itemizedlist> + <listitem> + <para> + <emphasis role="bold">hibernateConfiguration</emphasis> - the hibernate configuration file that will be used to create SessionFactory + </para> + + </listitem> + <listitem> + <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">addHibernateMappings</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 &lt;supported-relationship-types&gt; (IdentityObjectRelationshipType in SPI model) during IdentityStore initialization. Default value is 'false' + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">populateIdentityObjectTypes</emphasis> - true/false - Populate configured &lt;supported-identity-object-types&gt; (IdentityObjectType in SPI model) during IdentityStore initialization. Default value is 'false' + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">allowNotDefinedAttributes</emphasis> - true/false - Allow to set IdentityObject attributes that are not specified in &lt;identity-object-type&gt; configuration. Such attributes are assumed to have "text" type and many values. Default value is 'false'. + </para> + + </listitem> + <listitem> + <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> + <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> + + </section> + + <section id="sect-PicketLink_IDM_Reference_Guide-Hibernate_IdentityStore-Sample_Configuration"> + <title>Sample Configuration</title> + +<programlisting language="XML" role="XML"><xi:include href="../../extras/sample_config.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <para> + In case 'addHibernateMappings' option is not set to true hibernate configuration need to list all annotated model classes: + </para> + +<programlisting>&lt;mapping resource="mappings/HibernateRealm.hbm.xml"/&gt; +&lt;mapping resource="mappings/HibernateIdentityObjectCredentialBinaryValue.hbm.xml"/&gt; +&lt;mapping resource="mappings/HibernateIdentityObjectAttributeBinaryValue.hbm.xml"/&gt; +&lt;mapping resource="mappings/HibernateIdentityObject.hbm.xml"/&gt; +&lt;mapping resource="mappings/HibernateIdentityObjectCredential.hbm.xml"/&gt; +&lt;mapping resource="mappings/HibernateIdentityObjectCredentialType.hbm.xml"/&gt; +&lt;mapping resource="mappings/HibernateIdentityObjectAttribute.hbm.xml"/&gt; +&lt;mapping resource="mappings/HibernateIdentityObjectType.hbm.xml"/&gt; +&lt;mapping resource="mappings/HibernateIdentityObjectRelationship.hbm.xml"/&gt; +&lt;mapping resource="mappings/HibernateIdentityObjectRelationshipType.hbm.xml"/&gt; +&lt;mapping resource="mappings/HibernateIdentityObjectRelationshipName.hbm.xml"/&gt;</programlisting> + + </section> + + +</section> + Added: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/IdentityStore_Implementations/LDAP_IdentityStore.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/IdentityStore_Implementations/LDAP_IdentityStore.xml (rev 0) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/IdentityStore_Implementations/LDAP_IdentityStore.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -0,0 +1,239 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../../PicketLink_IDM_Reference_Guide.ent"> +%BOOK_ENTITIES; +]> +<section id="sect-PicketLink_IDM_Reference_Guide-LDAP_IdentityStore"> + <title>LDAP IdentityStore</title> + <section id="sect-PicketLink_IDM_Reference_Guide-LDAP_IdentityStore-Class_Name"> + <title>Class Name</title> + <para> + org.picketlink.idm.impl.store.ldap.LDAPIdentityStoreImpl + </para> + + </section> + + <section id="sect-PicketLink_IDM_Reference_Guide-LDAP_IdentityStore-Overview"> + <title>Overview</title> + <para> + LDAPIdentityStoreImpl provides support for LDAP as identity persistence store (IdentityStore). At this stage the implementation is a bit limitted: + </para> + <itemizedlist> + <listitem> + <para> + Role management (IdentityObjectRelationshipName) is not supported + </para> + + </listitem> + <listitem> + <para> + Only "text" attribute type can be mapped + </para> + + </listitem> + <listitem> + <para> + Only "PASSWORD" &lt;credential-type&gt; can be mapped + </para> + + </listitem> + + </itemizedlist> + + </section> + + <section id="sect-PicketLink_IDM_Reference_Guide-LDAP_IdentityStore-Configuration"> + <title>Configuration</title> + <para> + &lt;identity-object-type&gt;&lt;options&gt; + </para> + <itemizedlist> + <listitem> + <para> + <emphasis role="bold">idAttributeName</emphasis> - attribute name under which IdentityObject name is specified. Required. + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">passwordAttributeName</emphasis> - attribute name under which IdentityObject password is specified. Optional. + </para> + + </listitem> + <listitem> + <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> + <emphasis role="bold">allowCreateEntry</emphasis> - true/false - Specify if new IdentityObject can be created. + </para> + + </listitem> + <listitem> + <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> + <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> + <emphasis role="bold">isParentMembershipAttributeDN</emphasis> - defines if values of attribute defined in parentMembershipAttributeName are fully qualified LDAP DNs. + </para> + + </listitem> + <listitem> + <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> + <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">entrySearchScope</emphasis> - defines a search scope. Values can be "subtree" and "object" + </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> + <emphasis role="bold">&lt;identity-store&gt;&lt;options&gt;</emphasis> + </para> + <itemizedlist> + <listitem> + <para> + <emphasis role="bold">providerURL</emphasis> - LDAP connection URL. For example "ldap://localhost:389" + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">adminDN</emphasis> - LDAP entry used to connect to the server. + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">adminPassword</emphasis> - password related to adminDN + </para> + + </listitem> + <listitem> + <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> + <listitem> + <para> + <emphasis role="bold">sortExtensionSupported</emphasis> - if set to "false" will disable the use of sort extension that triggers sort on LDAP server side + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">pagedResultsExtensionSupported</emphasis> - if set to "true" will enable paged search. Searches that exceed size defined by "pagedResultsExtensionSize" option will be splitted into few smaller ones. + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">pagedResultsExtensionSize</emphasis> - defines page size for "pagedResultsExtensionSupported" option. + </para> + + </listitem> + <listitem> + <para> + <emphasis role="bold">createMissingContexts</emphasis> - if set to "true" LDAP store will try to create missing LDAP contexts defined in the configuration. + </para> + + </listitem> + + </itemizedlist> + + </section> + + <section id="sect-PicketLink_IDM_Reference_Guide-LDAP_IdentityStore-Sample_Configuration"> + <title>Sample Configuration</title> + +<programlisting language="XML" role="XML"><xi:include href="../../extras/sample_config2.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + + </section> + + +</section> + Added: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/IdentityStore_Implementations/Minimal_Configuration.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/IdentityStore_Implementations/Minimal_Configuration.xml (rev 0) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/IdentityStore_Implementations/Minimal_Configuration.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -0,0 +1,15 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../../PicketLink_IDM_Reference_Guide.ent"> +%BOOK_ENTITIES; +]> +<section id="sect-PicketLink_IDM_Reference_Guide-Minimal_Configuration"> + <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 language="XML" role="XML"><xi:include href="../../extras/lazy-config.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + +</section> + Added: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Quick_Start/Core_Files.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Quick_Start/Core_Files.xml (rev 0) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Quick_Start/Core_Files.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -0,0 +1,22 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../../PicketLink_IDM_Reference_Guide.ent"> +%BOOK_ENTITIES; +]> +<section id="sect-PicketLink_IDM_Reference_Guide-Core_Files"> + <title>Core 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 language="XML" role="XML"><xi:include href="../../extras/idm-config.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <para> + <emphasis role="bold">hibernate.cfg.xml</emphasis> - hibernate SessionFactory setup + </para> + +<programlisting language="XML" role="XML"><xi:include href="../../extras/hibernate.cfg.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> +</section> + Added: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Quick_Start/Examples.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Quick_Start/Examples.xml (rev 0) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Quick_Start/Examples.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -0,0 +1,36 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../../PicketLink_IDM_Reference_Guide.ent"> +%BOOK_ENTITIES; +]> +<section id="sect-PicketLink_IDM_Reference_Guide-Examples"> + <title>Examples</title> + <para> + As PicketLink IDM is a Maven2 based project it is very easy to leverage it from this build system. There is a ready to use Maven2 example project in the svn. It contains three sample test cases for with following configurations: + </para> + <itemizedlist> + <listitem> + <para> + database setup + </para> + + </listitem> + <listitem> + <para> + LDAP setup + </para> + + </listitem> + <listitem> + <para> + mixed LDAP + database setup + </para> + + </listitem> + + </itemizedlist> + <para> + Sample project uses embedded OpenDS and HSQLDB so there is no need for any additional setup to be able to play with the API. + </para> +</section> + Added: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Quick_Start/Test_Cases.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Quick_Start/Test_Cases.xml (rev 0) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/Quick_Start/Test_Cases.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -0,0 +1,12 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../../PicketLink_IDM_Reference_Guide.ent"> +%BOOK_ENTITIES; +]> +<section id="sect-PicketLink_IDM_Reference_Guide-Test_Cases"> + <title>Test Cases</title> + <para> + One of the best ways to get familiar with the PicketLink 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 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> +</section> + Added: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/chap_Attributes.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/chap_Attributes.xml (rev 0) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/chap_Attributes.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -0,0 +1,11 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../PicketLink_IDM_Reference_Guide.ent"> +%BOOK_ENTITIES; +]> + +<chapter> + <title>Attributes</title> + <xi:include href="Attributes/API.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Attributes/SPI.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> +</chapter> \ No newline at end of file Added: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/chap_Concepts_API_SPI.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/chap_Concepts_API_SPI.xml (rev 0) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/chap_Concepts_API_SPI.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -0,0 +1,13 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../PicketLink_IDM_Reference_Guide.ent"> +%BOOK_ENTITIES; +]> + +<chapter> + <title>Concepts behind API to SPI mappings</title> + <xi:include href="Concepts_API_SPI/Introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Concepts_API_SPI/User_and_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Concepts_API_SPI/Associations.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Concepts_API_SPI/Role.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> +</chapter> \ No newline at end of file Added: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/chap_Configuration.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/chap_Configuration.xml (rev 0) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/chap_Configuration.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -0,0 +1,16 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../PicketLink_IDM_Reference_Guide.ent"> +%BOOK_ENTITIES; +]> + +<chapter> + <title>Configuration</title> + <xi:include href="Configuration/IdentitySessionFactory.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Configuration/XML_Configuration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Configuration/IdentityStore.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Configuration/IdentityStoreRepository.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Configuration/Realm.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Configuration/Realm_Templates.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Configuration/API_Cache.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> +</chapter> \ No newline at end of file Added: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/chap_Credentials.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/chap_Credentials.xml (rev 0) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/chap_Credentials.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -0,0 +1,11 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../PicketLink_IDM_Reference_Guide.ent"> +%BOOK_ENTITIES; +]> + +<chapter> + <title>Credentials</title> + <xi:include href="Credentials/Credential_API.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Credentials/Credential_SPI.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> +</chapter> \ No newline at end of file Added: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/chap_Deployment.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/chap_Deployment.xml (rev 0) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/chap_Deployment.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -0,0 +1,11 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../PicketLink_IDM_Reference_Guide.ent"> +%BOOK_ENTITIES; +]> + +<chapter> + <title>Deployment</title> + <xi:include href="Deployment/Usage_Scenario.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Deployment/Deployment.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> +</chapter> \ No newline at end of file Added: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/chap_Design_and_Architecture.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/chap_Design_and_Architecture.xml (rev 0) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/chap_Design_and_Architecture.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -0,0 +1,16 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../PicketLink_IDM_Reference_Guide.ent"> +%BOOK_ENTITIES; +]> + +<chapter> + <title>Design and Architecture</title> + <xi:include href="Design_and_Architecture/Main_Concepts.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Design_and_Architecture/API_Model.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Design_and_Architecture/Group_And_Roles.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <!--Edited to here.--> + <xi:include href="Design_and_Architecture/SPI_Model.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Design_and_Architecture/Architecture.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Design_and_Architecture/Realms.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> +</chapter> \ No newline at end of file Added: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/chap_IdentityStoreRepository_Implementations.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/chap_IdentityStoreRepository_Implementations.xml (rev 0) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/chap_IdentityStoreRepository_Implementations.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -0,0 +1,11 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../PicketLink_IDM_Reference_Guide.ent"> +%BOOK_ENTITIES; +]> + +<chapter> + <title>IdentityStoreRepository Implementations</title> + <xi:include href="IdentityStoreRepository_Implementations/WrapperIdentityStoreRepository.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="IdentityStoreRepository_Implementations/FallbackIdentityStoreRepository.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> +</chapter> \ No newline at end of file Added: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/chap_IdentityStore_Implementations.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/chap_IdentityStore_Implementations.xml (rev 0) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/chap_IdentityStore_Implementations.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -0,0 +1,12 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../PicketLink_IDM_Reference_Guide.ent"> +%BOOK_ENTITIES; +]> + +<chapter> + <title>IdentityStore Implementations</title> + <xi:include href="IdentityStore_Implementations/Hibernate_IdentityStore.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="IdentityStore_Implementations/LDAP_IdentityStore.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="IdentityStore_Implementations/Minimal_Configuration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> +</chapter> \ No newline at end of file Added: epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/chap_Quick_Start.xml =================================================================== --- epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/chap_Quick_Start.xml (rev 0) +++ epp/docs/branches/5.2/PicketLink_IDM_Reference_Guide/en-US/modules/chap_Quick_Start.xml 2011-08-29 07:26:00 UTC (rev 7244) @@ -0,0 +1,12 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../PicketLink_IDM_Reference_Guide.ent"> +%BOOK_ENTITIES; +]> + +<chapter> + <title>Quick Start</title> + <xi:include href="Quick_Start/Test_Cases.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Quick_Start/Examples.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Quick_Start/Core_Files.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> +</chapter> \ No newline at end of file