4.5. PicketLink IDM integration

GateIn 3.5 uses the PicketLink IDM component to keep the necessary identity information, such as users, groups, memberships. While the legacy interfaces are still used (org.exoplatform.services.organization) for identity management, there is a wrapper implementation that delegates to the PicketLink IDM framework.

This section does not provide information about PicketLink IDM and its configuration. See here for further information.

Note

It is important to fully understand the concepts behind this framework design before changing the default configuration.

The identity model represented in 'org.exoplatform.services.organization' interfaces and the one used in PicketLink IDM have some major differences.

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.

For example: PicketLink IDM provides greater abstraction. It is possible for groups in IDM framework to form memberships with many parents (which requires recursive ID translation), while the GateIn model allows only pure tree-like membership structures.

Additionally, the GateIn membership concept needs to be translated into the IDM Role concept. Therefore, the PicketLink IDM model is used in a limited way. All these translations are applied by the integration layer.

Configuration files

The main configuration file is idm-configuration.xml:


<configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

               xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd http://www.exoplaform.org/xml/ns/kernel_1_0.xsd"

               xmlns="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd">

 

   <component>

        <key>org.exoplatform.services.organization.idm.PicketLinkIDMService</key>

      <type>org.exoplatform.services.organization.idm.PicketLinkIDMServiceImpl</type>

      <init-params>

         <value-param>

            <name>config</name>

            <value>war:/conf/organization/idm-config.xml</value>

         </value-param>

         <value-param>

            <name>portalRealm</name>

            <value>realm${container.name.suffix}</value>

         </value-param>

       </init-params>

   </component>

 

   <component>

      <key>org.exoplatform.services.organization.OrganizationService</key>

      <type>org.exoplatform.services.organization.idm.PicketLinkIDMOrganizationServiceImpl</type>

      <init-params>

      <object-param>

        <name>configuration</name>

        <object type="org.exoplatform.services.organization.idm.Config">

          <field name="useParentIdAsGroupType">

            <boolean>true</boolean>

          </field>

 

          <field name="forceMembershipOfMappedTypes">

            <boolean>true</boolean>

          </field>

 

          <field name="pathSeparator">

            <string>.</string>

          </field>

 

          <field name="rootGroupName">

            <string>GTN_ROOT_GROUP</string>

          </field>

 

          <field name="groupTypeMappings">

            <map type="java.util.HashMap">

              <entry>

                <key><string>/</string></key>

                <value><string>root_type</string></value>

              </entry>

 

              <!-- Sample mapping -->

              <!--

              <entry>

                <key><string>/platform/*</string></key>

                <value><string>platform_type</string></value>

              </entry>

              <entry>

                <key><string>/organization/*</string></key>

                <value><string>organization_type</string></value>

              </entry>

              -->

 

            </map>

          </field>

 

          <field name="associationMembershipType">

            <string>member</string>

          </field>

 

          <field name="ignoreMappedMembershipType">

            <boolean>false</boolean>

          </field>

        </object>

      </object-param>

    </init-params>

   </component>

 

</configuration>

PicketlinkIDMServiceImpl

The org.exoplatform.services.organization.idm.PicketLinkIDMServiceImpl service has the following options:

config (value-param): The PicketLink IDM configuration file.
hibernate.properties (properties-param): A list of hibernate properties used to create SessionFactory that will be injected to Picketlink IDM configuration registry.
hibernate.annotations: A list of annotated classes that will be added to Hibernate configuration.
hibernate.mappings: A list of .xml files that will be added to the hibernate configuration as mapping files.
jndiName (value-param): If the 'config' parameter is not provided, this parameter will be used to perform the JNDI lookup for IdentitySessionFactory.
portalRealm (value-param): The realm name that should be used to obtain the proper IdentitySession. The default is 'PortalRealm'.
apiCacheConfig (value-param): The infinispan configuration file with cache configuration for Picketlink IDM API. It is different for cluster and non-cluster because infinispan needs to be replicated in the cluster environment.
storeCacheConfig (value-param): The infinispan configuration file with cache configuration for Picketlink IDM IdentityStore. Actually it is used only for LDAP store (not used with default DB configuration). It is different for cluster and non-cluster because infinispan needs to be replicated in the cluster environment.

PicketLinkIDMOrganizationServiceImpl

The org.exoplatform.services.organization.idm.PicketLinkIDMOrganizationServiceImpl key is a main entrypoint implementing org.exoplatform.services.organization.OrganizationService and is dependent on org.exoplatform.services.organization.idm.PicketLinkIDMService.

The org.exoplatform.services.organization.idm.PicketLinkIDMOrganizationServiceImpl service has the following options defined as fields of object-param of type org.exoplatform.services.organization.idm.Config:

defaultGroupType: The name of the PicketLink IDM GroupType that will be used to store groups. The default is 'GTN_GROUP_TYPE'.
rootGroupName: The name of the PicketLink IDM Group that will be used as a root parent. The default is 'GTN_ROOT_GROUP'
passwordAsAttribute: 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.
useParentIdAsGroupType: 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 GateIn 3.5 group tree.
pathSeparator: 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.
associationMembershipType: 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.
groupTypeMappings: This parameter maps groups added with GateIn 3.5 API as children of a given group ID, and stores them with a given group type name in PicketLink IDM.
If the parent ID ends with "/*", all child groups will have the mapped group type. Otherwise, only direct (first level) children will use this type.
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 GateIn 3.5 group tree, while all other groups will remain in the database.
forceMembershipOfMappedTypes: 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.
This parameter can be set to false if all groups are added via GateIn 3.5 APIs. This may be useful with the LDAP configuration when being set to true, it will make every entry added to LDAP appear in GateIn 3.5. This, however, is not true for entries added via GateIn 3.5 management UI.
ignoreMappedMembershipType: 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.

Additionally, PicketlinkIDMOrganizationServiceImpl uses those defaults to perform identity management operations.

GateIn 3.5 User interface properties fields are persisted in Picketlink IDM using those attributes names: firstName, lastName, email, createdDate, lastLoginTime, organizationId, password (if password is configured to be stored as attribute).
GateIn 3.5 Group interface properties fields are persisted in Picketlink IDM using those attributes names: label, description.
GateIn 3.5 MembershipType interface properties fields are persisted in Picketlink IDM using those RoleType properties: description, owner, create_date, modified_date.

A sample PicketLink IDM configuration file is shown below. To understand all the options it contains, please refer to the PicketLink IDM Reference Guide.


<jboss-identity xmlns="urn:jboss:identity:idm:config:v1_0_beta"

                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

                xsi:schemaLocation="urn:jboss:identity:idm:config:v1_0_alpha identity-config.xsd">

    <realms>

        <realm>

            <id>PortalRealm</id>

            <repository-id-ref>PortalRepository</repository-id-ref>

            <identity-type-mappings>

                <user-mapping>USER</user-mapping>

            </identity-type-mappings>

        </realm>

    </realms>

    <repositories>

        <repository>

            <id>PortalRepository</id>

            <class>org.jboss.identity.idm.impl.repository.WrapperIdentityStoreRepository</class>

            <external-config/>

            <default-identity-store-id>HibernateStore</default-identity-store-id>

            <default-attribute-store-id>HibernateStore</default-attribute-store-id>

        </repository>

    </repositories>

    <stores>

        <attribute-stores/>

        <identity-stores>

            <identity-store>

                <id>HibernateStore</id>

                <class>org.jboss.identity.idm.impl.store.hibernate.HibernateIdentityStoreImpl</class>

                <external-config/>

                <supported-relationship-types>

                    <relationship-type>JBOSS_IDENTITY_MEMBERSHIP</relationship-type>

                    <relationship-type>JBOSS_IDENTITY_ROLE</relationship-type>

                </supported-relationship-types>

                <supported-identity-object-types>

                    <identity-object-type>

                        <name>USER</name>

                        <relationships/>

                        <credentials>

                            <credential-type>PASSWORD</credential-type>

                        </credentials>

                        <attributes/>

                        <options/>

                    </identity-object-type>

                </supported-identity-object-types>

                <options>

                    <option>

                        <name>hibernateSessionFactoryRegistryName</name>

                        <value>hibernateSessionFactory</value>

                    </option>

                    <option>

                        <name>allowNotDefinedIdentityObjectTypes</name>

                        <value>true</value>

                    </option>

                    <option>

                        <name>populateRelationshipTypes</name>

                        <value>true</value>

                    </option>

                    <option>

                        <name>populateIdentityObjectTypes</name>

                        <value>true</value>

                    </option>

                    <option>

                        <name>allowNotDefinedAttributes</name>

                        <value>true</value>

                    </option>

                    <option>

                        <name>isRealmAware</name>

                        <value>true</value>

                    </option>

                    <option>

                        <name>lazyStartOfHibernateTransaction</name>

                        <value>true</value>

                    </option>

                </options>

            </identity-store>

        </identity-stores>

    </stores>

</jboss-identity>

See also