7.5 zOS LDAP Native Authentication

---

7.5 z/OS LDAP Native Authentication

The native authentication feature uses LDAP with TDBM, and any of the V3 person type object classes, since they have the appropriate attributes for this method of authentication. Portal Server still uses CUR and accesses LDAP for its authentication step, but from a z/OS and OS/390 platform perspective the authentication is actually performed by RACF using all its usual stringent rules. From a management perspective there is no need for administration of multiple registries or synchronization of passwords. Native authentication is implemented through the addition of an LDAP attribute called ibm-nativeId.

More importantly, from a WebSphere Portal perspective, RACF users and non-RACF users can be defined in the same LDAP directory and portal users are unaware of any differences from what is normally done to log into the portal.

Attention: 

The z/OS LDAP Native Authentication setup is optional. This is not a requirement for WebSphere Portal Server configuration and installation.

7.5.1 The scenario

If all portal users are created from new, then all those userids will be created in LDAP server as normal. More often than not, z/OS enterprises will have existing users in RACF who need access to the portal along with the newly registered external portal users. Therefore a mechanism is needed to be able to authenticate using both LDAP and RACF.

7.5.2 The proposed solution

As was mentioned in Chapter 1, "Benefits of having WebSphere Portal on z/OS" on page 16 one of the benefits of having the LDAP server running on the z/OS system is that you can do native authentication. Native authentication allows connection between the LDAP server and RACF wherein the userid and password that is used to authenticate to LDAP is actually passed to the System Security Server to be verified. This setup allows new internet or extranet portal customers to authenticate directly against the LDAP server, while existing RACF intranet users would be authenticated using their RACF userid and password. The architecture at a high level is shown Figure 7-12 on page 299, where userid java3 is also configured as the native-id attribute in LDAP, resulting in the authentication request going to RACF. For a complete description of how this is done refer to Putting the Latest z/OS Security Features to Work, SG24-6540.

Figure 7-12: Portal login binding to LDAP server using RACF Native Authentication

7.5.3 Steps to implement the solution

The way we implemented the solution was basically to re-run some of the LDAP configuration steps described in Step seven: Configure LDAP server. There are two parts:

1. Add the object class to the LDAP server.

2. Add the attribute to user entries in LDAP.

1. Add the object class to the LDAP server

We show the steps performed on our z/OS system to add the required object class to the LDAP server.

Create a specific IBM schema

The schema to be added is an IBM schema that includes definitions for handling Native Authentication from LDAP to RACF. It is stored in an LDAP Directory Interchange Format (LDIF) file called schema.IBM.ldif that is found in the /tmp directory. We made a copy of that file in the /tmp directory and called it schema.IBM.itso.ldif. The only modifications made to it are shown in Example 7-1.

Example 7-1: schema.IBM.itso.ldif file extract

 (...) dn: dc=ibm,dc=com changetype:modify add:attributetypes (...) 

We changed the DN to match the DN that we used for WebSphere Portal on z/OS and OS/390 namely, "dc=itso,dc=com". By default the file contains O=WASLRAC because it applies to the WebSphere Application Server DN which we were not using.

Create a specific bbomtdbm.sh script

In order to apply this new schema you can copy and reuse the existing shell script of WebSphere Application Server and point to our new LDIF file.

Note 

Do not change the original LDIF file because you will not be able to build a new LDAP server for WebSphere Application Server.

We copied /tmp/bboldtbm.sh to /tmp/bbomtdbmitso.sh and made the modifications as shown in Example 7-2:

Example 7-2: bboltdbmitso.sh file

 LDAPUSERID=$1 LDAPPWD=$2 ldapmodify -h 127.0.0.1 -p 2389 -D $LDAPUSERID -w $LDAPPWD -f /tmp/schema.IBM.itso.ldif 

Important: 

Note that there are only three lines in Example 7-2, such that each of the lines beginning with ldapmodify must be contained wholly within a single line.

Modify the schema

In order to modify the schema you need to run the modified bboltdmmitso.sh shell script. Make sure you are logged to the system as a user with UID=0 and run the script as shown:

    bboltdbmitso.sh "cn=CBAdmin" <password> 

The generic syntax of that command is:

    bboltdbmitso.sh "<LDAP_ADMIN>"<LDAP_ADMIN_PWD> 

The output of that script should tell you that your DN was modified.

Enable Native Authentication

To enable native authentication in Portal for z/OS LDAP server you need to modify the property file (slapd.conf) of the specific LDAP server used for portal. That file is located <WAS_HOME>/<SYSPLEX_NAME>/etc/ldap and is called <SYSPLEX_NAME>.bboslapd.conf.portal.

In our case it was:

    /WebSphere390/CB390/PLEX58/etc/ldap/SC58.bboslapd.conf.portal. 

Modify the file as shown in Example 7-3 in bold. Instead of "dc=ibm,dc=com" you need to specify the DN suffix you chose for your z/OS portal. It has to match the suffix that is recognized by TDBM which you should find at the end of your file.

Example 7-3: Enable Native Authentication in <SYSPLEX_NAME>.bboslapd.conf.portal

 (...) #------------------------------------------------- # tdbm database definitions #------------------------------------------------- database tdbm GLDBTDBM servername   DB2A databasename BBOLDAT dbuserid     BBOLDAT attroverflowsize 255 extendedgroupsearching on usenativeauth selected nativeauthsubtree dc=ibm,dc=com nativeupdateallowed off suffix   "dc=ibm,dc=com" 

Configuration options of the three parameters are as follows:

• useNativeAuth <selected | all | off>

  • selected - only entries located in native subtrees that contain the ibm-nativeId attribute will be subject to native authentication

  • all - every entry in native subtrees will use native authentication and the RACF ID can be specified with either the ibm-nativeId or UID attribute

  • off - Native Authentication is disabled

• nativeAuthSubtree <all | DN>

  • all - the entire TDBM directory will use native authentication

  • DN - subtree containing entries that will use native authentication. This option might be specified multiple times to allow for several native authenticating sub-trees.

• nativeUpdateAllowed <on / yes | off / no>

  • on / yes - allow updating of the native RACF password

  • off / no - not allowed to update the native RACF password

Note 

Our recommendation is to not allow native RACF password updates.

Restart Portal for z/OS LDAP server

The LDAP server for WebSphere Portal on z/OS and OS/390 should be restarted, for the changes that were made to enable Native authentication, to take effect.

• First stop the LDAP server by issuing the following command: /P BBOLDAT

• Then restart the LDAP server by issuing the start command: /S BBOLDAT.

Examine the log for the BBOLDAT job. It should show that Native Authentication is enabled as shown in Example 7-13 on page 303. Notice the line that reads - GLD3132I The useNativeAuth configuration option SELECTED has been enabled.

Figure 7-13: Portal for z/OS LDAP server startup with Native Authentication enabled

2. Add the attribute to user entries in LDAP

Using the DMT as an example we show how to add the ibm-nativeId attribute to users in LDAP.

Modifying the user attribute in LDAP

IBM Directory Server (IDS) comes with a client tool that can connect to any LDAP server and allows you to manage the directory. It is known as the Directory Management Tool (DMT) and the executable is found in <IDS_HOME>/bin directory on the distributed platform. We used this graphical user interface (GUI) tool to see the changes made in the previous step and to manually add the attribute to a user entry.

There are other LDAP browsers that one could use.

Note 

The manual steps to add an attribute described here are simply to demonstrate what needs to be done. In a production environment we recommend using some kind of a LDAP modification script that can handle a large number of user entries in bulk.

One possibility is to generate a flat file output of RACF database using the IRRDBU00 utility. Then use a program to create a LDIF file from that IRRDBU00 output and import it into LDAP.

1. Start DMT client and connect to the LDAP server on z/OS and OS/390. We used port 2389 to connect to the LDAP server on our server.

2. Use Simple Authentication to bind to the server, by giving the User DN and User password of the LDAP administrative user, so that you will be able to view and edit the LDAP server tree. See Figure 7-14.

   
   Figure 7-14: Adding LDAP server in DMT

3. To view the object class that was added to LDAP in the previous step on z/OS, in the left navigation pane, navigate down to Schema->Object classes->View object classes. All the object classes will be displayed in the main window.

4. Find ibm-nativeAuthentication object class and click on the plus sign to see the details of the schema as shown in Figure 7-15. Notice the object class has one required attribute namely, ibm-nativeId.

   
   Figure 7-15: Viewing the installed object classes

5. You can view the details of the attributes by navigating down to Schema->Attributes->View attributes in the navigation pane.

6. In the main window search for ibm-nativeId and expand it by clicking on the plus icon. From Figure 7-16 we can see this attribute is of String type and its value is not case-sensitive.

   
   Figure 7-16: Viewing the ibm-nativeId attribute

7. If you click on Browse tree in the navigation pane you will see the LDAP tree. Expand the suffix that is in use for WebSphere Portal on z/OS and OS/390 and you should see something similar to what is shown in Figure 7-17 on page 307. Note, our suffix was dc=ibm,dc=com.

   
   Figure 7-17: Browsing the LDAP tree used by WebSphere Portal on z/OS

8. Before you can add the attribute to the user, that attribute should be available at the higher Root DN (RDN™). In this case the ibm-nativeId attribute should first be added to cn=users.

9. Highlight cn=users and click Add auxiliary class. In the pop-up window, select ibm-nativeAuthentication and click OK as shown in Figure 7-18 on page 308.

   
   Figure 7-18: Adding auxiliary class at the cn=users level

10. Now add that class to a LDAP user. In a similar manner highlight the user and click Add auxiliary class. In the pop-up window, select ibm-nativeAuthentication and click OK. We chose uid=JAVA3 as shown in Figure 7-19.

    
    Figure 7-19: Adding auxiliary class at the UID level

11. If you examine the attribute details of the user id that was modified you will see a new required attribute called ibm-nativeId. You can view the attributes by highlighting uid=JAVA3 in the main window of DMT and clicking Edit. Notice the label is displayed in bold, indicating that this is a required field.

12. The value of this attribute should be the RACF user id. Enter the RACF UID and click OK. In our case the RACF UID was also JAVA3. See Figure 7-20.

    
    Figure 7-20: Adding the RACF UID value in the ibm-nativeID field

13. The next step is to verify that all the modifications done to enable LDAP native authentication actually work.

7.5.4 Solution verification

Bring up the WebSphere Portal login page via the URL

• http://<HOST_NAME>/wps/myportal

Enter the User ID and Password and make sure you can authenticate successfully. Interestingly, when you log into WebSphere Portal successfully there is no way to tell whether the authentication was done by the LDAP server or by RACF. Therefore, to verify that the native authentication is truly setup correctly, you have to run a negative test.

Enter the User ID of a user that exists in RACF. Enter a wrong password and attempt to login. You should not be successful. If you examine the system log using z/OS System Display and Search Facility (SDSF) you should see a message from RACF rejecting the authentication. That tells us that the userid and password was passed on to RACF because of the special LDAP attribute, namely ibm-nativeId, and indeed RACF performed the authentication check but returned a failure.

That successfully demonstrates the setup and verification of Native Authentication.

7.5.5 Tips for exporting RACF users to LDAP

Here we provide sample solutions to add RACF users to the LDAP database.

Accessing RACF via an LDAP browser

Users in RACF can be exported to an LDAP LDIF file by using an LDAP client. For example we used a freely available LDAP Browser with an LDIF export capability. To use the LDAP client and access RACF you need to sign on with the following DN format: racfid=<userid>,profiletype=user,o=WASLRAC as shown in Figure 7-21.

Figure 7-21: Accessing RACF via an LDAP client

Figure 7-22 on page 311 shows the LDAP client display of users in RACF.

Figure 7-22: RACF users displayed in an LDAP client

After using the LDAP client to export all the users to an LDIF file the format, the partial contents of the file is shown in Example 7-4.

Example 7-4: Example of LDIF export from RACF

 dn: racfid=ALEX,profiletype=USER, o=WASLRAC dn: racfid=ALEX1,profiletype=USER, o=WASLRAC dn: racfid=ALEX2,profiletype=USER, o=WASLRAC dn: racfid=ALVAREZ,profiletype=USER, o=WASLRAC dn: racfid=AMCHENG,profiletype=USER, o=WASLRAC dn: racfid=ANDY,profiletype=USER, o=WASLRAC dn: racfid=ANTOGNI,profiletype=USER, o=WASLRAC dn: racfid=ANTONIO,profiletype=USER, o=WASLRAC dn: racfid=ARDINI,profiletype=USER, o=WASLRAC dn: racfid=ARMIGES,profiletype=USER, o=WASLRAC 

This format, with a single line for each user is quite easy to modify using a variety of tools. The only part we are interested in is the userid's identified by field racfid. We need to identify which users we do want to add to the Portal Server LDAP for native authentication and discard all other users. A suggested way to parse and modify the file are:

• Use macros in a word processor

• User macros in a spreadsheet

• Use a script, for example REXX or UNIX shell

• If the number of users is small, use an LDAP editor

The LDIF format exported needs to be parsed as suggested and converted into the LDIF format used by Portal Server, with its required attributes. As an example of this we added two users. CHEN and JAVA7 to an LDIF file, we called NAUpdate.ldif as shown in Example 7-5. Note that the required format does not use or need an attribute for the userpassword.

Example 7-5: NAUpdate.ldif, LDIF file for portal using native authentication

 dn: uid=CHEN,cn=users, dc=ibm,dc=com givenname: Chen ibm-nativeid: CHEN sn: Chen mail: [e-mail] objectclass: top objectclass: inetOrgPerson objectclass: Person objectclass: ORGANIZATIONALPERSON objectclass: ibm-nativeAuthentication uid: CHEN cn: Chen preferredlanguage: en dn: uid=JAVA7,cn=users, dc=ibm,dc=com givenname: Java7 ibm-nativeid: JAVA7 sn: Java7 mail: [e-mail] objectclass: top objectclass: inetOrgPerson objectclass: Person objectclass: ORGANIZATIONALPERSON objectclass: ibm-nativeAuthentication uid: JAVA7 cn: Java7 preferredlanguage: en 

In our example user CHEN was not in RACF, but user JAVA7 was in RACF. We added the users to the Portal server LDIF by executing the following command:

    ldapmodify -a -p 2389 -f ./NAUpdate.ldif -D "cn=CBAdmin" -w    <password> 

After this we tested that the changes were successful as follows:

We tried to login to Portal server using userid CHEN. This did not succeed due to an authentication error because userid CHEN was not in RACF.

We logged in successfully to Portal server using userid JAVA7, which was in RACF, and confirms the successful modification of LDAP with users authenticating via native authentication.

7.5.6 Mass-exporting RACF users to LDAP

If you are planning on exporting a large amount of RACF userid(s) into LDAP server as registered Portal users, use the following example.

Note 

The mass-exporting RACF users to LDAP is not a requirement for Portal Server configuration and installation. This can be part of initial environment set up for a corporate Portal. Instead of having all employees to self-register or the RACF, LDAP administrators to register all individual employees as portal users.

The mass-exporting RACF users to LDAP requires LDAP Native Authentication.

Exporting from RACF

First, here are the steps for exporting your RACF native userids to a file using the LDAP Browser which has an LDIF export capability.

• You need to sign on to the LDAP Browser with a valid RACFID as shown in Figure 7-21 on page 310.

• Move your mouse to the objectclass "profiletype=user" and click on it. Move your mouse to the browser's menu "LDIF" and select "Export".

• Click the "All children" option; expand the "…" folder option on the upper-right corner and select your desired folder and enter the file name.

• Click the "Export" button and the file will be generated.

Running the REXX program

Second, we have prepared and tested a sample REXX program and a template file with predefined tokens similar to Example 7-5 on page 312 for you to use. Please refer to Appendix D, "Additional material" on page 339 for details how to get the files. You will need to unzip the downloaded file. The zip file contains:

• A REXX program convldif.rexx (see Example C-1 on page 331).

• A template file template.ldif (see Figure 7-23).

  
  Figure 7-23: Sample LDIF template

• A sample exported RACF users list file (see Figure 7-24 on page 315).

  
  Figure 7-24: The exported RACFID sample file

• A sample merged output file merged.output. (see Figure 7-25 on page 315).

  
  Figure 7-25: Merged sample LDIF output file

You will then need to upload all these four files to the z/OS mainframe area.

Logon to TSO and use ISPF 3.2 to create three new datasets:

• "<YourHLQ>.RACFID.INPUT" (RACF userid list file)

• "<YourHLQ>.TEMPLATE.INPUT" (Template ldif input file)

• "<YourHLQ>.MERGED.OUTPUT"(Merged ldif output file).

The RACF users and the template input datasets should have PS Organization, RECFM=FB and record length of 80, whereas the merged output dataset should have PS Organization, RECFM=VB and Record Length of 255.

These three files are used by the sample REXX program convldif.rexx. Also copy the REXX program convldif.rexx to your Portal Server Installation library (that is, "<YourHLQ>.JOBS.CNTL") as the member CONVLDIF. Do the following customization:

• The REXX program CONVLDIF

  Replace all three <YourHLQ> to match with your selected dataset names. See Example C-1 on page 331.

• <YourHLQ>.RACFID.INPUT

  This input file contains the begin pattern of 'racfid=' and the end pattern ',' that the REXX program CONVLDIF will extract any names specified in between the two patterns.

• <YourHLQ>.TEMPLATE.INPUT

  The template file contains three recognized token names to be replaced by the extracted RACF userid names.

  • #racfid1 is the default userid name in uppercase

  • #racfid2 is the userid name in lowercase

  • #racfid3 is the userid name with first letter in upper case

  Note 

  Only one token per line will be replaced with extracted RACF name and any line which doesn't have those three recognized definitions will be generated as is. You will also need to change the "dc=ibm,dc=com".

• <YourHLQ>.MERGED.OUTPUT

  After running the REXX exec, this file will contain the generated output in ldif format. Make sure the template file format is valid, so the output file will contain the valid ldif format as well.

To invoke the REXX program, you should logon to TSO, then ISPF and select option 6, "command". At the ISPF Command Shell prompt, enter "exec <YourHLQ>.JOBS.CNTL(CONVLDIF)" to execute the CONVLDIF REXX program. The merged output should be in the <YourHLQ>.MERGED.OUTPUT dataset.

Importing into LDAP

Once you have modified all the required dataset prefixes and ldif suffix changes, you should be able to execute this REXX program and review the merged output file. After validating the results, the next step is to import the ldif file into your Portal LDAP server using the ldapmodify command.

 ldapmodify -a -h 127.0.0.1 -p <your LDAP port #> -D cn=CBAdmin -w <pswd> -f <your ldif file name> 

---