The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
Service Catalog Directory Integration simplifies security administration and enhances user convenience and productivity by implementing centralized user authentication and synchronization with an enterprise directory.
Service Catalog enables customers to integrate with an external directory (typically using the LDAP protocol) for user information synchronization. This synchronization is invoked whenever a user is selected for Order-on-behalf (OOB) or during Person Lookup.
Single Sign-On (SSO) integration enables centralized user authentication, eliminating the need for a separate login mechanism. When the SSO event is enabled, users who are already logged in to an enterprise portal with which Service Catalog has been integrated do not have to login again. Service Catalog relies on the SSO tool to protect all Service Catalog URLs and to perform authentication. Service Catalog requires that the SSO tool provide person identification information for each successful authentication to a Service Catalog URL via the HTTP header or cgi header. Once a person has been authenticated, their information can be synchronized to the application database.
If SSO is not enabled, then the Service Catalog login screen is presented to all users so they can provide a valid username and password combination. By default, these credentials are authenticated against the internal database. Alternatively, Directory Integration could be configured to authenticate to an external system (generally an LDAP directory). Users who wish to access Service Catalog must be present in this source for successful authentication.
The Directory Integration Framework provides the above capabilities for many frequently deployed SSO and directory server products through configuration options available in the Administration module. The framework also includes an application programming interface (API) which can supplement predefined configuration capabilities. The API allows programmers to access additional SSO portals and directory servers, as well as to alter or supplement default behavior for synchronizing user information between Service Catalog and the external directory.
This chapter describes how to configure directory integration for Service Catalog using the Administration module. It also describes the set of public APIs and interfaces available for customizing the integration options available, best practices for compiling and deploying custom code, and steps to configure the custom code using the Administration module.
Configuring directory integration requires the following:
Note Access to an LDAP browser is strongly recommended.
To configure directory integration, you need to have handy information about the current implementation of SSO (if used) and directory servers at your company, and to document the requirements for integrating these systems with Service Catalog. This section provides a set of worksheets for collecting this information.
These worksheets should help you collect the information required to configure directory/SSO integration, and to identify issues which need to be resolved before the integration can be implemented. This, in turn, can help in estimating the amount of development and testing time required for the directory integration.
Service Catalog defines a “datasource” for each directory which stores personnel and organization data to be accessed. The datasource definition includes all information required to connect to the external directory and extracting information from that directory.
You will need to define one datasource for each external directory. For example, different development and production directories may be used. In addition, Service Catalog supports LDAP directory referrals—a datasource needs to be defined for each directory in the referral chain.
The name of the datasource. Do not use spaces or special characters. |
||
LDAP is the only supported protocol at this time. If directory information is stored using another protocol, you need to create custom code to access this information. |
||
Choose the directory server product you are using. If the server is not currently supported, you will need to create custom code to access the server and extract directory information. |
||
Simple means plain text user/password. SASL (Simple Authentication and Security Layer) is also available, but SASL only works with Sun ONE Directory Server. |
||
Only needed if you choose Simple or SASL as the authentication method. |
||
Bind distinguished name field. BindDN is used to connect to the LDAP server when Service Catalog performs a directory operation. You may want to create a service account for this purpose. When this datasource is used in an External Authentication step, you will provide an EUA Bind DN in the Options area to override this value. For more details, see the External User Authentication (EUA) Operation. |
||
Required if you choose Simple or SASL authentication; the password for the user specified as the Bind DN. If the account uses password aging, you will need to update this password periodically. |
||
Fully qualified domain name or IP address of the LDAP directory server. |
||
Port number to connect to the directory server. Port Number 389 is typically used for non-SSL access. |
||
The directory from which to start searching for persons in the directory; since corporate directories may include many branches, specifying a base DN for the user data will optimize directory searches. |
||
This filter are added to other search filters you use, and it can be used to effectively change the search results. The filter expression must be enclosed in parentheses; for example, the filter: (&(!(msExchHide=true)(ISC-GID=*))) will return only those entries for which the msExchHide attribute is true and for which an ISC-GID attribute is defined. |
||
Required if you choose SSL as the connection mechanism. Do not use spaces or special characters in the certificate alias name. |
||
You can add one or more datasources as a referral. When a datasource search does not return results, the system searches the referral datasources as well. Referrals are supported for searches only, not binding. You cannot set up cyclic referrals. Cyclic referrals are those where one datasource has another datasource as a referral, while that datasource has the original as a referral. For example, datasource A has datasource B as a referral, while datasource B has datasource A as a referral. |
A “mapping” is a set of rules that gives instructions for how data is to be transferred from the external directory to Service Catalog. It maps between source attributes in the directory and target fields in the Service Catalog database. The rules are used to transfer data from the directory to the designated target field when the Service Catalog database is synchronized with the directory.
The same mapping can be applied to multiple directories (datasources).
A mapping includes the user/person’s profile along with all related entities: addresses, contacts, locations, one or more group associations, one or more organizational unit (OU) associations, and one or more RBAC (role-based access control) role associations.
A person profile includes seven mandatory fields, listed in the “Mandatory” section of the Mapping Worksheet below. Directory records which do not provide a value for any of these fields cannot be imported. Other fields which are part of the person profile can also be mapped. For more information, see People section, in Organization Designer chapter of Cisco Prime Service Catalog Administration and Operations Guide .
Most of the fields on the person profile are used to drive the Service Catalog functionality, and the mapping should ensure that mapped attributes provide a source value appropriate for the field; that is, do not try to overload these fields with more information than would be suggested by the field name, or with information that does not match the field name.
Service Catalog also includes fields which provide an extension to the standard personnel data. These fields are denoted as “Extension” on the following table and appear on the Extensions page of the Person information in Organization Designer. Some of the most frequently required extended fields have been assigned meaningful names (such as Company Code and Division), but others have the names Custom 1 through Custom 10, and are intended to be freely used, with no preconceived semantics. If you have additional personnel information in the LDAP directory that needs to be exposed in Service Catalog, map the attributes containing that information to one of the personnel extended fields.
The “Directory Attribute” column in the worksheet below should be filled in for all Person profile fields for which the directory must supply data. The Attribute should be one of the following:
The return type of the LDAP attribute being mapped must return a long. Service Catalog does not support other formats. |
|
The return type of the LDAP attribute being mapped must return a long. Service Catalog does not support other formats. |
|
The mapped attribute must return a value in one of the following formats: As of the March 2008, the familiar three-letter time zone designations (for example, “EST” for Eastern Standard Time) should not be used. For a list of supported values for the above formats, see the Supported Time Zones. If the return value does not match one of the valid formats, Service Catalog uses PST as the default time zone. |
|
The mapped attribute must return a value in the form: where language is a two-letter language code and the country is a two-letter country code. |
|
This field represents the identification of manager. For more details, see the Import Manager Operation. |
|
This should return a number. When used with the Import Manager event, Management Level is expected to be in increasing order according to the hierarchy. For example, if there are two designations, Junior Engineer and Senior Engineer, Management Level returned for Junior Engineer should be less than the Management Level of Senior Engineer. |
|
Use this mapping to associate the person with one or more Organizational Units. The mapping may return multiple values. For this field Service Catalog uses all values returned by multivalued LDAP attributes. Input for this field should be in one of the following formats:
|
|
Similar to Organizational Unit List. The returned roles may be either system- or user-defined. For system-defined roles, the names must be exactly as they appear in a browser with language US English. Other languages are not supported. For example, “My Services Executive” should be returned to associate a user with this role. For user-defined roles, the name must exactly match the user input in user language while creating the role. |
Integration events are the interfaces between Service Catalog and an external directory or SSO program—the only times in the use of Service Catalog that the external program or directory is accessed. These events consist of a series of operations which are executed in sequence.
Service Catalog supports four directory integration events:
– Person Lookup for Order on Behalf : A user requests a service on behalf of another person, and must choose the person who is the customer for the service.
– Person Lookup for Service Form : A service form includes a Person field, which allows the user to designate another person as part of the service data.
– Person Lookup for Authorization Delegate : A user responsible for reviewing or authorizing service requests modifies his/her profile to designate another person as a temporary authorization delegate.
You can configure events to perform various types of operations. The operations are specified for each event in a series of steps, which determines the sequence in which each operation in invoked.
The directory framework includes the following operations:
Each operation can be customized via implementation of custom code interfaces.
Trigger Order below shows the sequence in which operations are triggered.
If a directory integration login event is not configured, the default behavior is to present the login screen and validate the credentials entered (user name and password) against the contents of the application database.
If the directory integration event is enabled, the Login event may be configured with either one of the following operations as its first step:
If EUA is enabled and both Username and Password is passed , an LDAP authentication is triggered. The Password provided must be the LDAP Password and LDAP user owns the session..
Once the user credentials have been validated, the Login event may include additional operations to synchronize user data between the external datasource and Service Catalog:
Integration with Single Sign-On (SSO) solutions can use one of the following two mechanisms/protocols:
1. Active Directory Services (ADS)/NT LAN Manager (NTLM)-based authenticated user
– The third-party IM/AM/SSO product is not needed to log into Service Catalog.
– The logged in user credentials from any POSIX-compliant OS are returned by the browser to Service Catalog.
– This is also called integration through CGI Headers for SSO.
– This is for non-ADS/NTLM integration.
– It requires the third-party IM/AM/SSO product to log into Service Catalog using RequestHeaders in the http protocol.
For customers who plan to use SSO for both Portlet and Directory Integration, only HTTP Header SSO is supported. Custom SSO plug-ins within the Directory Integration framework are not supported.
It is sometimes necessary to allow some users to bypass the Single Sign-On and login directly to Service Catalog. This capability is typically required for:
Service Catalog provides a mechanism for allowing users to access the login screen and enter a user name and password. The newscale.properties file (located within the RequestCenter.war) specifies a value for the “BackDoorURLParam”; for example:
The URL used to access Service Catalog via the login screen must include a parameter. For the above value of the backDoorURLParam; for example, a sample URL might be:
<app_server_port> is the port number of application server.
It is the responsibility of the administrator to establish policies for aging out the value of the BackDoorURLParam according to corporate guidelines and for controlling administrative access to Service Catalog. Access via the administrative URL can be restricted to only those users who have the “Site Administrator” role via the corresponding Administration Setting:
Figure 8-2 Administration Setting
The administrator must also ensure that the URL is directly accessible to users—access to the Service Catalog application may have previously been restricted to the SSO software via web server or network configuration parameters.
The Service Catalog service must be restarted for a change to this parameter to take effect.
Use External Authentication to authenticate all Service Catalog users with a corporate directory. This way you do not have to worry about synchronizing user passwords.
External User Authentication must follow a login attempt—either via a configured Single Sign-On operation or through the application login screen. The LoginId retrieved from the previous operation is available to the EUA operation. However, validating this user in the external directory requires additional information, so that the BindDN can be located.
The EUABindDN setting allows the application to automatically extrapolate the bind DN of the user trying to sign on.
All Person Lookup events (Order on Behalf, Service Form, and Authorization Delegate) share the same behavior and configuration options.
If the directory integration event is not enabled, the Person Search window searches personnel information in the Service Catalog database. If a person is selected, their information is used. Personnel information is not updated.
If the directory integration event is enabled, the Person Lookup event may be configured with the following operations:
Settings for the Person Search operation determine the appearance and behavior of the window that displays people meeting the search criteria.
In order for a person to be imported into Service Catalog, all mandatory fields must have a valid attribute mapping, which returns in a nonblank value. If any required values are missing, the default behavior is to exclude that person from the Search Results. The alternative is to include such people in the Search Results, and flag them as having incomplete information.
People with incomplete information cannot be chosen.
When configuring and testing a Person Search, you need to be aware of the use of the asterisk (*) as a wildcard character.
Transparent to the user, the system always appends an * to the end of the search string. Therefore, if a user enters john in the Last Name field, and clicks Search , the system returns all persons in the directory whose last name begins with the word john, such as “John”, “Johnson”, and “Johnston”.
A user may also explicitly enter the * character in the search string of the Search Person dialog box. Some examples of the usage for wildcard search are:
Note The * is always treated as a wildcard character in the search string. Therefore, the user is NOT able to search for a value in the directory that contains the character *. Any other special characters may be used in the search string.
By default, the Search Results window in the Select Person Popup displays the person's first name followed by the last name. Additional fields can be added to the display by changing the Setting for the Person Popup available in the Administration module.
Import Person settings govern whether person information in the application is refreshed from current information about the selected person (when Import Person is used in a Person Search event) or the person who has logged in (when Import Person is used in a Login event).
Service Catalog allows authorizations and reviews to be dynamically assigned. For example, a request with a dollar value greater than a specified threshold might need approval by the director of a particular department. Another request might need to be reviewed by the requestor's immediate superior.
To implement business rules like these, the managers of an employee who can request a service must also be present in the Service Catalog database. The Import Manager operation supports this requirement, importing manager (supervisor) data in conjunction with the employee's data.
To govern the behavior of the Import Manager operation:
In one possible scenario, a single attribute exists in each person's directory record which uniquely identifies the person's supervisor. Assume, for example, that the person's directory record contains the manager’s email ID within the attribute manager_email . No other manager information is present.
An alternative scenario may be that the directory record contains an attribute that is exactly the DN of the person's supervisor. Assume the name of this attribute is manager .
Supervisory hierarchies may also need to be accommodated.
For example, consider this organizational chart:
Figure 8-4 Organizational Chart
If requests were subject to an immediate supervisor’s approval, a “relative” search is needed, going up the tree one level.
Alternatively, if certain requests were subject to, for example, a Director’s approval, an “absolute” search is needed. People (managers) would be imported until the position of the current person was “Director”. In the example above, in the case of S. Person, two additional people would be needed—her immediate manager, A. Name, and his manager, J. Doe, who is their Director. For T. Tom, only one import would be required.
If you are using an absolute search (import all managers with successively higher levels of authority until you find one with the specified position), you must assign numeric equivalents to the positions:
You may configure a search terminator if you do not want to synchronize supervisors beyond a known value. You can specify multiple values in the format: #value1#, #value2# and so on.
For example, you may not want to import any supervisors who rank above a person with uid as “scarter.” His Supervisor attribute is mapped to his email (scarter@email.com). In this case set the Search Terminator to #scarter@email.com#. The directory integration will stop supervisor synchronization as soon as a record is found with scarter@email.com as the supervisor.
Supervisor synchronization stops as soon as either limiting condition is met—Maximum Level or Search Terminator.
Create a file jboss-web.xml with the following contents in the directory ServiceCatalogServer/RequestCenter.war/'WEB-INF'.
Note You must add this after </context-param>, and before the filters.
Modify standalone-full.xml, add a security domain:
Note You must search for security–domains and add the following contents below it.
Note For Cluster, you should create jboss-web.xml and should modify the web.xml in the directory C:\Install_dir\dist\RequestCenter.war, for more information see Cisco Prime Service Catalog 11.1.1, section Applying Patch or Customizations to the WildFly Cluster Setup.
Configuring directory integration involves using the Directories options of the Administration module. The basic process is to:
To enable directory integration:
Step 1 Log in using an account with administrative privileges and choose the Administration module.
Step 2 Click the Settings tab.
Step 3 Next to Directory Integration, click On .
Step 4 On the bottom of the Customizations screen, click Update .
You have now enabled directory integration. (See Enabling Directory Integration.)
Figure 8-5 Enabling Directory Integration
You use the Directories tab of the Administration module to configure many of the directory integration settings.
Figure 8-6 The Directory Integration Area
To configure directory integration settings:
Step 1 Log in using an account with administrative privileges.
Step 2 From the drop-down menu, choose Administration .
Step 3 Click the Directories tab.
The Directory Integration page appears. These settings will be in effect once directory integration has been enabled.
The following sections guide you through configuring datasource specific information. The tasks include:
At least one datasource must be defined. To add a new datasource:
Figure 8-7 Adding or Editing a Datasource
Step 1 Navigate to the Directory Integration page by choosing the Administration module and then clicking the Directories tab.
Step 2 In the page navigator, click the Datasources option, if not already selected.
Step 3 Click Add . To edit an existing datasource instead of adding a new datasource, click Edit next to the desired datasource in the list.
The Datasource Configuration area expands.
Step 4 Enter the Datasource Name, Datasource Description, and the desired settings. Click to access all of the settings in the adjacent area. See the Datasource Worksheet for more information about these settings, or see the following sections.
Specify the connection protocol and user credentials used to connect to the datasource.
Figure 8-8 Configuring Connection Information
If you chose SSL as the connection mechanism, you need to specify the certificates for the directory integration system.
Figure 8-9 Configuring Security Certificates
Step 1 Navigate to the Directory Integration page by choosing the Administration module and then clicking the Directories tab.
Step 2 In the page navigator, click the Datasources option, if not already selected.
Step 3 Next to the datasource to which you wish to add a certificate, click Edit .
Step 4 Click Add Certificate .
Step 5 Name the certificate. Do not use spaces or special characters in the certificate alias name.
Step 6 From the Certificate Type drop-down menu, choose the certificate type.
Step 7 Paste the certificate value (obtained from a vendor like VeriSign) into the certificate field.
If you have multiple datasources configured, you can designate datasources as referral systems to a selected datasource. This way, whenever the system performs a search against the selected datasources, it will also search all referral datasources.
The referral datasources are searched in the order in which they are specified until a match is found.
A match is said to be found when the search criteria returns one or more records.
Referral datasources are typically used when directory information is divided among multiple directories. For example, different company divisions may each maintain their own directory.
Figure 8-10 Configuring Referral Datasources
To configure referral datasources:
Step 1 Navigate to the Directory Integration page of the Administration module.
Step 2 In the page navigator, click the Datasources option, if not already selected.
Step 3 Next to the datasource for which to configure a referral datasource, click Edit .
Step 5 The Referral Datasource area appears. From the Datasource Name drop-down menu choose a datasource name, and then from the Mapping Name drop-down menu choose a mapping name.
If you have completed all the necessary configuration steps, then you are ready to test the directory integration connection.
Figure 8-11 Testing the Connection
Step 1 Navigate to the Directory Integration page in the Administration module.
Step 2 In the page navigator, click the Datasources option, if not already selected.
Step 3 Choose the datasource to test by checking the check box to the left of the datasource name.
Step 4 Click Test Connection .
The Test Status column displays OK if the connection is successful, and if it is unsuccessful.
You use the Mappings area of the Administration module’s Directories tab to map Service Catalog data to directory server data.
To configure mapping, see Configuring Mapping and follow the procedure below.
Figure 8-12 Configuring Mapping
Step 1 Navigate to the Directory Integration page of the Administration module.
Step 2 In the page navigator, click the Mappings option.
Step 3 Click Add to add a new mapping, or click Edit next to the desired mapping in the list to edit an existing mapping.
The Mapping Configuration area expands.
Step 4 Configure the mapping name, description, and attributes, based on the requirements documented in the Mapping Worksheet. The mappings prefixed with an asterisk (*), shown in the Person Data section, are mandatory. You may also configure optional mappings by clicking the button, to expand the Optional Person Data Mappings section.
The mapping fields accept simple, composite, expression, and Java mapping types, as described below.
This section describes accepted mapping types, illustrates a valid sample mapping, and explains with examples expression mapping. The following table describes the supported mapping types.
One directory attribute maps to the field. This is simple one-to-one mapping. For example: |
|
A combination of attributes maps to the field. # delimits each attribute name. The mapping may include literals. For example: |
|
An expression uses regular expressions and pattern matching to derive the mapping. For more details see the Expression Mapping. |
|
Use Java mapping when simple, composite, or expression mapping does not offer the desired functionality. This involves writing a Java class and placing the compiled class file on the appropriate directory on the application server. For more details see the Java Class Mapping. |
The following table illustrates sample simple and composite mappings for the mandatory fields.
Expression mapping allows you to conditionally assign a value to an attribute, based on which pattern (regular expression) the expression matches. The system expression mapping uses the Perl5 Regular Expression Language, to specify patterns to be matched, combined with syntax similar to that of the Java conditional operator. Syntax :
If <expression> matches <pattern1>, then return <value1>.
If <expression> matches <pattern2>, then return <value2>.
If <expression> does not match any pattern, then return <default>.
Each element (expression, pattern, or value) can contain a directory attribute name, delimited by the # symbol. For example, a pattern can be specified as “#givenName#_#sn#”, where both #givenName# and #sn# are attribute names:
In addition, parentheses can be used to group a series of pattern elements to a single element. When you match a pattern within parentheses, you can use back-references, in the form of $1, $2, and so on, to refer to the previously matched pattern.
A simple use of an expression applied to directory integration may be to translate one or more coded values in the directory to more user friendly descriptions or broader categories. For example, some services may need to differentiate between employees and contractors. The costCenter attribute is known to be “000000” for contractors. Therefore, the following expression could be applied to the “Employee Type” field:
Another suse of an expression is to supply a default value for a field when the source attribute is blank. This may frequently be a “stop gap” measure, until directory data can be standardized. Or it could be standard; for example, if outside contractors are not assigned a department. The following expression could be applied to the “Home OU” field (a mandatory field for the mapping):
This expression uses the DeptLevel2 attribute if available, or defaults to the “Unknown” Business Unit for the user’s Home OU.
Similarly, the expression can be used to translate from a set of input values to a different set of return values. This is the equivalent of a case statement, or nested if/then construct. For example, the following expression could be applied to the “Locale ID” field, to assign a language for the user, based on his/her location:
If the user’s country is the United States, set the language to American English; if it is Germany, set the language to German. For any other country, set the language to American English.
Regular expressions can check the length of a source attribute and whether it is composed of alphabetic or numeric characters. For example, sometimes zip codes are stored as numeric data types, truncating leading zeroes. To restore a leading zero, an expression such as the following could be applied to the “Company Postal Code” field:
If the postalCode attribute consists of precisely four digits, add a leading zero to the value of the attribute. This converts zip code 1701 to 01701 , and leaves any source values which do not match the specified pattern unchanged.
A similar use of regular expressions might check that the format of an attribute value matches an expected pattern. Consider a use case in which a valid manager's user ID needs to consist of two letters followed by a series of numbers. Valid IDs would be, for example, fd1024 and ID3839. The following expression could be used:
Attributes can be used in the expression, pattern, or return value:
The last name and first name from directory records are combined into a string such as “Doe, Jane” before any attempt is made to match the patterns.
Embedded parentheses and back-references are useful for extracting a portion of the pattern. For example, the organization to which a person belongs is frequently embedded within a distinguished name (dn) attribute:
The expression mapped to the “Home Organizational Unit” field might have the format:
The returned value, “Corporate” is a back-reference value $1, which equals the pattern matched by the expression within the first set of parentheses, ([a-zA-Z]+).
Usage of back-referenced variables may be required to parse overloaded attributes which include the values for more than one field. For example, an attribute can include the business address of a person, including the building name, floor (level), and office.
The same pattern could be used to match the three elements in the expression, by using different back-referenced variables as the value:
You will need to be familiar with Java programming and have a Java development environment set up in order to implement a custom Java class to map directory data to fields.
Any custom mapping class must follow the guidelines given in “Using Custom Code in Directory Integration” section. The mapping class must implement an IEUIAttributeMapping interface.
The developer must follow the guidelines below to test and install the custom code module.
1. Install a Java IDE of choice, and set up a project for developing custom mapping code.
2. Edit the custom code file to fulfill your requirements.
4. The custom Java class must be installed on the Service Catalog web archive (war), to be accessible to the Service Catalog service. Create a directory in RequestCenter.war/WEB-INF/classes to correspond to the package. Such directories are typically named:
com/newscale/client/<clientname>, for example, com/newscale/client/aib.
5. Copy the CustomMapping.class file to the directory created in the previous step.
6. Restart the Service Catalog service.
7. Specify the fully qualified name of the class file as the Mapped Attribute for the field to be populated.
8. Test the custom code by using the Directories Test feature.
You can use the Mapping Test feature to test that your data mapping settings are configured correctly and pulling the correct values from the directory server.
To enable the directory map testing feature, see Enabling Mapping Testing and follow the procedure below.
Figure 8-13 Enabling Mapping Testing
Step 1 Click the Settings tab of the Administration module to display the Settings page.
Step 2 In the page navigator, click the Debugging option.
The Debug Settings page appears.
Step 3 Next to the Directory Map Testing setting, click On .
The system enables the Data Mapping Test feature. Now when you access the Data Mapping tab, the following additional features appear as shown in Mapping Test Controls:
Figure 8-14 Mapping Test Controls
To use the Data Mapping test controls:
Step 1 Click Mappings , if you are not already on the Mapping page.
Step 2 Next to the mapping you wish to test, click Edit .
Step 3 From the “ Choose a Datasource for testing” drop-down menu, choose the desired datasource.
Step 4 In the Test Values column, enter test values. You can use simple, composite, Java, or expression mapping.
Step 6 The test values appear in the Test Values column and a summary of the results appears at the bottom of the page.
Note Fetch returns values from only one datasource and does not search referrals. This is for convenience because it becomes difficult to debug with referrals search integrated.
Step 7 To the right of the Fetch button, click Clear and retry new values until you have configured the desired mappings.
You use the Events area of the Administration module’s Directories tab to configure directory integration behavior for the following events:
To configure events, see Configuring Events and follow the procedure below.
Step 1 Navigate to the Directory Integration page of the Administration module.
Step 2 In the Page Navigator, click Events to display the Events page.
Step 3 Next to the type of event to configure, click Edit .
The Event Configuration area appears.
Step 4 From the Event Status drop-down menu, choose Enabled to enable the event.
Step 5 Click Add step to add a step for the system to initiate when the selected event occurs.
Step 6 Choose an operation associated with the step you just added.
Step 7 Click Options to configure the options associated with the operation you just chose. The Options area appears. The Options area will differ according to which operation is chosen. Details on the available operations and their options are given in the next section.
Step 8 Configure the associated options. See the relevant sections in this chapter on directory Events for a description of the operations available and options for configuring them.
Step 9 Click Update and repeat these steps for each step and operation you wish to add.
Figure 8-15 Configuring Events
The directory integration framework is designed for flexibility and customization of the “Login” and “Person Lookup” events.
Standard operations for all events are available on the Administration module’s Directories tab. These include: SSO, External User Authentication, Import Person, Import Manager, and Person Search.
In cases where these standard operations do not fully satisfy a business scenario, the Directories tab also provides interfaces to execute custom Java code. This custom code should adhere to the interfaces described in this chapter, and you should develop any customized solutions using Service Catalog exposed APIs.
The following are valid use cases for scenarios in which you may wish to customize an event operation:
The directory integration custom code framework also defines interfaces that can be implemented to provide complex retrieval logic for a specific field in the person/user profile from a record in an external datasource.
Public APIs and interfaces for directory integration include the:
A typical custom code project will involve following types of activities:
Directory Integration Operations below summarizes the directory integration operations in more detail.
Mixing and matching, or replacing, standard operations with custom code operations is also supported by the directory integration framework. Service Catalog supports various combinations of operations per event, as described in the table below, using your own customized code and Service Catalog public APIs, designed to help implement these interfaces.
It is important that custom code design and development engineers understand the directory integration framework, public APIs, and custom code interfaces, which are discussed in detail in this chapter.
Table 8-16 below portrays the relationship between methods, events, and operation types for custom code operations. Combinations not listed in Table 8-16 below are not supported.
If you are providing a custom implementation of an operation configured within an event, you will need to implement a “custom code operation interface”.
Custom code operation interfaces define callback methods that are invoked when a particular operation is triggered. Exactly which method is invoked depends on the operation type chosen in the operation. For more details see the Method, Event, and Operation Type for Custom code Operations table. All methods defined in the custom code operation interfaces follow the same pattern:
In the following list, “**” must be replaced by the operation type, which is one of:
1. **OperationDTO: This object contains the information on how you have set the operation on the Directories tab of the Administration module. It includes mapping and datasource information.
2. **OperationContext: The Context object is used to share information across method invocations. The directory Integration framework makes information stored in one context object available to other context objects during the same HttpServletRequest invocation.
a. Use setLocalContextObject and getLocalContextObject to set any custom information that does not fall as a part of results.
b. Use get**Result to get a result object. Result objects contain all the information about what happened throughout the event request. Results contain information that is supported in a productized import. The LocalContext object is used to store objects that were unforeseen during the implementation of productized operations.
3. Request: This is the HttpServletRequest.
4. **ImportAPI: This object is used to import a person. More details can be found in the Javadocs.
5. **LDAPAPI: This API is used to make LDAP queries. More details can be found in the Javadocs.
**Result. After performing the custom task the API must return a valid return type with results populated. Return the same result object retrieved from OperationContext after updating relevant properties. There may be unexpected behavior if a new instance of the result object is returned.
Table 8-17 below maps the expected input/return to the objects in the parameters of each of these callback methods:
You must implement all methods to compile your implementation class. If you customize only limited operation types, you must provide an empty implementation of methods not relevant to the operation types.
For example, if you are only interested in a customized SSO, then provide a complete implementation of the getCredentials method. For all other methods, return null.
The system may pool an instance of an interface and may be concurrently accessed from multiple threads. Thus, it is recommended to keep the instance stateless.
This is the interface that custom code should implement in order to customize login events: SSO, EUA, Import Person, Import Manager and custom code operations.
The primary purpose of an SSO custom code operation is to retrieve and return the Login Name from HttpHeader based Sign-On or from CGI Header (CGI variable REMOTE_USER) in the case of Remote NTML/IWA type of Sign-On.
As outlined in Table 8-16 , you must provide a Java class that implements the ISignOn interface. Please provide a complete implementation of the getCredentials method in this interface, and read the documentation for the ISignOn interface for detailed specifications.
The following are some guidelines for implementing the getCredentials method. It is not required that all of these guidelines are implemented; There may be additional requirements, dependent on the customization, which are not covered by what is outlined below.
SSO Operation Options received through IEUIEventSSOOperationDTO.getEventSsoDTO() may be null as SSO options are not accepted in the Administration module for custom code operations.
The primary purpose of an EUA custom code operation is to authenticate a user against an external system.
As outlined in Table 8-16 , you must provide a Java class that implements the ISignOn interface. Please provide a complete implementation of the authenticate method in this interface, and read the documentation for the ISignOn interface for detailed specifications.
The following are some guidelines for implementing an EUA operation. It is not required that all of these guidelines are implemented; There may be additional requirements, depending on the customization, that are not covered below.
– Remove the prefix “!@^_” and suffix “_^@!” from the string.
– Use Java’s Base64 decode method on the above resultant string.
EUA Operation Options received through IEUIEventEUAOperationDTO.getEventEuaDTO() will be empty as EUA options are not accepted in the Administration module for custom code operations.
The primary purpose of the Import Person operation is to import/refresh a user from an external system, like a directory server or an external database, into the Service Catalog application.
As outlined in Table 8-16 , you must provide a Java class that implements the ISignOn interface. Please provide a complete implementation of the importPerson method in this interface, and read the documentation for the ISignOn interface for detailed specifications.
The following are some guidelines for implementing an Import Person operation. It is not required that all of these guidelines are implemented; There may be additional requirements, dependent on the customization, which are not covered below.
Import Person operation options through the IEUIEventImportPersonOperationDTO.getImportPersonDTO() method will be empty as Import Person options are not accepted in the Administration module for custom code operations.
The primary purpose of the Import Manager operation is to import/refresh the Supervisor chain of the person from an external system, like a directory server, into Service Catalog.
As outlined in Table 8-16 , you must provide a java class that implements the ISignOn interface. Please provide a complete implementation of the importPerson method in this interface, and read the documentation for the ISignOn interface for detailed specifications.
The following are some guidelines for the Import Manager operation:
It is recommended that when importing the manager chain, you import the top level managers before persons. This avoids unnecessary updates for personDTO to update the link with the person’s manager.
Import Manager Operation Options received through IEUIEventImportManagerOperationDTO. getImportManagerDTO() will be empty as Import Manager Options are not accepted in the Administration module for custom code operations.
The primary purpose of the custom code operation is to perform any custom operation that is needed and not represented elsewhere in the application.
The following are some guidelines for the Custom Code operation:
This is the interface that a custom code should implement in order to customize Person Search events: Person Search, Import Person, Import Manager and custom code operations.
The implementation class is configured in the Administration module > Directories tab > Events, and can be configured for searching a for person in the following places within the Service Catalog application:
The primary purpose of the Person Search operation is to search for users from an external system, like a directory server.
As outlined in Custom Code Operations table, you must provide a Java class that implements the IPersonSearch interface. Please provide a complete implementation of the search method in this interface, and read the documentation for the ISignOn interface for detailed specifications.
The following are some guidelines for the Person Search operation:
Person Search Operation Options received through the IEUIEventPersonSearchOperationDTO.getPersonSearchOperationDTO() method will be empty as Person Search Options are not accepted in the Administration module for custom code operations.
As outlined in Custom Code Operations table, you must provide a Java class that implements the IPersonSearch interface. Please provide a complete implementation of the importPerson method in this interface, and read the documentation for the IPersonSearch interface for detailed specifications.
Steps to customize this are similar to the Customizing the Import Person Operation for the Login Event.
As outlined in Custom Code Operations , you must provide a Java class that implements the IPersonSearch interface. Please provide a complete implementation of the search method in this interface, and read the documentation for the IPersonSearch interface for detailed specifications.
Steps to customize this are similar to the Customizing the Import Manager Operation for the Login Event.
As outlined in Custom Code Operations , you must provide a Java class that implements the IPersonSearch interface. Please provide a complete implementation of the performCustom method in this interface, and read the documentation for the IPersonSearch interface for detailed specifications.
Steps to customize this are similar to the Customizing Custom Operations for the Login Event.
When simple, composite, or regular expression attribute mappings do not suffice, a custom Java class can be used in a directory integration attribute mapping.
This is the interface that a custom code should implement in order to customize directory attribute mappings. The primary purpose of custom mapping class is to customize the attribute value fetched from the directory server.
The implementation class has to be configured in the Administration module > Directories tab > Mappings , and can be configured for any attribute in the mapping.
Figure 8-16 Custom Java Class for Attribute Mapping
The following are some guidelines for using a custom Java class mapping class:
This is an API wrapper that Cisco provides for integrating with the directory server (LDAP) connection facility built into the product.
Authentication to, and querying, the directory server are the only features this API provides. This API supports all directory servers supported by Service Catalog.
Typically, the Directory Server API works from the directory integration datasource and mapping configurations, and eliminates the need for hand-coding connection information, filters, and the attributes for querying.
Generally, to use the LDAP API, you also need the LDAPConfigInfo object. Use EUIUtil.get LDAPConfigInfo() from any datasource and mapping for this purpose.
The javadoc for LDAP API can be located in the javadocs folder of the product package.
An instance of ILDAPApi does not need to be created. It is available in all method arguments of both custom code API interfaces (ISignOn and IPersonSearch).
The directory integration utility class (EUIUtil) converts the datasource and mapping configured in the Administration module into a format that the Directory Server API can use as input for authentication, search, and query functions.
An object of LDAPConfigInfo class encapsulates all the following configuration options that must be passed to the directory server API:
For more advanced users, if there is a need to override any configuration, LDAPConfigInfo provides getters and setters for all configurations. For further details on these methods, see the Javadoc for this class.
The ILDAPApi is the main interface that provides two basic operations on the directory server:
The ILDAPApi interface provides methods to interact with LDAP consistently throughout Service Catalog.
After querying/searching the directory server using the ILDAPApi.query(…) method, the results are returned as a collection of LDAPEntryBean.
This API can be used to import/refresh Person profile, create OUs or groups and also to link or unlink a person to an OU, group, or role. This API also supports transaction management for importing a person, and connectivity to SQL datasources. This API includes a method to read from the CnfParams table.
The Import/Refresh Person API interface provides methods for the following:
To customize the Java class to connect to a SQL datasource:
Step 1 Get a connection to a SQL datasource database from ISignOnImportPersonAPI by passing the DatasourceName. The DatasourceName should be prefixed with the JNDI prefix, as defined by the “DatasourceJNDIPrefix” property in newscale.properties file.
Step 2 Use the above connection to execute any query using a JDBC statement.
Step 3 Commit the connection object directly at the end of the try block.
Step 4 Call ISignOnImportPersonAPI to roll back the connection when there are any failures/exceptions.
Step 5 In the final block, close the statement directly and call ISignOnImportPersonAPI to release the connection and return it to the connection pool.
The following are steps to compile and deploy custom code:
Step 1 Copy the build.xml file given in the Sample build.xml File and paste it to any folder; for example, C:\CustomCode.
Step 2 Edit the build.xml file to change the property “rcwar.dir” to point to the full path where the RequestCenter.war is available.
Step 3 Edit the build.xml to change the property “javax.servlet.dir” to point to the full path where the servlet-api.jar is available. This is specific to the application server.
Step 4 Create a subfolder for the custom code java files; for example, C:\CustomCode\src.
Step 5 Create a custom code with a package name like “com.newscale.SignOnCustomCode” and place the SignOnCustomCode.java file in the following directory: C:\CustomCode\src\com\newscale\SignOnCustomCode.java
Step 6 Run “ant” from a command line in the C:\CusomCode folder.
Step 7 The ant build file will compile all the java files under the “src” subfolder and place the class files in the “out” subfolder.
Step 8 The ant build file will also deploy the class files to the “RequestCenter.war\WEB-INF\classes” folder.
Step 9 Restart the application server.
After you have developed, compiled, and deployed the custom code, the Administration module must be configured to use the code. Configuration involves specifying when (in which event), in which operation and in what sequence (step) to invoke the custom code.
Ensure that the Directory Integration has been enabled by turning on this setting in the Administration module’s Settings tab. Instructions for turning on Directory Integration are given in the Enabling Directory Integration.
Most operations, customized or not, require a datasource and mapping, so these two areas of the Directory Administration must be configured first.
Datasources are the external servers, such as LDAP, where your data is currently stored, and which Service Catalog must access. The only custom operation which does not require a datasource is SSO.
See the Defining Datasources and the Configuring Datasource Information for more information on configuring datasources.
Once you have set up the external datasource, you must map the person-related data available in Service Catalog to the data in the LDAP directory (or other external datasource). These mappings tell Service Catalog where to look and what to get during an event and sequence of operations.
To configure a mapping follow the guidelines and instructions in the Defining Mappings and the Configuring Mappings.
Customizing the Single Sign-On (SSO) and authentication operations for any event other than Login is considered an illegal action. There is no other time when these operations are necessary. Once a user is signed into and authenticated in the application from the external LDAP server, the process does not need to be replicated.
All events requiring connection to external datasources are configured here. When invoking the Custom Code APIs described in this guide, it is important to think through the sequence of operations for each event so that the custom operation does not occur out of order and fail.
Step 1 From the Navigation Pane, click Events .
Step 2 For the event you wish to customize, click Edit .
Step 3 If the event is disabled, use the drop-down menu to choose Enabled .
Step 4 Click Add step to add an operation. You can add as many steps are as necessary now, or complete the details of each step before adding and configuring the next.
Step 5 Choose the Operation from the drop-down menu.
Step 6 Choose your mapping and datasource from the drop-down menus.
Step 7 Under the “Additional Options” heading, click Options .
Step 8 Configure the options for that step:
Step 9 Click Close to close the additional options for the step.
Step 10 Continue adding and configuring steps, as necessary.
Step 11 Click Update to save all steps for that event.
In the steps above, if you choose Custom Code as the operation and Custom Code again for the operation type, you are then calling an undefined Custom Code, which you must design.
In the Custom Code test example provided by Cisco, you can use the Java Class “performCustom” to define your own custom code.
All custom code must be packaged as a customization to the Service Catalog installer. This allows the customizations to be reapplied if the installation needs to be upgraded or to install a new site.
Instructions for packaging and deploying custom code are dependent on the application server which hosts Service Catalog. See the Cisco Prime Service Catalog 12.0 Adapter Integration Guide and Cisco Prime Service Catalog Administration and Operations Guide for further information about configuring custom code.
The solution here satisfies these use cases:
It also creates the home OU for the person as a business unit, if it doesn’t already exist in Service Catalog.
Note The solution requires a datasource to be configured on the application server. The following sections illustrate configuration and usage of the EUIPersonSearchSQL class.
Any SQL table or tables that contain data for the mandatory fields in a Person profile (or from which values for those fields can be derived) could be used as a datasource. Here is the table definition used in this example:
The following is some sample data to go with the above table definition:
To use the Directory Integration interface you have to have an LDAP datasource configured. LDAP is the only UI supported datasource. You can create maps without a datasource, but you cannot test them without an LDAP datasource.
Figure 8-17 Sample Datasource Configuration
Configuring a container-managed datasource depends on the container. Detailed instructions on configuring datasources are given in the Cisco Prime Service Catalog Installation and Upgrade Guide .
A mapping must be created for the EUIPersonSearchSQL class.
Figure 8-18 Sample Mapping Configuration
This mapping includes references to the JNDI as Custom 9 and the table name for Custom 10. Using a mapping like this, it is possible to do a simple query such as “select * from tablename” and use the metadata functionality in JDBC to select the column based on the mapping.
The “Person Lookup for Order on Behalf” event has two steps: The first must perform a “Person Search” operation. The name of the class is given as the mapping. The complete package specification is given as the Java class.
Figure 8-19 Custom Person Search Operation
The second step in the “Person Lookup for Order on Behalf” event is to import the selected person (“Import Person”). This configuration uses the same Java class, but a different Custom Code Operation Type. The Custom Code Operation Types in the drop-down menu correspond to the methods that are called in the interface class.
Figure 8-20 Event Step 2 – Custom Import Person Operation
The following is the source for the custom class: