Identify tenancy information

Before you can modify your configuration for multi-tenant applications, you need to identify how tenancy information (grouping) is determined in your environment for the individual users. Then, you associate the tenancy information to specific multitenancy properties. To identify tenancy information, you can use the position of a user within a hierarchy, or you can use the properties associated with user objects. You can also create custom code that is invoked during the user authentication process.

Use hierarchies to determine tenancy information

One way to determine tenancy information is to reuse the node structure information within a hierarchy.

When reusing the node structure information, you can use the information provided by the ancestors user attribute, which represents the hierarchical path to a user account in the form of an array. The following table shows how you could map the ancestors attribute to a hierarchy to identify the tenancy information:

Table 1. Ancestors attribute mapped to hierarchy information
Ancestors information	Hierarchy	LDAP example
`ancestors[0]`	Directory node
`ancestors[1]`	Namespace ID	`base DN`
`ancestors[2]`	Tenant grouping, such as folders	`organizational units`

For example, if users are stored in an LDAP directory and tenants are directly under the base Distinguished Name (DN) as organizational units, set the multitenancy.TenantPattern advanced property to the following value:

multitenancy.TenantPattern = ~/ancestors[2]/defaultName

Note: In addition to defaultName, the following ancestors qualifiers can return tenancy information:

name/locale, where locale is based on the mapping in the namespace configuration. If no locale is given, the name is the title of the object. For example, you could specify: multitenancy.TenantPattern = ~/ancestors[2]/name/EN-ca.
searchPath/objectID. For example, you could specify: multitenancy.TenantPattern = ~/ancestors[2]/searchPath/objectId.

Use object attributes to determine tenancy information

If you cannot use the node structure hierarchy to determine the tenancy information, you can use specific object attributes from your authentication provider. This method requires that you also identify any additional properties to be queried during the user authentication process.

For example, if the departmentNumber attribute of an LDAP user object identifies the user’s tenant, set the multitenancy.TenantPattern and the AdditionalUserPropertiesToQuery advanced properties as follows:

multitenancy.TenantPattern = ~/parameters/parameter_name
AdditionalUserPropertiesToQuery = parameters

In this example, you must also set the following LDAP custom property:

parameter_name = departmentNumber

Use custom code to determine tenancy information

When the tenancy information cannot be obtained through a hierarchy or a user attribute, you must create a custom class that is invoked during the user authentication process to determine the tenancy information. For example, you might need to join data from multiple authentication sources, or from an authentication source and a relational database.

In such cases, you create a custom Java class using the IBM® Cognos® Software Development Kit and specify its name during the BI configuration. In this scenario, set the multitenancy.ITenantProvider property as follows:

multitenancy.ITenantProvider = custom_class_name

where custom_class_name represents the name of your custom class, for example, com.example.Class.

IBM Cognos Software Development Kit includes a sample custom class to determine tenancy information. You can find the sample files in the c10_location\sdk\java\AuthenticationProvider\MultiTenancyTenantProviderSample directory.