McAfee Cloud Identity Manager

Transcription

1 Provisioning SDK Guide McAfee Cloud Identity Manager version 3.5

2 COPYRIGHT Copyright 2013 McAfee, Inc. All Rights Reserved. No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any language in any form or by any means without the written permission of McAfee, Inc., or its suppliers or affiliate companies. TRADEMARK ATTRIBUTIONS McAfee, the McAfee logo, Avert, epo, epolicy Orchestrator, Foundstone, GroupShield, IntruShield, LinuxShield, MAX (McAfee SecurityAlliance Exchange), NetShield, PortalShield, Preventsys, SecureOS, SecurityAlliance, SiteAdvisor, SmartFilter, Total Protection, TrustedSource, Type Enforcement, VirusScan, and WebShield are registered trademarks or trademarks of McAfee, Inc. or its subsidiaries in the United States and other countries. LICENSE INFORMATION License Agreement NOTICE TO ALL USERS: CAREFULLY READ THE APPROPRIATE LEGAL AGREEMENT CORRESPONDING TO THE LICENSE YOU PURCHASED, WHICH SETS FORTH THE GENERAL TERMS AND CONDITIONS FOR THE USE OF THE LICENSED SOFTWARE. IF YOU DO NOT KNOW WHICH TYPE OF LICENSE YOU HAVE ACQUIRED, PLEASE CONSULT THE SALES AND OTHER RELATED LICENSE GRANTOR PURCHASE ORDER DOCUMENTS THAT ACCOMPANIES YOUR SOFTWARE PACKAGING OR THAT YOU HAVE RECEIVED SEPARATELY AS PART OF THE PURCHASE (AS A BOOKLET, A FILE ON THE PRODUCT CD, OR A FILE AVAILABLE ON THE WEBSITE FROM WHICH YOU DOWNLOADED THE SOFTWARE PACKAGE). IF YOU DO NOT AGREE TO ALL OF THE TERMS SET FORTH IN THE AGREEMENT, DO NOT INSTALL THE SOFTWARE. IF APPLICABLE, YOU MAY RETURN THE PRODUCT TO MCAFEE OR THE PLACE OF PURCHASE FOR A FULL REFUND. 2 McAfee Cloud Identity Manager Provisioning SDK Guide

3 Contents 1.0 McAfee Cloud Identity Manager Provisioning API Overview Provisioning Actions Setting Up Your Java Development Environment Import Custom Java Code Directory Locations of Internal and External JAR File Dependencies Action API Interfaces Writing an Action Plug-in: Simple Configuration Example AAMV3Interface Methods Used in Sample Code Simple Configuration Summary of Sample Code for Simple Configuration Writing an Action Plug-in: Advanced Configuration Example AAMV3Interface Methods Used in Sample Code Advanced Configuration Summary of Sample Code for Advanced Configuration...13 McAfee Cloud Identity Manager Provisioning SDK Guide 3

4 4 McAfee Cloud Identity Manager Provisioning SDK Guide

5 1.0 McAfee Cloud Identity Manager Provisioning API Overview McAfee Cloud Identity Manager (Cloud Identity Manager, formerly Intel Expressway Cloud Access 360-SSO) provides two Application Programming Interfaces (APIs) for developers who wish to customize the provisioning service by creating plug-ins. Action API Use the Action API to develop custom actions. Web Service Listener API Use the Web Service Listener API to synchronize information over HTTP/HTTPS between two Cloud Identity Manager instances. Note: Information about the Web Service Listener API is available upon request. 1.1 Provisioning Actions Provisioning actions are the key to policy implementation. In addition to a large menu of built-in actions, the provisioning service offers an Action API that lets you configure custom actions for your particular situation. There are three types of provisioning actions. Getters Getters are actions that add data from one or more data sources to the internal virtual image of an object. Getters create new session objects and session attributes. Modifiers Modifiers are actions that update existing session objects and session attributes. Setters Setters are actions that save data from existing session objects and session attributes to one or more databases. Note: For more information about provisioning actions, see the McAfee Cloud Identity Manager Provisioning Guide. McAfee Cloud Identity Manager Provisioning SDK Guide 5

6 1.2 Setting Up Your Java Development Environment Before using one of the provisioning APIs, you need to have Cloud Identity Manager installed. You also need a basic understanding of the provisioning service. For more information, see the following guides. McAfee Cloud Identity Manager Installation Guide McAfee Cloud Identity Manager Provisioning Guide You can use any Integrated Development Environment (IDE) to develop custom plug-ins for the provisioning service, including the following: Eclipse For more information, visit: IntelliJ IDEA For more information, visit: NetBeans For more information, visit: The Action API, which is written in Java code and distributed in JAR (Java ARchive) files, consist of Java classes. To view the Javadoc and Java classes, visit: Import Custom Java Code Before you begin, you can import sample Java code in the Provisioning Studio and view two custom actions. One action is an example of a simple configuration, and the other is advanced: Reverse String (Action Advanced Config) Reverse String (Action Simple Config) To download the sample Java code, click: AAMActionAPISampleCode.zip The downloaded.zip file includes the following.jar file: AAMActionAPISampleCode.jar. You import the.jar file in Provisioning Studio, where you can view the custom actions. To import custom Java code 1. Open the Provisioning Studio. 2. Go to Tools Plugin Manager. 3. Click Import from file, browse to locate the.jar file, and click OK. 4. Restart the Provisioning Studio. 6 McAfee Cloud Identity Manager Provisioning SDK Guide

7 1.4 Directory Locations of Internal and External JAR File Dependencies On a Microsoft Windows operating system, you place internal and external JAR file dependencies in specified locations. Internal JAR file dependencies are those.jar files that you import in the Provisioning Studio. Internal JAR File Dependencies Place all.jar files imported in the Provisioning Studio in the following directory: <installation_directory>\lib <installation_directory> Specifies the directory where Cloud Identity Manager is installed. Default: C:\Program Files\McAfee\CIM\SSO\current\provisioning External JAR File Dependencies Place all external JAR file dependencies in the following directory: <installation_directory>\ext <installation_directory> Specifies the directory where Cloud Identity Manager is installed. Default: C:\Program Files\McAfee\CIM\SSO\current\provisioning McAfee Cloud Identity Manager Provisioning SDK Guide 7

8 1.5 Action API Interfaces In the Provisioning Studio, there are two different API interfaces for developing action plug-ins. Simple Action API Interface Using the simple interface, you can develop simple actions. For example, you can develop actions that update session attributes, create a Microsoft Excel file with values read from session objects and attributes, or browse an LDAP directory or file system. The following screenshot shows an action in the simple interface. Advanced Action API Interface Using the advanced interface, you can develop advanced actions. For example, you can develop actions that synchronize user information between two or more databases. In the advanced interface, a JPanel is used and graphical components can be added. The following screenshot shows an action group in the advanced interface. 1.6 Writing an Action Plug-in: Simple Configuration Example To write a simple action plug-in, implement the following interface in a new class or use the sample code classes as templates: se.nordicedge.aamv3interface AAMV3Interface Methods Used in Sample Code Simple Configuration Summarizes the primary AAMV3Interface methods used by the sample code written for a simple action plug-in Summary of Sample Code for Simple Configuration Summarizes the runplugin method that is called when the action is invoked. This method is where you place your code. For instructions on how to download the sample code, see section 1.3 Import Custom Java Code. To view the Javadoc and Java classes, visit: 8 McAfee Cloud Identity Manager Provisioning SDK Guide

9 1.6.1 AAMV3Interface Methods Used in Sample Code Simple Configuration The sample Java code for a simple action plug-in uses the following primary AAMV3Interface methods. getdescription Type: String Description: Returns a brief description of the plug-in s function. geticonname Type: String Description: Returns the name of the image file. Note: Set the icon size to 21x21 pixels. Supported image formats include BMP, JPG, and PNG. getname Type: String Description: Obsolete getsimpleconfigparameters Type: Vector Description: Returns configuration parameters. Each vector element represents a parameter using a string array. Example: String[] sarray0 = new String[] {"Session Attribute Containing Givenname [MANDATORY]", "LDAP-ATTRIBUTE", "Attribute of the incoming session object which contains the value to be manipulated. Example: givenname"; gettype Type: String Description: Returns the plug-in type. The type is used when creating a new instance of the action in the Provisioning Studio. Note: The type is a unique identifier. Do not modify its value after the plug-in is released for production. getusage Type: Boolean[] Description: Returns the action s type, as follows. Table 1. Type Getter Modifier Setter Action types and return values Return Value Boolean.TRUE, Boolean.FALSE, Boolean.FALSE Boolean.FALSE, Boolean.TRUE, Boolean.FALSE Boolean.FALSE, Boolean.FALSE, Boolean.TRUE getversion Type: Float Description: Returns the version number of the action. runplugin Type: Boolean Description: This method is called when the action is invoked. Place your code here. setconfigpanel Type: Boolean Description: Returns TRUE when the configuration is advanced and FALSE when the configuration is simple. Value: FALSE McAfee Cloud Identity Manager Provisioning SDK Guide 9

10 1.6.2 Summary of Sample Code for Simple Configuration The following steps and comments summarize the sample code for a simple action plug-in. For instructions on how to download the complete sample code, see section 1.3 Import Custom Java Code. To view more information about the AAMV3Interface methods used in the code, visit: 1. Check for search results. If there are search results, you can continue. If there are no search results, end the action and return a TRUE value. if (results == null results.size() == 0){ NELogger.debug("No session objects available."); return Boolean.TRUE; // End the action. 2. Get the parameters. String sacontaininggivenname = action.getparametervalue(0, ""); // No default value is specified and therefor the setting is MANDATORY. String sanameforstatus = action.getparametervalue(1, "status"); // "status" is the the default value. 3. Check the parameters. if (sacontaininggivenname.trim().equalsignorecase("")){ NELogger.error("ERROR: The 'Session Attribute Containing Givenname' is unset. Please enter a session attribute which contains the given name. Example: givenname"); return Boolean.FALSE; 4. Loop through all session objects in the search result. for (int xx = 0; xx < results.size(); xx++){ // Get the session object. SessionObject currentsessionobject = (SessionObject) results.get(xx); // Get the session attribute for given name. SessionAttribute sagivenname = currentsessionobject.getsessionattribute(sacontaininggivenname); String givenname = ""; boolean success = Boolean.FALSE; if (sagivenname!= null){ // Get the value from the session attribute. givenname = sagivenname.getvalue(); if (givenname == null givenname.isempty()){ NELogger.debug(currentSessionObject.getName() + " has no value in attribute: " + sacontaininggivenname); else { // Manipulate the incoming data (given name) as desired. // In this example the given name is reversed. StringBuffer sbuf = new StringBuffer(givenName); givenname = sbuf.reverse().tostring(); // Set the session attribute with the manipulated data. sagivenname.setvalue(givenname); success = Boolean.TRUE; 10 McAfee Cloud Identity Manager Provisioning SDK Guide

11 else { NELogger.error(currentSessionObject.getName() + " is missing attribute: " + sacontaininggivenname); /* In this example a session status attribute containing a result string is added to the session. SUCCESS or FAILURE is set depending on the result. */ SessionAttribute sastatus = new SessionAttribute(); sastatus.setname(sanameforstatus); if (success){ sastatus.setvalue("success"); else { sastatus.setvalue("failure"); sastatus.sethasbeenedited(true); currentsessionobject.addsessionattribute(sastatus); return Boolean.TRUE; //Success 1.7 Writing an Action Plug-in: Advanced Configuration Example To write an advanced action plug-in, implement the following interface in a new class or use the sample code classes as templates: se.nordicedge.aamv3interface AAMV3Interface Methods Used in Sample Code Advanced Configuration Summarizes the primary AAMV3Interface methods used by the sample code written for an advanced action plug-in Summary of Sample Code for Advanced Configuration Summarizes the runplugin method that is called when the action is invoked. This method is where you place your code. For instructions on how to download the sample code, see section 1.3 Import Custom Java Code. To view the Javadoc and Java classes, visit: McAfee Cloud Identity Manager Provisioning SDK Guide 11

12 1.7.1 AAMV3Interface Methods Used in Sample Code Advanced Configuration The sample Java code for a advanced action plug-in uses the following primary AAMV3Interface methods. getdescription Type: String Description: Returns a brief description of the plug-in s function. geticonname Type: String Description: Returns the name of the image file. Note: Set the icon size to 21x21 pixels. Supported image formats include BMP, JPG, and PNG. getname Type: String Description: Obsolete getsimpleconfigparameters Type: Vector Description: Returns null. gettype Type: String Description: Returns the plug-in type. The type is used when creating a new instance of the action in the Provisioning Studio. Note: The type is a unique identifier. Do not modify its value after the plug-in is released for production. getusage Type: Boolean[] Description: Returns the action s type, as follows. Table 2. Type Getter Modifier Setter Action types and return values Return Value Boolean.TRUE, Boolean.FALSE, Boolean.FALSE Boolean.FALSE, Boolean.TRUE, Boolean.FALSE Boolean.FALSE, Boolean.FALSE, Boolean.TRUE getversion Type: Float Description: Returns the version number of the action. runplugin Type: Boolean Description: This method is called when the action is invoked. Place your code here. setaction Type: void Description: Sets the action object that stores information for this action. To extract the parameter values, use: action.getparametervalue. setconfigpanel Type: Boolean Description: Returns TRUE when the configuration is advanced and FALSE when the configuration is simple. Value: TRUE 12 McAfee Cloud Identity Manager Provisioning SDK Guide

13 1.7.2 Summary of Sample Code for Advanced Configuration The following steps and comments summarize the sample code for an advanced action plug-in. For instructions on how to download the complete sample code, see section 1.3 Import Custom Java Code. To view more information about the AAMV3Interface methods used in the code, visit: 1. Check for search results. If there are search results, continue. If there are no search results, end the action and return a TRUE value. if (results == null results.size() == 0){ NELogger.debug("No session objects available."); return Boolean.TRUE; // End the action. 2. Get the parameters. String sessionattribname = action.getparametervalue(0, ""); boolean copytonewattribute = action.getparametervalue(1, false); 3. Check the parameters. if (sessionattribname.trim().equalsignorecase("")){ NELogger.error("ERROR: The 'Session Attribute Name' is unset. Please enter a session attribute name which contains a string value. Example: givenname"); return Boolean.FALSE; 4. Loop through all session objects in the search result. for(int xx=0; xx < results.size(); xx++){ // Get the session object. SessionObject sessionobj = (SessionObject) results.get(xx); // Get the session attribute from sessionattribname. SessionAttribute sessionattrib = sessionobj.getsessionattribute(sessionattribname); if(sessionattrib!= null){ // The session object has the attribute. String s = sessionattrib.getvalue(); StringBuffer sbuf = new StringBuffer(s); s = sbuf.reverse().tostring(); // If checked, add a new session attribute to the session object. if(copytonewattribute){ SessionAttribute newsessionattrib = new SessionAttribute(); newsessionattrib.setname("new-"+sessionattribname); newsessionattrib.setvalue(s); newsessionattrib.sethasbeenedited(true); sessionobj.addsessionattribute(newsessionattrib); else{ sessionattrib.setvalue(s); sessionattrib.sethasbeenedited(true); McAfee Cloud Identity Manager Provisioning SDK Guide 13

14 return Boolean.TRUE; //Success 14 McAfee Cloud Identity Manager Provisioning SDK Guide

15

16 Order Number: US [Revision A]