Tivoli SecureWay User Administration. LDAPConnectionUser sguide. Version 3.8

Transcription

1 Tivoli SecureWay User Administration LDAPConnectionUser sguide Version 3.8

2

3 Tivoli SecureWay User Administration LDAPConnectionUser sguide Version 3.8

4 Tivoli SecureWay User Administration LDAP Connection User s Guide Copyright Notice Copyright IBM Corporation All rights reserved. May only be used pursuant to a Tivoli Systems Software License Agreement, an IBM Software License Agreement, or Addendum for Tivoli Products to IBM Customer or License Agreement. No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any computer language, in any form or by any means, electronic, mechanical, magnetic, optical, chemical, manual, or otherwise, without prior written permission of IBM Corporation. IBM Corporation grants you limited permission to make hardcopy or other reproductions of any machine-readable documentation for your own use, provided that each such reproduction shall carry the IBM Corporation copyright notice. No other rights under copyright are granted without prior written permission of IBM Corporation. The document is not intended for production and is furnished as is without warranty of any kind. All warranties on this document are hereby disclaimed, including the warranties of merchantability and fitness for a particular purpose. U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corporation. Trademarks IBM, the IBM logo, Tivoli, the Tivoli logo, AIX, Cross-Site, NetView, OS/2, Planet Tivoli, RS/6000, Tivoli Certified, Tivoli Enterprise, Tivoli Enterprise Console, Tivoli Ready, and TME are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both. Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. UNIX is a registered trademark in the United States and other countries licensed exclusively through X/Open Company Limited. ActionMedia, LANDesk, MMX, Pentium, and ProShare are trademarks of Intel Corporation in the United States, other countries, or both. For a complete list of Intel trademarks, see Other company, product, and service names may be trademarks or servicemarks of others. Notices References in this publication to Tivoli Systems or IBM products, programs, or services do not imply that they will be available in all countries in which Tivoli Systems or IBM operates. Any reference to these products, programs, or services is not intended to imply that only Tivoli Systems or IBM products, programs, or services can be used. Subject to valid intellectual property or other legally protectable right of Tivoli Systems or IBM, any functionally equivalent product, program, or service can be used instead of the referenced product, program, or service. The evaluation and verification of operation in conjunction with other products, except those expressly designated by Tivoli Systems or IBM, are the responsibility of the user. Tivoli Systems or IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to the IBM Director of Licensing, IBM Corporation, North Castle Drive, Armonk, New York , U.S.A.

5 Contents Preface... v Who Should Read This Guide... v What This Guide Contains.... v Publications... v Prerequisite and Related Documents... v Accessing Publications Online.... vii Ordering Publications... vii Providing Feedback about Publications... vii Contacting Customer Support... viii Conventions Used in This Guide... viii Chapter 1. Managing User Data with LDAP... 1 WhyUseLDAP?... 1 The LDAP Directory Service Model... 2 The LDAP Connection... 3 Remarks about LDAP Connection... 5 Assigning LDAP Connections as Managed Resources... 8 Creating LDAP Connections Editing LDAP Connection Properties Using Tivoli-LDAP Attribute Name Mapping Deleting LDAP Connections Using the wmkkf Command Chapter 2. LDAP Commands wldap wmkkf Chapter 3. User Profile Attributes Tivoli SecureWay User Administration LDAP Connection User s Guide iii

6 Index iv Version 3.8

7 Preface The Tivoli SecureWay User Administration LDAP Connection User s Guide describes how to use Tivoli SecureWay User Administration to manage Lightweight Directory Access Protocol (LDAP) connections. Who Should Read This Guide This guide is for system managers and administrators who manage user data on any systems that are accessible by means of LDAP. Users of the guide should have some knowledge of: Tivoli SecureWay User Administration Lightweight Directory Access Protocol What This Guide Contains Publications This guide contains the following sections: Managing User Data with LDAP Provides an overview of LDAP, including information on the directory service model and LDAP connections. LDAP Commands Describes the commands associated with the LDAP application. User Profile Attributes Provides the actual names of attributes in the Tivoli user profile. This section lists prerequisite and related publications. It also describes how to access Tivoli publications online, how to order Tivoli publications, and how to make comments on Tivoli publications. Prerequisite and Related Documents You must be familiar with the information in the related documents before you install and use the software described in this guide. Tivoli SecureWay User Administration LDAP Connection User s Guide v

8 Tivoli SecureWay UserTivoli SecureWay User Administration Management Guide Provides task-oriented information on how to manage user and group accounts using Tivoli profiles. It also provides background information on user and group accounts, information about how Tivoli manages these types of accounts, examples of setting up and using Tivoli SecureWay User Administration for user and group management, and procedures for using all components of the user interface, including the graphical user interface and examples using the command line interface. Tivoli SecureWay User Administration Reference Manual Provides detailed documentation for Tivoli SecureWay User Administration CLI commands, authorization roles, and policy. Tivoli SecureWay User Administration NIS Management Guide Provides information about managing NIS domains, NIS maps, NIS map entries, NIS transactions, and NIS locks using Tivoli SecureWay User Administration. Tivoli Management Framework Planning for Deployment Guide Explains how to plan for deploying your Tivoli environment. It also describes Tivoli Management Framework and its services. Tivoli Enterprise Installation Guide Explains how to install and upgrade Tivoli Enterprise software within your Tivoli management region using the available installation mechanisms provided by Tivoli Software Installation Service and Tivoli Management Framework. Tivoli Enterprise software includes the Tivoli management region server, managed nodes, gateways, endpoints, and RDBMS Interface Module (RIM) objects. This guide also provides information about troubleshooting installation problems. Tivoli Management Framework User s Guide Describes the concepts and procedures for using Tivoli Management Framework services. It provides instructions for performing tasks from the Tivoli desktop and from the command line. Tivoli Management Framework Reference Manual vi Version 3.8

9 Provides in-depth information about Tivoli Management Framework commands. This manual is helpful when writing scripts that are later run as Tivoli tasks. This manual also documents Tivoli-provided policy scripts. Accessing Publications Online You can access many Tivoli publications online at the Tivoli Customer Support Web site: These publications are available in PDF or HTML format, or both. Translated documents are also available for some products. To access most of the documentation, you need an ID and password. If necessary, you can obtain these from the following Web site: Ordering Publications You can order many Tivoli publications online at the following Web site: You can also order by telephone by calling one of these numbers: In the U.S.: In Canada: In other countries, for a list of telephone numbers, see the following Web site: Providing Feedback about Publications We are very interested in hearing about your experience with Tivoli products and documentation, and we welcome your suggestions for improvements. If you have comments or suggestions about our products and documentation, contact us in one of the following ways: Tivoli SecureWay User Administration LDAP Connection User s Guide vii

10 Send an to Complete our customer feedback survey at the following Web site: Contacting Customer Support If you have a problem with any Tivoli product, you can contact Tivoli Customer Support. See the Tivoli Customer Support Handbook at the following Web site: The handbook provides information about how to contact Tivoli Customer Support, depending on the severity of your problem, as well as the following information: Registration and eligibility Telephone numbers and addresses, depending on the country you are in What information you should gather before contacting support Conventions Used in This Guide The following typeface conventions are used in this guide: Bold Commands, keywords, file names, authorization roles, URLs, or other information that you must use literally appear like this, inbold type. Names of windows, dialogs, and other controls also appear like this, inbold type. Italics Variables and values that you must provide appear like this, in italic type. Words and phrases that are emphasized also appear like this, in italic type. Monospace Code examples, output, and system messages appear like this, inmonospace type. viii Version 3.8

11 1 Managing User Data with LDAP 1. Managing User Data with LDAP Why Use LDAP? Tivoli SecureWay User Administration provides a method for managing user data on any system accessible via the Lightweight Directory Access Protocol (LDAP). LDAP is a directory service protocol that runs over Transmission Control Protocol/Internet Protocol (TCP/IP). It is designed to provide access to the X.500 directory while not incurring the resource requirements of the Directory Access Protocol (DAP). Some ways LDAP can be used include: systems, so user mail accounts can be managed along with system accounts. Native LDAP directories, such as Netscape Directory Server and IBM SecureWay LDAP Directory. Existing directory servers that have added an LDAP front-end to access their data, such as Novell s NDS, and other X.500 directories. An LDAP directory can provide authentication services to applications by storing user IDs and passwords. LDAP is based on the client-server model. One or more LDAP servers contain the data that makes up the LDAP directory tree. An LDAP client connects to an LDAP server and sends a request. No Tivoli SecureWay User Administration LDAP Connection User s Guide 1

12 Why Use LDAP? matter which LDAP server a client connects to, it accesses the same view of the directory (depending upon the user s authorization); thus one LDAP server references the same entry in the directory tree as another LDAP server. Tivoli SecureWay User Administration is based on the Tivoli Configuration and Change Management System (CCMS) architecture. User information is maintained in a profile. Sets of profiles are maintained within a profile manager. Profile managers query and distribute profile information to subscribed profile endpoints. The Tivoli LDAP Connection is a profile endpoint. It is a two-way bridge between Tivoli user profiles and LDAP directories. Data in LDAP directories can be copied to Tivoli user profiles (via populate), and data in user profiles can travel to LDAP directories (via distribute). The LDAP Directory Service Model The LDAP directory service model is based on entries. An entry is a collection of attributes called a class. Each entry has a distinguished name (DN), which is used to unambiguously refer to the entry. Each attribute in the entry has a name, type, and one or more values. The types are typically strings, such as mail for address. The values for an attribute depend on what sort of attribute it is. For example, a mail attribute might contain the value pubs@noontide.com. In LDAP, entries are arranged in a hierarchical structure. Entries representing countries are at the top of the tree. Below the countries are entries representing states, provinces, companies, corporations, and other organizations. Below these are organizational units (OUs) that could represent subsidiaries, divisions, or departments. Finally, the leaf-most entries typically represent people, but they can also exist for things such as printers or badge readers. Each leaf-most entry has a relative distinguished name (RDN) that must be unique among its siblings in that branch of the tree. 2 Version 3.8

13 The LDAP Directory Service Model... c=gb o=noontide c=us Managing User Data with LDAP cn=michael Smith cn:mike Smith fax: The preceding figure is a sample LDAP directory tree. In this figure, c is the LDAP attribute name for country, o is organization, and cn is common name. The RDN for Mr. Smith is cn=michael Smith. This RDN must be unique among its siblings under o=noontide, c=us. Thus, the distinguished name for Mr. Smith is cn=michael Smith, o=noontide, c=us. The LDAP Connection The Tivoli LDAP Connection requires that you install software on both a TMR server and on Tivoli managed nodes. First, install Tivoli SecureWay User Administration, the LDAP Server Install Package, and the LDAP Connection Package on the TMR server. Then, install Tivoli SecureWay User Administration and the LDAP Connection Package on any managed nodes that will host an LDAP Connection. If you choose to install Tivoli SecureWay User Administration and the LDAP Connection Package on the same machine as the LDAP directory server, this machine must have a platform supported by Tivoli. Tivoli SecureWay User Administration LDAP Connection User s Guide 3

14 TMR Server, Tivoli SecureWay User Administration, Tivoli LDAP Server Install Package, Tivoli LDAP Connection Machine 1 1 Tivoli Managed Node, Tivoli SecureWay User Administration 2 Tivoli LDAP Connection LDAP directory server Machine 2 3 The preceding figure shows an LDAP Connection and Tivoli managed node installed on the same machine as the LDAP directory server. You do not have to install Tivoli SecureWay User Administration and the LDAP Connection Package on the same machine that hosts the LDAP directory server as long as the LDAP directory server can be reached by a managed node that is hosting an LDAP Connection. You can choose a configuration that uses a proxy machine to run the managed node and the LDAP Connection. 4 Version 3.8

15 TMR Server, Tivoli SecureWay User Administration, Tivoli LDAP Server Install Package, Tivoli LDAP 1 Tivoli Managed Node, Tivoli SecureWay User Administration 2 Tivoli LDAP connection 3 LDAP directory server 1. Managing User Data with LDAP Machine 1 Proxy Machine 2 Machine 3 This figure shows Tivoli services running on a proxy machine situated between the Tivoli TMR server and the LDAP directory server. In both figures, arrow 3 represents the use of the LDAP protocol over TCP/IP, with the option to use a secure socket. However, for the configuration represented in the figure that shows an LDAP Connection and Tivoli managed node installed on the same machine as the LDAP directory server, it may not be required to use secure sockets, because the Tivoli-LDAP link is on the same machine and does not travel across a network. For more information, see See Configuring LDAP Connection Properties later in this book. The Tivoli TMR server is inherently a managed node, so it is possible to install LDAP Connection on the same machine as the TMR server. Choose a scheme; then install the Tivoli LDAP Connection. Remarks about LDAP Connection This version of the LDAP Connection partially supports Make Exact Copy distribution of user profiles. For Make Exact Copy Tivoli SecureWay User Administration LDAP Connection User s Guide 5

16 distributions, the LDAP Connection will insert all the users in the user profile into the LDAP directory, but it will not remove any entries from the LDAP directory. The installation of the LDAP Server Install Package affects all existing Tivoli SecureWay User Administration user profiles as well as any profiles created in the future. It adds new user profile attributes and a default policy script to all user profiles, including the template user profile. Note: If you have many users, installation of the LDAP Server Install Package can take a while. New User Profile Attributes The new user profile attributes are: LDAP_dn The user s distinguished name. This should be a complete DN. Policy scripts should set a reasonable default and ensure the RDN portion of this DN is unique among its siblings. The value of this attribute may contain %b. During a distribution, the LDAP Connection will substitute its endpoint property Base DN for %b.this user attribute must have a value; if not, the LDAP Connection will make no attempt to insert the user into the LDAP directory. LDAP_dn_as_last_distributed This is the user s Distinguished Name as it was in the LDAP directory from the previous distribution. This attribute is set and used by the LDAP Connection and requires little attention from Tivoli administrators. During a distribution, the LDAP Connection compares the value of this attribute to LDAP_dn. If different, and LDAP_dn_as_last_distributed is not nil, then the LDAP Connection uses it to delete the user s previous location in the LDAP directory before inserting the user again using LDAP_dn. After the distribution, a server-side versioning action (wchgusrprop -v) copies the value of LDAP_dn to LDAP_dn_as_last_distributed. During populate, this variable is set to the same value as LDAP_dn without the use of %b. 6 Version 3.8

17 Use the GUI to Edit Users Distinguished Names After LDAP Connections have been installed, the user profile has a new category and subcategory of attributes for LDAP. There are many attributes in Tivoli user profiles, so Tivoli groups them into categories and subcategories. The new category is LDAP, and the new subcategory is LDAP_panel with a friendly name of LDAP Distinguished Name. To see the new categories, visit the User Properties window. Then select category LDAP. This brings the LDAP Distinguished name panel to the foreground. 1. Managing User Data with LDAP During LDAP Server Install Package installation, LDAP-related user profile attributes are added to all user profiles. Use this dialog to set the distinguished name for this user. Command-line Interfaces The command-line interfaces add flexibility to your LDAP Connection installation. Here is a review of those interfaces. Setting LDAP_dn via CLI: wsetusr sets the value of attributes in a user profile. wsetusr -x can set an attribute by name. For example, to set LDAP_dn in user profile pro1 for the user scarter: wsetusr -x LDAP_dn 'uid=scarter,ou=people,o=airius.com' scarter Tivoli SecureWay User Administration LDAP Connection User s Guide 7

18 The shell is expected to remove the quotes around the DN. (Windows NT CMD.EXE shell expects instead of.) The quotes should not be part of the final LDAP_dn value in the user profile. Or this example: wsetusr -x LDAP_dn scarter shows the use of %b. At distribution time, %b expands to the value of Base DN as set in the LDAP Connection endpoint properties. Default Policy and Validation Policy Scripts During installation, the LDAP Connection installs one default policy script. The default policy script provides a default value for the LDAP_dn attribute when a new user is added. The LDAP Connection does not install validation policy scripts. LDAP_dn Default Policy Script The LDAP Connection installs a default policy for the user profile attribute LDAP_dn. The script accepts one argument, common login, also known as sso_login. It sets the default value of LDAP_dn to be uid=$1,%b such that $1 is replaced by the value of that user s sso_login, and %b will be replaced at distribution time with the value of Base DN, an LDAP Connection attribute. This default policy uses uid, an LDAP attribute. Be sure uid maps to a sensible Tivoli attribute, probably sso_login. For more information, see the commands wlspol, wgetpol, wputpol, and wrmpol. Assigning LDAP Connections as Managed Resources Each policy region maintains a list of managed resource types that are valid or defined for that specific policy region. After installation, you must add LDAP Connections as managed resources before you can manage LDAP user accounts with Tivoli SecureWay User Administration. 8 Version 3.8

19 The following table provides the context and authorization roles required for this task: Activity Context Required Role Add LDAP connections as managed resources for a policy region Policy region senior You can perform this task from the desktop or from the command line. 1. Managing User Data with LDAP Desktop Use the following steps to add an LDAP connection as a managed resource for the policy region: 1. From the policy region, select Managed Resources from the Properties menu to display the Set Managed Resources dialog. 2. Double-click on the LDAP selection in the Available Resources scrolling list. This moves the selected managed resource to the Current Resources scrolling list. 3. Press the Set & Close button to add the new managed resource to the policy region and close the Set Managed Resources dialog. Tivoli SecureWay User Administration LDAP Connection User s Guide 9

20 Command Line The following example adds LDAP connections as managed resources to the policy region: wsetpr where: LDAP Specifies the type of managed resource to add to the policy Specifies the name of the policy region. For more information about using the command line to add user profiles as managed resources for a policy region, see the wsetpr command in the Tivoli Framework Reference Manual. Creating LDAP Connections To manage LDAP user accounts, you must first create an LDAP Connection. The following table provides the context and authorization role required to perform this task: Activity Context Required Role Create an LDAP Profile manager senior connection You can perform this task from the desktop or from the command line. Desktop Use the following steps to create an LDAP connection: 1. From the desktop, double-click on a policy region icon to display the Policy Region window. 10 Version 3.8

21 1. Managing User Data with LDAP 2. Select LDAP from the Create menu option to display the Initialize LDAP Connection dialog. 3. Enter a unique name in the LDAP Connection Icon Label field. This is the label that will be associated with this LDAP connection icon. 4. Enter the name of the managed node on which to run the LDAP Connection in the LDAP Connection Managed Node field. Depending on your installation, the managed node name may not be the same as the LDAP directory service machine name. 5. Press the Set & Close button to create the LDAP Connection and close the Initialize LDAP Connection dialog. Tivoli creates the LDAP Connection and displays the icon in the Profile Manager window. Tivoli SecureWay User Administration LDAP Connection User s Guide 11

22 Command Line The following creates an LDAP Connection: wldap -c PolicyRegionManagedNodeConnectionLabel where: PolicyRegion Specifies the Policy Region for the LDAP Connection ManagedNode Specifies what machine hosts the connection ConnectionLabel Specifies the name of the connection On successful completion, there will be a new LDAP Connection. This lookup command confirms the creation of the new LDAP Connection endpoint: wlookup -ar LDAP Editing LDAP Connection Properties After creating an LDAP Connection endpoint, you must set its properties. For example, the endpoint needs to store the hostname where the LDAP directory service is running. The following table provides the context and authorization role required to perform this task: Activity Context Required Role Edit the properties of an Profile manager senior LDAP connection You can perform this task either from the desktop or from the command line. Desktop Use the following steps to edit the properties of an LDAP Connection: 1. Right-click on the LDAP Connection icon. This presents a pop-up menu. 12 Version 3.8

23 2. Select LDAP Connection Properties. The following dialog is displayed: 1. Managing User Data with LDAP 3. Configure the following settings for Tivoli-LDAP interoperability: Host Enter the hostname (or IP address) of the LDAP directory server machine. Bind DN Enter the distinguished name of the person or Tivoli SecureWay User Administration LDAP Connection User s Guide 13

24 administrator with the authority to perform updates, searches, and deletes against the LDAP directory. Tivoli LDAP Connection will bind as this person when required. For example, the Netscape Directory Server may use the DN cn=directory Manager Bind DN password Enter the password for the Bind DN. Base DN This setting is used during population and distribution. For populate actions, it is the distinguished name of a node in the LDAP directory tree. The LDAP Connection will populate a Tivoli user profile based on the entries it finds under this node. For distributions, the value of Base DN can be used in the specification of a distinguished name. If the value of the LDAP_dn user profile property contains a %b, it will be substituted at distribution time with the value of Base DN. If there is no %b, the LDAP_dn value is used as-is. Class The class name must be person. Additional classes can be specified in the Other classes field. The list of classes govern which attributes are allowed to be set per LDAP directory entry. LDAP protocol version Select version 2 or 3 depending on the implementation of the LDAP directory server. Search scope This setting governs Tivoli behavior when populating a Tivoli user profile from an LDAP directory. one Search one level sub Search a subtree base search the base DN entry Use secure sockets (SSL) Select this check box to add secure sockets layer for the 14 Version 3.8

25 communications link between LDAP Connection and the LDAP directory server. Checking this box requires the additional settings below. Secure socket port Enter the port number where the LDAP directory server is listening for bind requests made in SSL (secure sockets) mode. Key ring file Enter the name of the key ring file prepared with the CLI wmkkf. Key ring file password Enter the password for the key ring file. Certificate name Enter the certificate label (optional) associated with the client certificate in the key ring file. If omitted, will attempt to use the default certificate (set with wmkkf utility). Provide a certificate name to use some certificate other than the default. Non-SSL port Enter the port number where the LDAP server is listening for bind requests from clients using normal (non-ssl) communication links. Other classes Enter a list of Class names to qualify the LDAP attributes given in the Tivoli-LDAP attribute mapping. The inetorgperson class must be added to the list of classes. 1. Managing User Data with LDAP To verify the information you enter in all of the fields on the LDAP Connection Properties window, press the Verify Properties button. Command Line The following command provides an example for editing properties of an LDAP connection: wldap -g ConnectionLabel > outputfile Tivoli SecureWay User Administration LDAP Connection User s Guide 15

26 where: ConnectionLabel Specifies the name of the connection. The -g command ports the connection information to an output file. Use an editor to make changes to the properties in the output file. Then, update the connection by porting the information from the output file using: wldap -s ConnectionLabel < outputfile LDAP connection property values are read from the standard input of the wldap command. See the wldap command for the format of the expected input. Using Tivoli-LDAP Attribute Name Mapping You must provide a mapping of Tivoli user profile attribute names to LDAP objectclass attribute names. The LDAP Connection endpoint uses this mapping during data transfers between Tivoli and the LDAP directory. In most instances you can obtain the LDAP attribute names from objectclass definitions. Your LDAP directory server should provide an interface to this information or query the schema of the directory. When an LDAP Connection is created, some default attribute mappings are added to the list. For example, if you create an LDAP Connection using inetorgperson, you get the following attribute mappings: Tivoli attribute name inetorgperson object class attribute name real_name cn sso_password userpassword sso_login uid Tivoli attribute names are case-sensitive. Depending on the LDAP directory schema, some LDAP attributes are required attributes. Thus, you cannot insert an LDAP entry without supplying values for the required attributes. Refer to your LDAP directory schema to 16 Version 3.8

27 determine which attributes are required and ensure there is a Tivoli-LDAP attribute mapping for them. Note: Certain LDAP attribute names must be qualified with an objectclass name. Use these objectclass names in the Other classes list. Refer to the description for Other classes on page 15. A single Tivoli attribute may map to one or more LDAP attributes. During distribution, the value of the single Tivoli attribute gets assigned to multiple different LDAP attributes. During population, the first Tivoli-LDAP mapping pair has precedence; that is, the value of the first-listed LDAP attribute gets assigned to the Tivoli attribute. The other LDAP attributes mapped to the single Tivoli attribute are ignored, except for strings. When the destination Tivoli attribute is a string or string list, the LDAP Connection will concatenate or append all the LDAP attribute values to the single Tivoli attribute. 1. Managing User Data with LDAP Conversely, a single LDAP attribute may map to one or more Tivoli attributes. During distribution, the LDAP Connection will set the single LDAP attribute multiple times to the values of the multiple Tivoli attributes. Depending on the LDAP objectclasses and attributes, this can be quite acceptable, or it can violate the LDAP directory schema and cause an error. During population, the value of the single LDAP attribute gets assigned to multiple Tivoli attributes. For Tivoli user profile attribute names, refer to Tivoli SecureWay User Administration User and Group Management Guide Desktop To add, change, and delete attribute name mappings, do the following from the LDAP Connection Properties dialog: Tivoli SecureWay User Administration LDAP Connection User s Guide 17

28 1. Select the Tivoli-LDAP Attribute Mapping button. To add a new mapping, enter an attribute name in each of the text-entry fields labeled Tivoli and LDAP; then press the Add button. To delete mappings, select a mapping in the list, then press the Delete button. (To select multiple items, hold down the Control key while selecting list items.) To change a mapping, select a mapping in the list. Its contents will appear in the text-entry fields labeled Tivoli and LDAP. Change the text in the text fields; then press the Change button. 2. Press the Set & Close button to save your changes and close the dialog. 18 Version 3.8

29 Command Line The following command provides an example for editing a mapping on an LDAP connection: wldap -g ConnectionLabel > outputfile where: ConnectionLabel Specifies the name of the connection. 1. Managing User Data with LDAP The -g command ports the connection information to an output file. Use an editor to make the mapping changes in the output file. Then, update the connection by porting the information from the output file using: wldap -s ConnectionLabel < outputfile LDAP connection property values are read from the standard input of the wldap command. See the wldap command for the format of the expected input. Deleting LDAP Connections You may from time to time want to delete an LDAP Connection. You can do this from the command line. The following table provides the context and authorization role required to perform this task: Activity Context Required Role Edit the properties of an Profile manager senior LDAP Connection Desktop To delete an LDAP Connection: 1. Select the connection icon. 2. Select Delete from the Edit menu. Tivoli SecureWay User Administration LDAP Connection User s Guide 19

30 Command Line The following command provides an example for deleting an LDAP Connection: wldap -d ConnectionLabel where: ConnectionLabel Specifies the name of the connection. Using the wmkkf Command This section discusses the functions of wmkkf, including creating key pairs and requesting certificates from certificate authorities. If your client application connects to an LDAP server that requires client and server authentication, you need to create a public-private key pair and a certificate. If your client application connects to an LDAP server that requires only server authentication, you need to designate a keyring file as a trusted root. If the certificate authority that issued the server s certificate is not already defined in your client keyring file, you need to request the certificate authority s certificate from the certificate authority, receive it into your keyring file, and mark it as trusted.for more information, see To designate a key as a trusted root on page 32. The client uses its private key to sign messages sent to servers. The server sends its public key to clients so they can encrypt messages to the server, which the server then decrypts with its private key. The client needs a certificate to send its public key to a server. The server uses the key ring file to store one or more key pairs and certificates. The certificate contains the client s public key, the Distinguished Name associated with the client s certificate, the serial number of the certificate, and the expiration date of the certificate. A certificate is issued by a certificate authority, which verifies the identity of the client. 20 Version 3.8

31 Receiving a Certificate for a Certificate Authority Before you can receive your signed client certificate into the keyring file, you need to obtain the certificate authority s certificate, receive it into your keyring file, and mark it as trusted. Note: In this case, since wmkkf is being used to obtain a client certificate, it is appropriate to generate a low assurance certificate request instead of a server certificate request. A low assurance certificate uses someone s name for the Distinguished Name. For a secure server certificate, the Distinguished Name includes several components that identify the server and where it is located. 1. Create a certificate request using wmkkf. 2. Submit the certificate request to the certificate authority. This is done via or on-line from the certificate authority s web page. 3. Receive the response from the certificate authority to an accessible location on the file system of your server. 4. Receive the certificate into your key ring file. 1. Managing User Data with LDAP Creating a Public-private Key Pair and Requesting a Certificate To Create a public-private key pair and request a certificate, you must perform the following tasks: 1. Change to the path where you want to put the key ring file and certificate request that you are creating with wmkkf. 2. Start wmkkf. 3. Press the N key to create a new key ring file. 4. Enter a key ring filename. If you specify a file that doesn t exist, a new one is created for you. wmkkf puts the file in the directory where you re running wmkkf unless you specify a fully qualified path and file name. Tivoli SecureWay User Administration LDAP Connection User s Guide 21

32 If you want the key ring filename to be KEYFILE.KYR, press the Enter key to continue. wmkkf displays the currently selected key ring. 5. Press the W key to work with keys and certificates or press the C key to create more key pairs and requests. 6. Enter the key ring password. For more information, see To change a key ring password on page Enter the key ring password again for verification. 8. Determine what version of the server you are using. If you have an export version of the server, continue to step 9. If you do not have an export version of the server, choose if you want to assign an expiration date to the key ring password. 9. Choose the kind of certificate request you want to create. To request a low assurance certificate (best used for non-commercial purposes, such as for a beta test of ssl), press the L key and then press the Enter key. To request a secure server certificate, press the S key and then press the Enter key. 10. Provide the following information to create a public-private key pair and a certificate request. Note: wmkkf displays the fields required for the key pair and certificate request. Because this is a new request, all the fields initially contain (none) or 0. You provide the information to create the key pair and the Distinguished Name. You can use non-alphanumeric characters in a Distinguished Name; however, some operating systems have special uses for some of these characters. Press the M key to modify the key and certificate fields. 22 Version 3.8

33 Enter the key name. Note: The key name is the label that identifies the key pair and certificate in the key ring. You may use non-alphanumeric characters in key names; however, keep in mind that some operating systems have special uses for some of these characters. Enter the number for the key size you want (for example, enter 2 for a key size of 512). If you are requesting a low assurance certificate, enter the user s name. This must be unique and is usually the full name of the user. If you are requesting a secure server certificate, enter the following information: Server name This is the X.500 common name of the server. Usually this is the TCP/IP fully qualified host name (for example, For a Verisign server certificate, it must be the fully qualified host name. Organization name This is the name of your organization, such as the name of your company. For a VeriSign secure server certificate, if you already have an account with VeriSign, the name in this field should match the name on that account. Organizational unit name This is an optional field. Locality/city name This is an optional field that shows where the server is located. Three-character abbreviation This shows the state/province where the server is located. 1. Managing User Data with LDAP Tivoli SecureWay User Administration LDAP Connection User s Guide 23

34 Postal code Use the postal code appropriate for the server s location. Two-character country code This shows the country where the server is located. 11. Verify the information you have provided for the key pair and the certificate request. If you want to change any fields, press the M key; then press the Enter key. If you are ready to create the key pair and certificate request, press the R key and then press the Enter key. 12. Enter the name of the file where you want to store the certificate request. If the file does not exist, one is created for you. If you do not specify a fully qualified path name, the file is written in the directory where you invoked wmkkf. Press the Enter key to continue. 13. Exit the wmkkf menus and save the key ring file. a. Press the X key to exit the Key Menu. b. Press the X key to exit the Key Ring Menu. c. Press the Y key to save the Key Ring. d. Press the Enter key to exit wmkkf. 14. Send the certificate request to the certificate authority. Note: If this is a request for a VeriSign low assurance certificate or secure server certificate, you must the certificate request to VeriSign. You can mail the low assurance certificate request to VeriSign immediately. A secure server certificate request requires more documentation. To find out what VeriSign requires for a secure server certificate request, go to the following URL: 24 Version 3.8

35 When you receive the certificate from the certificate authority, use the wmkkf command to receive it into the key ring file where you stored the key pair. Accessing the Key Ring File for Modifications You can access the key ring file by doing the following: 1. Change to the path that has the key ring you want to open. 2. Start wmkkf. 3. Enter the key ring filename or press the O key followed by the Enter key to open the key ring file. 1. Managing User Data with LDAP Note: If you did not change to the path where the key ring is located before starting wmkkf, you must specify the fully qualified path and filename of the key ring. 4. Enter the key ring password. For more information about passwords, see To change a key ring password on page Enter the key ring password again for verification. From the key ring file, you can perform a number of actions. To receive a certificate into a key ring file After receiving a response from your certificate authority, you need to receive the certificate into a key ring file. To receive a certificate into a key ring file: 1. Change to the path where the key ring file for which you want to receive the certificate is located. See Accessing the Key Ring File for Modifications. 2. Press the R key to receive the certificate into the key ring. If the certificate filename is Cert.txt, enter the certificate filename or press the Enter key. Then press the Y key followed by the Enter key. Tivoli SecureWay User Administration LDAP Connection User s Guide 25

36 Note: If you did not change to the path where the certificate file is located before starting wmkkf, you must specify the fully qualified path and filename for the certificate. If you are acting as your own certificate authority, you are prompted whether to accept the self-signed certificate into the key ring. 3. Enter a label to identify this certificate when using wmkkf in the future. 4. Exit the wmkkf menus and save the key ring file. a. Press the X key to exit the Key Ring Menu. b. Press the X key to exit wmkkf. c. Press the Y key; then press the Enter key to save the changed key ring file. d. Press the Enter key to exit. To change a key ring password The password protects the private key. The private key is the only key that can sign documents or decrypt messages encrypted with the public key. The password should be at least six characters, contain at least two nonconsecutive numbers, and be from the U.S. English character set. Make sure the password doesn t contain publicly available information such as your initials, birth date, or the like. To change a key ring password: 1. Change to the path that has the key ring you want to open. For more information, see Accessing the Key Ring File for Modifications on page Press the P key followed by the Enter key to change the key ring password. 3. Enter the current key ring password and press the Enter key. 4. Enter the new key ring password and press the Enter key. 26 Version 3.8

37 5. Enter the key ring password again for verification and press the Enter key. 6. Determine whether you want the password to expire (valid for domestic version only). Note: It s a good practice to change the key ring password frequently. If you specify an expiration date, you need to keep track of when to change the password. If the password expires before you change it, the key ring is not usable until the password is changed. If you want to have the password expire, press the Y key, enter the number of days until the password expires, and press the Enter key to continue. If you do not want the password to expire, press the N key; then press the Enter key to continue. 7. Save the key ring file and exit wmkkf. a. Press the X key to exit the Key Ring Menu. b. Press the X key to exit wmkkf. c. Press the Y key; then press the Enter key to save the changed key ring file. d. Press the Enter key to exit. 1. Managing User Data with LDAP To show information about a key To show information about a key, such as its name, size or whether it is a trusted root: 1. Change to the path where the key ring file you want to open is located. See Accessing the Key Ring File for Modifications on page Select the key about which you want information. a. Press the W key to work with keys and certificates, followed by the Enter key. b. Press the L key to select the key with which you want to work. Tivoli SecureWay User Administration LDAP Connection User s Guide 27

38 If the current key is the key for which you want information, press the S key; then press the Enter key. If the current key is not the key for which you want information, press the N key; then press the Enter key to show the next key in the key ring. Repeat until you find the key you want. 3. Press the S key followed by the Enter key to show information about the key. When through viewing the information, press the Enter key to continue. 4. Save the key ring file and exit wmkkf. a. Press the X key to exit the Key Ring Menu. b. Press the X key to exit wmkkf. c. Press the Y key; then press the Enter key to save the key ring file. d. Press the Enter key to exit. To delete a key To delete a key: 1. Change to the path where the key ring file you want to open is located. See Accessing the Key Ring File for Modifications on page Select the key you want to delete. 3. Select the key about which you want information. a. Press the W key to work with keys and certificates, followed by the Enter key. b. Press the L key to select the key with which you want to work. If the current key is the key for which you want information, press the S key; then press the Enter key. 28 Version 3.8

39 If the current key is not the key for which you want information, press the N key; then press the Enter key to show the next key in the key ring. Repeat until you find the key you want. 4. Select the key you want to delete. a. Press the D key followed by the Enter key to delete the selected key from the key ring. b. Press the Y key followed by the Enter key to confirm that you want to delete the key. c. Press the Enter key to continue. 5. Save the key ring file and exit wmkkf. a. Press the X key to exit the Key Ring Menu. b. Press the X key to exit wmkkf. c. Press the Y key followed by the Enter key to save the changed key ring file. d. Press the Enter key to exit. 1. Managing User Data with LDAP To make a key the default key in the key ring The default key should be the private key the server uses for its secure communications. To define a key as the default key in the key ring file: 1. Change to the path where the key ring file you want to open is located. See Accessing the Key Ring File for Modifications on page Select the key that you want to make the default key. a. Press the W key to work with keys and certificates; then press the Enter key. b. Press the L key to select the key with which you want to work. If the current key is the key you want, press the S key; then press the Enter key. Tivoli SecureWay User Administration LDAP Connection User s Guide 29

40 If the current key is not the key you want, press the N key; then press the Enter key to show the next key in the key ring. Repeat until you find the key you want. 3. Make the selected key the default key in the key ring file. a. Press the F key; then press the Enter key to make the key the default key in the key ring. b. Press the Y key followed by the Enter key to confirm. c. Press the Enter key to continue. 4. Save the key ring file and exit wmkkf. a. Press the X key to exit the Key Ring Menu. b. Press the X key to exit wmkkf. c. Press the Y key; then press the Enter key to save the changed key ring file. d. Press the Enter key to exit. To export a key If you need to transfer a key pair or certificate to another computer, you can export it from its key ring to a file. On the other computer, you can import it into a key ring. To export a key from a key ring: 1. Change to the path where the key ring file you want to open is located. See Accessing the Key Ring File for Modifications on page Select the key you want to export from the key ring. a. Press the W key to work with keys and certificates; then press the Enter key. b. Press the L key to select the key with which you want to work. If the current key is the key you want, press the S key; then press the Enter key. 30 Version 3.8

41 If the current key is not the key you want, press the N key; then press the Enter key to show the next key in the key ring. Repeat until you find the key you want. 3. Export the selected key from the key ring. a. Press the E key followed by the Enter key to begin. b. Enter the export filename; then press the Enter key. c. Enter the armor password used to protect the exported file; then press the Enter key. 1. Managing User Data with LDAP d. Enter the armor password again for verification and press the Enter key. 4. Save the key ring file and exit wmkkf. a. Press the X key to exit the Key Ring Menu. b. Press the X key to exit wmkkf. c. Press the Y key followed by the Enter key to save the changed key ring file. d. Press the Enter key to exit. To import a key To import a key into a key ring: 1. Change to the path where the key ring file you want to open is located. See Accessing the Key Ring File for Modifications on page Import the key into the key ring. a. Press the W key to work with keys and certificates; then press the Enter key. b. Press the I key followed by the Enter key to import the key. c. Enter the export filename and press the Enter key. This is the name of the file containing the key you want to import. d. Enter the armor password to protect the file you want to import and press the Enter key. Tivoli SecureWay User Administration LDAP Connection User s Guide 31