<?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 PicketLink IDM component to keep the necessary identity information (users, groups, memberships, etc.).
      While legacy interfaces are still used (org.exoplatform.services.organization) for identity management,
      there is a wrapper implementation that delegates to PicketLink IDM framework.
	</para>
	<para>
		This section doesn&#39;t 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>TODO: tell more about org.exoplatform.services.organization</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 GateIn model allows only pure tree-like membership structures.
	</para>
	<para>
		Additionally, GateIn <emphasis>membership</emphasis> concept needs to be translated into the IDM <emphasis>Role</emphasis> concept. Therefore <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>&#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 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 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 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 PicketLink IDM Credential object or as a plain attribute. The default is 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', then 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 to be used in group type name in PicketLink IDM.
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>associationMembershipType</term>
							<listitem>
								<para>
									If this option is used, then each Membership, created with MembrshipType that is equal to the value specified here, will be stored in PicketLink IDM as 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 "/*", then all child groups will have the mapped group type. Otherwise, only direct (first level) children will use this type. 
								</para>
								<para>
									This can be leveraged by LDAP if LDAP DN is configured in PicketLink IDM to only store a specific group type. This will then store the given branch in &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. Group relationships linked by 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 LDAP configuration as, when 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, then 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 role="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>


