<?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 "../../Reference_Guide.ent">
%BOOK_ENTITIES;
]>
<section id="sect-Reference_Guide-PicketLink_IDM_integration">
	<title>PicketLink IDM integration</title>
	<para>
		&PRODUCT; uses the PicketLink IDM component to keep the necessary identity information, such as users, groups, memberships.
      While legacy interfaces are still used (org.exoplatform.services.organization) for identity management,
      there is a wrapper implementation that delegates to the PicketLink IDM framework.
	</para>
	<para>
		This section does not provide information about PicketLink IDM and its configuration. Please refer to the appropriate project documentation (<ulink url="http://jboss.org/picketlink/IDM.html" />) for further information.
	</para>
	<note>
		<para>
			It is important to fully understand the concepts behind this framework design before changing the default configuration.
		</para>
	</note>
	<para>
		The identity model represented in &#39;<emphasis role="bold">org.exoplatform.services.organization</emphasis>&#39; interfaces and the one used in <emphasis role="bold">PicketLink IDM</emphasis> have some major differences.
	</para>
   <para>The org.exoplatform.services.organization interface stores and manages information of users, groups or memberships, user profiles, relationships and retrieval. The management of org.exoplatform.services.organization interface is divided into many layers, such as model object, data access object and authentication.</para>
	<para>
		For example: <emphasis role="bold">PicketLink IDM</emphasis> provides greater abstraction. It is possible for groups in <emphasis role="bold">IDM</emphasis> framework to form memberships with many parents (which requires recursive ID translation),
      while the GateIn model allows only pure tree-like membership structures.
	</para>
	<para>
		Additionally, the GateIn <emphasis>membership</emphasis> concept needs to be translated into the IDM <emphasis>Role</emphasis> concept. Therefore, the <emphasis role="bold">PicketLink IDM</emphasis> model is used in a limited way. All these translations are applied by the integration layer.
	</para>
	<section id="sect-Reference_Guide-PicketLink_IDM_integration-Configuration_files">
		<title>Configuration files</title>
		<para>
			The main configuration file is <emphasis role="bold">idm-configuration.xml</emphasis>:
		</para>
		<programlistingco>
			<areaspec>
				<area coords="5" id="area-Reference_Guide-PicketLink_IDM_integration-Configuration_files-JBossIDMServiceImpl" />
				<area coords="22" id="area-Reference_Guide-PicketLink_IDM_integration-Configuration_files-JBossIDMOrganizationServiceImpl" />
			</areaspec>
<programlisting language="xml">&#60;configuration xmlns:xsi=&#34;http://www.w3.org/2001/XMLSchema-instance&#34;
               xsi:schemaLocation=&#34;http://www.exoplaform.org/xml/ns/kernel_1_0.xsd http://www.exoplaform.org/xml/ns/kernel_1_0.xsd&#34;
               xmlns=&#34;http://www.exoplaform.org/xml/ns/kernel_1_0.xsd&#34;&#62;
 
   &#60;component&#62;
        &#60;key&#62;org.exoplatform.services.organization.idm.PicketLinkIDMService&#60;/key&#62;
      &#60;type&#62;org.exoplatform.services.organization.idm.PicketLinkIDMServiceImpl&#60;/type&#62;
      &#60;init-params&#62;
         &#60;value-param&#62;
            &#60;name&#62;config&#60;/name&#62;
            &#60;value&#62;war:/conf/organization/idm-config.xml&#60;/value&#62;
         &#60;/value-param&#62;
         &#60;value-param&#62;
            &#60;name&#62;portalRealm&#60;/name&#62;
            &#60;value&#62;realm${container.name.suffix}&#60;/value&#62;
         &#60;/value-param&#62;
       &#60;/init-params&#62;
   &#60;/component&#62;
 
 
   &#60;component&#62;
      &#60;key&#62;org.exoplatform.services.organization.OrganizationService&#60;/key&#62;
      &#60;type&#62;org.exoplatform.services.organization.idm.PicketLinkIDMOrganizationServiceImpl&#60;/type&#62;
      &#60;init-params&#62;
      &#60;object-param&#62;
        &#60;name&#62;configuration&#60;/name&#62;
        &#60;object type="org.exoplatform.services.organization.idm.Config"&#62;
          &#60;field name="useParentIdAsGroupType"&#62;
            &#60;boolean&#62;true&#60;/boolean&#62;
          &#60;/field&#62;
 
          &#60;field name="forceMembershipOfMappedTypes"&#62;
            &#60;boolean&#62;true&#60;/boolean&#62;
          &#60;/field&#62;
 
          &#60;field name="pathSeparator"&#62;
            &#60;string&#62;.&#60;/string&#62;
          &#60;/field&#62;
 
          &#60;field name="rootGroupName"&#62;
            &#60;string&#62;GTN_ROOT_GROUP&#60;/string&#62;
          &#60;/field&#62;
 
          &#60;field name="groupTypeMappings"&#62;
            &#60;map type="java.util.HashMap"&#62;
              &#60;entry&#62;
                &#60;key&#62;&#60;string&#62;/&#60;/string&#62;&#60;/key&#62;
                &#60;value&#62;&#60;string&#62;root_type&#60;/string&#62;&#60;/value&#62;
              &#60;/entry&#62;
 
              &#60;!-- Sample mapping --&#62;
              &#60;!--
              &#60;entry&#62;
                &#60;key&#62;&#60;string&#62;/platform/*&#60;/string&#62;&#60;/key&#62;
                &#60;value&#62;&#60;string&#62;platform_type&#60;/string&#62;&#60;/value&#62;
              &#60;/entry&#62;
              &#60;entry&#62;
                &#60;key&#62;&#60;string&#62;/organization/*&#60;/string&#62;&#60;/key&#62;
                &#60;value&#62;&#60;string&#62;organization_type&#60;/string&#62;&#60;/value&#62;
              &#60;/entry&#62;
              --&#62;
 
            &#60;/map&#62;
          &#60;/field&#62;
 
          &#60;field name="associationMembershipType"&#62;
            &#60;string&#62;member&#60;/string&#62;
          &#60;/field&#62;
 
          &#60;field name="ignoreMappedMembershipType"&#62;
            &#60;boolean&#62;false&#60;/boolean&#62;
          &#60;/field&#62;
        &#60;/object&#62;
      &#60;/object-param&#62;
    &#60;/init-params&#62;
 
 
   &#60;/component&#62;
 
&#60;/configuration&#62;
</programlisting>
			<calloutlist>
				<callout arearefs="area-Reference_Guide-PicketLink_IDM_integration-Configuration_files-JBossIDMServiceImpl">
					<para>
						The <emphasis role="bold">org.exoplatform.services.organization.idm.PicketLinkIDMServiceImpl</emphasis> service has the following options:
					</para>
					<variablelist>
					<varlistentry>
						<term>config</term>
						<listitem>
							<para>
								(value-param)
							</para>
							<para>
								PicketLink IDM configuration file
							</para>
						</listitem>
					</varlistentry>
					<varlistentry>
						<term>hibernate.properties</term>
						<listitem>
							<para>
								(properties-param)
							</para>
							<para>
								A list of hibernate properties used to create SessionFactory that will be injected to JBoss Identity IDM configuration registry.
							</para>
						</listitem>
					</varlistentry>
					<varlistentry>
						<term>hibernate.annotations</term>
						<listitem>
							<para>
								A list of annotated classes that will be added to Hibernate configuration.
							</para>
						</listitem>
					</varlistentry>
					<varlistentry>
						<term>hibernate.mappings</term>
						<listitem>							
							<para>
								A list of .xml files that will be added to the hibernate configuration as mapping files.
							</para>
						</listitem>
					</varlistentry>
					<varlistentry>
						<term>jndiName</term>
						<listitem>
							<para>
								(value-param)
							</para>
							<para>
								If the &#39;config&#39; parameter is not provided, this parameter will be used to perform the JNDI lookup for IdentitySessionFactory.
							</para>
						</listitem>
					</varlistentry>
					<varlistentry>
						<term>portalRealm</term>
						<listitem>
							<para>
								(value-param)
							</para>
							<para>
								The realm name that should be used to obtain the proper IdentitySession. The default is &#39;PortalRealm&#39;.
							</para>
						</listitem>
					</varlistentry>
					</variablelist>
				</callout>
				<callout arearefs="area-Reference_Guide-PicketLink_IDM_integration-Configuration_files-JBossIDMOrganizationServiceImpl">
					<para>
						The <emphasis role="bold">org.exoplatform.services.organization.idm.PicketLinkIDMOrganizationServiceImpl</emphasis>
            key is a main entrypoint implementing <emphasis role="bold">org.exoplatform.services.organization.OrganizationService</emphasis>
            and is dependant on <emphasis role="bold">org.exoplatform.services.organization.idm.PicketLinkIDMService</emphasis>
					</para>
					<para>
						<emphasis role="bold">org.exoplatform.services.organization.idm.PicketLinkIDMOrganizationServiceImpl</emphasis>
            service has the following options defined as fields of object-param of type
            <emphasis role="bold">org.exoplatform.services.organization.idm.Config</emphasis>:
					</para>
      					<variablelist>
					<varlistentry>
						<term>defaultGroupType</term>
						<listitem>
							<para>
								The name of the PicketLink IDM GroupType that will be used to store groups. The default is &#39;GTN_GROUP_TYPE&#39;.
							</para>
						</listitem>
					</varlistentry>
					<varlistentry>
						<term>rootGroupName</term>
							<listitem>
								<para>
									 The name of the PicketLink IDM Group that will be used as a root parent. The default is &#39;GTN_ROOT_GROUP&#39;
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>passwordAsAttribute</term>
							<listitem>
								<para>
									This parameter specifies if a password should be stored using the PicketLink IDM Credential object or as a plain attribute. The default value is set to false.
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>useParentIdAsGroupType</term>
							<listitem>
							<para>
								This parameter stores the parent ID path as a group type in PicketLink IDM for any IDs not mapped with a specific type in 'groupTypeMappings'.
                        If this option is set to false, and no mappings are provided under 'groupTypeMappings', only one group with the given name can exist in the &PRODUCT; group tree.
							</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>pathSeparator</term>
							<listitem>
								<para>
									When 'userParentIdAsGroupType' is set to true, this value will be used to replace all "/" characters in IDs. The "/" character is not allowed in the group type name in PicketLink IDM.
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>associationMembershipType</term>
							<listitem>
								<para>
									If this option is used, each Membership created with MembrshipType that is equal to the value specified here, will be stored in PicketLink IDM as the simple Group-User association.
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>groupTypeMappings</term>
							<listitem>
								<para>
									This parameter maps groups added with &PRODUCT; API as children of a given group ID, and stores them with a given group type name in PicketLink IDM.
								</para>
								<para>
									If the parent ID ends with "/*", all child groups will have the mapped group type. Otherwises, only direct (first level) children will use this type. 
								</para>
								<para>
									This can be leveraged by LDAP if the LDAP DN is configured in PicketLink IDM to only store a specific group type. This will then store the given branch in the &PRODUCT; group tree, while all other groups will remain in the database.
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>forceMembershipOfMappedTypes</term>
							<listitem>
								<para>
									Groups stored in PicketLink IDM with a type mapped in 'groupTypeMappings' will automatically be members under the mapped parent. The Group relationships linked by the PicketLink IDM group association will not be necessary.
								</para>
								<para>
									This parameter can be set to false if all groups are added via &PRODUCT; APIs. This may be useful with the LDAP configuration when being set to true, it will make every entry added to LDAP appear in &PRODUCT;. This, however, is not true for entries added via &PRODUCT; management UI.
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>ignoreMappedMembershipType</term>
							<listitem>
								<para>
									If "associationMembershipType" option is used, and this option is set to true, Membership with MembershipType configured to be stored as PicketLink IDM association will not be stored as PicketLink IDM Role.
								</para>
							</listitem>
						</varlistentry>
  				</variablelist>
					<para>
						Additionally, <emphasis role="bold">JBossIDMOrganizationServiceImpl</emphasis> uses those defaults to perform identity management operations.
					</para>
					<itemizedlist>
						<listitem>
							<para>
								&PRODUCT; User interface properties fields are persisted in JBoss Identity IDM using those attributes names: firstName, lastName, email, createdDate, lastLoginTime, organizationId, password (if password is configured to be stored as attribute).
							</para>
						</listitem>
						<listitem>
							<para>
								&PRODUCT; Group interface properties fields are persisted in JBoss Identity IDM using those attributes names: label, description.
							</para>
						</listitem>
						<listitem>
							<para>
								&PRODUCT; MembershipType interface properties fields are persisted in JBoss Identity IDM using those RoleType properties: description, owner, create_date, modified_date.
							</para>
						</listitem>
					</itemizedlist>
				</callout>
			</calloutlist>
		</programlistingco>
		

		<para>
			A sample <emphasis role="bold">PicketLink IDM</emphasis> configuration file is shown below. To understand all the options it contains, please refer to the PicketLink IDM Reference Guide.
		</para>
		
<programlisting language="xml">&#60;jboss-identity xmlns=&#34;urn:jboss:identity:idm:config:v1_0_beta&#34;
                xmlns:xsi=&#34;http://www.w3.org/2001/XMLSchema-instance&#34;
                xsi:schemaLocation=&#34;urn:jboss:identity:idm:config:v1_0_alpha identity-config.xsd&#34;&#62;
    &#60;realms&#62;
        &#60;realm&#62;
            &#60;id&#62;PortalRealm&#60;/id&#62;
            &#60;repository-id-ref&#62;PortalRepository&#60;/repository-id-ref&#62;
            &#60;identity-type-mappings&#62;
                &#60;user-mapping&#62;USER&#60;/user-mapping&#62;
            &#60;/identity-type-mappings&#62;
        &#60;/realm&#62;
    &#60;/realms&#62;
    &#60;repositories&#62;
        &#60;repository&#62;
            &#60;id&#62;PortalRepository&#60;/id&#62;
            &#60;class&#62;org.jboss.identity.idm.impl.repository.WrapperIdentityStoreRepository&#60;/class&#62;
            &#60;external-config/&#62;
            &#60;default-identity-store-id&#62;HibernateStore&#60;/default-identity-store-id&#62;
            &#60;default-attribute-store-id&#62;HibernateStore&#60;/default-attribute-store-id&#62;
        &#60;/repository&#62;
    &#60;/repositories&#62;
    &#60;stores&#62;
        &#60;attribute-stores/&#62;
        &#60;identity-stores&#62;
            &#60;identity-store&#62;
                &#60;id&#62;HibernateStore&#60;/id&#62;
                &#60;class&#62;org.jboss.identity.idm.impl.store.hibernate.HibernateIdentityStoreImpl&#60;/class&#62;
                &#60;external-config/&#62;
                &#60;supported-relationship-types&#62;
                    &#60;relationship-type&#62;JBOSS_IDENTITY_MEMBERSHIP&#60;/relationship-type&#62;
                    &#60;relationship-type&#62;JBOSS_IDENTITY_ROLE&#60;/relationship-type&#62;
                &#60;/supported-relationship-types&#62;
                &#60;supported-identity-object-types&#62;
                    &#60;identity-object-type&#62;
                        &#60;name&#62;USER&#60;/name&#62;
                        &#60;relationships/&#62;
                        &#60;credentials&#62;
                            &#60;credential-type&#62;PASSWORD&#60;/credential-type&#62;
                        &#60;/credentials&#62;
                        &#60;attributes/&#62;
                        &#60;options/&#62;
                    &#60;/identity-object-type&#62;
                &#60;/supported-identity-object-types&#62;
                &#60;options&#62;
                    &#60;option&#62;
                        &#60;name&#62;hibernateSessionFactoryRegistryName&#60;/name&#62;
                        &#60;value&#62;hibernateSessionFactory&#60;/value&#62;
                    &#60;/option&#62;
                    &#60;option&#62;
                        &#60;name&#62;allowNotDefinedIdentityObjectTypes&#60;/name&#62;
                        &#60;value&#62;true&#60;/value&#62;
                    &#60;/option&#62;
                    &#60;option&#62;
                        &#60;name&#62;populateRelationshipTypes&#60;/name&#62;
                        &#60;value&#62;true&#60;/value&#62;
                    &#60;/option&#62;
                    &#60;option&#62;
                        &#60;name&#62;populateIdentityObjectTypes&#60;/name&#62;
                        &#60;value&#62;true&#60;/value&#62;
                    &#60;/option&#62;
                    &#60;option&#62;
                        &#60;name&#62;allowNotDefinedAttributes&#60;/name&#62;
                        &#60;value&#62;true&#60;/value&#62;
                    &#60;/option&#62;
                    &#60;option&#62;
                        &#60;name&#62;isRealmAware&#60;/name&#62;
                        &#60;value&#62;true&#60;/value&#62;
                    &#60;/option&#62;
                &#60;/options&#62;
            &#60;/identity-store&#62;
        &#60;/identity-stores&#62;
    &#60;/stores&#62;
&#60;/jboss-identity&#62;
</programlisting>
	</section>

</section>


