IBM Support

How to configure EIM and NAS using IBM Heritage Navigator for i

Question & Answer


Question

How can I configure Single Sign-on using the IBM Heritage Navigator for i GUI?

Answer

NOTE: If you would like to configure Single Sign-on using the new IBM Navigator for i GUI, please refer to the following documentation:

How to configure EIM and NAS using IBM Navigator for i


Configuring Single Sign-On using Heritage Navigator for i

Prerequisites

It is recommended to go through the Single Sign-on Configuration Planning Worksheets prior to configuring Single Sign-on. The worksheets can be found here: Single Sign-on Configuration Planning Worksheets

The IBM Tivoli Directory Server (LDAP) must be active and have a basic working configuration. If a cleanup and configure of LDAP is needed, refer to Complete LDAP / Directory Server Cleanup and Reconfigure


The HTTP *Admin server must be active and the latest HTTP group PTF level is recommended to be installed.


To access the IBM Heritage Navigator for i page the HTTP server ADMIN must be active in the QHTTPSVR subsystem as seen below. If it is not active, use the following command:

STRTCPSVR SERVER(*HTTP) HTTPSVR(*ADMIN)

This may take anywhere from 5 minutes to 1/2 hour + (depending on system size/resources) to become fully active.**

NOTE: The IBM Heritage Navigator for i GUI runs in the ADMIN2 job, which was recently set not to autostart due to a recent Log4J vulnerability exposure.  See the following site for information about this and how to enable ADMIN2 to access the GUI:

Security Bulletin: IBM i components are affected by CVE-2021-4104 (log4j version 1.x)


You should have 3 ADMIN jobs as well as ADMIN1 through ADMIN5 active.

Access the IBM Heritage Navigator for i page

If the Admin jobs are active, use the following URL and replace <system_name or IP> with your IBM i system name or IP address:

http:// <system_name or IP> :2001

You should be prompted for your user ID and password. This is the same user ID and password you use to log into the IBM i system.

Log in using your IBM i credentials

  •     
  •         Configure Network Authentication Service (NAS)



    We recommend configuring NAS prior to configuring EIM. This is due to the fact that the majority of problems seen with initial configuration is due to improper NAS configuration and/or DNS resolution issues. For this reason it is highly recommended that you first go through the NAS configuration and test it prior to moving on to the Enterprise Identity Mapping (EIM) setup.

    Host Name Resolution - The #1 most common problem with new SSO configurations

    Take note of the following two crucial elements that will help you get a successful NAS configuration:

    1.  Have the IBM i system's fully qualified domain name (FQDN) as the first name in the list for the IP address it is associated with in the local host table (LHT).
      image-20190627161256-1
       
    2.  Test DNS lookups for the IBM i using both the name and the IP.  Note that it is recommended the same DNS server is used by the client PC and the IBM i.  You can check what DNS server you are using on the IBM i by typing CHGTCPDMN <F4> and page down to see the Domain Name Servers.  The top one in the list is the primary one used.

      To test the DNS lookups you can use the NSLOOKUP command from your PC's command prompt.  You can also do this on the IBM i but you need 5770SS1 option 31 (Domain name server) installed for the NSLOOKUP command to work.  Note the commands used in the image below and the results.
      image-20190627164347-3
      In the above screenshot the things to note are the IP address returned from the first lookup of the name used (rch730a.rchland.ibm.com) and the name returned when using "set type=ptr" to change the lookup to a "Reverse Lookup".  In this case the system name returned is the same fully qualified domain name that was entered above.  This is a successful test.  If the name returned by the PTR lookup was different than the name you typed in for the "A" record lookup (meaning it comes back with either JUST the short name or a different name entirely, or no name at all), an adjustment would need to be made to the DNS server to fix the record.


    **Refer to your planning worksheet details for what information to fill in the fields as you go through the wizard.**

    Step 1 - Open Network Authentication Services from the Navigator for i

    • Click on Security > All Tasks > Network Authentication Service > configure and then click Next to begin.
       
      NAS configuration wizard welcome screen

    Step 2 - Specify realm information
    • The Default realm is typically the Microsoft Windows domain that the users log in to from their PC. If you are using a Windows server (any version) as your primary domain controller, leave the box checked for "Microsoft Active Directory is used for Kerberos authentication". In the image below, "rchland.ibm.com" is used for our local domain example.
       

    Step 3 - Specify the fully qualified domain name of your KDC
    • The KDC (or Key Distribution Center) is typically the primary Windows server that has Active Directory configured on it. The Fully Qualified Domain Name refers to the server's full name, which is the host name...or system name, with the domain name appended to it. The default Kerberos port is 88 which should not be changed unless your network administrator has specifically changed this on the KDC. This example uses the server's host name of ctawinsvr and the domain of rchland.ibm.com is appended to it to make the fully qualified domain name (or FQDN).
       

    Step 4 - Specify Password Server Information
    • The default values can be kept here. The explanation of the password server is at the top of this window. Click Next to continue.
       
    Step 5 - Select the keytab entries to be created
    • By default, all boxes are checked. Each one will create service principal entries for the respective service. The service used for all 5250 and telnet emulation sessions is the top one - IBM i Kerberos Authentication.

      *NOTE*
      Use caution when configuring NetServer for SSO. If the principal is added to the Active Directory server (one of the last steps of NAS configuration) and you have not yet created EIM Identifiers and Associations for users, you may experience a loss of NetServer service (mapped drives to the i).
       
    Step 6 - Generate passwords for each service principal that you will use.
    • You will need to create a password for each service principal you checked in the previous screen. These passwords will ONLY be used to encrypt/decrypt the tickets by the KDC and the IBM i. Be sure that the password used falls within the password policies in place for your KDC (typically the Microsoft AD server).
       

    Step 7 - Batch File
    • This next screen gives you the option of having the wizard generate a batch file which must be sent to, and run on the Microsoft Windows Active Directory server (only). Note that the default location and name of the batch file stored is:
      /QIBM/UserData/OS400/iSeriesNavigator/config/NASConfig_CTA05.bat
      (The name will change depending on your system name as you will see the one here is called NASConfig_CTA05.bat because my example system is CTA05).

      If you do not want the passwords included in the batch file, remove the check from the respective check box. Be aware though that you will be prompted to manually enter the password for each service principal while the batch file runs on the AD server. Any mistakes will cause failures with the Single Sign-on connections. We recommend checking the box next to the option "Set the AD service principal passwords to never expire". If a service principal password expires, SSO connections that use that principal will fail to connect. If this happens, the password must be changed/renewed not only on the AD entry, but in the NAS keytab list as well.

    • What does this batch file do?
      • The batch file is created to make it easy for you to add the required Active Directory user entries. It takes a few seconds to run, adds all of the required service principals to Active Directory, and it is in plain text so you can edit the file to see what is in it (no hidden commands or functions). Many Windows administrators prefer to add the entries themselves which is ok, as long as it is done correctly. When incorrectly added, NAS (and therefore Single Signon) will fail to work. Here is an excerpt of what is in the batch file when generating a principal for krbsvr400.
    DSADD user "cn=CTA05_1_krbsvr400,cn=users,dc=RCHLAND,dc=IBM,dc=COM" -pwd Passw0rd -display CTA05_1_krbsvr400 -pwdneverexpires yes -desc "IBM i Kerberos services on system CTA05"
    KTPASS -MAPUSER CTA05_1_krbsvr400 -PRINC krbsvr400/[email protected] -PASS Passw0rd -mapop set -crypto All -ptype KRB5_NT_PRINCIPAL
      • *Note* The password - PasswOrd is included in this batch file example in plain text. If you unchecked the box "Include password in the batch file" from the previous screen capture above, the password would not show in this batch file.

        Once the batch file is run on the AD server (or if the Windows administrator correctly added the account to AD) it should look similar to this:
     
    In this image you can see the default naming convention when the batch file is run on the Active Directory server. The default location that the batch file creates these accounts is in the domain Users folder shown on the right. The default name of the accounts will have the system name followed by a number, then the service principal prefix.
    This is an image of the properties of the user account. Note that we are concerned with the details of the Account tab. The User logon name should look like the example to the right, but it should show your own system name and domain. Note that the checkbox for "Password never expires" is checked. If the box is not checked, the password will expire after the number of days dictated by the Windows Password Policy. If this happens, all users connected via Kerberos authentication will fail to connect.
    Under the Account options section, check the box(es) for the AES 256 and/or 128-bit encryption types. Uncheck the box for DES encryption.
    Click the Apply button to confirm the change.


    image-20190920123842-1
    This is an image of the Delegation tab of the same user account for krbsvr400. Delegation is not necessarily required for getting SSO to work for Telnet/5250 sessions, but it is required for a number of other applications to function with SSO, including FTP, QNTC, HTTP, and several others. For this reason, it is recommended the options be set similar to what is shown here. Windows administrators may be able to customize this further to their own requirements if necessary.

    • Step 8 - Test the NAS configuration
      • Now that the NAS configuration is complete and the batch file has been run on the AD server (or the entries were created manually), it is time to test the configuration. Before we do this however, to avoid a few commonly seen errors, you will want to make sure two things are done:

        First: Go into the Network Authentication Service properties and make sure the "Use TCP" box is checked.


      • The Second thing you will want to make sure of is that the user profile running the steps below has a /home/<user> directory in the IFS. If not, you can use the command mkdir /home/<user profile name>. This MUST exist or you will get an error when running the steps below.

        Once that is done, use these steps to test NAS:

        1. Open QSHELL on your IBM i emulation session using the command QSH <enter>
        2. Type keytab list and hit enter
        3. Scroll back up until you find the krbsvr400/<system.domain> entry similar to the screen capture below and then copy that entry name
        4. Type kinit -k and paste in the krbsvr400 entry after it, then hit enter.

    •  
      • The blue arrow in the image above points to the $ prompt. If you get this back after issuing the kinit -k command (as shown in the image) then you have a successful test.
        Congratulations! Now it's time to configure EIM.

  •         IBM Tivoli Directory Server (LDAP) Setup



    The IBM Tivoli Directory Server (LDAP server) must be active and have a basic configuration. All EIM data is stored within LDAP, however it will not affect any existing LDAP configurations. If LDAP is not functioning and it is NOT currently in use, you can use the instructions on the Complete LDAP / Directory Server Cleanup and Reconfigure page to start with a fresh LDAP setup.

    Once LDAP is configured or if it is already configured, you will need to know the password for cn=administrator. This is the default LDAP administrator account. You can set this in the properties for the IBM Tivoli Directory Server from the Network > Servers > TCP/IP Servers section of IBM i Navigator.

    • 1. Right-click IBM Tivoli Directory Server for IBM i and click on "Properties"

    • 2. On the General tab, click on the "Password" button next to Administrator name: cn=Administrator

    • 3. Set the desired password for the LDAP administrator and click OK.
    Then click OK again on the LDAP properties page. This will set the LDAP administrator password which will be used in the EIM configuration wizard and for future editing of the EIM entries.
    • Once the password is set, you can start the EIM Configuration Wizard.
  •         Configure Enterprise Identity Mapping



    Step 1 - Open Enterprise Identity Mapping from the Navigator for i window and start the configuration wizard

    • Click on Network > All Tasks > Enterprise Identity Mapping > Configuration > Configure to start the wizard, and then click on the option to Create and Join a new domain, then click Next.
      *NOTE* The "New domain" referred to here is an EIM domain, not a Windows domain. It is created within LDAP and is separate from any other parts of LDAP or domains. It will not interfere with any network domains.


    Step 2 - Take the default option of "On the local directory server"
    • The Directory Server it refers to is the local LDAP server on the i. As stated previously, EIM data is stored in LDAP on the i. Click Next to continue.

    Step 3 - Do not configure Network Authentication Service
    • NAS was configured in the first part of this document. You can select "No" and click Next to continue.


    Step 4 - Specify User For Connection
    • The configuration wizard needs to connect to LDAP with an authorized user/administrator. The default is the LDAP administrator distinguished name of cn=Administrator. You will need to know the password for cn=administrator which you should have set just prior to these steps (If not, refer to the 3 steps under the title: "Before configuring EIM" earlier in this document).
      Enter the password and the confirmed password, then click on "Verify Connection". If this fails, the password here and the password set for cn=Administrator in the LDAP properties does not match. Use the steps above to set the password again and make sure the LDAP server is active.

      Once the connection is verified successfully, click "OK" and then click "Next" to continue.
       

    Step 5 - Specify the EIM Domain Name

    • The default domain name is simply EIM. You can change this to something else if you prefer but it is not required. Click Next to continue.


    Step 6 - Parent Distinguished Name
    • You do not have to specify a Parent DN for the EIM data. By default, the EIM Wizard will create the EIM data in its own subdirectory. This option is only recommended for those who are familiar with LDAP administration. We recommend keeping this option at its default value of "No".

    Step 7 - Registry Information

     

    The Registry Information should already be filled in based on values entered in the NAS configuration. Leave the default values (which should have your IBM i fully qualified name as the Local IBM i and the domain name for your Windows domain server). Click Next to continue.

      Step 8 - Specify EIM System User


      • The operating system connects to the domain controller as this user when performing EIM functions. The default value is cn=Administrator which is fine. Click the Verify Connection to confirm the correct password and, once confirmed, click OK and then click Next to continue.
         














































      •  
      Step 9 - Summary page

      • The next screen is just a summary of the settings you selected through the wizard. Click on Finish and wait for the wizard to complete. Once it is done you will need to add Identifiers and their associations.
    •         Create Identifiers and Associations in EIM



      What are Identifiers?

      • In a normal setup, an Identifier basically represents a person. An Identifier must be created, and associations added to that Identifier before that individual can use the EIM infrastructure. All EIM Identifiers must be unique, so two individuals with the same first and last name should have a way to distinguish which Identifier is for which individual. For example; two people named John Smith can be defined by their first name, middle initial, and last name which results in different Identifiers - John R. Smith and John J. Smith.

      What are Associations?
      • Associations are the relationships between an EIM Identifier and that person's profiles on individual systems. This allows EIM to map individuals to their user profiles on multiple systems, even if the user profile is different on each system. Using our example of John Smith; one system may have a user profile of JSMITH, while another system has him as JOHNS. With correct associations, John Smith is logged on as the correct user in either system automatically.

      Step 1 - Open the EIM Domain

      • Expand Network > All Tasks > Enterprise Identity Mapping and click on Domain Management.
        This should show you your EIM domain in the right frame. Right-click the domain and click on "Open".
        ***NOTE*** You may get a message that you first need to connect. If you see this, right-click on the EIM domain and then click on Connect. You can sign in with cn=Administrator and the LDAP administrator password that was configured earlier in the LDAP setup.

      Step 2 - Create an Identifier


      • Right-click "Identifiers" and click on "New Identifier".

      Step 3 - Enter the name of the Identifier


      • The only requirement on this screen is an Identifier name. It must be unique, meaning you cannot have another Identifier with the same name. Add the name and click OK.
      Step 4 - Getting to the Associations

      • ***NOTE*** Depending on what HTTP Group PTF level you are at, the next steps will differ. If you have an HTTP group that was released on 7/13/2017 or later, when you click "OK" on the Identifier creation window, you will immediately get that Identifier's properties window which is where Associations are added. If you have an HTTP group PTF that is older than 7/13/2017, you will just go back to the window with the EIM domain and the Identifiers option. If that happens, right-click Identifiers and click on "Open". This will show you your current list of Identifiers. Then Right-click the Identifier you wish to work with and select "Properties". In either case you should get to the window shown below.

        Click on the Associations tab and then click on the "Add" button.
         

      Step 5 - Add the Associations

      • The "Add Association" window allows you to select a Registry (which represents your systems), add a user name, and select an Association type.
        At this point you will only have 2 options for Registries; the local IBM i system name, and the Windows domain (which represents your AD server).
        1. With "Registry" set to your IBM i system name, add the user profile name you want to have associated with this account. In this case, John Smith will be JSMITH.
        2. When the Registry is set to your IBM i server name, the Association Type should be set to "Target" because this system will receive Kerberos tickets, it does not generate them.
        3. Click OK.

      • **Every Identifier must have, at a minimum, one Target association and one Source association. A Source association is where the Kerberos tickets are created. This, in most cases, is a Windows server. A Target association is a system that will be receiving the tickets.**

        4. Since we just created our Target association in the previous window, you will now need to create the Source association. To do this, click on the "Add" button again.

        5. Next click the "Browse" button next to "Registry" and select the registry with the type of "Kerberos". This usually will be your Windows domain name.

        6. Click OK.

        7. Add the user profile that this person logs into the Windows domain with (their network user ID when signing into their PC).

        8. Change the Association type to "Source" and click OK.

        9. You now have a Source and a Target association for this user. Click OK from the Associations page and click OK when you see message that the user was created.

        Congratulations! EIM is now configured and has a user who is ready to test Single Sign-On!

    •         Enabling Kerberos Authentication

      Enabling Kerberos Authentication For Access Client Solutions (ACS) and 5250 Emulation


      • To enable Kerberos authentication for one or more systems through ACS, you can either specify it on the 5250 emulator or you can set it from the ACS System Configurations window.

        • Step 1 - Open ACS and click on System Configurations

        • Step 2 - Select the system that Kerberos was configured for and click Edit.

        • Step 3 - Click the "Connection" tab, select "Use kerberos authentication...", and click "Apply"

        Select the connection tab, select "use Kerberos" and apply the change
        • After applying the changes, you should be able to log in without using passwords. It is possible that you may need to request new credentials from the Windows server.
          This can be done by logging off from your PC and then logging back into the network or possibly by using the KLIST PURGE command from a Windows command prompt.

          If you are still prompted to log into the system after enabling Kerberos, check WRKSYSVAL QRMTSIGN from an IBM i session on your system and make sure it is set to *VERIFY instead of *FRCSIGNON.


    [{"Type":"MASTER","Line of Business":{"code":"LOB57","label":"Power"},"Business Unit":{"code":"BU058","label":"IBM Infrastructure w\/TPS"},"Product":{"code":"SWG60","label":"IBM i"},"ARM Category":[{"code":"a8m0z0000000CGrAAM","label":"Single Sign On"}],"ARM Case Number":"","Platform":[{"code":"PF012","label":"IBM i"}],"Version":"All Versions"}]

    Document Information

    Modified date:
    27 June 2022

    UID

    nas8N1021979